Skip to content

About

Agent skills: local PR review from a clone, and fixed-shape PR creation

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

15 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

agent-skills

Agent skills for turning an issue or a work description into planned, locally committed code, opening pull requests with a fixed-shape description, and reviewing a GitHub pull request from a local clone.

These are plain SKILL.md directories — no build step, no runtime, no package manager. They work with any agent that reads the SKILL.md convention.

Skills

Skill What it does Trigger
local-triage-work Turns a GitHub issue link or a text description of a bug, feature, or tech debt into an agreed plan and local commits: interviews the user, designs a strategy, presents the plan for review, then on approval cuts a feature branch from the updated base branch and commits each step. Never pushes or opens a PR. You paste an issue link or describe the work and ask to triage, plan, or implement it
local-open-pr Opens the PR for the current branch with a fixed shape: one sentence for the problem target with a Closes line for each issue it resolves, one for how it is solved, then a Mermaid data-flow diagram of the Dart, Kotlin, and Python components the diff touches. "open a PR", "raise a pull request", "put this up for review"
local-code-review Reviews a GitHub PR from a clone sitting on the PR's updated base branch: short PR summary, diff-health checklist, integration with the local code, tests and regressions, a green/yellow/orange/red diagnostic, then per-finding triage that publishes the accepted findings to GitHub. Read-only: never checks out or executes PR code. You paste a github.com/.../pull/... URL and ask for a review

The three are stages of one pipeline, not alternatives: local-triage-work starts from an issue or a description and ends at local commits on a feature branch, local-open-pr starts once those commits exist and owns only the PR, and local-code-review starts from a reviewer's clone and owns only the review.

Install

Global (available in every project):

npx skills add CodandoTV/agent-skills -g --skill local-triage-work --skill local-code-review --skill local-open-pr

Preview without installing (lists what the repository contains):

npx skills add CodandoTV/agent-skills -l

Project-scoped instead of global (commit-able, shared with everyone who clones that repository):

npx skills add CodandoTV/agent-skills --skill local-triage-work --skill local-code-review --skill local-open-pr

The installer symlinks into the detected agent directories by default. From a local checkout where the source may move, add --copy.

Manual install — copy the folders into any skill root your agent watches:

cp -R skills/local-triage-work skills/local-code-review skills/local-open-pr ~/.agents/skills/

Update later with:

npx skills update local-triage-work local-code-review local-open-pr

Versioning

Versions are git tags. The installer has no semantic versioning of its own — a version is whatever ref you ask it to clone. Latest release: v2.1.0.

Installing without a ref follows main, so corrections arrive with npx skills update (recommended):

npx skills add CodandoTV/agent-skills -g --skill local-triage-work --skill local-code-review --skill local-open-pr

Pinning a release holds the skill still:

npx skills add CodandoTV/agent-skills#v2.1.0 -g --skill local-triage-work --skill local-code-review --skill local-open-pr

That difference is not cosmetic. npx skills update re-resolves the ref recorded in the lock file, so a pinned install is frozen on that tag and never moves — to upgrade it you re-run add with the new tag. Pin by tag, not by commit SHA: the installer clones with git clone --branch, which rejects a SHA.

One version covers the whole repository because the three skills are stages of one pipeline that ship together. What counts as major, minor, and patch is written down at the top of CHANGELOG.md.

Editing a skill

On a machine that installs these skills there are two copies — this checkout and the one the agent reads in ~/.agents/skills. Pick one writable side, or they drift silently.

Recommended: link the installed copies to the checkout (once).

make link

This replaces ~/.agents/skills/<name> with a symlink into skills/<name> here, so editing the installed copy is editing the repository: nothing to sync, and make drift stays quiet by construction. The skill provider follows symlinked entries, so discovery is unaffected. Old copies are moved to .backup-<timestamp>-<name>, never deleted. make link refuses when a copy has diverged, because linking would silently pick a side.

If you edit the installed copy instead (another machine, or before linking):

make sync-dry   # what would change, including deletions
make sync       # installed copy wins; validates, then prints git status

If you edit here and want the agent to use it right away:

make deploy     # checkout wins; the agent re-reads the body on its next load

Then publish, the same way in every case:

# 1. add "## [x.y.z] - YYYY-MM-DD" with its entries to CHANGELOG.md
# 2. commit
make release VERSION=x.y.z

make release validates, refuses a dirty tree or a missing CHANGELOG section, tags vX.Y.Z, pushes, and publishes notes taken from that section. To see the plan without touching GitHub: bash tools/release.sh x.y.z --dry-run.

Do not run npx skills add (or update) for these three names once linked: the installer materializes its own copy under ~/.agents/skills, replacing the link, and its lock entry then disagrees with your edits.

Requirements

All three:

  • git, with a clone of the repository the work belongs to.

local-triage-work additionally uses an authenticated GitHub CLI (gh auth login, repo scope) only when the input is a GitHub issue link, and runs the target repository's own test and typecheck commands.

local-code-review additionally uses an authenticated gh (repo scope), jq, and ripgrep (rg) or the agent's own search tool, and reads the local code around the diff, so the clone should be on an up-to-date base branch.

local-open-pr uses an authenticated gh (repo scope) to resolve issues and create the PR, and draws its blast-radius diagram as Mermaid, so the component listing is limited to Dart, Kotlin, and Python files in the diff.

Layout

skills/
  local-code-review/
    SKILL.md
    references/
      diff-health-checklist.md
      integration-checklist.md
      tests-and-regressions-checklist.md
    scripts/
      changed-lines.sh          # maps added lines to inline-comment anchors
  local-open-pr/
    SKILL.md
  local-triage-work/
    SKILL.md
    references/
      interview-checklist.md
      plan-template.md
tools/
  validate-skills.py            # frontmatter, catalog cap, cited paths
  drift.sh                      # installed copy vs checkout
  sync-from-global.sh           # installed copy -> checkout
  deploy.sh                     # checkout -> installed copy
  link.sh                       # replace installed copies with symlinks
  release.sh                    # validate, tag, push, publish
Makefile                        # make validate | drift | sync | deploy | link | release
.github/workflows/
  validate-skills.yml           # runs the validator plus a discovery smoke test

references/ and scripts/ are loaded on demand by the skill body, so keep them beside the SKILL.md that mentions them.

Changing a skill

Run the validator before pushing — CI runs the same thing and will fail the PR:

pip install pyyaml
python3 tools/validate-skills.py

It rejects a name that does not match its directory, a description over the 500-character catalog cap (the tail with the trigger phrases is what gets truncated), a body that cites a references/ or scripts/ path that does not exist, and camelCase invocation flags. Adding a behavioural change means adding a CHANGELOG.md entry and tagging the release.

About

Agent skills: local PR review from a clone, and fixed-shape PR creation

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages