Write a Skill

Phase 0 Status: Skills framework is spec-defined. .agents/skills/ and .claude/skills/ directories do not yet exist. This guide documents the target design; actual implementation comes in Phase 0 execution tasks.

Phase 0 constraint (ε skill-registry read-only): In Phase 0 the only active skill tool is skill_list — it returns the catalog of registered skills. skill_get (fetch SKILL.md content) and skill_invoke (execute a skill) activate in Phase 1.5 (R91+). This means: you can write a SKILL.md, register it in .agents/skills/<name>/SKILL.md, and it will appear in skill_list. But dispatching the skill to a sub-agent must be done manually (via the Agent tool in Claude, not via skill_invoke). Skill authorship and registration are always allowed. Runtime dispatch waits for Phase 1.5.

Skills are reusable tool-call sequences. Define once, use across agents.

1. Create the directory

.agents/skills/my-skill/
  SKILL.md
  references/    (optional)

Skills also work in .claude/skills/ for Claude Code-specific skills.

2. Write SKILL.md

# my-skill

## Triggers
- When a task with tag "auth" is assigned
- When tool `task_create` is called with priority "urgent_important"

## Required tools
- task_create
- task_update
- thought_record
- merkle_finalize

## Workflow

1. Call `thought_record` with type "plan" describing the approach
2. Execute the implementation
3. Call `thought_record` with type "observation" for test results
4. Call `task_update` with status="done", progress=100
5. Call `merkle_finalize` to seal the proof

## Verification
- thought_verify returns valid=true
- task status is "done"
- merkle_root returns a hash

3. Register the skill

Skills in .agents/skills/ are auto-discovered by agents at startup. No manual registration needed.

4. Reference the skill when spawning a sub-agent

Phase 0: There is no gsd_agent_spawn MCP tool. Sub-agents are spawned via the Task tool (Claude’s built-in sub-agent dispatch). The skill is referenced by name in the Task-tool prompt and the skill contents are included verbatim so the sub-agent can follow them.

Task(
  description: "<task id> — run colibri-executor on feature/<slug>",
  subagent_type: "general-purpose",
  prompt: "You are running the colibri-executor skill.\n\n<paste SKILL.md here>\n\nTask ID: ...\nWorktree: .worktrees/claude/<slug>\nWriteback: task_update + thought_record"
)

(Heritage — the donor AMS runtime used gsd_agent_spawn type="worker" count=1 pool_id="implementation" skills=["my-skill"]. That tool is deferred to Phase 1.5 per ADR-005.)

Skill tiers

Skills are grouped into six tiers. Each tier describes a family of responsibilities; the tier number is used in prompts and routing decisions so that a sub-agent asked for “Tier 3” work knows to look at GSD / Execution skills first.

Tier #	Tier	Purpose
1	PM & Orchestration	Coordinate tasks, hand off between agents, dispatch sub-agents, gate waves.
2	Task & Roadmap	Task CRUD, roadmap tracking, next-actions queries, status transitions.
3	GSD & Execution	Workflow execution, phase management, 5-step chain scaffolding, FSM transitions.
4	Audit & Proof	Audit trails, memory snapshots, Merkle proofs, chain verification, session sealing.
5	Infrastructure	Server ops, monitoring, DB health, migrations, backup / restore.
6	Integration	Obsidian sync, GitHub PR / issue flow, Claude API routing, external-service bridges.

Place your skill in the appropriate tier by naming convention: colibri-<tier>-<name> (e.g. colibri-pm, colibri-observability, colibri-obsidian-integration). The tier is informational — it does not change runtime semantics — but it keeps the catalog grep-able and makes dispatch prompts unambiguous.