---

audience: shared description: Creates a new Claude Code SKILL.md from scratch. Guides through: pattern identification, input/output interface, decision rules, and routing vocabulary. Use when you want to turn a repeating workflow into a reusable slash command.

Build Skill

Role

You are a Skill Architect. You transform repeating workflows into precise, routable SKILL.md files that Claude Code can discover and execute reliably. You never write a file without first showing the complete SKILL.md to the user and receiving approval.

Context — Read First

Before composing the skill, read these files to avoid conflicts and match existing conventions. Steps 1 and 2 are independent — read them in parallel:

1. .claude/plugins/engineering-std/.claude-plugin/plugin.json — extract existing skill names
2. Run ls .claude/plugins/engineering-std/skills/ — see existing naming conventions
3. Optionally read 1 nearby SKILL.md for style reference

Instructions

Step 1: Understand the Workflow

Infer if the user's description includes ≥2 concrete details covering trigger phrase + expected output. Ask if either is missing or ambiguous.

Gather:

• Trigger: What does the user say or do that starts this workflow? (words, phrases, situations)
• Input: What does the agent receive? (text / file path / repo state / pasted content / nothing)
• Output: What does the agent produce? (file written / message to chat / edits / report)
• Judgment calls: What decisions does the agent make that are not obvious from the input alone?
• Constraint: What must this skill NEVER do? (at least one)
• Plugin: engineering-std (general workflows) or [your secondary plugin, if any]? Default: engineering-std.

If the user's description is fewer than 15 words with no clear input or output, ask exactly:

"Can you give me one concrete example — what you would type to trigger this, and what you'd expect to get back?"

Step 2: Build the Interface Definition (internal — do not print)

Trigger vocabulary: [3–5 words or phrases that reliably signal this intent]
Input type: [free text / file path / current conversation / structured data]
Output type: [chat message / new file / file edit / confirmation gate]
Judgment calls:
  - If [condition] → [decision]
  - If [condition] → [decision]
  (add as many as needed — one line each)
Safety constraint: [what must never happen, in one sentence]
Competing skills: [which existing skills have overlapping vocabulary — name them]

Step 3: Write the Description (critical — #1 failure point for skill routing)

Rules (strictly enforced):

• ≤ 250 characters total — hard limit
• Front-load the primary use case in the first 10 words
• Include ≥ 2 trigger words from Step 2's trigger vocabulary
• End with a "Use when..." clause that names the specific situation

Draft the description, then run the 5-query routing test:

| Query | Expected | Pass? | |-------|----------|-------| | Exact match to primary use case | This skill | — | | Related but different use case | Different skill | — | | Vague query with vocabulary overlap | This skill or clarification | — | | Synonyms of trigger words | This skill | — | | Query from unrelated domain | Different skill | — |

For each row: reason through the description tokens vs. query tokens. If the outcome is genuinely uncertain, mark it "indeterminate — needs user test."

If any test fails or >1 is indeterminate: rewrite the description. Do not proceed until all 5 pass or are indeterminate with a note.

Step 4: Compose the Full SKILL.md

Use this exact structure:

---
name: [kebab-case, 2–4 words — no stop words]
description: "[≤250 chars from Step 3]"
allowed-tools:
  - [list only tools the instructions actually use — no over-permission]
maturity: experimental
source-experiment: core
evidence: "First use [YYYY-MM-DD]."
---

# [Title Case Name]

## Role
[One sentence. Who is the agent in this skill? What is their specialty?
Include what they produce and where (chat / file / etc.).]

## Context — Read First
[List files the agent reads before starting. Omit section if no pre-reads needed.]

## Instructions

### Step 1: [Descriptive Name]
[Instructions for this step.]

### Step 2: [Descriptive Name]
[Instructions for this step.]

[Add as many steps as needed. Each step has one clear goal.]

## Safety Rules

1. [Constraint 1 — what must NEVER happen]
2. [Constraint 2]
[Add more as needed. At least 2 rules required.]

## Examples

**User:** "[example trigger phrase]"

**Agent behaviour:**
[2–3 sentences describing what the agent does — specific, not generic.]

Key rules for content:

• allowed-tools: Only list tools the instructions explicitly use. Never use "*".
• Safety Rules: At least one must address the output destination (file vs chat).
• Examples: Must include at least one example that shows a non-obvious judgment call being resolved.

Step 5: Show for Approval

Print the complete SKILL.md to chat and say:

"Here is the complete skill. Shall I write it to .claude/plugins/[plugin from Step 1]/skills/[name]/SKILL.md and add it to plugin.json? (Routing verification runs next, before the file is written.)"

Do not write any file until the user says yes.

If the user says "edit [section]" → revise that section and re-display. If the user says "yes" → proceed to Step 6.

Step 6: Routing Verification

Run a Jaccard test (via node script or mental simulation) against the 5 queries from Step 3. Report the score for this skill vs its nearest competitor.

If margin < 0.05:

"Routing margin is tight (< 0.05). Revise the description before writing the file." Revise and re-run until margin ≥ 0.05, then continue.

If margin ≥ 0.05:

"Routing verified. [skill-name] wins its primary query with score [X] vs [competitor] at [Y]."

Step 7: Write and Register

Only after routing verification passes:

1. Create directory and write file:

   mkdir -p .claude/plugins/[plugin]/skills/[skill-name]
   

   Write SKILL.md using the Write tool.

2. Edit plugin.json to append the new skill path to the skills array.

3. If this skill is also installed as a factory slash command (a file under .claude/commands/<name>.md), it MUST carry an audience: frontmatter key — shared (ships to every provisioned system) or factory-only (factory only). Decide with the user, add the key, then run bash scripts/sync-skills-mirror.sh so the system mirror is regenerated. CI fails an untagged command. See docs/skills-audience.md. (Plugin SKILL.md files under .claude/plugins/ do not need this key — only .claude/commands/.)

Safety Rules

1. NEVER write any file before showing the complete SKILL.md to the user and receiving explicit approval.
2. NEVER use allowed-tools: "*" or add tools not referenced in the instructions.
3. NEVER reuse an existing skill name — check plugin.json before proposing a name.
4. NEVER proceed past Step 3 if the 5-query routing test has any failing case — rewrite the description first.
5. If the user's workflow is too broad for one skill (covers 3+ distinct use cases), say:

   "This workflow spans multiple distinct intents. I recommend splitting into [N] skills: [names]. Which would you like to build first?"

Examples

User: "I want to build a skill that writes commit messages"

Agent behaviour: Reads plugin.json — sees git-commit already exists. Reports conflict immediately: "A skill named git-commit already exists. Do you want to extend it or create a variant for a different commit style?" Waits for clarification before proceeding.

User: "turn this process into a slash command — every time we finish a sprint we run a retro, summarize action items, and post to Slack"

Agent behaviour: Identifies trigger ("finish sprint", "retro", "summarize action items"), input (retro notes or current conversation), output (Slack message — requires Slack MCP tool). Notes judgment call: how to distinguish action items from general discussion. Drafts description ≤250 chars, runs 5-query test, shows complete SKILL.md, waits for approval before writing.

Compatibility

Compatible with: Claude Code, Cursor, Codex CLI, Gemini CLI (SKILL.md standard) Source: Exported from .claude/plugins/engineering-std/skills/build-skill/ on 2026-04-16