| name | skill-authoring |
| user-invocable | true |
| description | Create and maintain repo-local skills from repeated workflows, recurring corrections, and durable agent guidance. Use when adding a new skill, updating an existing skill, distilling a conversation into a skill, or auditing skill/index/registry drift. |
| argument-hint | [new-skill-name | existing-skill-path] |
| version | 1.0.0 |
| status | active |
| packages | ["all"] |
| dependencies | [] |
| last_updated | 2026-05-15 |
| last_verified | 2026-05-15 |
Skill Authoring Skill
Turns hard-won workflow knowledge into small, maintainable repo-local skills.
Use this when a conversation produces reusable guidance, when an agent needs repeated correction, or when a workflow has enough judgment that a plain script would be too brittle.
Activation
| Trigger | Action |
|---|
| "create a skill" | Draft a new skill under .claude/skills/<slug>/SKILL.md |
| "turn this into a skill" | Distill the current workflow/corrections into durable instructions |
| "update this skill" | Patch the smallest existing skill surface |
| "audit skills" | Check index, registry, bundles, evals, and stale references |
| Repeated correction | Propose a skill update instead of repeating the correction again |
When a Skill Is Worth It
Create or update a skill when at least one is true:
- The same correction has happened in multiple sessions.
- The workflow crosses tools, files, or validation steps.
- The task depends on Coop-specific judgment, not generic best practice.
- A flexible process is better than a rigid script because the task may start mid-stream.
- The guidance should survive context compaction and agent handoff.
Do not create a skill for one-off preferences, narrow temporary tasks, or guidance already covered by a nearby skill.
Authoring Workflow
1. Find the Nearest Existing Skill
Before creating anything new:
- Read
.claude/skills/index.md.
- Search
.claude/skills/**/SKILL.md for overlapping triggers.
- Prefer updating a sub-file or existing skill when the new guidance is a sub-concern.
- Create a new top-level skill only when the activation surface is distinct.
2. Extract the Stable Rule
Distill the conversation into:
- When to use it: concrete triggers and non-triggers.
- Workflow: ordered steps the agent can follow.
- Repo references: exact files, scripts, or commands.
- Validation: what proves the workflow worked.
- Failure modes: common mistakes and how to recover.
Keep voice and examples repo-specific. Avoid generic "be helpful" instructions.
3. Write the Skill
Every active top-level skill needs YAML frontmatter:
---
name: skill-slug
user-invocable: true
description: One concise sentence with trigger language and intended use.
argument-hint: "[optional-argument]"
version: "1.0.0"
status: active
packages: ["all"]
dependencies: []
last_updated: "YYYY-MM-DD"
last_verified: "YYYY-MM-DD"
---
Body shape:
- Short purpose statement.
- Activation table.
- Ordered workflow.
- Output or handoff contract when relevant.
- Validation or maintenance checklist.
- Related skills.
4. Wire the Skill
For active top-level skills:
- Add it to
.claude/skills/index.md.
- Add it to
.claude/registry/skills.json.
- Add or update
.claude/registry/skill-bundles.json only when it belongs to a common workflow.
- Update
.claude/agents/*.md or .codex/agents/*.toml only if an agent should load it routinely.
- Add an eval prompt under
.claude/evals/skills/ for judgment-heavy skills.
5. Verify Drift
Before finishing, check:
rg -n "old-skill-name|new-skill-name" .claude .codex AGENTS.md CLAUDE.md --glob '!.claude/worktrees/**'
jq empty .claude/registry/skills.json .claude/registry/skill-bundles.json .claude/registry/commands.json
If the skill changes command or validation guidance, verify the referenced command exists in package.json.
Maintenance Rules
- Skills should point at repo truth, not duplicate large sections from
AGENTS.md or CLAUDE.md.
- Use sub-files for deep references instead of making one top-level skill enormous.
- Archive stale skills by moving them under
.claude/skills/_archived/ and recording the replacement in skills.json.
- If a skill includes code examples, keep them aligned with this repo's actual stack.
- If a skill names an external tool or plugin, state the fallback when that tool is unavailable.
- If a skill changes behavior for code review, planning, or agent output, update
output-contracts.md or explain why it does not apply.
Related Skills
plan -- Feature-pack and lane workflow.review -- Findings, severity, and human judgment callouts.browser-verification -- Visual/browser proof for UI-impacting skills.design -- Coop-specific visual and interaction judgment.
