How Scripts Work in Claude Skills

Research notes — compiled from the official Claude Code docs and the Agent Skills open standard

1. Overview: What Is a Skill?

A skill is a folder containing a SKILL.md file (with YAML frontmatter + Markdown instructions) plus optional supporting files. Claude Code discovers skills in:

Skills follow the Agent Skills open standard (adopted by Claude Code, Cursor, VS Code, Gemini CLI, Roo Code, and many others). Claude Code extends the standard with invocation control, subagent execution, and dynamic context injection.

2. Skill Directory Structure

my-skill/
├── SKILL.md           # Required — metadata + instructions (the entrypoint)
├── scripts/           # Optional — executable code Claude can run
│   ├── validate.sh
│   └── process.py
├── references/        # Optional — extra docs loaded on demand
│   └── REFERENCE.md
├── assets/            # Optional — templates, schemas, data files
│   └── template.json
└── examples/          # Optional — example outputs
    └── sample.md

Key points from the spec:

• SKILL.md is the only required file. Everything else is optional.
• Supporting files (scripts/, references/, assets/) are loaded on demand, not automatically injected into context.
• SKILL.md should be kept under 500 lines. Move detailed material to separate files.

3. How Scripts Under scripts/ Are Used by Claude Code

Here's the full lifecycle:

1. Discovery — Claude Code scans skill directories and loads each skill's name and description into context so Claude knows what's available (~100 tokens per skill).
2. Activation — When a skill is invoked (by the user via /skill-name, or by Claude when it decides the skill is relevant), the full SKILL.md body is loaded into Claude's context.
3. Instruction following — Claude reads the SKILL.md instructions, which tell it to run specific scripts. Claude uses its Bash tool to execute them.
4. Script execution — Claude runs the script as a shell command. The script's stdout/stderr are returned to Claude, which then uses the output to continue its task.

How Claude resolves script paths

There are two approaches:

# In SKILL.md:
Run the validation script:
```bash
bash scripts/validate.sh "$INPUT_FILE"
```

# In SKILL.md:
```bash
python ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

The allowed-tools connection

If your script needs Claude to run Bash commands, you can pre-approve them in frontmatter so Claude doesn't ask for permission each time:

---
name: my-skill
allowed-tools: Bash(python *), Bash(bash *)
---

4. Conventions for Writing Skill Scripts

These conventions come from the Agent Skills "Using Scripts" guide and are critical for making scripts work well with Claude (or any AI agent):

# ❌ Bad: hangs waiting for input
$ python scripts/deploy.py
Target environment: _

# ✅ Good: accepts input via flags
$ python scripts/deploy.py --env staging --tag v1.2.3

# ✅ Good: clear error when required args missing
$ python scripts/deploy.py
Error: --env is required. Options: development, staging, production.
Usage: python scripts/deploy.py --env staging --tag v1.2.3

Usage: scripts/process.py [OPTIONS] INPUT_FILE

Process input data and produce a summary report.

Options:
  --format FORMAT   Output format: json, csv, table (default: json)
  --output FILE     Write output to FILE instead of stdout
  --verbose         Print progress to stderr

Examples:
  scripts/process.py data.csv
  scripts/process.py --format csv --output report.csv data.csv

# ❌ Opaque
Error: invalid input

# ✅ Actionable
Error: --format must be one of: json, csv, table. Received: "xml"

# ❌ Hard to parse
NAME        STATUS    CREATED
my-service  running   2025-01-15

# ✅ Unambiguous
{"name": "my-service", "status": "running", "created": "2025-01-15"}

5. Referencing Scripts from SKILL.md

List available scripts and tell the agent how to run them:

## Available scripts
- **`scripts/validate.sh`** — Validates configuration files
- **`scripts/process.py`** — Processes input data

## Workflow
1. Run the validation script:
   ```bash
   bash scripts/validate.sh "$INPUT_FILE"
   ```
2. Process the results:
   ```bash
   python3 scripts/process.py --input results.json
   ```

6. Self-Contained Scripts (Inline Dependencies)

When you need third-party packages, use inline dependency declarations so the script is self-contained — no separate requirements.txt or install step needed:

Python (PEP 723 + uv)

#!/usr/bin/env python3
# /// script
# dependencies = [
#     "beautifulsoup4>=4.12,<5",
#     "requests>=2.31",
# ]
# requires-python = ">=3.10"
# ///

from bs4 import BeautifulSoup
import requests
# ... your code ...

Run with: uv run scripts/extract.py — uv creates an isolated environment, installs deps, and runs it.

Deno (TypeScript/JavaScript)

import { parse } from "jsr:@std/csv@1.0.4";
// ... Deno auto-resolves jsr: and npm: imports

Run with: deno run scripts/process.ts

Bun

import { $ } from "bun";
// bun auto-installs missing packages

7. Dynamic Context Injection with ! Commands

Claude Code extends the Agent Skills standard with a preprocessing feature: the !`command` syntax runs shell commands before the skill content is sent to Claude. Output replaces the placeholder:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

This is preprocessing, not something Claude executes. Claude only sees the final rendered output. This is different from scripts in scripts/ which Claude actively runs during its task.

8. Full Example: Codebase Visualizer Skill

This example from the official docs shows the complete pattern — a skill that bundles a Python script to generate an interactive HTML visualization:

Directory layout

~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
    └── visualize.py

SKILL.md

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your
  codebase. Use when exploring a new repo, understanding project structure,
  or identifying large files.
allowed-tools: Bash(python *)
---

# Codebase Visualizer

Generate an interactive HTML tree view of your project's file structure.

## Usage

Run the visualization script from your project root:

```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it
in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

scripts/visualize.py

A regular Python script using only stdlib (json, sys, webbrowser, pathlib, collections). It scans a directory tree and generates a self-contained HTML file. Key properties:

• Takes a directory path as CLI argument (no interactive prompts)
• Uses only built-in libraries (no install step)
• Prints status to stdout ("Generated /path/to/codebase-map.html")
• Opens result in browser automatically

9. Quick Checklist for Writing Skill Scripts