# How to Add Custom Python or JavaScript Scripts to Claude Skills: A Complete Guide

> Learn to add custom Python or JavaScript scripts to Claude Skills. Follow this guide to place scripts in the scripts directory and reference them in SKILL.md for powerful extensions.

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

---

**To add custom scripts to Claude Skills, place your `.py` or `.js` files in the `scripts/` directory of your skill folder and reference them by relative path in [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md), then package using [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py).**

Claude Skills in the **ComposioHQ/awesome-claude-skills** repository follow a self-contained folder architecture that separates deterministic code from conversational instructions. This design allows you to extend Claude's capabilities with executable Python or JavaScript while keeping context windows lightweight through progressive disclosure.

## Understanding the Claude Skills Architecture

Each Claude Skill is a standalone directory containing a mandatory [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file and optional resource subdirectories. According to the repository's design principles documented in [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/SKILL.md), the `scripts/` folder serves as the designated location for executable code that Claude can invoke without loading the full source into the initial context.

When a skill initializes, Claude receives only the metadata (name and description) plus the body of [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md). The actual script files remain external to this context until explicitly referenced, ensuring token-efficient interactions while providing deterministic execution paths for complex operations.

## Step-by-Step Guide to Adding Custom Scripts

### 1. Initialize the Skill Structure

Use the initialization utility to scaffold a new skill with the required directory structure. The [`init_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/init_skill.py) script automatically creates the `scripts/` folder with placeholder examples.

```bash
./skill-creator/scripts/init_skill.py my-custom-skill --path ./skills

```

This command generates `my-custom-skill/` containing [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md), [`scripts/example.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/scripts/example.py), and additional template directories under `references/` and `assets/`.

### 2. Place Scripts in the scripts/ Directory

Add any file with a `.py` or `.js` extension to the `scripts/` subdirectory. The repository treats these as executable resources that can run on the host environment when the skill is deployed. Replace the placeholder [`scripts/example.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/scripts/example.py) with your custom implementation.

### 3. Reference Scripts in SKILL.md

Inside your skill's markdown instructions, use relative paths to point to the script. This referencing method allows Claude to locate the executable without increasing token load until the specific capability is triggered.

```markdown
When processing PDF files, run `scripts/rotate_pdf.py <file_path> <angle>` to rotate the document.

```

### 4. Document Usage Patterns

Provide imperative instructions describing when and how the script executes. Clear documentation enables Claude to autonomously determine skill applicability and pass correct arguments.

Example documentation structure:

```markdown

## Instructions

1. Inspect the user request for a PDF file and rotation angle.
2. When both are present, execute `scripts/rotate_pdf.py <pdf_path> <angle>`.
3. Return the processed file to the user.

```

### 5. Package the Skill

Validate the folder structure and create a distributable archive using the packaging utility.

```bash
python skill-creator/scripts/package_skill.py my-custom-skill

```

The [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py) script checks for required files and bundles the skill for distribution across Claude.ai, Claude Code, and the Skills API.

## Why Progressive Disclosure Matters

The **scripts/** directory architecture implements a progressive disclosure design pattern that delivers three critical advantages:

- **Token Efficiency**: Scripts load only when referenced, keeping initial context lightweight and focused on instructions rather than implementation details.
- **Deterministic Execution**: Code provides reliable, repeatable behavior that Claude delegates to hosted execution environments, unlike pure-prompt approaches that may vary between runs.
- **Cross-Platform Portability**: Because scripts bundle with the skill directory, they travel unchanged across deployment environments, ensuring consistent behavior whether running on Claude.ai or via the Skills API.

## Complete Code Examples

### Python Script Example: PDF Rotation

Create a skill for rotating PDF documents with this file structure:

```

rotate-pdf/
├── SKILL.md
├── scripts/
│   └── rotate_pdf.py
└── assets/

```

**SKILL.md content:**

```markdown
---
name: rotate-pdf
description: Rotate a PDF file by a user-specified angle.
---

## Overview

Rotate a PDF document without altering its content.

## Instructions

1. Inspect the user request for a PDF file and rotation angle.
2. When both are present, run `scripts/rotate_pdf.py <pdf_path> <angle>`.
3. Return the rotated PDF to the user.

```

### JavaScript Script Example: HTTP Fetching

Implement a URL fetching capability with this structure:

```

fetch-url/
├── SKILL.md
├── scripts/
│   └── fetch_url.js
└── assets/

```

**SKILL.md content:**

```markdown
---
name: fetch-url
description: Retrieve JSON from a URL and present a summary.
---

## Overview

Fetch remote JSON data and generate a concise summary.

## Instructions

1. Detect a request to fetch a URL.
2. Execute `scripts/fetch_url.js <url>`.
3. Parse the JSON output and embed the summary in the response.

```

## Key Files and Utilities Reference

The following files in the **ComposioHQ/awesome-claude-skills** repository manage the custom script workflow:

- [`skill-creator/scripts/init_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/init_skill.py) — Generates new skill directories including the `scripts/` folder with [`example.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/example.py) placeholders.
- [`skill-creator/scripts/package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/package_skill.py) — Validates skill structure and creates distributable packages.
- [`skill-creator/scripts/quick_validate.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/quick_validate.py) — Performs quick compliance checks on skill formatting.
- [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/SKILL.md) — Documents the progressive disclosure design principle and scripts/ usage patterns.
- [`skill-creator/scripts/example.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/scripts/example.py) — Placeholder Python script created during initialization.

## Summary

- Place custom Python (`.py`) or JavaScript (`.js`) files in the `scripts/` subdirectory of your skill folder.
- Reference scripts using relative paths (e.g., [`scripts/my_script.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/scripts/my_script.py)) within [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) instructions.
- Use [`init_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/init_skill.py) to scaffold new skills with proper directory structure and placeholder examples.
- Package completed skills with [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py) to validate and distribute them.
- The progressive disclosure architecture keeps initial context lightweight while providing deterministic execution when needed.

## Frequently Asked Questions

### What file types are supported in the scripts directory?

Claude Skills support `.py` and `.js` extensions in the `scripts/` folder. These files are treated as executable resources that run on the host environment when the skill is deployed. While the examples focus on Python and JavaScript, the architecture accommodates any executable file type that your deployment environment supports, provided you reference it correctly in [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md).

### How does Claude access scripts without loading them into context?

Claude accesses scripts through **progressive disclosure**. Initially, Claude sees only the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) metadata and instructions, including the relative path references to scripts. The actual script content remains unloaded until the workflow requires execution, at which point the host environment runs the script. This design prevents token bloat while maintaining deterministic behavior as implemented in [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/skill-creator/SKILL.md).

### Can I include external dependencies in my custom scripts?

Yes, but you must ensure the deployment environment contains the required dependencies. Since scripts execute on the host rather than within Claude's context, they can access system packages, Node.js modules, or Python libraries installed on the execution machine. Document any dependencies clearly in [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) so users know what to install before running the skill.

### Where should I place non-script resources like images or data files?

Place static assets in the `assets/` directory, which [`init_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/init_skill.py) creates alongside `scripts/`. The `references/` folder stores additional documentation or lookup tables. Both directories travel with the skill when you run [`package_skill.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package_skill.py), ensuring all resources remain accessible across Claude.ai, Claude Code, and API deployments.