Skill Creator

Skill Creator

$ARGUMENTS

Create a new skill following the Agent Skills standard.

Workflow

1. Capture intent -- ask: what should the skill do? Who invokes it?
2. Classify -- task, hybrid, or knowledge? (see Classification Guide below)
3. Interview -- gather: framework, tools, scope, output format, constraints
4. Write SKILL.md -- frontmatter + body, under 500 lines
5. Create supporting files -- reference/, templates/, scripts/ as needed
6. Test and iterate -- invoke, observe, refine

Frontmatter Reference

Classification Guide

Writing Guidelines

• Description: third person ("Generates...", "Provides..."), min 50 chars, include searchable key terms and a trigger hint (e.g., "Use when..."). Short descriptions cause over-triggering — adjacent skills fight for the same query.
• Name: lowercase, hyphens, max 64 chars -- match the directory name
• Length: SKILL.md under 500 lines; use reference/ for overflow
• Be concise: Claude is smart -- give structure, not lectures
• Degrees of freedom: be specific on format/constraints, flexible on implementation
• File references: max 1 level deep (e.g., reference/details.md)
• Use $ARGUMENTS: place it early so user input is visible
• Tables over prose: for options, patterns, mappings

Mandatory Sections (meta-architect audit criteria)

Every SKILL.md must contain all five, or it will lower the toolkit quality score:

1. Description ≥50 chars with trigger hint in frontmatter
2. At least one concrete example — fenced code block or ## Example section
3. Hard rules using uppercase markers: MUST, NEVER, CRITICAL, MANDATORY, or DO NOT
4. "When NOT to Use" section — list 2-3 adjacent skills and the boundary between them
5. Under 500 lines — split into reference/ if needed

These map directly to the mutation strategies in meta-architect.md: add_example, add_constraint, add_edge_case, restructure.

Rules vs Gotchas — different semantic buckets

Split the "hard rules" criterion into two sections when both apply:

• ## Rules — prescriptive process constraints (always-true MUST / NEVER): "MUST form a testable hypothesis before changing code", "NEVER force-push main". Required in every skill.
• ## Gotchas — environment-specific traps the agent would miss without being told, taken from Anthropic's best practices. Example from their docs: "The users table uses soft deletes. Queries must include WHERE deleted_at IS NULL or results will include deactivated accounts." Add this section only when real domain traps exist — do not pad with a (none) placeholder.

Directory Structure

skill-name/
  SKILL.md              # Main instructions (required, <500 lines)
  reference/            # Detailed docs (loaded on-demand)
  templates/            # Reusable templates for output
  scripts/              # Executable helper scripts

Only create subdirectories when the skill needs them. Most skills are a single SKILL.md.

SKILL.md Template

---
name: {name}
description: "{Third-person description, min 50 chars, with trigger hint like 'Use when...'}"
argument-hint: "[hint]"
allowed-tools: Read, Grep, Glob
---

# {Title}

$ARGUMENTS

{One-line purpose statement.}

## Usage

\`\`\`
/{name} [arguments]
\`\`\`

## What This Command Does

1. **Step one**
2. **Step two**
3. **Step three**

## Example

\`\`\`
/{name} example-argument
\`\`\`

{Expected observable behavior.}

## Rules

- **MUST** {non-negotiable rule 1}
- **NEVER** {forbidden action}
- **CRITICAL**: {safety constraint}

## Gotchas

- {environment-specific trap the agent would miss — concrete, not general}
- {non-obvious behavior of a tool, API, or data layout}

## When NOT to Use

- For {adjacent use case} -- use `/{other-skill}` instead
- For {another case} -- use `/{another-skill}`
- If {precondition} is not met

Leave out ## Gotchas entirely when the skill has no domain-specific traps — it is not mandatory, and a stub with nothing concrete is worse than no section.

Quality Checklist

Before finalizing, verify:

• Description ≥50 chars, third-person, with trigger hint
• At least one concrete code-fenced example
• ## Rules section with prescriptive MUST / NEVER / CRITICAL / MANDATORY
• ## Gotchas section when the domain has real environment-specific traps (otherwise omit)
• ## When NOT to Use section naming 2-3 adjacent skills
• SKILL.md under 500 lines
• No time-sensitive information (versions, dates)
• Consistent terminology throughout
• File references max 1 level deep
• Workflows have numbered steps
• Frontmatter fields match classification type
• $ARGUMENTS is present for task/hybrid skills
• allowed-tools is minimal (principle of least privilege)

Evaluation

After creating the skill, test it:

1. Invoke with a representative prompt
2. Check output matches expected structure
3. Verify dynamic injection ($ARGUMENTS) works
4. Test with varied argument patterns
5. Confirm allowed-tools are sufficient but not excessive
6. Iterate: tighten instructions where output diverges

Installation

After creating the skill:

1. Verify the skill directory exists under app/skills/{name}/
2. Update skills-catalog.md if it exists
3. Update ARCHITECTURE.md skill counts if referenced
4. Run validate.sh if available
5. Run evaluate-skills.sh if available

Common Mistakes