Shared agent skills and sub-agent definitions.
skills/- Agent Skills, one directory per skill with aSKILL.md.agents/- sub-agent definitions (Markdown with frontmatter).
How the skills and agents chain together. Define is optional; simple work starts at Build. Every arrow crossing a gate needs explicit user approval. Artifact layout, spec/plan linking and session-start rules: docs/work-artifacts.md.
flowchart TD
subgraph S0["0 Session start"]
rules["Agent instructions<br/>permission policy"]
gate{"Artifact gate<br/>user selects ~/.agent-work spec/plan?<br/>ask, never guess"}
rules --> gate
end
subgraph S1["1 Define (optional, any order)"]
grill["grill-with-docs (grill me)<br/>work/<id>/notes.md<br/>context/CONTEXT.md<br/>decisions/NNNN.md"]
plan["create-plan<br/>work/<id>/plan.md"]
spec["to-feature-spec<br/>work/<id>/spec.md"]
breakdown["feature-spec-breakdown<br/>tickets/NN-*.md<br/>optional todos / tracker"]
grill <--> plan
plan <-->|reciprocal links| spec
spec --> breakdown
plan --> breakdown
end
approve{{"Design approved != implementation approved"}}
subgraph S2["2 Build"]
tdd["tdd (external)<br/>red-green-refactor"]
debug["debug / prod-debug<br/>read-only diagnosis"]
end
subgraph S3["3 Verify"]
review["code-review"]
workers["workers per round: behavior, blind,<br/>code-health, security, tests,<br/>simplicity, approach, spec"]
simplify["simplify-code<br/>propose, edit approved only"]
qa["qa-review<br/>Playwright + Figma"]
review --> workers
end
subgraph S4["4 Feedback"]
triage["review-triage (all incoming feedback)<br/>one item at a time"]
sources["Feedback sources<br/>code-review, simplify-code, qa-review,<br/>GitHub / GitLab / other PR/MR comments,<br/>human reviewers, pasted bug lists"]
sources --> triage
prr["pr-review (outgoing)<br/>publish only after exact preview approved"]
end
subgraph S5["5 Ship"]
commit["commit<br/>focused commits<br/>never stage work artifacts"]
end
subgraph META["Side lane: meta"]
meta["skill-writer, find-skills (external)"]
end
voice["writing-for-humans<br/>voice for published text"]
prr -.-> voice
triage -.->|code-host replies| voice
breakdown -.->|ticket prose| voice
gate -->|new or selected work| S1
gate -->|standalone task| S2
breakdown --> approve --> S2
debug --> tdd
S2 --> S3
S3 -->|review report| sources
triage -->|Fix: one commit per fix| commit
S3 -->|clean| commit
commit -.->|next ticket| S2
Installed by the dotfiles installer (install-dotfiles), which clones this repository to ~/Developer/agents and links it into ~/.agents:
mkdir -p ~/.agents/skills
stow -d ~/Developer -t ~/.agents agents~/.agents/skills stays a real directory so skills installed with npx skills live beside the linked ones without landing in this repository.
The workflow also uses these upstream skills, installed separately with npx skills and not kept in this repository:
| Skill | Source | License |
|---|---|---|
| tdd | mattpocock/skills | MIT |
| find-skills | vercel-labs/skills | MIT |
| skill-writer | getsentry/skills | Apache-2.0 |
Install them globally for Pi (~/.agents/skills) and Claude Code (~/.claude/skills). Requires Node.js 22.20 or later.
-
Install the skills:
npx skills add mattpocock/skills --skill tdd -g -a pi -a claude-code npx skills add vercel-labs/skills --skill find-skills -g -a pi -a claude-code npx skills add getsentry/skills --skill skill-writer -g -a pi -a claude-code
-
Check them with
npx skills ls -g, and update later withnpx skills update -g.
Restart running agent sessions to pick up the new skills.
Each skill's SOURCES.md records full provenance, decisions and validation. "Based on" means the local skill adapts that upstream skill; "Pattern reference" means ideas were compared but the skill is a local synthesis. Revisions are the ones last inspected.
| Skill | Based on | Pattern reference |
|---|---|---|
| code-review | Local | Google eng-practices; OWASP |
| commit | Local | getsentry/skills commit |
| create-plan | Local | getsentry/skills skill-writer |
| debug | Local | - |
| feature-spec-breakdown | mattpocock/skills to-tickets |
- |
| grill-with-docs | mattpocock/skills grill-with-docs, grilling, domain-modeling |
- |
| pr-review | Local | anthropics/claude-plugins-official; feiskyer/claude-code-settings |
| prod-debug | Local | - |
| qa-review | Local | microsoft/playwright-mcp; vercel-labs/agent-browser; microsoft/playwright-cli |
| review-triage | Local | obra/superpowers receiving-code-review |
| simplify-code | Local (grugbrain.dev philosophy) | getsentry/skills code-simplifier; anthropics/claude-code; mattpocock/skills |
| to-feature-spec | mattpocock/skills to-spec |
- |
| writing-for-humans | Local | blader/humanizer; hardikpandya/stop-slop; zlliang/skills writing-issues-and-prs; Google eng-practices; Conventional Comments |
When refreshing a skill from upstream, keep local contracts (approval gates, work-artifact identity, title-only commits) over upstream defaults.
MIT.