Bundled Resources

Using scripts, references, and assets directories to extend skill capabilities

Bundled Resources

Bundled resources extend skills beyond basic instructions by providing executable scripts, detailed reference documentation, and static assets. These resources are loaded only when needed, keeping context efficient.

Directory Structure

skill-name/
├── SKILL.md
├── scripts/      # Executable code
├── references/   # Documentation loaded on demand  
└── assets/       # Static files for outputs

All three directories are optional. Add them only when they provide clear value.

scripts/ Directory

The scripts/ directory contains executable code for deterministic or repetitive tasks.

When to Add Scripts

Repeated Work

If test runs all independently create similar helper code, bundle it as a script

Deterministic Tasks

Operations requiring exact behavior (parsing, validation, formatting)

Performance

Tasks where native code is faster than Claude generating it each time

Complexity

Multi-step operations with edge cases better handled in tested code

Real Example: skill-creator Scripts

The skill-creator skill includes 9 Python scripts:

scripts/
├── aggregate_benchmark.py   # Combine grading results into benchmark.json
├── generate_report.py        # Create HTML evaluation viewer
├── improve_description.py    # Optimize skill descriptions
├── package_skill.py          # Create .skill distribution files
├── quick_validate.py         # Validate skill structure
├── run_eval.py              # Execute evaluation queries
├── run_loop.py              # Run optimization iterations
├── utils.py                 # Shared utilities
└── __init__.py              # Python package marker

Usage in SKILL.md:

### Step 4: Grade, aggregate, and launch the viewer

1. Grade each run...

2. Aggregate into benchmark:
   ```bash
   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>

3. Launch the viewer:
   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   

Notice how scripts eliminate the need to regenerate complex code each time.

### Real Example: mcp-builder Scripts

The mcp-builder skill has simpler script needs:

scripts/ ├── run_eval.py # Run MCP server evaluations └── …

### Script Best Practices

<Steps>
  <Step title="Make Scripts Self-Contained">
    Include all dependencies, error handling, and documentation within the script.
  </Step>
  
  <Step title="Provide Clear Interfaces">
    Use command-line arguments with `--help` documentation.
  </Step>
  
  <Step title="Test Thoroughly">
    Scripts should handle edge cases - Claude won't fix bugs during execution.
  </Step>
  
  <Step title="Document in SKILL.md">
    Show exactly how to invoke each script with examples.
  </Step>
</Steps>

## references/ Directory

The `references/` directory contains detailed documentation loaded into context only when explicitly referenced.

### When to Use References

- **Large documentation** (>300 lines) that shouldn't always be in context
- **Domain-specific guides** for different frameworks or platforms
- **Technical specifications** needed for specific tasks
- **Schema definitions** for data formats

### Real Example: skill-creator References

The skill-creator skill uses references for schemas and agent instructions:

references/ └── schemas.md # JSON schemas for evals, grading, benchmarks

agents/ ├── grader.md # Grading subagent instructions ├── comparator.md # Comparison subagent instructions └── analyzer.md # Analysis subagent instructions

**schemas.md excerpt:**

```markdown
# JSON Schemas

This document defines the JSON schemas used by skill-creator.

## evals.json

Defines the evals for a skill. Located at `evals/evals.json`.

```json
{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's example prompt",
      "expected_output": "Description of expected result",
      "files": ["evals/files/sample1.pdf"]
    }
  ]
}

**Referenced in SKILL.md:**

```markdown
See `references/schemas.md` for the full schema (including the `assertions` field).

Real Example: mcp-builder References

The mcp-builder skill heavily uses references for different frameworks:

reference/
├── mcp_best_practices.md     # Universal MCP guidelines
├── node_mcp_server.md        # TypeScript patterns and examples
├── python_mcp_server.md      # Python patterns and examples
└── evaluation.md             # Evaluation creation guide

Referenced in SKILL.md:

### Core MCP Documentation (Load First)
- [📋 MCP Best Practices](./reference/mcp_best_practices.md)

### Language-Specific Implementation Guides (Load During Phase 2)
- [🐍 Python Implementation Guide](./reference/python_mcp_server.md)
- [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md)

### Evaluation Guide (Load During Phase 4)  
- [✅ Evaluation Guide](./reference/evaluation.md)

This pattern:

1. Keeps SKILL.md focused on workflow (237 lines)
2. Loads detailed guides only when needed
3. Supports multiple frameworks without bloating context

Reference Organization Patterns

Single Domain

Pattern: One main reference file

references/
└── schemas.md

Use when: Single topic with comprehensive documentation

Multiple Domains

Pattern: One reference per domain/framework

references/
├── aws.md
├── gcp.md
└── azure.md

Use when: Supporting multiple platforms/frameworks

SKILL.md guidance:

Load the appropriate reference:
- AWS: Read `references/aws.md`
- GCP: Read `references/gcp.md`  
- Azure: Read `references/azure.md`

Hierarchical Topics

Pattern: Organized subdirectories

reference/
├── core/
│   └── mcp_best_practices.md
├── languages/
│   ├── node_mcp_server.md
│   └── python_mcp_server.md
└── evaluation.md

Use when: Complex skill with natural topic hierarchy

Reference File Best Practices

1. Include Table of Contents

   For files >300 lines, add a TOC at the top so Claude can navigate efficiently.

2. Use Clear Headings

   Structure content with markdown headings for easy scanning.

3. Provide Context

   Each reference should be understandable on its own, not require reading other files.

4. Link from SKILL.md

   Always provide clear pointers: “Read references/schemas.md for the full schema”

assets/ Directory

The assets/ directory contains static files embedded in skill outputs: templates, images, fonts, etc.

When to Use Assets

• Templates - HTML, document, or presentation templates
• Images - Logos, icons, graphics for outputs
• Fonts - Custom typography files
• Data files - Configuration, lookup tables, example data

Real Example: skill-creator Assets

assets/
└── eval_review.html         # HTML template for evaluation viewer

Usage in SKILL.md:

Present the eval set to the user for review using the HTML template:

1. Read the template from `assets/eval_review.html`
2. Replace the placeholders:
   - `__EVAL_DATA_PLACEHOLDER__` → the JSON array
   - `__SKILL_NAME_PLACEHOLDER__` → the skill's name
   - `__SKILL_DESCRIPTION_PLACEHOLDER__` → current description
3. Write to a temp file and open it

Real Example: brand-guidelines Assets

While the brand-guidelines skill doesn’t currently have an assets/ directory, it could include:

assets/
├── fonts/
│   ├── Poppins-Regular.ttf
│   └── Lora-Regular.ttf
├── logos/
│   ├── anthropic-logo.svg
│   └── anthropic-logo.png
└── templates/
    ├── letterhead.docx
    └── presentation.pptx

Then reference in SKILL.md:

If custom fonts aren't system-installed, use the bundled fonts:
- Headings: `assets/fonts/Poppins-Regular.ttf`
- Body: `assets/fonts/Lora-Regular.ttf`

Asset Best Practices

File Sizes: Keep assets reasonable. A 50MB template defeats the purpose of progressive loading.

Portability: Use relative paths from the skill root: assets/logo.png, not absolute paths.

Licensing: Ensure you have rights to distribute any bundled assets.

Documentation: Explain in SKILL.md what each asset is and when to use it.

Deciding What to Bundle

Use this decision tree:

Progressive Loading in Practice

Here’s how skill-creator uses progressive loading:

Level 1: Always in context (frontmatter)

name: skill-creator
description: Create new skills, modify and improve existing skills...

Level 2: Loaded when skill triggers (SKILL.md body)

# Skill Creator

A skill for creating new skills and iteratively improving them.

## Creating a skill
...

Level 3: Loaded as needed

• references/schemas.md - Only when working with JSON structures
• agents/grader.md - Only when spawning grading subagent
• scripts/aggregate_benchmark.py - Executes without loading into context

Next Steps

Best Practices

Learn how to write effective, maintainable skills

Skill Structure

Review the overall anatomy of a skill