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

> Master bundling scripts, references, and assets for Claude Skills. Follow our complete guide to package your Claude Skills efficiently using ComposioHQ conventions.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: how-to-guide
- Published: 2026-07-27

---

**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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/requirements.txt) or [`package.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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:**

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

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

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

```

**[`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md):**

```markdown
---
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:**

```bash

# 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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) at the root and auxiliary files in `scripts/`, `templates/`, and `resources/` or `references/`.
- **Lazy-loading** fetches only the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) front-matter initially, keeping context windows small until the skill is needed.
- **Use relative paths** for all file references within [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/requirements.txt)/[`package.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/requirements.txt) (for Python) or [`package.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file and all bundled `scripts/` and `resources/` subdirectories.