> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anthropics/skills/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
If test runs all independently create similar helper code, bundle it as a script
Operations requiring exact behavior (parsing, validation, formatting)
Tasks where native code is faster than Claude generating it each time
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:**
````markdown theme={null}
### Step 4: Grade, aggregate, and launch the viewer
1. Grade each run...
2. Aggregate into benchmark:
```bash
python -m scripts.aggregate_benchmark /iteration-N --skill-name
````
3. Launch the viewer:
```bash theme={null}
nohup python /eval-viewer/generate_review.py \
/iteration-N \
--skill-name "my-skill" \
--benchmark /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
Include all dependencies, error handling, and documentation within the script.
Use command-line arguments with `--help` documentation.
Scripts should handle edge cases - Claude won't fix bugs during execution.
Show exactly how to invoke each script with examples.
## 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:**
```markdown theme={null}
### 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
**Pattern:** One main reference file
```
references/
└── schemas.md
```
**Use when:** Single topic with comprehensive documentation
**Pattern:** One reference per domain/framework
```
references/
├── aws.md
├── gcp.md
└── azure.md
```
**Use when:** Supporting multiple platforms/frameworks
**SKILL.md guidance:**
```markdown theme={null}
Load the appropriate reference:
- AWS: Read `references/aws.md`
- GCP: Read `references/gcp.md`
- Azure: Read `references/azure.md`
```
**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
For files >300 lines, add a TOC at the top so Claude can navigate efficiently.
Structure content with markdown headings for easy scanning.
Each reference should be understandable on its own, not require reading other files.
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:**
```markdown theme={null}
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:**
```markdown theme={null}
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:
```mermaid theme={null}
graph TD
A[Need to extend skill?] -->|No| B[Just use SKILL.md]
A -->|Yes| C{What type of extension?}
C -->|Executable code| D[scripts/]
C -->|Documentation| E[references/]
C -->|Static files| F[assets/]
D --> G{When to execute?}
G -->|Every time| H[Bundle it]
G -->|Sometimes| H
G -->|Never same twice| I[Don't bundle, let Claude generate]
E --> J{How large?}
J -->|>300 lines| K[Definitely bundle]
J -->|<300 lines| L[Consider inline in SKILL.md]
F --> M{Used in outputs?}
M -->|Yes| N[Bundle it]
M -->|No| O[Don't bundle]
```
## Progressive Loading in Practice
Here's how skill-creator uses progressive loading:
**Level 1: Always in context (frontmatter)**
```yaml theme={null}
name: skill-creator
description: Create new skills, modify and improve existing skills...
```
**Level 2: Loaded when skill triggers (SKILL.md body)**
```markdown theme={null}
# 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
Learn how to write effective, maintainable skills
Review the overall anatomy of a skill