Explore the guides +
Skills/smart-push
Ship / SKILL GUIDE

smart-push

Turn local changes into a pull request a reviewer can follow.

Finishing the code is only part of the job. Someone still has to split the work into sensible commits, keep secrets and scratch files out, push to the right place, and write a pull request that tells the truth about testing. Smart Push does that preparation, then stops and asks before anything leaves your machine.

When I’d use it

Use it when the change is ready to share: a new branch and PR, more commits for an open PR, or a branch that was pushed but never got its PR. It only runs when you invoke it, so it never publishes code just because files changed.

Before you start

Have git and the GitHub CLI installed, and run gh auth login. In a fork workflow, keep your fork and the original project as remotes. The names don’t matter, because the skill checks ownership rather than trusting origin and upstream. In Codex, invoke it as $smart-push.

Install it. Then give it a task.

Run this in your project’s terminal. Choose your coding agent in the installer, then start a new agent session if it needs one to discover the skill.

TERMINAL
$ npx skills add akdevsaha-dev/factory-skills --skill smart-push

Once installed, send a prompt like the ones below to your agent. These are example requests to adapt to your own project, not terminal commands or recorded results.

If slash commands aren’t available in your agent, write “Use the smart-push skill to…” and describe the same task.

New to skills? Start with the installation walkthrough

What happens next

  1. Inspects the working tree, branches, remotes, existing PRs, and the repository’s conventions.
  2. Plans atomic commits and a branch, staging part of a file when a file holds two changes.
  3. Runs the repository’s own relevant checks and scans for secrets, debug code, and stray files.
  4. Shows the targets, commits, and check results, then pushes and opens or updates the PR after your approval.

A few ways to ask

6 examples

Copy the one closest to your task. Replace names, paths, dates, and refs with ones that exist in your project.

01

The everyday handoff

SEND TO YOUR AGENT
› /smart-push

Commits locally, then asks before the first push and before the PR.

02

Preview the plan

SEND TO YOUR AGENT
› /smart-push --dry-run

Shows the commits, targets, and checks without staging, committing, or pushing anything.

03

Share work in progress

SEND TO YOUR AGENT
› /smart-push --draft

Opens the pull request as a draft. It also opens a draft on its own when important verification is still unresolved.

04

Skip the slow checks

SEND TO YOUR AGENT
› /smart-push --skip-checks

Skips linting, type checking, and tests. The secret scan still runs, and the PR says plainly that checks were skipped.

05

Commit and push only

SEND TO YOUR AGENT
› /smart-push --no-pr

Use --no-push to stop after the local commits instead.

06

Name the target

SEND TO YOUR AGENT
› /smart-push target the develop branch and leave the config changes out

Plain-language instructions work alongside the flags.

What to look for in the result

A short report with the branch, commit hashes and messages, push destination, PR link, base and head, check results, and warnings. Each remote step is confirmed against GitHub before it’s reported. Commits and PR descriptions carry no AI attribution.

A thing worth watching

It never force-pushes, rewrites published history, merges, or pushes to a repository you don’t own unless you ask for that specific action. A rejected push or a conflict comes back to you as a decision. Skipped or failing checks are reported as they are, never as passing.

Use it with

Based on the repository’s skill instructions.Read the source
PUT IT INTO PRACTICE

Build a workflow you can repeat.

Follow the step-by-step guide to working with agents.

Explore Learn