How Agent Skills Work in Claude Code

"A beginner-friendly walkthrough of Agent Skills: what they are, how they differ from slash commands, how to create them, and how to use progressive disclosure, supporting files, and auto-invocation to build real capabilities."

Version 1.0.0 • Updated 03/01/2026, 12:00 PM EST

Part 0: Intro

Already comfortable with slash commands but hitting their limits? This is the next step.

What this tutorial will show you is:

• ✅ Understand what Agent Skills are and how they differ from slash commands
• ✅ Create your first Skill from scratch
• ✅ Write effective SKILL.md files with proper frontmatter
• ✅ Add supporting files (scripts, templates, references, examples)
• ✅ Understand progressive disclosure and why it matters for context management
• ✅ Configure auto-invocation so Claude loads Skills without being asked
• ✅ Share Skills with your team, install them from plugins, and debug when things break

The Big Idea: A slash command is a prompt you invoke manually. A Skill is a capability Claude invokes on its own when it recognizes the task matches. Skills are directories, not single files. They can contain scripts, templates, reference docs, and examples that Claude loads progressively as needed. Think of a Skill as an onboarding guide you'd write for a new team member who needs to do a specific job.

What to expect: This tutorial assumes you've read (or are familiar with) the slash commands tutorial. If you haven't, the short version: slash commands are Markdown files in .claude/commands/ that you invoke with /command-name. Skills build on that foundation.

Prerequisites:

• Claude Code installed (requires Anthropic API key or Claude Max subscription): https://docs.anthropic.com/en/docs/claude-code
• Basic comfort with a terminal
• Familiarity with slash commands (recommended, not required)

Tutorial Path

1. Part 1: Why Skills Exist (5 min)
2. Part 2: Skills vs. Slash Commands (5 min)
3. Part 3: The Fast Way, Let Claude Build It (5 min)
4. Part 4: Creating Your First Skill Manually (10 min)
5. Part 5: Writing Effective SKILL.md Files (10 min)
6. Part 6: Progressive Disclosure (10 min)
7. Part 7: Adding Supporting Files (10 min)
8. Part 8: Auto-Invocation and Descriptions (10 min)
9. Part 9: Tool Restrictions with allowed-tools (5 min)
10. Part 10: Sharing Skills with Your Team (10 min)
11. Part 11: Bundled and Plugin Skills (5 min)
12. Part 12: Debugging Skills (10 min)
13. Part 13: Real-World Skill Examples (15 min)
14. Part 14: Quick Reference (5 min)
15. Part 15: What to Do Next (5 min)

Part 1: Why Skills Exist (5 min)

The Limitation of Slash Commands

Slash commands solve one problem: you stop retyping the same prompts. That's valuable. But as your workflows get more complex, single-file commands run into walls:

• You need Claude to reference a style guide while writing documentation. Where does it go? You can't bundle it with a .md command.
• You want Claude to run a validation script after generating code. A single Markdown file can't include executable scripts.
• You want Claude to automatically know when to apply your deployment procedure without you typing /deploy. Slash commands only fire when you invoke them manually.
• You have 15 files of reference material for a complex workflow. Stuffing it all into one Markdown file would blow out the context window.

What Skills Solve

Skills are the answer to all four problems:

• Directory-based. A Skill is a folder, not a single file. You can bundle scripts, templates, reference docs, and examples alongside the main instructions.
• Progressive disclosure. Claude doesn't load everything at once. It reads the SKILL.md first, then pulls in supporting files only when needed. This keeps context usage efficient.
• Auto-invocation. Claude reads Skill descriptions at startup and decides when to load them based on your request. You don't have to type anything.
• Cross-platform. Agent Skills follow an open standard. They work in Claude Code, Claude.ai, the API, VS Code (via Copilot), and other tools that support the spec.

The Mental Model

Think of a slash command as a sticky note with instructions.

Think of a Skill as a full onboarding binder: the main playbook, reference materials, utility scripts, templates, and examples. You hand it to a new hire and they can do the job without asking you 20 questions.

Part 2: Skills vs. Slash Commands (5 min)

Side-by-Side Comparison

When to Stay with Slash Commands

Slash commands are still the right choice when:

• Your prompt fits in a single file
• You want explicit control over when it runs
• It's a simple, repeatable action (commit, review, explain)

When to Upgrade to Skills

Move to a Skill when:

• You need supporting files (templates, scripts, reference docs)
• Claude should activate it automatically based on context
• The workflow has multiple steps with validation or branching logic
• You want to share a standardized capability across a team
• A single Markdown file is getting unwieldy

Compatibility

Your existing .claude/commands/ files still work. If a command and a Skill share the same name, the Skill takes precedence. You don't need to migrate anything. Skills and commands coexist.

Part 3: The Fast Way, Let Claude Build It (5 min)

Just like with slash commands, you can ask Claude Code to build Skills for you. In fact, Anthropic ships a bundled "skill-creator" Skill specifically for this purpose.

The Prompt Template

Copy this into your Claude Code session and fill in the blanks:

Create a Skill called [SKILL-NAME] that does the following:

[DESCRIBE THE CAPABILITY IN PLAIN ENGLISH. INCLUDE:
- What the Skill does
- When Claude should activate it
- What supporting files it needs (scripts, templates, references)
- Any tool restrictions (read-only, specific tools only)]

Requirements:
- Scope: [personal (available everywhere) | project (this repo only)]
- Auto-invocation triggers: [describe when Claude should load this automatically]
- Supporting files needed: [list any scripts, templates, or reference docs]
- Tool restrictions: [read-only | full access | specific tools]
Click to copy

Example

Create a Skill called hl7-review that does the following:

Review HL7 v2.x interface configurations for correctness. Check OBR, OBX,
ORC, and PID segment mappings against LOINC standards. Flag mismatched
data types, missing required fields, and incorrect segment ordering.
Include a reference file with common HL7 segment patterns.

Requirements:
- Scope: project (this repo only)
- Auto-invocation triggers: when I mention HL7, lab interfaces, segment
  mappings, or LOINC codes
- Supporting files needed: a reference doc with common segment patterns
  and a validation checklist
- Tool restrictions: read-only (should analyze, not modify files)
Click to copy

Claude Code creates the directory, writes the SKILL.md with proper frontmatter, generates supporting files, and the Skill is immediately available.

Using the Skill-Creator Skill

If you have the bundled skill-creator available, you can also use it interactively:

Help me create a new Skill
Click to copy

Claude will ask you questions about your workflow, generate the folder structure, format the SKILL.md, and bundle the resources. This is useful when you're not sure exactly what you need yet.

The Manual Way: Understanding How It All Works

The rest of this tutorial walks through Skills from the ground up. If you want to understand directory structure, frontmatter fields, progressive disclosure mechanics, and debugging, keep reading.

Part 4: Creating Your First Skill Manually (10 min)

Step 1: Create the Directory

Skills live in .claude/skills/ with each Skill in its own subdirectory. The directory name should match the Skill name.

For a personal Skill (available everywhere):

mkdir -p ~/.claude/skills/code-reviewer
Click to copy

For a project Skill (shared via repo):

mkdir -p .claude/skills/code-reviewer
Click to copy

Step 2: Create SKILL.md

Every Skill needs a SKILL.md file (case-insensitive) as its entry point:

touch ~/.claude/skills/code-reviewer/SKILL.md
Click to copy

Open it and write:

---
name: code-reviewer
description: Review code for bugs, security issues, and performance problems.
  Use when the user asks for a code review, mentions reviewing changes, or asks
  to check code quality.
---

# Code Reviewer

## Instructions

1. Read the target files or staged changes
2. Check for logic errors and potential bugs
3. Identify security vulnerabilities (injection, auth bypass, data exposure)
4. Flag performance concerns
5. Note error handling gaps
6. Present findings in a table: severity, file, line, issue, recommendation

## What to Skip

- Style opinions and formatting nitpicks
- Variable naming preferences (unless genuinely confusing)
- Comments about comment density

## Output Format

| Severity | File | Line | Issue | Recommendation |
|---|---|---|---|---|
| HIGH | ... | ... | ... | ... |
Click to copy

Save the file. Your Skill is now active.

Step 3: Test It

You don't invoke Skills with a / command (though you can). Instead, just ask Claude something that matches the Skill's description:

Can you review my recent changes?
Click to copy

Claude sees that your request matches the "code-reviewer" Skill's description, loads the SKILL.md, and follows the instructions. You can also invoke it directly:

/code-reviewer
Click to copy

Both work.

How Claude Code Finds Skills

At startup, Claude Code scans these locations and loads the name and description from every SKILL.md it finds:

1. ~/.claude/skills/*/SKILL.md (personal)
2. .claude/skills/*/SKILL.md (project)
3. Plugin-provided skills
4. Bundled skills (ship with Claude Code)
5. Skills in subdirectories added via --add-dir

Only the frontmatter (name + description) is loaded initially. The full SKILL.md body is read only when Claude decides to use the Skill. This is the first level of progressive disclosure.

Part 5: Writing Effective SKILL.md Files (10 min)

The Two Parts

Every SKILL.md has two sections:

1. YAML frontmatter (between --- markers): metadata that tells Claude when and how to use the Skill
2. Markdown body: the actual instructions Claude follows

Required Frontmatter Fields

Optional Frontmatter Fields

Writing Good Descriptions

The description is how Claude decides whether to use your Skill. A bad description means Claude never loads it. A good description is specific about both what the Skill does and when to use it.

Bad:

description: Helps with data
Click to copy

Good:

description: Analyze Excel spreadsheets, create pivot tables, and generate
  charts. Use when working with Excel files, spreadsheets, or analyzing
  tabular data in .xlsx format.
Click to copy

Better (with explicit triggers):

description: Analyze Excel spreadsheets, create pivot tables, and generate
  charts. Use when working with Excel files, spreadsheets, or analyzing
  tabular data in .xlsx format. Also activate when the user mentions
  CSV analysis, data summaries, or financial reports.
Click to copy

Claude currently tends to "undertrigger" Skills, meaning it doesn't use them even when it should. Being explicit and slightly "pushy" in descriptions helps. Include key terms users would naturally say when they need this capability.

Writing Good Instructions

The Markdown body is what Claude reads when the Skill activates. Structure it like an SOP:

1. What to do (step-by-step instructions)
2. What not to do (explicit exclusions prevent wasted effort)
3. Output format (tables, code blocks, specific structure)
4. Examples (concrete input/output pairs)
5. Edge cases (what to do when things are ambiguous)

Keep it focused. One Skill = one capability. If your SKILL.md is getting past 200 lines, split the content into supporting files and reference them.

Part 6: Progressive Disclosure (10 min)

The Core Concept

Progressive disclosure is the most important architectural concept in Skills. It means: show Claude only what it needs, when it needs it.

Here's how it works across three layers:

Layer 1: Startup (Metadata Only)

When Claude Code starts, it reads the name and description from every installed Skill. That's it. Not the full SKILL.md. Not the supporting files. Just the frontmatter.

This means you can have 50 Skills installed and the context cost at startup is minimal. Claude just knows what's available.

Layer 2: Activation (SKILL.md Body)

When your request matches a Skill's description, Claude reads the full SKILL.md body into context. Now it has the instructions. But it still hasn't loaded supporting files.

Layer 3: On-Demand (Supporting Files)

As Claude works through the instructions, it reads supporting files only when needed. If the SKILL.md says "for form filling, see FORMS.md," Claude only reads FORMS.md if the current task involves forms. If it doesn't, FORMS.md never enters the context window.

Why This Matters

Context is finite. Every token in the context window counts. Without progressive disclosure, a Skill with 5 reference files and 3 scripts would consume thousands of tokens immediately, even if 80% of that content isn't relevant to the current task.

With progressive disclosure:

• 50 Skills installed costs only a few hundred tokens at startup
• Activating one Skill costs only the tokens in SKILL.md
• Supporting files load one at a time, only when referenced
• Scripts can be executed without loading their full source into context (only the output consumes tokens)

Designing for Progressive Disclosure

When writing a Skill, think about what Claude needs at each stage:

SKILL.md:
  "Here's the overview and the main workflow steps"
  "For security patterns, see SECURITY.md"
  "For deployment steps, see DEPLOY.md"
  "To validate, run scripts/validate.sh"

SECURITY.md:
  [loaded only if the task involves security checks]

DEPLOY.md:
  [loaded only if the task involves deployment]

scripts/validate.sh:
  [executed only when validation is needed; output enters context, not source code]
Click to copy

Part 7: Adding Supporting Files (10 min)

Directory Structure

A Skill with supporting files looks like this:

my-skill/
├── SKILL.md              # Main instructions (required)
├── reference.md          # Reference documentation
├── style-guide.md        # Style or formatting rules
├── templates/
│   ├── report.md         # Template Claude fills in
│   └── summary.md        # Another template
├── examples/
│   └── sample-output.md  # Example of expected output
└── scripts/
    ├── validate.py       # Validation script
    └── extract.sh        # Data extraction script
Click to copy

Referencing Files from SKILL.md

Tell Claude about supporting files in the SKILL.md body so it knows what's available and when to load them:

## References

- For the complete API reference, see [reference.md](reference.md)
- For output formatting rules, see [style-guide.md](style-guide.md)

## Validation

After generating output, run the validation script:

```bash
python scripts/validate.py output.json
Click to copy

Templates

Use templates/report.md as the base structure for all generated reports.

Claude reads these files only when it needs them during task execution.

### Types of Supporting Files

**Reference docs** (`*.md`): Loaded into context when Claude needs detailed knowledge. Good for API references, style guides, checklists, and domain-specific rules.

**Templates** (`templates/`): Files Claude reads and fills in. Good for standardized report formats, PR templates, and documentation structures.

**Examples** (`examples/`): Show Claude what good output looks like. Concrete examples are more effective than abstract instructions.

**Scripts** (`scripts/`): Executable code Claude runs as tools. The script's output enters context, not the source code. Good for validation, data extraction, formatting, and any task where deterministic code is better than LLM generation.

### Scripts Are Powerful

Here's why scripts matter: some tasks are better done with code than with token generation. Sorting a list, validating JSON schema, extracting PDF fields, running linters, all of these are faster, cheaper, and more reliable as scripts.

When Claude runs a script:

1. It executes the script via bash
2. The script's output enters the context window
3. The script's source code does NOT enter context
4. Claude uses the output to continue the task

This means a 500-line Python script costs zero context tokens until it runs, and then only the output costs tokens.

Make sure scripts have execute permissions:

```bash
chmod +x .claude/skills/my-skill/scripts/*.py
chmod +x .claude/skills/my-skill/scripts/*.sh
Click to copy

Part 8: Auto-Invocation and Descriptions (10 min)

How Auto-Invocation Works

At startup, Claude Code loads every Skill's name and description into the system prompt. When you send a message, Claude's language model (not a keyword matcher, not an intent classifier, the actual LLM) decides whether any Skill is relevant.

There is no regex. No embedding similarity. No routing algorithm. Claude reads the descriptions and reasons about whether they match your request. This is pure LLM reasoning happening inside the forward pass.

What This Means for You

1. Descriptions are everything. If your description is vague, Claude won't match it. If your description is specific, Claude will consistently activate the Skill.

2. Include trigger words. Think about what a user would naturally say when they need this capability, and put those words in the description.

3. Be slightly pushy. Claude tends to undertrigger (not use Skills when it should). Adding explicit activation instructions helps:

description: Generate commit messages from staged git changes.
  Use when the user mentions commits, commit messages, staged changes,
  or asks to prepare changes for version control. Also activate when
  the user says "wrap up" or "save my work" in a coding context.
Click to copy

4. You can still invoke manually. Even with auto-invocation, every Skill with a name field creates a /slash-command. Typing /code-reviewer always works, regardless of description matching.

Controlling Invocation

If you want a Skill that Claude ONLY uses when explicitly invoked (not automatically), make the description very narrow or describe it as "invoke only when explicitly requested":

description: Database migration runner. Only use when the user explicitly
  asks to run migrations or types /run-migrations.
Click to copy

Context Budget

All Skill descriptions are loaded into the system prompt. If you have many Skills, they can exceed the character budget. The default budget is 15,000 characters. If exceeded, some Skills will be excluded.

Check your context usage:

/context
Click to copy

If you see warnings about excluded Skills, you can:

• Make descriptions shorter
• Remove unused Skills
• Increase the budget with the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable

Part 9: Tool Restrictions with allowed-tools (5 min)

What allowed-tools Does

The allowed-tools frontmatter field restricts which tools Claude can use while a Skill is active. This is important for two scenarios:

1. Read-only Skills. Analysis, audits, and reviews that should never modify files.
2. Scoped Skills. Capabilities that should only use specific tools (e.g., only Git commands, only file reading).

Example: Read-Only Reviewer

---
name: security-audit
description: Audit codebase for security vulnerabilities. Use when the user
  asks for a security review or mentions vulnerabilities.
allowed-tools: Read, Grep, Glob
---
Click to copy

With this configuration, Claude can read files, search contents, and find files by pattern. It cannot write files, execute bash commands, or make any changes.

Example: Git-Only Skill

---
name: release-prep
description: Prepare a release by checking branch status, generating
  changelogs, and creating tags.
allowed-tools: Bash(git:*), Read, Grep
---
Click to copy

Claude can run any git command, read files, and search, but cannot write files or run non-git bash commands.

When to Use allowed-tools

Use it when:

• The Skill should analyze but never modify
• You want guardrails against accidental changes
• The Skill is shared with a team and you want to enforce safety

If allowed-tools is not specified, Claude follows the standard permission model (asks before using tools that require approval).

Part 10: Sharing Skills with Your Team (10 min)

Option 1: Project Repository (Simple)

The simplest way to share Skills is to commit them to your project repo:

# Create the Skill
mkdir -p .claude/skills/deploy-procedure
# ... write SKILL.md and supporting files ...

# Commit it
git add .claude/skills/
git commit -m "Add deploy-procedure Skill for standardized deployments"
git push
Click to copy

When teammates pull:

git pull
# Skills are immediately available in Claude Code
Click to copy

This works well for project-specific Skills.

Option 2: Plugin Marketplace (Scalable)

For Skills that should work across multiple projects or be shared outside your team, package them as a Claude Code plugin and distribute through a plugin marketplace.

1. Create a plugin with Skills in the skills/ directory
2. Add the plugin to a marketplace
3. Team members install with /plugin install

This is the recommended approach for reusable, cross-project Skills.

Option 3: Personal Skills (Individual)

If a Skill is just for you, keep it in ~/.claude/skills/. It won't appear in any git repo and is available in every project you open.

Priority Order

When multiple Skills or commands share the same name, the highest-priority source wins:

1. Enterprise Skills
2. Personal Skills (~/.claude/skills/)
3. Project Skills (.claude/skills/)
4. Plugin Skills
5. Personal commands (~/.claude/commands/)
6. Project commands (.claude/commands/)

Part 11: Bundled and Plugin Skills (5 min)

Bundled Skills

Claude Code ships with several built-in Skills that are always available. These power features like document creation:

• PDF Processing: Extract text, fill forms, merge documents
• PPTX: Create and edit PowerPoint presentations
• XLSX: Create and manipulate Excel spreadsheets
• DOCX: Create and edit Word documents
• Skill-Creator: Interactively build new Skills

You don't need to install these. They're already active.

There's also a bundled developer platform Skill that activates automatically when your code imports the Anthropic SDK. You never need to invoke it.

Plugin Skills

Plugins can bundle Skills that become available when the plugin is installed. These work identically to personal and project Skills but are distributed through the plugin system.

Notable public Skills are available in the Anthropic skills repository:

https://github.com/anthropics/skills

This includes the source for the document creation Skills (DOCX, PDF, PPTX, XLSX) and community-contributed Skills for creative, technical, and enterprise workflows.

Browsing Available Skills

To see what Skills are currently loaded in your session:

What Skills are available?
Click to copy

or

List all available Skills
Click to copy

Claude will list all Skills from all sources (personal, project, plugin, bundled).

Part 12: Debugging Skills (10 min)

Claude Doesn't Use My Skill

This is the most common issue. Check these in order:

1. Is the description specific enough?

Vague descriptions fail. Claude's LLM needs clear signal.

Bad:

description: Helps with data
Click to copy

Good:

description: Analyze Excel spreadsheets, create pivot tables, and generate
  charts. Use when working with Excel files, spreadsheets, or analyzing
  tabular data in .xlsx format.
Click to copy

2. Is the SKILL.md in the right location?

# Personal Skills
ls ~/.claude/skills/*/SKILL.md

# Project Skills
ls .claude/skills/*/SKILL.md
Click to copy

The file must be named SKILL.md (case-insensitive) inside a subdirectory of .claude/skills/.

3. Is the YAML valid?

Check the first 10 lines:

head -n 10 .claude/skills/my-skill/SKILL.md
Click to copy

Common YAML problems:

• Missing opening or closing ---
• Tabs instead of spaces
• Unquoted strings with special characters (colons, brackets)
• Multi-line descriptions not properly formatted

4. Does the name match the directory?

The name field in frontmatter should match the parent directory name. If the directory is skills/my-skill/, the name should be my-skill.

Skill Loads but Doesn't Work Correctly

1. Do scripts have execute permissions?

chmod +x .claude/skills/my-skill/scripts/*.py
chmod +x .claude/skills/my-skill/scripts/*.sh
Click to copy

2. Are file paths correct?

Use forward slashes (Unix style) everywhere: scripts/helper.py not scripts\helper.py.

3. Are dependencies available?

If your scripts require packages, list them in SKILL.md. Claude will attempt to install them or ask for permission.

Multiple Skills Conflict

If Claude keeps using the wrong Skill, the descriptions are too similar. Make them distinct by using different trigger terms:

Instead of:

# Skill 1
description: For data analysis

# Skill 2
description: For analyzing data
Click to copy

Use:

# Skill 1
description: Analyze sales data in Excel files and CRM exports.
  Use for sales reports, pipeline analysis, and revenue tracking.

# Skill 2
description: Analyze log files and system metrics data.
  Use for performance monitoring, debugging, and system diagnostics.
Click to copy

Debug Mode

Run Claude Code with the --debug flag to see Skill loading and invocation details:

claude --debug
Click to copy

This shows which Skills were discovered, any loading errors, and which Skill Claude chose for a given request.

Part 13: Real-World Skill Examples (15 min)

Simple Skill: Commit Message Generator

commit-helper/
└── SKILL.md
Click to copy

---
name: commit-helper
description: Generate clear, conventional commit messages from staged changes.
  Use when the user mentions commits, commit messages, staged changes, or
  asks to wrap up their work.
---

# Commit Message Generator

## Instructions

1. Run `git diff --staged` to see changes
2. Analyze the scope of changes (what files, what type of change)
3. Generate a commit message following this format:

Click to copy

type(scope): short description (under 50 chars)

Detailed description of what changed and why. Not how. The diff shows how.

## Types

- feat: new feature
- fix: bug fix
- refactor: code change that neither fixes a bug nor adds a feature
- docs: documentation only
- test: adding or correcting tests
- chore: build process, tooling, dependencies

## Rules

- Present tense: "add feature" not "added feature"
- No period at the end of the first line
- Body wraps at 72 characters
- If there are multiple logical changes, suggest separate commits
Click to copy

Skill with Tool Restrictions: Security Audit

security-audit/
├── SKILL.md
├── checklist.md
└── patterns.md
Click to copy

SKILL.md:

---
name: security-audit
description: Audit codebase for security vulnerabilities including injection,
  auth bypass, data exposure, and dependency issues. Use when the user asks
  for a security review, mentions vulnerabilities, or wants to check code
  before deployment. Read-only, will not modify any files.
allowed-tools: Read, Grep, Glob
---

# Security Audit

## Instructions

1. Scan the codebase structure using Glob
2. Read source files in security-sensitive areas (auth, API, database, input handling)
3. Check against the patterns in [patterns.md](patterns.md)
4. Walk through the full checklist in [checklist.md](checklist.md)
5. Present findings in a table

## Output Format

| Severity | File | Line | Vulnerability | Recommendation |
|---|---|---|---|---|
| CRITICAL | ... | ... | ... | ... |
| HIGH | ... | ... | ... | ... |

## Severity Levels

- CRITICAL: Exploitable now, data at risk
- HIGH: Exploitable with effort, should fix before deploy
- MEDIUM: Potential issue, fix in next sprint
- LOW: Best practice violation, no immediate risk
Click to copy

Multi-File Skill: Documentation Generator

doc-generator/
├── SKILL.md
├── style-guide.md
├── templates/
│   ├── api-reference.md
│   ├── getting-started.md
│   └── changelog.md
├── examples/
│   └── sample-api-doc.md
└── scripts/
    └── extract-types.py
Click to copy

SKILL.md:

---
name: doc-generator
description: Generate project documentation including API references,
  getting started guides, and changelogs. Use when the user asks to
  document code, generate docs, write a README, or create API references.
---

# Documentation Generator

## Instructions

1. Analyze the codebase structure
2. Determine what type of documentation is needed
3. Follow the [style-guide.md](style-guide.md) for all output
4. Use the appropriate template from the templates/ directory:
   - API documentation: [templates/api-reference.md](templates/api-reference.md)
   - Getting started: [templates/getting-started.md](templates/getting-started.md)
   - Changelog: [templates/changelog.md](templates/changelog.md)
5. See [examples/sample-api-doc.md](examples/sample-api-doc.md) for expected output quality

## For TypeScript Projects

Run the type extraction script to get a structured overview:

```bash
python scripts/extract-types.py src/
Click to copy

Use the output as the basis for API reference documentation.

Rules

• Every public function gets documented
• Include at least one usage example per function
• Note breaking changes explicitly
• Use the project's existing terminology (don't rename concepts)

---

### Skill for a Specific Domain: HL7 Interface Validator

Click to copy

hl7-validator/ ├── SKILL.md ├── segment-reference.md ├── common-errors.md └── scripts/ └── parse-hl7.py

**SKILL.md:**

```markdown
---
name: hl7-validator
description: Validate HL7 v2.x interface configurations and message
  structures. Use when the user mentions HL7, lab interfaces, segment
  mappings, OBR, OBX, ORC, PID, LOINC codes, or integration testing.
allowed-tools: Read, Grep, Glob, Bash(python:*)
---

# HL7 Interface Validator

## Instructions

1. Read the interface configuration or HL7 message file
2. Parse segments using [scripts/parse-hl7.py](scripts/parse-hl7.py) if a raw message is provided
3. Validate against the segment reference in [segment-reference.md](segment-reference.md)
4. Check for common errors listed in [common-errors.md](common-errors.md)
5. Report findings

## Validation Checks

- Required segments present (MSH, PID, OBR, OBX minimum)
- Segment ordering follows standard
- OBX data types match LOINC-specified types
- OBR universal service IDs are valid
- PID demographics are properly mapped
- Result status codes are correct (F = Final, P = Preliminary, C = Correction)

## Output Format

### Valid Configuration
Summary: [PASS/FAIL]
Segments found: [list]
Issues: [list or "None"]

### Issues Found
| Segment | Field | Issue | Expected | Found |
|---|---|---|---|---|
Click to copy

Part 14: Quick Reference (5 min)

Cheat Sheet

Directory Summary

~/.claude/
└── skills/                     # Personal Skills (all projects)
    ├── code-reviewer/
    │   └── SKILL.md
    └── commit-helper/
        └── SKILL.md

your-project/
└── .claude/
    └── skills/                 # Project Skills (this repo, shared)
        ├── deploy/
        │   ├── SKILL.md
        │   ├── checklist.md
        │   └── scripts/
        │       └── validate.sh
        └── doc-generator/
            ├── SKILL.md
            ├── style-guide.md
            ├── templates/
            │   └── api-reference.md
            └── examples/
                └── sample.md
Click to copy

Frontmatter Reference

---
name: skill-name              # Required. Lowercase, hyphens, max 64 chars
description: What and when     # Required. Max 1024 chars. Be specific.
allowed-tools: Read, Grep      # Optional. Restricts available tools.
---
Click to copy

Part 15: What to Do Next (5 min)

Start Small

Week 1:

• Pick one workflow you do repeatedly that involves more than a simple prompt
• Create a Skill with just a SKILL.md (no supporting files yet)
• Test auto-invocation by asking questions that match the description
• Refine the description until Claude consistently activates it

Week 2:

• Add supporting files: a reference doc, a template, or an example
• Reference them from SKILL.md so Claude knows when to load them
• Test that progressive disclosure works (Claude loads files only when needed)

Week 3:

• Add a script to one of your Skills for validation, extraction, or formatting
• Share a project Skill with your team via git
• Browse the Anthropic skills repo for inspiration: https://github.com/anthropics/skills

Week 4+:

• Build domain-specific Skills for your most complex workflows
• Experiment with allowed-tools for read-only audit Skills
• Iterate on descriptions based on how consistently Claude triggers them
• Check /context to make sure your Skill library isn't exceeding the character budget

The Compounding Effect

Skills get better over time. As you refine instructions, add examples, and improve descriptions, the quality of Claude's output improves across every future interaction. A well-built Skill is a permanent upgrade to your workflow.

Resources

• Claude Code Skills Docs: https://code.claude.com/docs/en/skills
• Agent Skills Overview: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
• Authoring Best Practices: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices
• Anthropic Skills Repository: https://github.com/anthropics/skills
• Engineering Blog (Architecture Deep Dive): https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• Slash Commands Tutorial: /tutorials/claude-code-slash-commands