gh-bbrowning-bbrowning-claude-marketplace-bbrowning-claude/skills/skill-builder/reference/skill-structure.md

Skill Structure Reference

Complete guide to organizing and structuring Claude Code skills for maximum effectiveness.

Directory Locations

Skills can be placed in three locations:

Personal Skills

• Location: ~/.claude/skills/
• Scope: Available across all projects for the user
• Use case: Personal utilities, workflows, preferences

Project Skills

• Location: .claude/skills/
• Scope: Project-specific, shared via version control
• Use case: Team workflows, project conventions, tooling

Plugin Skills

• Location: Within plugin skills/ directory
• Scope: Bundled with plugin, shareable via plugin marketplace
• Use case: Reusable capabilities for distribution

Required Structure

Minimum Viable Skill

my-skill/
└── SKILL.md

The only required file is SKILL.md with YAML frontmatter:

---
name: Skill Name
description: One-line description of what this skill does
---

# Skill content and instructions

Frontmatter Fields

Required

• name: Human-readable name (max 64 characters)

  • Use gerund form: "Processing", "Analyzing", "Creating"
  • Be specific, avoid vague terms

• description: One-line explanation (max 1024 characters)

  • Third person: "Guides...", "Helps...", "Provides..."
  • Include key terms for discoverability
  • Specify when to use this skill

Optional

• allowed-tools: Array of tool names to restrict access

  allowed-tools: [Read, Grep, Glob, Bash]
  

  • Use for safety-critical operations
  • Use for read-only analysis
  • Omit to allow all tools

Progressive Disclosure Structure

For complex skills, organize supporting materials:

my-skill/
├── SKILL.md              # Entry point (concise)
├── reference/            # Detailed documentation
│   ├── concepts.md       # Background information
│   ├── api-reference.md  # API/interface details
│   └── examples.md       # Extended examples
├── scripts/              # Utility scripts
│   ├── validator.py      # Validation logic
│   └── formatter.sh      # Formatting helper
└── templates/            # Starter templates
    ├── output.json       # Expected output format
    └── config.yaml       # Configuration template

When to Use Each Directory

reference/

Use for detailed documentation that supports SKILL.md:

• Comprehensive API documentation
• Extended conceptual explanations
• Additional examples and use cases
• Specification documents
• Background context

Pattern: Reference from SKILL.md with phrases like:

• "For detailed API documentation, see reference/api-reference.md"
• "See reference/examples.md for more examples"

scripts/

Use for executable utilities that perform deterministic operations:

• Data validation
• Format conversion
• File processing
• API calls
• System operations

Best practices:

• Handle errors explicitly
• Provide clear output/error messages
• Make scripts idempotent when possible
• Document script usage in SKILL.md or reference files
• Make scripts executable: chmod +x scripts/script.py
• Include proper shebang: #!/usr/bin/env python3

Referencing scripts in SKILL.md:

• Use relative paths from SKILL.md location: [script.py](scripts/script.py)
• Use standard Markdown link syntax for Claude to reference
• In bash code blocks, use full absolute paths for execution examples
• NO special @ syntax needed

Example in SKILL.md:

### compare_runs.py

Run [scripts/compare_runs.py](scripts/compare_runs.py) to compare test results:

```bash
.claude/skills/bfcl-results/scripts/compare_runs.py baseline/ modified/ test_name

#### `templates/`
Use for starter files and examples:
- Output format examples
- Configuration templates
- Code scaffolding
- Document structures

**Pattern**: Reference in instructions:
- "Use `templates/output.json` as the output format"
- "Start with `templates/component.tsx` structure"

## File Organization Patterns

### Pattern 1: Simple Focused Skill
Best for single-purpose, straightforward skills:

focused-skill/ └── SKILL.md

All instructions in one concise file.

### Pattern 2: Documented Skill
For skills needing additional context:

documented-skill/ ├── SKILL.md └── reference/ └── details.md

Core instructions in SKILL.md, extended details in reference.

### Pattern 3: Scripted Skill
For skills with deterministic operations:

scripted-skill/ ├── SKILL.md └── scripts/ ├── process.py └── validate.sh

Instructions in SKILL.md, automation in scripts.

### Pattern 4: Complete Skill
For comprehensive, production-ready skills:

complete-skill/ ├── SKILL.md ├── reference/ │ ├── concepts.md │ ├── api-docs.md │ └── examples.md ├── scripts/ │ ├── validator.py │ └── helper.sh └── templates/ └── output.json

Full progressive disclosure with all supporting materials.

## Content Organization in SKILL.md

### Recommended Structure

```markdown
---
name: Skill Name
description: Clear, specific description
---

# Skill Name

Brief introduction explaining what this skill does.

## Core Concepts
Essential background (if needed, otherwise move to reference/)

## Instructions
Step-by-step guidance or workflow

## Examples
2-3 concrete examples showing usage

## Validation
How to verify success or check results

## References
- `reference/file.md`: Description of what's there
- `scripts/script.py`: What the script does

Content Guidelines

Keep in SKILL.md:

• Essential instructions
• Core workflow steps
• Key examples
• Critical constraints
• References to additional files

Move to reference files:

• Extensive background
• Comprehensive API docs
• Many examples
• Edge cases and variations
• Historical context

Tool Restrictions

Control which tools Claude can use within the skill:

Syntax

---
name: Skill Name
description: Description here
allowed-tools: [ToolName1, ToolName2]
---

Common Tool Sets

Read-Only Analysis

allowed-tools: [Read, Grep, Glob]

File Operations

allowed-tools: [Read, Write, Edit, Glob, Grep]

Development Tasks

allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]

Script Execution Only

allowed-tools: [Bash]

When to Restrict Tools

Restrict tools when:

• Safety is critical (prevent unintended changes)
• Skill is analysis-only (no modifications needed)
• Enforcing specific workflow (must use provided scripts)
• Testing or validation (read-only verification)

Naming Conventions

Skill Directory Names

• Use kebab-case: my-skill-name
• Be descriptive: react-component-generator not helper
• Indicate purpose: pdf-invoice-processor

File Naming

• SKILL.md: Always uppercase, always this name
• Reference files: Descriptive, kebab-case: api-reference.md
• Scripts: Descriptive, indicate function: validate-output.py
• Templates: Indicate what they template: component-template.tsx

Name Field (in frontmatter)

• Use gerund form: "Processing PDFs"
• Title case: "Creating React Components"
• Specific and descriptive

Size Guidelines

SKILL.md

• Target: 200-400 lines
• Maximum: 500 lines
• If approaching max, move content to reference files

Reference Files

• Keep focused on one topic per file
• Split large references into multiple files
• No hard limit, but stay organized

Scripts

• One responsibility per script
• Document usage at top of file
• Keep maintainable

Version Control

What to Include

• All skill files (SKILL.md, reference, scripts, templates)
• README.md explaining the skill (optional but helpful)
• Tests for scripts (if applicable)

What to Exclude

• Generated outputs
• User-specific configurations
• Temporary files
• Cache files

Git Best Practices

# In skill directory
*.pyc
__pycache__/
.DS_Store
*.tmp
cache/

Testing Your Structure

Verify your skill structure:

1. Completeness: SKILL.md exists with required frontmatter
2. Clarity: Name and description are specific
3. Organization: Supporting files are logically organized
4. References: All file references in SKILL.md are valid
5. Scripts: All scripts are executable and documented
6. Size: SKILL.md is under 500 lines

Migration Patterns

From Monolithic to Progressive

If SKILL.md is too large:

1. Identify sections that could be separate files
2. Create reference directory
3. Move sections to focused reference files
4. Update SKILL.md with references
5. Keep core workflow in SKILL.md

Example:

# Before (in SKILL.md)
## API Documentation
[50 lines of API details]

# After (in SKILL.md)
## API Documentation
See `reference/api-reference.md` for complete API documentation.

From Simple to Scripted

Adding automation:

1. Identify deterministic operations
2. Create scripts directory
3. Implement operations in scripts
4. Update SKILL.md to reference scripts
5. Add error handling to scripts

Example:

# Before
Validate the output format matches the expected schema.

# After
Run `scripts/validate-output.py` to verify the output format.

Advanced Patterns

Multi-Language Scripts

skill/
├── SKILL.md
└── scripts/
    ├── process.py      # Python for data processing
    ├── validate.sh     # Bash for quick checks
    └── analyze.js      # Node for JSON operations

Conditional References

For basic usage, follow the instructions above.

For advanced scenarios, see:
- `reference/advanced-patterns.md`: Complex workflows
- `reference/error-handling.md`: Troubleshooting guide

Shared Resources

skills/
├── skill-one/
│   └── SKILL.md
├── skill-two/
│   └── SKILL.md
└── shared/
    ├── common-scripts/
    └── common-templates/

Reference shared resources with relative paths:

Use `../shared/common-templates/output.json` as the format.

Key Takeaways

1. Only SKILL.md is required
2. Use progressive disclosure for complex skills
3. Keep SKILL.md under 500 lines
4. Organize supporting files logically
5. Reference additional files clearly
6. Use scripts for deterministic operations
7. Restrict tools when appropriate
8. Follow naming conventions consistently
9. Test structure before distributing
10. Evolve structure as skill complexity grows