agentleFS
Sign inStart free
cashew-labscashew-labs/libretto/.agents/skills/push/SKILL.md

push

Skill898 starsChanged 3 months agoMITView on GitHub

Commit and push changes, creating or updating a PR as needed. Use for standard push workflow.

  • Commits and pushes

We split this skill into the rules it gives an agent

23 rules. 0 are common, 16 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 40 edited versions we read keep these.

  • 16

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If on main, checkout a new branch first.

    line 8
  2. Distinctive:

    If on a non-main branch where the existing PR is already merged, the uncommitted changes are likely unrelated to that branch.

    line 10
  3. Distinctive:

    Create a new branch with a name describing the uncommitted changes

    line 13
  4. Distinctive:

    When writing or updating a PR title and description, always base them on the full diff against main (git diff main...HEAD), not just the …

    line 20
  5. Distinctive:

    When creating or updating a PR in this repo, make sure it has a changelog label so GitHub Releases can categorize it correctly.

    line 24
  6. Very specific:

    If the correct label is unclear, prefer enhancement.

    line 32
  7. Very specific:

    If the PR should be excluded from release notes, use skip-changelog.

    line 34
  8. Very specific:

    Use skip-changelog for PRs focused only on developer tooling changes, such as agent skills, workflow plumbing, local tooling, or similar …

    line 36
  9. Very specific:

    When the PR body contains Markdown code spans/backticks, parentheses, angle brackets, or shell-sensitive characters, do not pass it …

    line 40
  10. Very specific:

    Use --body-file with stdin/heredoc instead:

    line 42
  11. Distinctive:

    Use the same pattern for updates:

    line 51
  12. Distinctive:

    Do not report completion to the user until all required GitHub PR checks pass.

    line 62
  13. Distinctive:

    Do not auto-commit or auto-push fixes for issues discovered after the initial push, including CI failures and AI review bot findings.

    line 64
  14. Distinctive:

    Wait for the user to approve committing before committing, pushing, or restarting the CI loop.

    line 69
  15. Very specific:

    If GitHub returns no checks reported, treat it as possible propagation delay.

    line 74
  16. Distinctive:

    If checks are still not reported after those retries, run one remediation pass and treat merge conflicts with main as a likely cause:

    line 75
  17. Very specific:

    If merge conflicts occur, resolve them by following the fix-merge-conflicts skill.

    line 77
  18. Distinctive:

    Commit the conflict resolution if needed, push, and restart this CI loop once.

    line 78
  19. Distinctive:

    If checks are still not reported after that remediation pass, conclude no required checks are configured for this PR.

    line 79
  20. Distinctive:

    If checks appear, wait for all required checks to complete.

    line 80
  21. Distinctive:

    If any test or type-check command fails, inspect logs immediately, fix the issue locally, and hand the uncommitted fix back to the user for …

    line 81
  22. Distinctive:

    If checks are blocked on AI review bots, wait for bot completion and read all bot reviews before reporting completion.

    line 82
  23. Distinctive:

    Read every new AI review comment on the PR, including multiple reviews from multiple bots.

    line 86

“Common” is measured: kept by at least 6 in 10 of the 40 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Branch handling

If on main, checkout a new branch first.

If on a non-main branch where the existing PR is already merged, the uncommitted changes are likely unrelated to that branch. In this case:

  1. Checkout main and pull
  2. Create a new branch with a name describing the uncommitted changes
  3. Continue with the commit and PR workflow below

Commit and PR workflow

Commit the changes. Use gh cli to check if a PR exists for this branch. If no PR exists, create one with an appropriate title and description. If a PR exists, query its current title and description and update them if the new changes warrant it. Push the changes.

When writing or updating a PR title and description, always base them on the full diff against main (git diff main...HEAD), not just the most recent commits. The title and description should accurately summarize the entire set of changes in the PR.

Release note labels

When creating or updating a PR in this repo, make sure it has a changelog label so GitHub Releases can categorize it correctly.

Prefer one of:

  • enhancement
  • bug
  • documentation

If the correct label is unclear, prefer enhancement.

If the PR should be excluded from release notes, use skip-changelog.

Use skip-changelog for PRs focused only on developer tooling changes, such as agent skills, workflow plumbing, local tooling, or similar maintenance that should not appear in user-facing release notes.

PR body formatting

When the PR body contains Markdown code spans/backticks, parentheses, angle brackets, or shell-sensitive characters, do not pass it directly via --body "..." because shells can mangle it.

Use --body-file with stdin/heredoc instead:

cat <<'EOF' | gh pr create --base main --head <branch> --title "<title>" --body-file -
## Summary
- item with `code`
EOF

Use the same pattern for updates:

cat <<'EOF' | gh pr edit <branch-or-number> --body-file -
## Updated Summary
- item with `code`
EOF

CI and review gating

Do not report completion to the user until all required GitHub PR checks pass.

Do not auto-commit or auto-push fixes for issues discovered after the initial push, including CI failures and AI review bot findings. If fixes are needed after CI or review feedback:

  1. Inspect the failure or review feedback.
  2. Apply the fixes locally without committing them.
  3. Report the fixes to the user and explicitly hand the changes back for review.
  4. Wait for the user to approve committing before committing, pushing, or restarting the CI loop.

After every push:

  1. Watch PR checks with gh pr checks --watch.
  2. If GitHub returns no checks reported, treat it as possible propagation delay. Wait 15 seconds and retry gh pr checks --watch. Repeat up to 8 times (about 2 minutes total).
  3. If checks are still not reported after those retries, run one remediation pass and treat merge conflicts with main as a likely cause:
    • Pull and merge main into your branch.
    • If merge conflicts occur, resolve them by following the fix-merge-conflicts skill.
    • Commit the conflict resolution if needed, push, and restart this CI loop once.
  4. If checks are still not reported after that remediation pass, conclude no required checks are configured for this PR.
  5. If checks appear, wait for all required checks to complete.
  6. If any test or type-check command fails, inspect logs immediately, fix the issue locally, and hand the uncommitted fix back to the user for review. Do not commit, push, or repeat the CI loop until the user approves.
  7. If checks are blocked on AI review bots, wait for bot completion and read all bot reviews before reporting completion.

AI review bot handling:

  1. Read every new AI review comment on the PR, including multiple reviews from multiple bots.
  2. Analyze each concern and classify it as valid, partially valid, or not valid.
  3. For valid or partially valid concerns, apply fixes locally and hand the uncommitted changes back to the user for review. Do not commit, push, or restart the CI loop until the user approves.
  4. For concerns that are not valid, explain why with concrete technical reasoning when you report status to the user.

For follow-up edits in this session, continue to commit, push, and update the PR as needed. After each follow-up push, re-run the full check-wait loop above (gh pr checks --watch and retries) before reporting completion.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free