How to Bundle Scripts, References, and Assets for Claude Skills: A Complete Guide

Claude Skills are self-contained folders that include auxiliary files like helper scripts, document templates, and reference resources in dedicated sub-folders, automatically bundled when packaged according to the ComposioHQ/awesome-claude-skills repository conventions.

Properly bundling scripts, references, and assets for Claude skills requires following a specific folder structure that ensures self-containment and portability. The ComposioHQ/awesome-claude-skills repository defines the standard architecture where skills reside in isolated directories with dedicated sub-folders for auxiliary files. Understanding these bundling conventions is essential for creating skills that pass the official validator and function reliably when loaded by the Claude agent.

Claude Skill Architecture and Lazy Loading

Claude Skills operate as self-contained units that the agent loads on demand. At the root of every skill folder, the SKILL.md file serves as the entry point, containing YAML front-matter followed by full markdown instructions. When Claude loads a skill, it first reads only the front-matter—approximately 100 tokens—to understand the skill's name and description. The full body of SKILL.md and any auxiliary files are fetched only when the agent decides the skill is relevant, a behavior that keeps the agent's context window small while still allowing a skill to ship a rich set of assets.

The standard component layout includes:

• SKILL.md – Located at the root, contains YAML front-matter plus instructions.
• scripts/ – Holds executable helper scripts (Python, Bash, JS) that the skill calls during execution.
• templates/ – Stores document or code templates that the skill can render with variables.
• resources/ or references/ – Contains static assets such as PDFs, images, CSVs, and JSON files for lookup or processing.

Required Folder Structure for Bundling

To bundle scripts, references, and assets correctly, you must organize files into specific sub-directories within the skill folder. This structure ensures that the Claude agent can locate and execute auxiliary files when the skill is invoked.

The scripts/ Directory

The scripts/ directory houses executable helper scripts that extend the skill's functionality. Files placed here should have the executable bit set (chmod +x) if they need to be run directly by the agent via commands like !run. According to the source code in the skill-creator/SKILL.md template, this folder typically contains automation scripts written in Python, Bash, or JavaScript that perform specific tasks beyond the agent's native capabilities.

The templates/ Directory

The templates/ directory stores document or code templates that the skill can render dynamically. These files serve as blueprints that the agent populates with variables during execution. When bundling templates, ensure they are referenced using relative paths from the skill root within your SKILL.md instructions.

The resources/ and references/ Directories

Static assets that the skill requires for lookup or processing belong in either resources/ or references/. These folders accept PDFs, images, CSVs, JSON files, and other binary or text assets. The choice between resources/ and references/ depends on your organizational preference, as both function identically within the skill architecture outlined in the repository's README.md.

Bundling Rules and Conventions

The ComposioHQ/awesome-claude-skills repository enforces strict bundling rules through its official skill validator. Adhering to these conventions ensures your skill packages correctly and runs without errors.

Folder-relative Paths – All references inside SKILL.md must use paths relative to the skill root. Absolute paths will break when the skill is copied to different user environments.

Executable Permissions – Scripts that the agent executes directly must have executable permissions set. Use chmod +x scripts/your-script.py before packaging to ensure the agent can invoke them.

Self-containment – A skill must not rely on files outside its folder. Any third-party libraries required by scripts should be vendored within the skill directory or declared in dependency files like requirements.txt or package.json placed alongside the script.

Compression for Large Assets – For large binary assets such as images or PDFs, you can ship a .zip file inside resources/ and unzip it at runtime. Document the unzip step clearly in the skill instructions within SKILL.md.

Complete Example: Data Processing Skill

Below is a minimal, working skill that bundles a Python helper script and a CSV reference file, demonstrating the proper structure for the ComposioHQ/awesome-claude-skills ecosystem.

Folder Structure:

my-data-processor/
├── SKILL.md          # Main skill definition

├── scripts/
│   └── process.py    # Helper script

└── resources/
    └── lookup.csv    # Data file used by the script

SKILL.md:

---
name: data-processor
description: Processes a CSV with a custom Python script.
---

# Data Processor Skill

This skill runs a Python helper to transform a CSV file and returns the transformed data.

## Files

- `scripts/process.py` – the processing script.
- `resources/lookup.csv` – sample data used by the script.

## Instructions

1. Upload the CSV you want processed as `input.csv`.
2. Run the script:

   ```bash
   !run scripts/process.py input.csv resources/lookup.csv

The script will emit a new CSV to output.csv. 3. Return the contents of output.csv to the user.

Example

User uploads sales.csv → skill runs process.py → returns cleaned sales-clean.csv.

**[`scripts/process.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/scripts/process.py):**

```python
#!/usr/bin/env python3
import sys, csv

input_path, lookup_path = sys.argv[1], sys.argv[2]

# Simple example: add a column from lookup.csv

with open(lookup_path) as f:
    lookup = {row[0]: row[1] for row in csv.reader(f)}

with open(input_path, newline='') as src, open('output.csv', 'w', newline='') as dst:
    rdr = csv.reader(src)
    wtr = csv.writer(dst)
    header = next(rdr) + ['lookup_value']
    wtr.writerow(header)
    for row in rdr:
        key = row[0]
        wtr.writerow(row + [lookup.get(key, '')])

Installation for Claude Code:

# Place the skill in the local skill directory

mkdir -p ~/.config/claude-code/skills/data-processor
cp -r my-data-processor/* ~/.config/claude-code/skills/data-processor/

# Verify the skill metadata

head ~/.config/claude-code/skills/data-processor/SKILL.md

# Start Claude Code – the skill will auto-activate when relevant

claude

Validation and Marketplace Standards

The official skill validator, used by the Claude Skills marketplace, enforces the bundling conventions described above. The skill-creator/SKILL.md template in the repository provides placeholders for scripts/, templates/, and resources/, serving as the canonical starting point for new skills. Real-world examples like the connect-apps-plugin demonstrate how complex skills can ship plugin directories with scripts and assets for production actions.

Summary

• Claude Skills are self-contained folders with SKILL.md at the root and auxiliary files in scripts/, templates/, and resources/ or references/.
• Lazy-loading fetches only the SKILL.md front-matter initially, keeping context windows small until the skill is needed.
• Use relative paths for all file references within SKILL.md to ensure portability across different user environments.
• Set executable permissions on scripts in the scripts/ directory that the agent invokes directly.
• Maintain self-containment by vendoring dependencies or including requirements.txt/package.json files within the skill folder.
• Compress large assets optionally using .zip files in resources/ when dealing with bulky binary data.

Frequently Asked Questions

Can I use absolute paths when referencing bundled assets in SKILL.md?

No. According to the bundling rules in the ComposioHQ/awesome-claude-skills repository, all references inside SKILL.md must be relative to the skill root. Absolute paths will break when the skill is copied to different machines or user directories, as skills must remain portable and self-contained.

How do I handle third-party dependencies for scripts bundled in my skill?

You should declare dependencies in a requirements.txt (for Python) or package.json (for Node.js) placed alongside your script within the skill folder. Alternatively, vendor the dependencies directly into the skill directory. The skill must not rely on files or libraries outside its folder, as enforced by the official skill validator.

What is the recommended way to bundle large binary files like images or PDFs?

For large binary assets, ship a .zip file inside the resources/ directory and include instructions in SKILL.md for unzipping at runtime. This approach keeps the skill package organized while managing file size, and the unzip step should be clearly documented in the skill instructions so the agent knows to extract files before use.

Where should I place custom skill folders for Claude Code to recognize them?

Place custom skill folders in the user's Claude Code skills directory, typically located at ~/.config/claude-code/skills/ on Unix systems. Create a subfolder matching your skill name (e.g., ~/.config/claude-code/skills/data-processor/) and copy the entire skill contents there, including the SKILL.md file and all bundled scripts/ and resources/ subdirectories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}