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

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, then package using 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 file and optional resource subdirectories. According to the repository's design principles documented in 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. 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 script automatically creates the scripts/ folder with placeholder examples.

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

This command generates my-custom-skill/ containing SKILL.md, 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 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.

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:

## 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.

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

The 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:

---
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:

---
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 — Generates new skill directories including the scripts/ folder with example.py placeholders.
• skill-creator/scripts/package_skill.py — Validates skill structure and creates distributable packages.
• skill-creator/scripts/quick_validate.py — Performs quick compliance checks on skill formatting.
• skill-creator/SKILL.md — Documents the progressive disclosure design principle and scripts/ usage patterns.
• 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) within SKILL.md instructions.
• Use init_skill.py to scaffold new skills with proper directory structure and placeholder examples.
• Package completed skills with 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.

How does Claude access scripts without loading them into context?

Claude accesses scripts through progressive disclosure. Initially, Claude sees only the 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.

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 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 creates alongside scripts/. The references/ folder stores additional documentation or lookup tables. Both directories travel with the skill when you run package_skill.py, ensuring all resources remain accessible across Claude.ai, Claude Code, and API deployments.

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