Story: Improve LLM runbook and skill tooling
Table of Contents
This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Tighten the runbook and skill workflow by closing three gaps discovered during sprint 18. First, compass add does not support skill as a document type, forcing manual invocation of generate_v2_doc.sh; this should be added. Second, the skill-creation recipe does not reference compass, so LLM sessions use the wrong scaffold path; the recipe should be updated. Third, there is no skill to locate and execute runbooks on demand; a run-runbook skill should be created so that "run the PR review runbook" resolves automatically from the catalogue.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 18 |
| Now | Complete. |
| Waiting on | Nothing. |
| Next | None. |
| Last touched | 2026-05-28 |
Acceptance
compass add skillscaffolds a new skill underdoc/llm/skills/<slug>/SKILL.org.- The skill-creation recipe (
how_do_i_create_a_new_skill.orgor equivalent) referencescompass add skillas the scaffold step. - A
run-runbookskill exists atdoc/llm/skills/run-runbook/SKILL.org, properly scaffolded via compass. - Invoking the skill reads
doc/llm/runbooks/runbooks.org, matches the user's request to the closest runbook, and executes it step by step. - If no match is found the skill lists available runbooks and asks the user to choose.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Task: Add skill type to compass add | DONE | 2026-05-28 | 2026-05-28 | Extend compass add to support the skill document type so that LLM sessions can scaffold new skills via compass add skill rather than calling generate_v2_doc.sh directly. |
| Task: Update skill-creation recipe to use compass | DONE | 2026-05-28 | 2026-05-28 | Update the how-do-I-create-a-new-skill recipe so that the scaffold step uses compass add skill rather than calling generate_v2_doc.sh directly. |
| Task: Create run-runbook skill | DONE | 2026-05-28 | 2026-05-28 | Create a run-runbook skill that reads runbooks.org, matches the user request to the closest runbook, and executes it. If no match is found, lists available runbooks and asks the user to choose. |
Decisions
Out of scope
- Modifying the content of existing runbooks.
- Automated runbook testing or dry-run mode.