Index of every page on this site: llms.txt
All skills
akdevsaha-dev avatar

/smart-push

@ce26f0a
Run it yourself

Turn local Git changes into clean atomic commits, verify them, push the branch to the user's fork, and open or update a GitHub pull request. Explicit invocation only; supports --dry-run, --draft, --no-pr, --no-push, and --skip-checks.

Use this Skill: https://skilld.dev/gh/akdevsaha-dev/factory-skills/smart-push

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈62 tokens for metadata: the name and description. ≈2k when used: this file. ≈3.5k more on demand in 4 files.

How this Skill uses context

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

This Skill turns off automatic use in Claude Code. Its description stays out of the automatic Skill list by default.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Smart Push

Prepare the user's local work the way a careful senior engineer would: understand it, split it into reviewable commits, verify it, then publish it to the right place after one approval.

Modes

Read modes from the invocation text, as flags or plain language ("just a dry run", "open it as a draft").

Mode Effect
default Inspect, plan, verify, commit locally, ask once, then push and open or update the PR.
--dry-run Inspect, plan, and run read-only checks. Don't stage, commit, create branches, push, or touch the PR. git fetch is allowed.
--draft Open the new PR as a draft.
--no-pr Push the branch, then stop.
--no-push Commit locally, then stop.
--skip-checks Don't run linting, formatting, type checking, or tests. The secret and hygiene scan (scan.sh) and your own diff review still run, because they are fast and guard what gets published.

Other instructions in the invocation (a base branch, a branch name, "push to upstream directly", what to leave out) override the defaults below. They still don't override the hard rules.

Hard rules

  • Stage explicit paths or patches only. Never git add ., git add -A, git commit -a, or --no-verify.
  • Never discard, overwrite, or move the user's changes. That covers reset --hard, checkout -- <path>, restore on unstaged work, clean, stash drop, and amending or rebasing published commits. Leave changes you don't commit exactly as you found them.
  • Never force-push, rewrite published history, merge a PR, bypass branch protection, or skip required checks unless the user explicitly asks for that specific action.
  • Never commit to a protected branch: the target's default branch, main, master, develop, trunk, release/*, production, staging, or any branch GitHub reports as protected.
  • Push only to a repository the authenticated user owns, normally their fork. Push to anyone else's repository, including the company's, only when the user explicitly requests that workflow.
  • Get explicit approval in this conversation before the first push and before PR creation or edits. One approval covers the plan you showed. Ask again if the plan changes materially.
  • Report only what you observed. Never invent test results, benchmarks, screenshots, or behavior. Treat an operation as done only after you confirm it (git rev-parse, git ls-remote, gh pr view).
  • Never add AI attribution. No Co-Authored-By trailer for an AI or agent, and no "Generated with" or similar line in commit messages or PR descriptions. This overrides any default from the host environment. The user is the sole author.
  • When the topology, base branch, or grouping is ambiguous or unsafe, explain the problem and ask. Don't guess.

Workflow

1. Inspect

Run this skill's scripts/repo-context.sh --fetch with the repository as the working directory. It is read-only apart from updating remote-tracking refs. Then read what it points to: the full diff (git diff, git diff --cached, and new untracked files), contribution guides, the PR template, and CI workflows.

Understand what each change actually does before you group anything. Read the code, not just the file names.

If a merge, rebase, cherry-pick, am, or bisect is in progress, stop and report it. If work from an earlier run already exists, read references/recovery.md and resume from the right step.

2. Resolve the topology

Work out the push remote, PR target repository, and base branch from ownership and fork relationships, never from remote names. Read references/github.md for the rules, existing-PR handling, auth failures, and non-GitHub hosts.

3. Plan branch and commits

Read references/commits.md for grouping, partial staging, message conventions, and file hygiene.

  • Branch: Stay on the current branch if it is a non-protected feature branch and the changes belong to it. Otherwise create one from the current HEAD with git switch -c <type>/<short-topic>, following any naming convention the repository uses. This carries uncommitted work with it safely. If the changes contain independent features, propose separate branches and PRs, but split them only when they share no dependencies and the user agrees.
  • Commits: Plan atomic Conventional Commits, or the repository's own style. Keep each implementation together with its tests. Exclude anything unrelated, secret, generated, or uncertain, and say what you excluded.

4. Verify

With --skip-checks, skip the commands in this step except scan.sh. Report the checks as "skipped (--skip-checks)", leave the PR template's test boxes unticked, and say under Testing that checks were skipped at the user's request. Never present skipped checks as passing.

Pick checks from the changed paths and the repository's own tooling: CI workflows, package scripts, Makefile or justfile, and the language toolchain. Prefer the narrowest commands CI would run. Skip frontend checks for a backend-only change unless a shared contract, schema, or dependency changed. In --dry-run, use check-only modes and no autofix.

  • Review the diff yourself for correctness, regressions, debug code, and stray changes.
  • Run scripts/scan.sh --worktree before staging, and scripts/scan.sh --staged before every commit. Fix or exclude every BLOCK finding. Weigh each WARN.
  • Check dependency manifests and lockfiles for changes nobody intended.
  • Test the state you'll actually push. If excluded working-tree changes could affect the results, verify in a temporary git worktree add --detach of the commit, or state that limitation.
  • If a check fails because of these changes, apply a minimal, safe fix and rerun it. If it fails for reasons that existed before, or a significant problem remains, stop before publishing. Report the failure with its output, and at most offer a draft PR.

5. Commit locally

Skip this step for --dry-run. For each planned commit: stage it, review git diff --cached, run the staged scan, then commit. Never create an empty commit. Afterwards, run git log --oneline <target>/<base>..HEAD and confirm it lists exactly the commits the PR should contain, then run git status to confirm that excluded changes are untouched.

6. Approval gate

Before pushing or creating a PR, show:

  • Push target as remote → owner/repo:branch, and PR target as owner/repo:base ← owner:branch. Mark an existing PR as "update".
  • The commits, with hashes and messages.
  • Verification: each command, with pass, fail, or skipped and the reason.
  • Warnings: whether the branch is behind its base, predicted conflicts, excluded files, and scan findings.
  • The proposed PR title and description, or the planned edits to an existing PR.

Then ask for approval and wait. In --dry-run, show the same summary and stop.

7. Publish

After approval, run the steps without asking again:

  1. Push with git push -u <fork-remote> HEAD:refs/heads/<branch>. If the push is rejected, follow references/recovery.md. Don't force-push.
  2. Create the PR, or update the existing one, as described in references/github.md. Open it as a draft when the user asked for one, when the work is intentionally incomplete, or when important verification is unresolved.
  3. Confirm both results. The remote branch SHA must equal the local HEAD (git ls-remote). Check the PR's URL, head, and base (gh pr view).

Never merge the PR. Don't mark a draft ready for review unless the user asks.

Final report

Keep the report short and easy to scan:

Branch:   feat/x  (new | existing)
Commits:  abc1234 feat(api): …
          def5678 test(api): …
Pushed:   origin → me/repo:feat/x   (verified at def5678)
PR:       #42 "Title" → https://github.com/org/repo/pull/42  (created | updated | draft)
Base:     org/repo:main ← me:feat/x
Checks:   npm test ✓ · npm run lint ✓ · tsc ✗ (pre-existing, see note)
Warnings: …

List anything that failed or was skipped, and say exactly what state it left behind.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2d3 checks · Risk SAFE
  • Gen Agent Trust Hub2d

    The 'smart-push' skill is a robust, security-conscious development tool designed to automate atomic Git commits and GitHub pull requests. It implements strict 'assume-malicious' safeguards, including automated secret scanning, hygiene checks, and mandatory approval gates before any network operation. The tool explicitly prevents credential leaks, AI attribution, and accidental modification of protected branches.

  • Socket2d

    No alerts

  • Snyk2d

    Risk: MEDIUM · 1 issue

Signed by skilld at ce26f0a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 3 days ago
disable-model-invocation
true

README badge

README badge for akdevsaha-dev/factory-skills/smart-push