Add a skill

Skills are markdown modules under .claude/skills/<skill-id>/SKILL.md. Claude’s native Skill tool surfaces them — Coro workflows never hard-code when to read each file; prompts simply tell agents which invocation budget applies (FAST vs DEEP reviewers, QA on DEEP, etc.) (/guides/switch-lanes/).

Minimal layout

.claude/skills/
  golang-conventions/
    SKILL.md

The directory name traditionally matches the name in frontmatter (golang-conventions).

Frontmatter format

Use YAML frontmatter with at least name and description (the description drives tool selection):

---
name: my-service-api
description: >-
  REST error envelope, paging, Problem+JSON quirks, auth headers, and deprecation
  notes for Acme Payment Service. Invoke before designing or modifying HTTP APIs here.
---

# Payment Service HTTP conventions

...

Tips:

• One focused scope per skill. Large catch-all blobs defeat tool ranking.
• Mention invoke when cues in description: agents match against current task wording.
• Optional fields such as license or metadata used by tooling may appear in upstream examples — omit unless your team standardises them.

Merge semantics

Skills live under .claude/skills/**; they follow replace / last-wins rules like other non-append paths (/guides/tenant-overlay/, /guides/repo-overlay/). If tenant and repo both ship dotnet-conventions, the checkout’s .coro/ copy wins once it exists after clone.

When agents invoke skills

Typical invocation points (wired by base agents; override only if needed):

Phase	Example
Planning	Planner loads feature-planning for work-item decomposition.
Coding / review	Coder invokes golang-conventions (etc.) matching params.language.
QA / DEEP	QA + Evaluator read feature-testing tiers, db migration safety (db-migrations-safe), API design heuristics, etc.

Agents should explicitly Skill-invoke early (“read-before-write”) whenever the prompt mandates it — delaying until review burns tokens twice.

Authoring checklist:

1. Prefer skills over inflating .claude/CLAUDE.md with long encyclopaedic prose.
2. Cross-link related skills from memory when you institutionalise organisational lore (/guides/manage-memory/).
3. Ship new skills via propose_change like any other markdown intelligence (/guides/review-proposals/).

Related reading

• /reference/workflow-extension/ — how workflows constrain tool bundles (see /reference/workflow-extension/).
• /guides/customize-agent/ — when procedural steps change instead of encyclopaedic chunks.