Short answer: put helper scripts in the Skill folder, reference them by relative path in SKILL.md, and let Claude execute them in the sandboxed environment. Keep scripts focused and take input from files or stdin rather than long argument strings.

How should a script-bearing Skill be laid out?

A predictable structure helps Claude find things.

weekly-report/
  SKILL.md
  scripts/build_report.py
  references/columns.md
  templates/summary.md

Claude loads SKILL.md first, reads references/ only when the instructions say to, and runs files under scripts/ when a step calls for it. That ordering keeps context small.

How does Claude actually run your script?

1. The instruction in SKILL.md names the script and the expected input, for example: “Run scripts/build_report.py against the user’s CSV and read its stdout.”
2. Claude writes the input file into the sandbox working directory.
3. It executes the script with the bundled Python interpreter.
4. It reads stdout back into the conversation and continues.

Because the script’s stdout re-enters context, keep output terse. A script that dumps 5,000 rows will consume your window and derail the task.

What makes a Skill script reliable?

Favor the standard library. A dependency on pandas or requests will fail if the sandbox environment does not include it, and you cannot install packages at runtime.

How do you keep context usage under control?

This is the part teams get wrong. Every line Claude reads from your Skill costs tokens. Two techniques keep a Skill cheap.

First, put rarely used detail in references/ files and tell Claude to read them only when a specific condition applies. Second, have scripts output summaries rather than raw data — ten rows of JSON, not ten thousand.

Anthropic’s own guidance pushes toward the smallest instruction set that works. If your SKILL.md is 2,000 lines, it is firing on every matching request and eating your budget silently.

When is bundling a script the wrong move?

If the task is fundamentally judgment — tone, structure, prioritization — a script adds rigidity without helping. Skills that try to encode fuzzy decisions as code end up brittle, and you spend more time debugging the script than doing the work.

Scripts pay off for deterministic transforms: parsing CSV, computing dates, reformatting JSON, resizing images. Pair them with a rich SKILL.md and you get a Skill that is both consistent and flexible.

Quick Summary

• Store helper scripts under scripts/ and reference them by relative path in SKILL.md.
• Claude runs scripts in a sandbox and reads stdout back into the conversation.
• Emit terse, structured output — verbose stdout burns your context window.
• Stick to the standard library; you cannot install packages at runtime.
• Use scripts for deterministic transforms, not for judgment calls.

Short answer: create a folder, write a SKILL.md with YAML frontmatter (name and description), zip it, and upload it under Settings then Capabilities. Claude decides when to use it based on the description.

What is a Claude Skill, exactly?

A Skill is a directory. At minimum it holds one file named SKILL.md. Claude reads the frontmatter at startup and loads the full instructions only when a task matches. That progressive loading is why you can install dozens without burning context on each one.

The format is open — Anthropic published the spec, and Skills work across the Claude apps and the Agent SDK. A Skill can bundle Python scripts, reference documents, and templates alongside the instructions.

How do you write SKILL.md?

Frontmatter first, then the instructions as plain Markdown.

---
name: weekly-report
xdescription: Builds a weekly status report from a CSV of tickets. Use when the user asks for a weekly summary or status report.
---

# Weekly Report
1. Read the attached CSV.
2. Group rows by team.
3. Output a summary table, then three risks.

Remove the x before description — it is only here to stop the block rendering oddly. The description is the most important line in the file, because that is what Claude matches against your request.

How do you install a Skill in Claude?

1. Zip the folder — the ZIP must contain the folder, not just SKILL.md loose.
2. Open Claude Settings, then Capabilities (or Skills, depending on the client).
3. Upload the ZIP and enable the Skill.
4. Start a new chat and make a request that matches the description.
5. Check that Claude announces it is using the Skill — if it does not, the description needs work.

If Claude never triggers your Skill, the fault is almost always a vague description. “Helps with reports” will not fire; “Builds a weekly status report from a CSV of tickets” will.

What separates a good Skill from a bad one?

Keep the main instructions under about 500 lines. If a task needs more, put detail in separate reference files that Claude loads on demand. Numbered procedures beat paragraphs — the model follows them more reliably.

What are the limits?

Skills do not add new capabilities; they add instructions and optional scripts. They cannot bypass Claude’s safety rules or run code outside the sandbox. Bundled scripts execute in a restricted environment, so no network calls to arbitrary hosts by default.

Version control is manual — there is no registry or auto-update. Teams typically keep Skills in a git repo and share the ZIPs. That is a real weakness if you expect package-manager ergonomics.

Skills suit people with a repeatable workflow they want standardized: report generation, code review checklists, brand voice rules. They are overkill for a one-off prompt you will never reuse.

Quick Summary

• A Claude Skill is a folder with a SKILL.md file and optional scripts.
• The YAML description determines when Claude triggers the Skill — make it specific.
• Zip the folder and upload it under Settings, then Capabilities.
• Keep instructions under roughly 500 lines and use numbered steps.
• Skills add instructions, not new powers — and they have no auto-update.