Cheatsheet · 9 min read

The 6 Claude Skill design principles

A SKILL.md is not a README. It is a load balancer rule, a few-shot prompt, and a small unit-tested program. Here are the six rules that separate Skills that fire from Skills that just sit there.

Adapted from Christian Dussol's 6 Principles from Anthropic's Official Skills Guide(April 2026), plus Adithya Giridharan's Anthropic 32-Page Playbook (Feb 2026). Both are worth reading end to end. This page is the opinionated cheatsheet.

1. Description: WHAT + WHEN + NEGATIVE TRIGGERS

The description field in your YAML frontmatter is the single most important line in the whole file. It is the only thing Claude sees at startup — every other Skill in your library is also loading its description, and they are all competing for the same attention slot. Treat it like a load balancer rule, not like a README intro.

A good description answers three questions: WHAT the skill does, WHEN Claude should reach for it (concrete trigger phrases), and WHEN NOT TO USE IT. The negative triggers are what most authors skip — and they are why Skills misfire. Without an explicit "do not use for X" clause, Claude will happily reach for a Kubernetes policy skill the first time someone asks about a pod stuck in CrashLoopBackOff. You want the skill to fight its way in, not coast in by default.

description: |
  Use when the user says "create Kyverno policy",
  "enforce resource limits", or asks to write
  Kubernetes admission rules. Do NOT use for
  general Kubernetes troubleshooting or kubectl
  command help — that is handled by another skill.

description: A Kubernetes skill that helps
  with policies and security.

2. Progressive disclosure: keep SKILL.md under 5K tokens

Anthropic's loader has three levels: metadata (always loaded, ~100 tokens), the SKILL.md body (loaded on trigger, target under 5,000 tokens), and bundled files in scripts/, references/, and assets/ (loaded only when the body asks for them).

Most teams cram everything into SKILL.md. Don't. The body should be the orchestrator — a short list of steps that names the references and scripts it needs. The actual reference material lives in the references/folder and only loads when the body says "read api-spec.md to find the right endpoint." The difference between a 4K SKILL.md and a 12K one is the difference between Claude actually following the recipe and Claude losing the plot halfway through.

my-skill/
  SKILL.md              # < 5K tokens — the recipe
  references/
    api-spec.md         # loaded only when SKILL.md says "read api-spec.md"
    error-codes.md
  scripts/
    validate.py
    fixup.sh

3. Scripts for deterministic validation

Code is deterministic. Language interpretation is not. The instant your skill needs a check that must be exact — "all required annotations are present", "no PII slipped into the output", "the JSON parses" — write a script and have Claude run it. Do not describe the check in prose.

4. Concrete reasoning-chain examples

A good SKILL.md includes one or two worked examples: input → expected reasoning → output. Treat them like few-shot prompts inside the file. Abstract instructions hallucinate; examples anchor. The reasoning step is the part that matters most — "here is the decision the skill makes and why" — because Claude will pattern-match the decision logic, not just the surface format of the output.

One example covers the happy path. Two examples — one happy, one edge case — also teach Claude when to deviate. More than three and you are writing a test suite; move those into references/examples.md and let the body cite them on demand.

## Example

**User**: "Restrict namespaces to 2GB memory and 1 CPU."

**Reasoning**:
- This is a resource limit, so use a ClusterPolicy.
- Apply to all namespaces matching the org convention.
- Use `validate` rule with `pattern`, not `mutate`.

**Output**:
```yaml
apiVersion: kyverno.io/v1
kind: ClusterPolicy
# ...
```

5. No README.md inside the Skill folder

Claude scans the skill folder. If it sees both SKILL.md and README.md it gets confused about which one is the instructions. Pick one home. The Anthropic convention is SKILL.md for instructions, references/ for documentation, scripts/ for code, assets/ for everything else.

my-skill/
  SKILL.md
  references/
    architecture.md
  scripts/
    run.sh

my-skill/
  SKILL.md
  README.md       # <-- Claude reads both. Bad.
  scripts/
    run.sh

6. Test triggering BEFORE testing execution

If your Skill does not fire when it should, every other bug is downstream noise. You can write the most precise body in the world, but if Claude never reaches for it, none of that matters. Before you tune the prompt, write a triggering harness: 10 prompts that should trigger the skill, 10 that should not. Run them, score the fires, fix the description, repeat. Most teams discover their description was actually triggering on six unrelated topics — and that the fix is one sentence of negative triggers.

## Triggering harness — should fire

1. "Create a Kyverno policy to require resource limits"
2. "Write an admission rule blocking root containers"
3. "Enforce that every pod has a 'team' label"
4. "Generate a ClusterPolicy denying privileged"
5. "Add a Kyverno rule for sidecar injection limits"
6. "Restrict namespaces to 2GB memory and 1 CPU"
7. "Block hostPath mounts via admission"
8. "Require image tags from approved registries"
9. "Mutate pods to add default labels"
10. "Audit deployments for missing probes"

## Triggering harness — should NOT fire

1. "Why is my pod in CrashLoopBackOff?"        # troubleshooting
2. "kubectl describe pod failing — help"        # CLI help
3. "Explain Kubernetes RBAC"                   # general explainer
4. "Set up an HPA for my deployment"            # autoscaling
5. "How do I install Kyverno?"                  # ops setup
6. "What is a CRD?"                            # concept question
7. "Compare Kyverno vs OPA Gatekeeper"          # comparison
8. "My pod is stuck pending"                    # debug
9. "Write a Terraform module for EKS"           # infra-as-code
10. "Generate Helm chart values"                # templating

The recap

1. Description — WHAT + WHEN + NEGATIVE TRIGGERS.
2. Progressive disclosure — under 5K body, the rest in references/.
3. Scripts — anywhere determinism matters.
4. Examples — one or two worked reasoning chains.
5. No README.md in the skill folder.
6. Triggering harness — 10 yes, 10 no, before anything else.

Lint your skill against the six rules

We package this checklist as a Skill that audits other Skills. Drop a path to your SKILL.md folder and it returns a pass/fail report on every rule above, plus the offending lines.

Related

• Five-tool carpentry — when to write a Skill in the first place (vs Project, MCP, or a plain prompt).
• Cleanup your Claude Code setup — Skills that never fire are pure overhead. Audit, then prune.

References

• Christian Dussol, 6 Principles from Anthropic's Official Skills Guide, Medium, April 2026. medium.com/@christiandussol
• Adithya Giridharan, Anthropic's 32-Page Playbook for Building Claude Skills, Medium, February 2026. medium.com/@adithyagiridharan
• Anthropic skill-creator — a meta-skill that generates other Skills. Available in Claude Code.