Task: Define an action-oriented naming convention for skills
This page documents a task in the Action-oriented skill cleanup story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Define and document a single, action-oriented naming convention for all
Claude Code skills so that skill discovery is obvious. Names are actions
(verb phrases) prefixed by domain — e.g. agile-plan-sprint — never
artefact names like sprint-planner and never the compass command the
skill happens to run. The convention is the foundation for every
downstream task in the story: the compass command inventory, the audit
and rename of existing skills, and the new workflow skills all apply it.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Action-oriented skill cleanup |
| 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, with no miscellanea of styles.
- A knowledge document captures the convention and its rationale, including the chosen prefixes and worked examples (existing skill → conformant name).
- The convention distinguishes creating artefacts from picking them up (e.g. add vs start), matching the create vs pick-up distinction in the parent story.
Plan
Brainstormed 2026-06-06; design validated question by question.
- Convention:
<domain>-<verb>[-<object>], kebab-case, named after the action — never a role, artefact, or wrapped command. - Prefix register (closed):
agile-,pr-,doc-,code-(manual),codegen-(automatic),devops-,skill-. - Verb register (closed):
add(docs only, no side effects),start(pick up: branch + STARTED + journal),close(bookkeeping; cascades task→story),find,show(read-only),run,sync; rare bare verbs (pr-merge). - Reference-only skills demoted to knowledge docs
(
design-principles,icon-guidelines); role skills dissolved into actions;run-runbookdeleted — one skill per runbook. - Filed as Skill naming conventions (with full decision log), referenced from the skills inventory; skill-manager now validates names against the registers and checks the inventory for duplicates before scaffolding.
Notes
PRs
Review
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1 | Goal section has template placeholder despite STARTED | task_define_skill_naming_convention.org | Accepted | Fixed in 0fbc0c820. |
| 1 | Acceptance section is an empty bullet despite STARTED | task_define_skill_naming_convention.org | Accepted | Fixed in 0fbc0c820. |
| 2 | skill_meta crashes opaquely on malformed SKILL.org | generate_skills_catalogue.py | Accepted | Fixed in 847bf072e; descriptive ValueError. Declined the redundant or-empty coalescing. |
Result
Convention defined and filed as Skill naming conventions:
<domain>-<verb>[-<object>] with closed prefix and verb registers and
a decision log. Skills inventory note updated to state the policy and
require checking it before adding skills; skill-manager gained
validate-name and check-for-duplicates steps. The companion PR
close-out workflow design landed in the lifecycle story's design
task. All acceptance criteria met.