docs/15-agent-skills.md
15 — Agent Skills: install once, use every phase
signaltty is built spec-first (.specify/, from
github/spec-kit) with skills doing the
heavy lifting in every phase. This doc is the routing table: which skill to
load, when. The constitution (.specify/memory/constitution.md) enforces it.
Install (any environment)
One command from any checkout, only bash + git required:
| 1 | scripts/setup-agent.sh all # skills + spec-kit commands + git hooks |
| 2 | scripts/setup-agent.sh verify # re-check this environment |
| 3 | scripts/setup-agent.sh skills list # list the curated skills |
all installs the pinned skill set into every detected harness home
(~/.agents/skills, ~/.claude/skills, ~/.codex/skills), renders the
spec-kit slash commands (/speckit-specify, /speckit-plan, …) into the
project-local dir of each detected harness, and points git at .githooks/.
Override with --target DIR / --agent NAME (auto|all|claude|codex|cursor| opencode|gemini|copilot|muse). Spec-kit sources are vendored verbatim under
.specify/ (see .specify/SOURCES.md), so slash commands install offline;
skills are shallow-cloned at pinned revs into
$XDG_CACHE_HOME/signaltty/upstream (override --cache).
skills check compares installed contents with the cached pinned revision, not
just file presence. With a custom cache pass skills check --cache DIR explicitly.
If the cache is unavailable, verification fails and asks for installation again;
the check does not fetch or modify installed skills.
Task routing
The table is generated from .agents/workflow.json.
Use scripts/agent.sh context --task <key> --json for documents and commands,
then scripts/agent.sh index --write after changing routing.
Load the workflow for the current task, then read additional references only when that workflow needs them. Already clarified requirements and existing test seams remain valid across phases; do not repeat interviews or publish issues just because a generic skill includes those steps.
| Key | Task | Load first | Add when needed |
|---|---|---|---|
research | Investigate a question | research, how | why for architectural rationale |
specify | Specify a feature | speckit-specify, speckit-clarify | domain-modeling for new concepts |
design | Design a substantial change | speckit-plan, architect | codebase-design for module boundaries |
tasks | Break down work | speckit-tasks | to-issues only when publishing issues is requested |
implement | Implement | implement, tdd, karpathy-guidelines | principle-* for a concrete design or failure |
review | Review a diff | code-review | interrogate for adversarial review; blast-radius for cross-module risk |
verify | Verify a change | verify-signaltty, principle-prove-it-works | maintain-verification-skill when coverage changes |
gui | Change GTK visuals | frontend-design, emil-design-eng | motion/prototype skills for those changes |
diagnose | Diagnose a failure | diagnosing-bugs | figure-it-out when no narrower workflow fits |
docs | Write documentation | technical-writing | writing-for-agents for instructions or skills |
core | Change pure domain logic | implement, tdd, karpathy-guidelines | |
ipc | Change IPC contracts | implement, tdd, karpathy-guidelines | |
workflow | Change agent tooling | implement, tdd, writing-for-agents |
The canonical project verification skill is
.agents/skills/verify-signaltty.
Claude, Cursor and Copilot have relative links to the same source; other harnesses
can follow the pointer in AGENTS.md. It is repository-owned and is not replaced
by the upstream skill installer. scripts/verify.sh fast checks those links.
See agent development for environment setup, worktree isolation, handoffs and the task bank used to evaluate changes to this routing.
Sources and curation
| Source | Rev | Skills | License |
|---|---|---|---|
| mattpocock/skills | c55ee46 | 20 engineering/productivity | MIT |
| anthropics/skills | 8a1541c | frontend-design, skill-creator | Apache-2.0 |
| emilkowalski/skills | d16ebe6 | 7 design/motion (prototype → emilkowalski-prototype) | MIT |
| multica-ai/andrej-karpathy-skills | 2c60614 | karpathy-guidelines | MIT |
cursor/plugins (pstack/) | adf3218 | 19 workflows + 23 principle-* (tdd → pstack-tdd, teach → pstack-teach) | MIT |
| github/spec-kit | 8d3f64c | vendored .specify/ + vendored commands | MIT |
Excluded deliberately: harness-specific setup skills, TS-only skills,
writing-for-publication skills, and anthropics source-available doc skills
(docx/pdf/pptx/xlsx). Rename-on-collision keeps both variants
addressable (see skills list).
Refresh: scripts/setup-agent.sh pins shows pinned vs latest; to move, update
the PIN_* vars (and .specify/SOURCES.md for spec-kit), re-run all,
commit. Never hand-edit an installed skill: fix upstream or drop it.