domains / agent-tooling / skill-authoring / skill-development

skill-development

Skill card

combined

The two skills cover the same domain (creating and maintaining Claude Code skills) but diverge significantly in scope and methodology. The first copy (scenario-labs) is a theoretical guide focused on the 'Anatomy of a Skill' and 'Progressive Disclosure' design principles, treating skills as abstract plugin components. The second copy (brycewang-stanford) is a practical, environment-aware workflow that emphasizes inspecting the local filesystem, verifying the existence of referenced files, and performing integrity checks to prevent 'dead references.' The first copy lacks the local verification steps, while the second lacks the detailed theoretical breakdown of resource types (scripts vs. references vs. assets) and the specific 'Progressive Disclosure' context management strategy. Combining them yields a complete guide that covers both the design theory and the practical implementation/verification workflow.

Repositories

Other copies

Combined skill

---
name: skill-development
description: This skill should be used when the user wants to create a new skill, repair an existing skill, improve trigger descriptions, or organize skill content. It covers skill anatomy, progressive disclosure, and local integrity checks.
version: 0.3.0
---

# Skill Development

This skill provides guidance for creating effective, maintainable skills for Claude Code. It combines design principles with practical local verification workflows.

## 1. Design Principles & Anatomy

Skills are modular packages that extend Claude's capabilities. They follow a **Progressive Disclosure** model to manage context efficiently:
1. **Metadata (name + description)**: Always in context (~100 words). Determines when the skill triggers.
2. **SKILL.md body**: Loaded when the skill triggers (<5k words). Contains core workflow and boundaries.
3. **Bundled Resources**: Loaded as needed. Keeps SKILL.md lean.

### Skill Structure
```
skill-name/
├── SKILL.md (required)
└── Bundled Resources (optional)
    ├── scripts/      - Deterministic code (Python/Bash)
    ├── references/   - Documentation loaded into context as needed
    ├── examples/     - Concrete outputs or scaffolds
    └── assets/       - Files used in output (templates, images)
```

**Resource Guidelines:**
- **Scripts**: Use for deterministic reliability or repetitive code generation.
- **References**: Use for detailed schemas, policies, or API docs. If >10k words, include grep patterns in SKILL.md.
- **Assets**: Use for files that are part of the final output (e.g., logos, boilerplate).

## 2. Creation & Repair Workflow

### Step 1: Inspect the Environment
Before writing or editing:
- Inspect the target skill directory.
- Verify which agents, commands, and sibling skills actually exist locally.
- Identify stale references or dead paths.
- *Note: Do not write guidance against an imagined plugin layout; use the local inventory as authority.*

### Step 2: Define the Contract
Lock in four things before editing:
1. What the skill does.
2. What triggers it (concrete user phrases).
3. What it explicitly does **not** do.
4. Which bundled resources are actually needed.

### Step 3: Write Frontmatter
- Use the real skill identifier in `name`.
- Use a third-person trigger description (e.g., "This skill should be used when...").
- Include concrete phrases a user would naturally say.
- Keep it short and scannable.

### Step 4: Write SKILL.md (Keep it Lean)
- Include: Short goal, role boundaries, default workflow, safety rules.
- Exclude: Templates, exhaustive checklists, edge-case catalogs, long examples.
- Move detailed material to `references/` or `examples/`.

### Step 5: Add Real Bundled Resources
- Only create `references/`, `examples/`, or `scripts/` if they are needed.
- **Rule**: If a resource is mentioned in `SKILL.md`, it must exist locally.
- **Rule**: If a resource exists but is never referenced, delete it.

### Step 6: Integrity Checks
Before closing, verify:
- Frontmatter parses correctly.
- All referenced local files exist.
- Sibling skill or agent references are real.
- `SKILL.md` is not overloaded with material that belongs in references.
- No temporary logs, caches, or editor artifacts are left in the skill directory.

## 3. Repair Patterns

- **Too Long**: Move catalogs/deep detail to `references/`. Keep a short read order in SKILL.md.
- **Too Thin**: Add a default workflow and at least one concrete example. Make boundaries explicit.
- **Stale References**: Remove dead paths immediately. Replace historical names with current local names.

## 4. Output Format
When creating or repairing a skill, report:
- What changed.
- Which files were created or updated.
- What integrity checks were run.
- What still needs manual follow-up.