Build and ship a Claude Skill

Skills aren't generalists. The best skills do one thing the base model can't: a domain-specific lint, a templated report generation, a wrapper around your internal API, a workflow with a sandbox script. If you can't write the capability in 1 sentence ('this skill does X'), the trigger description will be vague and Claude won't load it on the right queries.

A skill is a folder named after the skill, containing SKILL.md as the entry point and any resources or scripts. Claude Code looks in ~/.claude/skills/ and your project's .claude/skills/. claude.ai (with Skills enabled) reads from the skills you upload. Keep the folder shallow: deep nesting confuses the loader.

SKILL.md has YAML front-matter (name, description) and a markdown body. The `description` is the most important field in the entire skill, it's what Claude reads to decide whether to load the skill on a given query. A vague description means the skill loads too rarely or too often. Treat the description like a search-engine query: dense with the keywords your target users actually use.

Read the spec from the Brief.

Draft SKILL.md with this structure:

```
---
name: <kebab-case-name>
description: <dense, 1-3 sentence trigger description, lead with "Use when..." or "Use this skill when the user...">
---

# <Skill name in title case>

<1-paragraph what the skill does>

## When to use

<bullets matching the description, in user-query phrasing>

## Resources

<references to resources/* with 1-line descriptions>

## Scripts

<references to scripts/* with 1-line descriptions>

## Workflow

<step-by-step the model follows when this skill is loaded>
```

Output as a Brief section titled "SKILL.md v1". Don't run evals yet, that's the next step.

Resources are static files the skill references. The model reads them on demand, not on skill load, so big resources don't blow your context window. Good resource candidates: a JSON schema, a markdown template, a glossary, a workflow diagram. Don't put logic in resources, that's what scripts are for.

Scripts let the skill run real code: a Python script that processes a user-uploaded CSV, a Node script that hits an internal API, a shell script that runs a build. Claude executes scripts in a sandboxed environment, no network unless explicitly granted, no host filesystem access. Treat scripts as the 'agent superpower' part of a skill: the part that does work, not just describes work.

Read the user's existing tooling (their codebase, scripts, or internal CLI).

Identify which operations should become scripts in this skill. For each:
1. Name (kebab-case, ends in .py / .js / .sh)
2. Args (what the model passes in)
3. Stdout (what the model gets back)
4. Failure modes (what stderr looks like + exit code)

Then draft each script as a self-contained file. Constraints:
- Pure stdlib where possible (Python: stdlib + no extra installs).
- No network unless absolutely necessary, document the network dependency in the SKILL.md.
- Idempotent. Running the script twice should produce the same result.

Output the scripts as a Brief section titled "Scripts v1".

The trigger description is right when the skill loads on the queries it should and doesn't load on the queries it shouldn't. Build a 20-30 query eval set: half should trigger the skill, half should not. Run it, log results, tweak the description, re-run. This is the loop that separates skills that ship from skills that get uninstalled after one frustrating session.

Run an eval pass on the current SKILL.md.

For each query in the Eval log surface:
1. Send the query to Claude with the skill loaded.
2. Check whether the skill triggered (look for the skill's distinctive output or behavior).
3. Update the row: actual_loaded (true/false), notes (what the model did instead, if it didn't).

After all 30 queries, compute:
- Hit rate on positive set
- False-positive rate on negative set

If hit rate < 90%: the trigger description is too narrow, suggest 2-3 expansions of the description and which positive queries each one would catch.
If false-positive rate > 10%: the trigger description is too broad, suggest 2-3 tightenings and which negative queries each one would reject.

Output the analysis as a Brief section titled "Eval results v<n>".

A skill ships when a teammate can install it in one step. That means a clean README.md, a SemVer version in the front-matter, and either a public registry entry or a git URL they can clone into their ~/.claude/skills/ folder. Don't ship a skill folder full of half-finished scripts and 'TODO' comments.

Distribution depends on your audience. Public skill: publish to a registry like the official Anthropic skills repo or claudehub.dev. Internal team skill: clone into a shared dotfiles repo, install via a one-line script. claude.ai Team skill: upload to the Team workspace from Settings -> Skills, every member auto-installs. Pick the channel that matches who needs the skill.

Skills age. Every base-model upgrade shifts how the trigger description is interpreted. Run the eval set monthly. When false-positive rate climbs, tighten the description. When hit rate drops, broaden it. Keep the eval log as the canonical history of what worked, you'll forget which trigger phrasing won by month 4.