Story: Action-oriented skill cleanup
Table of Contents
This page documents a story in Sprint 20. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
When working with an LLM, skill discovery is obvious: every skill is named
after the action it performs (e.g. agile-plan-sprint), not the artefact
it produces (e.g. sprint-planner), and every common compass workflow has a
dedicated skill. This makes the LLM reach for compass procedurally instead
of falling back to raw unix tools (find, grep, ad-hoc git=/=gh) when
asked to perform project actions.
This story blocks all other work in the sprint: no other story starts until the skill cleanup is done.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 20 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-06-06 |
Acceptance
- A documented naming convention exists for skills: action-oriented (verb phrase), domain-prefixed, no miscellanea of styles.
- An inventory maps every compass command/pillar to its skill (or records the deliberate absence of one).
- All existing skills either conform to the convention (renamed) or have been deleted/merged where they overlap with the new workflow skills.
- Workflow skills exist for at least: new story, new task, find recipe, find knowledge, find document, close task, close story, close task and story, merge PR, address PR review, sync branch, find bearings, journal, and fleet.
- Skills are named after the thing we want to do, never after the compass command they happen to run.
- Creating a story or task (docs only, for backlog refinement) and picking one up (branch, STARTED, journal) are distinct compass workflows with distinct skills.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Define an action-oriented naming convention for skills | DONE | 2026-06-06 | 2026-06-06 | Brainstorm and document a single naming convention for all Claude Code skills: names are actions (verb phrases) prefixed by domain, e.g. agile-plan-new-sprint, not artefact names like sprint-planner. The convention must make skill discovery obvious. Output: a knowledge document with the convention and rationale. |
| Inventory compass commands and map them to skills | DONE | 2026-06-06 | 2026-06-06 | Catalogue every compass command and subcommand across all pillars (orient, search, scaffold, capture, journal, provision, test, build, operate, shell, review, pr) and map each workflow onto a skill named per the convention. Identify gaps: workflows with no skill, skills with no compass backing. |
| Audit existing skills: rename or delete per convention | DONE | 2026-06-06 | 2026-06-06 | Review all ~40 existing skills in .claude/skills against the naming convention and the compass command map. Rename skills to action-oriented names (e.g. sprint-planner becomes agile-plan-sprint), delete or merge skills that overlap with the new compass workflow skills, and update all cross-references. |
| Create compass workflow skills | DONE | 2026-06-06 | 2026-06-06 | Create the new skills that wrap compass workflows so compass is used instead of raw unix tools: new story, new task, find recipe, find knowledge, find document, close task, close story, close task and story, merge PR, address PR review, sync branch, find bearings, journal, and fleet. Names follow the convention from the first task. |
| Add a setup-environment skill | DONE | 2026-06-06 | 2026-06-06 | New skill that sets up a working environment end-to-end: compass index with org-roam sync, build skills, build settings, env init, database recreate, and optionally run the ores shell provisioning script. Named per the convention from the first task. |
Decisions
- One story with ordered tasks under a new Epic: Skills heading in the sprint, rather than several stories: the work is a single coherent objective and the tasks have a strict ordering (convention → inventory → audit/rename → create).
- Creating a story/task (backlog refinement, no branch) and picking one up (branch + STARTED + journal) are distinct actions and get distinct skills. The compass-side change is owned by the sibling story Clean up the compass work lifecycle in the same epic.
- Tasks must execute in order: the naming convention is defined first and everything downstream applies it.
Out of scope
- Changes to compass itself (new commands, flags); this story only adds the skill layer. The create vs pick-up compass change is the sibling story Clean up the compass work lifecycle.
- Rewriting skill content beyond what renames and overlap-merges require.