Skill Creator Plus

Skill Creator+

Design and review reusable skills that trigger reliably and stay lean.

Decision Flow

Start by deciding whether the user really needs a skill.

If the answer is not Skill, stop and create the right primitive instead.

上表は「skill にすべきか」の即時ゲート。primitive 選択の詳細 SSOT は agentic-workflow-guide skill。

→ [references/customization-primitives.md](references/customization-primitives.md) for the full selection guide

When to Use

• Create skill, /create-skill, new skill, review skill, fix skill trigger, SKILL.md, workflow, スキル作成
• Creating a new skill from scratch
• Extracting a repeated workflow from a conversation, incident, or checklist
• Updating or refactoring an existing skill
• Reviewing existing SKILL.md files
• Deciding whether a customization should be a skill before authoring it

Start Here

1. Extract the workflow you want to package. 2. Clarify only the missing dimensions: target outcome, personal vs workspace scope, checklist vs full workflow. 3. Draft the smallest useful SKILL.md, then move detail into references.

Core Principles

Default assumption: Claude is already very smart. Challenge each piece: "Does this justify its token cost?"

Before adding a new section, ask whether it can replace an existing rule, move to references/, or be dropped as session-specific.

Skill Structure

→ [references/skill-structure.md](references/skill-structure.md) for locations, frontmatter, and bundled resource rules

skill-name/
├── SKILL.md (required)        # Lean overview + decision points
├── scripts/                   # Deterministic helpers
├── references/                # Load on demand
└── assets/                    # Templates and reusable outputs

→ See skill-structure.md > What NOT to Include for excluded files.

Creation Process

→ [references/creation-process.md](references/creation-process.md) for the end-to-end workflow

Clarify if Needed

• What outcome should this skill produce?
• Should it live in workspace scope or personal scope?
• Is a short checklist enough, or does it need a full multi-step workflow?

Refactor Order

When improving an existing skill, use this order:

1. Delete stale or low-value guidance 2. Merge duplicate rules 3. Move long detail to references/ 4. Add genuinely missing guidance last

Frontmatter and Triggering

Use the smallest viable frontmatter: name, description, and only behavior-changing optional fields. name must match the folder and description must include trigger conditions.

Frontmatter details and silent failures: references/common-pitfalls.md

SKILL.md Guidelines

Keep SKILL.md lean: <150 lines is good, >300 lines must split to references. Start When to Use with user phrases, keep essential workflow only, and push long examples / schemas / recipes to references.

Detailed review criteria: references/skill-review-checklist.md

Iteration Loop

1. Draft the skill and save it. 2. Identify the weakest or most ambiguous parts. 3. Tighten those parts, then summarize what the skill produces and example prompts to try.

Review Checklist

Use references/skill-review-checklist.md. For bloat review, use references/skill-bloat-review.md.

Key References

Done Criteria

• [ ] Request is confirmed to be a skill, not another primitive
• [ ] Scope is decided before file creation
• [ ] SKILL.md created and under 150 lines
• [ ] Frontmatter has name + description with trigger conditions
• [ ] Manually used skills have argument-hint
• [ ] user-invocable is set intentionally
• [ ] Optional fields are added only when they change behavior
• [ ] Details moved to references/ (Progressive Disclosure)
• [ ] Review checklist passed

Common Pitfalls

These issues often cause silent failures or poor skill routing.

Discovery and Triggering

Weak Description

Bad descriptions explain what the skill is, but not when it should trigger.

description: "Helpful skill for productivity"

Prefer explicit trigger phrases and task context.

description: "Create and review Agent Skills. Use when creating a new skill, updating SKILL.md, or fixing weak skill triggers."

Missing User Phrases

Add phrases users actually say: file names, verbs, and common shorthand.

• SKILL.md
• create skill
• review skill
• domain-specific phrases

Method-First Names

Skill names that foreground an implementation detail (tool, input format, intermediate artifact) make slash commands harder to find and reuse. Lead with the user-visible task or outcome; keep techniques in description and ## When to Use.

Example: review-security-structure for a security review skill — mention AST, structure maps, call graphs, Source/Sink in description only.

YAML and Frontmatter

Unquoted Colons

Descriptions containing colons can break YAML if left unquoted.

description: "Use when: reviewing skills"

Name Mismatch

name must match the folder name exactly. A mismatch breaks discovery.

Boilerplate Optional Fields

Do not add argument-hint, user-invocable, or disable-model-invocation unless they change behavior.

Accidental Prompt Tool Restrictions

In VS Code prompt files, tools: is not harmless metadata. It overrides the default agent's enabled tools for that prompt run and can appear in the tools picker as a current-session-only configuration.

Use tools: in *.prompt.md only when the prompt must deliberately narrow capabilities. If the prompt should inherit the user's normal Agent tools, omit tools: entirely.

Prefer custom agents for stable role/tool boundaries. Use prompt-level tools: only for narrow slash commands where losing unrelated built-in, extension, or MCP tools is intentional.

Structure Problems

Monolithic SKILL.md

If the body grows past the quick-start workflow, move details into references/.

Wrong Primitive

If the content spends most of its space describing prompts, instructions, agents, or hooks, you may be designing the wrong asset.

→ Re-check customization-primitives.md

Deep or Brittle Links

Use relative links and keep referenced files shallow and predictable.

Good:

• [references/creation-process.md](creation-process.md) from inside references/
• [references/creation-process.md](references/creation-process.md) from SKILL.md

Avoid absolute paths or workspace-specific locations.

Brittle Evaluation Assets

Eval files, graders, or review prompts can silently rot when they depend on one recorded session.

Avoid:

• temporary workspace paths
• machine-specific absolute paths
• long exact-string output assertions that encode one specific run

Prefer:

• headings or schema checks
• tool-usage checks
• stable identifiers such as file basenames or declared section names

Review Smells

• The description cannot be understood without reading the whole body.
• The skill includes README-like marketing content.
• The workflow has no validation step.
• The skill cannot explain why it is a skill instead of a prompt or agent.
• Example triggers are missing from both description and ## When to Use.
• Eval assets only pass for one captured session and break after simple renames.

Skill Creation Process

Detailed guide for each step of skill creation.

Overview

0. Route by skill archetype 1. Understand the skill with concrete examples 2. Plan reusable skill contents (scripts, references, assets) 3. Initialize the skill (run init_skill.py) 4. Edit the skill (implement resources and write SKILL.md) 5. Package the skill (run package_skill.py) 6. Iterate based on real usage

Step 0: Route by Skill Archetype

Before writing, check whether the skill fits one primary category. Skills that straddle several categories often become confusing.

If the candidate does not fit one category, split it or choose another primitive before adding scope.

Source inspiration: Anthropic, "Lessons from building Claude Code: how we use skills" - https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

Step 1: Understanding with Concrete Examples

To create an effective skill, clearly understand concrete examples of how the skill will be used.

Questions to ask:

• "What functionality should this skill support?"
• "Can you give some examples of how this skill would be used?"
• "What would a user say that should trigger this skill?"

Tip: Avoid asking too many questions in a single message. Start with the most important questions.

Step 2: Planning Reusable Contents

Analyze each example by:

1. Considering how to execute from scratch 2. Identifying helpful scripts, references, and assets 3. Capturing the non-obvious gotchas that caused past failures 4. Deciding how the skill will verify success, especially for UI, CLI, deployment, or data workflows

Examples:

Prefer code or structured files when they reduce repeated reasoning:

• scripts/ for deterministic steps, assertions, or reusable fetch helpers
• references/ for gotchas, schemas, command maps, and usage patterns
• assets/ for templates, starter files, or reusable output shapes
• config.json when the skill needs user-specific setup such as channels, environments, or default destinations
• append-only logs when previous runs are part of the workflow contract, such as standups or recurring reports
• named skill dependencies only when another installed skill owns a separate responsibility; include a fallback if it may be missing

Step 3: Initializing the Skill

Run init_skill.py for new skills:

scripts/init_skill.py <skill-name> --path <output-directory>

The script:

• Creates the skill directory
• Generates SKILL.md template with frontmatter
• Creates example scripts/, references/, assets/ directories

Step 4: Edit the Skill

Design Patterns

Consult these guides:

• Multi-step processes: See workflows.md
• Output formats: See output-patterns.md

Implement Resources

1. Start with scripts, references, assets identified in Step 2 2. Test scripts by running them 3. Delete unused example files

Write SKILL.md

Frontmatter:

---
name: skill-name
description: "What it does. Use when [trigger conditions]."
---

Body: Write instructions using imperative/infinitive form.

Step 5: Packaging

scripts/package_skill.py <path/to/skill-folder>
# Optional: specify output directory
scripts/package_skill.py <path/to/skill-folder> ./dist

The script:

1. Validates - YAML format, naming, structure, description quality 2. Packages - Creates .skill file (zip with .skill extension)

Step 6: Iterate

Iteration workflow:

1. Use the skill on real tasks 2. Notice struggles or inefficiencies 3. Identify needed updates 4. Implement changes and test again

When updating, prefer adding one precise gotcha or one verification helper over broad reminders. The strongest skill updates usually come from observed misses, not generic best practices.

For skills where routing quality matters, optionally track lightweight usage signals:

• manual invocation vs model-triggered invocation
• expected-but-not-triggered cases
• success, fallback, or abandoned outcome
• description or ## When to Use phrase that needs adjustment

Keep logs append-only and minimal. Do not store full prompts, secrets, personal data, customer data, or machine-specific paths.

Customization Primitive Selection

Choose the right customization primitive before creating files.

Decision Matrix

Questions to Ask First

1. Is this guidance needed in most conversations, or only for a specific task? 2. Does the user need a reusable slash command, or always-on behavior? 3. Does the solution need bundled scripts, templates, or detailed references? 4. Is persona or tool restriction the core requirement? 5. Must the behavior be enforced deterministically?

Scope Selection

Choose scope before creating the file.

Default to workspace only when the behavior should be shared through version control.

Fast Rules of Thumb

• If the request starts with "always", it is usually an instruction.
• If the request starts with "when I type /", it is usually a prompt or skill.
• If the request needs scripts, templates, or structured references, lean toward a skill.
• If the request is about a specialist persona or safe tool boundaries, lean toward a custom agent.
• If a prompt only lists tools to make them available, remove tools:. Prompt-level tools: narrows availability; it does not request tools opportunistically.
• If the request is about blocking commands or auto-running checks, use a hook.
• Treat prompts, templates, quick actions, and canned responses as product surfaces: define grounding source, prohibited actions, output format, and unknown-handling before adding examples or tone guidance.

Escalation Pattern

If you discover mid-design that the file type is wrong:

1. Stop editing the wrong primitive. 2. Explain the mismatch briefly. 3. Create or update the correct primitive. 4. Leave a short note in the related asset if cross-linking helps future maintenance.

Output Patterns

Use these patterns when skills need to produce consistent, high-quality output.

Template Pattern

Provide templates for output format. Match the level of strictness to your needs.

For strict requirements (like API responses or data formats):

## Report structure

ALWAYS use this exact template structure:

# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation

For flexible guidance (when adaptation is useful):

## Report structure

Here is a sensible default format, but use your best judgment:

# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]

## Recommendations
[Tailor to the specific context]

Adjust sections as needed for the specific analysis type.

Examples Pattern

For skills where output quality depends on seeing examples, provide input/output pairs:

## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:

fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation

Follow this style: type(scope): brief description, then detailed explanation.

Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.

Skill Bloat Review

Checklist for deciding whether a SKILL is growing by useful depth or by append-only accumulation.

Review Order

Use this order every time:

1. Delete 2. Merge 3. Move to references 4. Add only what is still missing

Triage Buckets

Delete Candidates

• Stale guidance tied to old tool names or workflows
• Repeated best practices already stated elsewhere in the same SKILL
• Session-specific notes that are not reusable
• Long examples that do not change behavior

Merge Candidates

• Two sections expressing the same rule with different wording
• Separate tables that should be one decision table
• Repeated warnings that belong under one principle
• Multiple mini-checklists that can become one review gate

Move Candidates

• Sections longer than roughly 40-50 lines
• Large examples, schemas, command catalogs, or recipes
• Long external link lists
• Markdown-linked catalogs inside always-loaded entry files such as copilot-instructions.md or AGENTS.md
• Variant-specific guidance that not every invocation needs
• Repo-global instruction files that started absorbing domain-specific workflow detail

Add Candidates

• Missing trigger guidance that affects discoverability
• A new decision point users repeatedly get wrong
• A reusable rule that cannot fit cleanly into existing sections
• A reference file that reduces main-file token cost

Bloat Signals

• New sections are appended without rewriting old ones
• The same concept appears in three or more places
• Main SKILL reads like a knowledge dump instead of an operating guide
• References exist, but detail still stays inline in SKILL.md
• Line count grows while the core workflow becomes harder to find
• A workspace entry file such as copilot-instructions.md starts acting like a full operations manual
• Persona rules, routing rules, and domain workflow rules are mixed in one always-loaded file
• An always-loaded entry file becomes a Markdown-linked directory of rules, agents, or docs

Keep vs Move

Entry File Note

For always-loaded entry files such as copilot-instructions.md and AGENTS.md, a short body is not enough.

• If the file becomes a Markdown-linked index, treat it as bloat even when line count still looks reasonable
• Prefer a one-line pointer to instructions/, README, or docs over a linked catalog in the entry file

Decision Questions

• Can this replace an old sentence instead of adding a new paragraph?
• Is this needed on every invocation, or only sometimes?
• Does this teach the operating shape of the skill, or just document background detail?
• If this were removed from the main file, would the skill still route and operate correctly?

Done Criteria

• Main SKILL still exposes the routing surface clearly
• Core workflow is visible without scrolling through recipes
• Duplicate rules are merged into one place
• Deep detail is loaded on demand via references
• New additions were made only after delete/merge/move was considered

SKILL.md Review Checklist

Checklist for reviewing and improving SKILL.md files.

Quick Check (5 items)

- [ ] SKILL.md is under 150 lines? (GitHub guideline: "2 pages or less")
- [ ] Frontmatter has name + description?
- [ ] Self-authored skills have license + metadata.author?
- [ ] Description clearly states WHEN to use (trigger conditions)?
- [ ] Detailed content moved to references/ (Progressive Disclosure)?
- [ ] Self-contained? Knowledge is bundled, not just linked to workspace files that break when copied elsewhere?
- [ ] No README.md or auxiliary docs in skill folder?
- [ ] The skill fits one primary archetype, or the split is intentional?
- [ ] Non-obvious gotchas are captured where they affect correctness?
- [ ] Success can be verified by scripts, assertions, artifacts, or explicit checks?

Size & Structure

Line Count Target

Source: GitHub Docs - Adding repository custom instructions

"Instructions must be no longer than 2 pages."

Progressive Disclosure

→ See skill-structure.md > Progressive Disclosure for the 3-level loading system.

Pattern: Keep SKILL.md lean, move details to references.

❌ Bad: 400-line SKILL.md with all details inline
✅ Good: 120-line SKILL.md + references/detailed-guide.md

Content Quality

Skill Archetype Fit

Before reviewing wording, identify the primary kind of skill:

• Library / API reference
• Product verification
• Data fetching / analysis
• Business process automation
• Code scaffolding / templates
• Code quality / review
• CI/CD / deployment
• Runbook / debugging
• Infrastructure operations

If it claims several at once, split it or move secondary behavior into references. A skill can depend on another skill, but its own responsibility should stay crisp.

Frontmatter

---
name: skill-name # Required
description: "..." # Required - include trigger conditions
license: CC BY-NC-SA 4.0 # Required for self-authored skills
metadata: # Required for self-authored skills
  author: yamapan (https://github.com/aktsmm)
---

Description must answer:

• What does this skill do?
• When should it be triggered?

Body Structure

What NOT to Include

→ See skill-structure.md > What NOT to Include for the complete list.

Gotchas and Verification

High-signal skill content is usually specific failure avoidance, not obvious process narration.

Check for:

• common field-name mismatches, API quirks, stale state, or misleading success responses
• verification steps that inspect real state, not just command exit codes
• scripts or assertions for fragile workflows such as UI flows, deployments, data pulls, or interactive CLIs
• setup state such as config.json when a missing channel, environment, or destination should trigger a user question

References Organization

When to Create references/

Naming Convention

references/
├── {topic}.md           # General pattern
├── {variant-name}.md    # For variants (aws.md, gcp.md)
├── examples/            # Example files
└── schemas/             # Schema definitions

Common Issues

Issue 1: SKILL.md Too Long

Symptoms: > 300 lines, scrolling required to find key info

Fix:

1. Identify sections > 50 lines 2. Create references/{section-name}.md 3. Replace with summary + link: → See [references/{name}.md](references/{name}.md)

Issue 2: Vague Description

Symptoms: Description says what skill does, not when to use it

Bad:

description: "Processes PDF files"

Good:

description: "Extract text, rotate pages, and fill forms in PDF files. Use when working with .pdf documents for text extraction, page manipulation, or form automation."

Issue 3: Duplicate Content

Symptoms: Same information in SKILL.md and references/

Fix: Information should live in ONE place only. Keep procedural instructions in SKILL.md, move detailed reference material to references/.

Issue 4: Missing Trigger Conditions

Symptoms: Skill doesn't activate when expected

Fix: Add specific triggers to description:

• File patterns (.pdf, .agent.md)
• Task keywords ("extract text", "rotate page")
• Context conditions ("when working with...")

Issue 5: Obvious Guidance Without Gotchas

Symptoms: The skill says what any capable agent would already do, but omits the edge cases that caused past failures.

Fix: Replace generic advice with specific gotchas, verification checks, or reusable scripts.

Good examples:

• "A UI success banner can appear before backend processing finishes; verify the persisted state."
• "Two systems expose similar request identifiers; document the canonical join key."
• "Append-only history tables need an explicit rule for choosing the active row."

Review Template

## SKILL.md Review: {skill-name}

### Metrics

- [ ] Line count: \_\_\_ (target: < 150)
- [ ] Frontmatter valid: Yes/No
- [ ] Description has triggers: Yes/No
- [ ] Primary archetype: **\_\_**

### Structure

- [ ] Progressive disclosure applied
- [ ] No auxiliary docs (README, CHANGELOG)
- [ ] References properly linked

### Content

- [ ] Single responsibility (SRP)
- [ ] No duplicate information
- [ ] Examples minimal but sufficient
- [ ] Gotchas are specific and actionable
- [ ] Verification path is explicit

### Action Items

1. ...
2. ...

Skill Structure Gallery

Use this gallery when /create-skill needs concrete structure ideas, not just abstract rules.

Do not cargo-cult entire files. Copy the smallest pattern that removes ambiguity.

Pattern 1: Signal Detection Matrix

Inspired by skills that review content against known tells.

Use when:

• The skill scans for repeated signals, smells, or rule violations
• Each detection should map cleanly to a recommended action
• A long prose list would hide the difference between "detect" and "fix"

Recommended shape:

Why it works:

• Compresses many heuristics into a searchable table
• Keeps detection logic and remediation aligned
• Makes reviews more consistent across languages or formats

Avoid when:

• There are fewer than 5 rules
• The output is procedural rather than evaluative

Pattern 2: Mode Selection Table

Inspired by skills that support multiple execution modes or setup paths.

Use when:

• The user must choose between 2 or more viable modes
• Trade-offs matter more than linear steps
• Setup differs by environment, browser, provider, or transport

Recommended shape:

Why it works:

• Surfaces the decision before the workflow branches
• Prevents hidden assumptions about the default path
• Gives /create-skill a compact way to encode trade-offs

Avoid when:

• There is a single recommended path with no real branching

Pattern 3: Output Pair and Variant Naming

Inspired by skills that produce both editable and publishable artifacts.

Use when:

• One task creates multiple deliverables that must stay aligned
• The user needs both source and rendered output
• Language or format variants must coexist without overwrite risk

Recommended shape:

name.ext           # editable or source artifact
name-rendered.ext  # publishable artifact
name-ja.ext        # language variant
name-en.ext        # language variant

Add a short rule block:

• Keep editable and publishable outputs as a pair
• Prefer parallel filenames over overwriting one artifact
• Name variants predictably so downstream docs can link them safely

Why it works:

• Makes the deliverable contract explicit
• Reduces drift between source and rendered assets
• Gives reviews a simple naming baseline

Avoid when:

• The task only creates one disposable output

Pattern 4: Quality Gates and Score Bands

Inspired by skills that need objective retry or escalation rules.

Use when:

• The workflow has review/retry loops
• "Good enough" must be defined before execution
• The agent should know when to proceed, retry, simplify, or ask

Recommended shape:

Why it works:

• Turns vague quality judgment into a stop condition
• Prevents endless refinement loops
• Helps /create-skill encode escalation behavior in one table

Avoid when:

• Quality is binary and easy to verify with a checklist alone

Pattern 5: Architecture Sketch and Naming Taxonomy

Inspired by skills that transform files through several stages.

Use when:

• The skill moves data across multiple steps or folders
• Naming rules are part of the workflow contract
• The user needs to understand where ambiguous items land

Recommended shape:

Input
  -> Normalize
  -> Classify
  -> Rename
  -> Output
  -> Fallback / quarantine branch

Then pair it with a naming block:

YYYY-MM-DD-type-subject.ext

And, if needed, a taxonomy table:

Why it works:

- Explains the pipeline faster than long prose
- Makes edge cases visible, especially fallback paths
- Gives naming conventions a place near the workflow they support

Avoid when:

- The task is a simple one-shot transformation

## Quick Selection Guide

| If the skill needs... | Start with... |
| --------------------- | ------------- |
| Repeated review signals | Signal Detection Matrix |
| A user-facing branch choice | Mode Selection Table |
| Multiple coordinated deliverables | Output Pair and Variant Naming |
| Retry thresholds or escalation | Quality Gates and Score Bands |
| A multi-stage file/data pipeline | Architecture Sketch and Naming Taxonomy |

Use one or two patterns first. If the structure starts looking like a dashboard, the skill is probably over-designed.

Skill Structure

Detailed guide for skill anatomy, bundled resources, and progressive disclosure patterns.

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts)

SKILL.md Structure

Every SKILL.md consists of:

• Frontmatter (YAML): Contains name and description fields. These are the only fields Claude reads to determine when the skill gets used.
• Body (Markdown): Instructions and guidance. Only loaded AFTER the skill triggers.

Bundled Resources

Scripts (scripts/)

Executable code for tasks requiring deterministic reliability or repeatedly rewritten.

• When to include: Same code rewritten repeatedly or deterministic reliability needed
• Examples: scripts/rotate_pdf.py for PDF rotation tasks; scripts/verify_flow.py for state assertions after UI or CLI workflows
• Benefits: Token efficient, deterministic, executed without loading into context

References (references/)

Documentation loaded as needed into context.

• When to include: Documentation Claude should reference while working
• Examples: references/schema.md, references/api_docs.md
• Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
• Avoid duplication: Information should live in ONE place only

Assets (assets/)

Files used in output, not loaded into context.

• When to include: Files used in final output
• Examples: assets/logo.png, assets/template.pptx
• Use cases: Templates, images, icons, boilerplate code

Config and Local State

Use structured state only when it is part of the workflow contract.

• Config: config.json for user-specific defaults such as channels, environments, output folders, or deployment targets
• Run logs: append-only logs for recurring workflows that need delta-only output or previous-run awareness
• Avoid: secrets, personal data, machine-specific absolute paths, and session transcripts

If config is missing, the skill should ask only for the missing setup value and then continue.

What NOT to Include

Do NOT create extraneous documentation:

• ❌ README.md
• ❌ INSTALLATION_GUIDE.md
• ❌ CHANGELOG.md
• ❌ QUICK_REFERENCE.md

Progressive Disclosure

Skills use a three-level loading system:

Pattern 1: High-level guide with references

# PDF Processing

## Quick start

Extract text with pdfplumber: [code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)

Pattern 2: Domain-specific organization

bigquery-skill/
├── SKILL.md (overview)
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

When user asks about sales, Claude only reads sales.md.

Pattern 3: Variant-based organization

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Guidelines

• Avoid deeply nested references - Keep references one level deep from SKILL.md
• Structure longer files - For files > 100 lines, include TOC at top

Workflow Patterns

Sequential Workflows

For complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md:

Filling a PDF form involves these steps:

1. Analyze the form (run analyze_form.py)
2. Create field mapping (edit fields.json)
3. Validate mapping (run validate_fields.py)
4. Fill the form (run fill_form.py)
5. Verify output (run verify_output.py)

Conditional Workflows

For tasks with branching logic, guide Claude through decision points:

1. Determine the modification type:
   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow: [steps]
3. Editing workflow: [steps]