Write Skills That Load: Five Rules from 500K Stars

The fastest-growing category on GitHub in 2026 is not a framework, a model, or a database. It is a folder containing a Markdown file. Matt Pocock's skills repo crossed 254,000 stars. Jesse Vincent's superpowers sits north of 284,000. Between them, automated trackers have indexed over 24,000 repositories containing Claude Code skill definitions — up from roughly 2,000 six months ago.

📖 Read the full version with charts and embedded sources on AgentConn →

And most of them are broken.

Not broken in the way that throws an error. Broken in the way that a skill sits in your .claude/skills/ directory, structurally valid, and Claude never loads it. You type the prompt that should trigger it, and Claude reaches for its default tools instead. The claude-code issue tracker has a recurring pattern: developers report that only 1 of their 32 skills loads, or that a skill works from a slash command but never fires from natural language, or that a version upgrade silently breaks a skill that worked yesterday.

View mattpocock/skills on GitHub →

The ecosystem treats skills as "just markdown" — drop a file and Claude figures it out. That framing hides the real failure modes. This article extracts five structural rules from Anthropic's official documentation, the patterns behind the top skill repos, and the most common bug reports. Follow them and your skills load. Break them and they sit there, inert, while you blame the model.

The Skill Loading Model: What Actually Happens

Before the rules, you need to understand how Claude decides whether to load a skill. The mental model most developers carry — "Claude reads all my skills and picks the best one" — is wrong.

Here is what actually happens, according to Anthropic's official skills documentation:

1. At session start, Claude reads only the name and description fields from each skill's YAML frontmatter. Not the body. Not the scripts. Just those two fields.
2. When you send a prompt, Claude semantically matches your request against those descriptions. If a description matches, it loads the full SKILL.md body into context.
3. The body executes as instructions. Claude follows the skill's steps using its available tools — Bash, file operations, browser, whatever the skill specifies.

The critical implication: the description is the only thing standing between your skill and oblivion. A skill with a perfect body and a vague description will never fire. A skill with a mediocre body and a precise description will fire every time.

View the official skills documentation →

⚠️ The Description Is the Trigger, Not the Name — Claude does not match on the skill name. It matches on the description. A skill named deploy-staging with the description "helps with deployment" will lose to a skill named ship-it with the description "Deploy the current branch to the staging environment, run smoke tests, and report the deployment URL."

This is the single most common cause of "skill not loading" reports — and it leads directly to Rule 1.

Rule 1: Write the Description as a Trigger, Not a Summary

The description field has one job: make Claude load this skill when the right prompt arrives. It is not a README abstract. It is not a marketing blurb. It is a semantic trigger.

Bad description:

---
name: code-review
description: "A skill for reviewing code"
---

Claude reads "A skill for reviewing code" and has no idea when to use it. Should it fire for "check this PR"? For "is this function correct"? For "review my architecture"? The description gives no signal.

Good description:

---
name: code-review
description: "Review the current diff, PR, or branch for correctness bugs, security issues, and performance problems. Use when asked to review code, check a PR, audit changes, or find bugs in a diff."
---

This description contains the exact phrases a developer would type: "review code," "check a PR," "audit changes," "find bugs." Claude's semantic matching has something to grab onto.

The pattern from top repos: Matt Pocock's skills repo uses descriptions that read like a union of trigger phrases. His plan skill's description is not "helps with planning" — it lists the specific scenarios: writing plans, designing implementation, considering trade-offs. Jesse Vincent's superpowers follows the same pattern, with each description explicitly naming when to use and when not to use the skill.

💡 Test Your Trigger — After writing a description, test it with 5 different phrasings a real developer would use. If any of them fail to trigger the skill, add those phrases to the description. Test with casual language too — "fix this mess" should trigger a debugging skill, not just "debug the application."

Rule 2: One Skill, One Job — and Keep It Under 500 Lines

A skill that tries to do everything will do nothing well. This is not philosophy — it is a context budget constraint.

Claude has a finite context window. Every skill body that gets loaded competes for space with your codebase, your conversation history, and your other active skills. A 2,000-line skill that covers deployment, testing, linting, and documentation is burning context tokens on three workflows the user did not ask for.

The top repos enforce this ruthlessly:

• superpowers splits its workflow into 14 separate skills: brainstorming, writing plans, test-driven development, code review, verification, and more. Each skill does exactly one thing.
• mattpocock/skills packages each skill as its own folder with a focused SKILL.md. No skill tries to cover multiple workflows.

The 500-line rule: Multiple community guides and Anthropic's own best practices recommend keeping SKILL.md under 500 lines. If your skill needs reference material — API docs, schema definitions, style guides — move them into a references/ subdirectory that the skill loads on demand.

.claude/skills/deploy/
  SKILL.md           # < 500 lines — the instructions
  references/
    aws-regions.md   # loaded only when needed
    env-vars.md      # loaded only when needed
  scripts/
    deploy.sh        # deterministic work in scripts, not prompts

💡 Scripts for Deterministic Work — Anything with one correct answer — a math calculation, a file rename, an API call with fixed parameters — belongs in a bundled script, not in the skill's instructions. The skill says "run scripts/deploy.sh"; the script does the deterministic work. This reduces token waste and eliminates the model misinterpreting instructions.

Rule 3: Respect the File System Contract

Skills fail silently when the file system layout is wrong. There are no error messages. The skill just does not appear. Here are the structural requirements that Anthropic's docs and the bug reports confirm:

The filename must be exactly SKILL.md. Capital S, capital K, capital I, capital L, capital L, dot, capital M, capital D. On macOS and Linux, filenames are case-sensitive. skill.md, Skill.md, and SKILLS.md will not be recognized.

Each skill gets its own directory. One SKILL.md per folder. If you put two SKILL.md files at different depths in the same directory tree, only one will load — and which one is undefined.

The directory structure matters:

# CORRECT
.claude/skills/my-skill/SKILL.md

# WRONG — double-nested
.claude/skills/my-skill/my-skill/SKILL.md

# WRONG — no wrapper directory
.claude/skills/SKILL.md

Personal vs. project scope:

• ~/.claude/skills/<name>/SKILL.md — personal skills, available across all projects
• .claude/skills/<name>/SKILL.md — project skills, committed to the repo, shared with your team

The YAML frontmatter is required. The name and description fields must be present between --- markers at the top of the file. A SKILL.md without frontmatter is treated as a plain Markdown file, not a skill.

---
name: my-skill
description: "What this skill does and when Claude should use it"
---

# My Skill Instructions

Steps go here...

Name constraints: The name field doubles as the slash-command name. Use only lowercase letters, numbers, and hyphens. A name like Code_Review or my skill will cause problems. And never use a name that collides with a reserved keyword — built-in commands like help, clear, config, or init will shadow your skill.

View the GitHub issue on skills not loading →

⚠️ The Restart Tax — Claude Code reads skills at session start. If you add, rename, or modify a skill, you must start a new session for the changes to take effect. There is no hot-reload. This catches people who edit a skill, test it in the same session, see no change, and conclude the skill is broken. It is not broken. You are looking at a stale cache.

Rule 4: Explain the Why, Not Just the What

A common pattern in broken skills: a list of commands with no reasoning.

# Deploy Skill

1. Run `npm run build`
2. Run `aws s3 sync ./dist s3://my-bucket`
3. Run `aws cloudfront create-invalidation --distribution-id E123`
4. Post to Slack channel #deploys

This works for a shell script. It does not work for a skill, because Claude is not a shell script interpreter — it is a reasoning engine that needs context to make judgment calls.

Better:

# Deploy Skill

## Build
Run `npm run build`. If it fails, read the error output and fix the
issue before proceeding — do NOT deploy a broken build.

## Upload
Sync the dist/ directory to the S3 bucket. Use `--delete` to remove
stale files, but NEVER delete the /assets/legacy/ path (it serves
URLs that external partners have hardcoded).

## Cache Invalidation
Invalidate the CloudFront distribution. This takes 5-15 minutes to
propagate. Do not report "deploy complete" until the invalidation
status shows "Completed".

## Notification
Post to #deploys with the commit SHA, deploy time, and a link to
the CloudFront distribution. Include any build warnings.

The second version explains why each step matters, names the constraints and edge cases, and tells Claude what to do when things go wrong. This is the difference between a skill that works on the happy path and one that works in production.

The top repos all follow this pattern. Superpowers' verification-before-completion skill does not just say "run tests" — it explains what counts as verified, what to do with flaky tests, and when to escalate. Matt Pocock's code-review skill explains what each priority marker means and how to format findings.

Rule 5: Guard the Boundaries — Do and Don't

Every skill should have explicit boundaries. Without them, Claude will drift. It will use the code-review skill to refactor code. It will use the deploy skill to also run tests. It will helpfully expand the scope of what you asked for, because that is what language models do without constraints.

The pattern:

## When to Use This Skill
- When the user asks to review a PR or diff
- When the user asks to check code for bugs
- When the user asks to audit changes before merge

## When NOT to Use This Skill
- Do not refactor or fix the code — only report findings
- Do not run the code or execute tests — this is a static review
- Do not review files outside the diff — scope to changed files only

This is not defensive programming. This is how the highest-quality skills prevent the most common failure mode: scope creep. When Claude loads a skill and the skill says "do not fix the code," Claude will report findings instead of making changes. Without that guard, it will happily "help" by rewriting your code — which is not what a review skill should do.

The disable-model-invocation escape hatch: If you want a skill that ONLY fires from a slash command and never from natural language matching, add this to your frontmatter:

---
name: dangerous-deploy
description: "Deploy to production with zero downtime"
disable-model-invocation: true
---

This is useful for skills that have side effects you do not want triggered by accident — production deployments, data migrations, account operations.

The Ecosystem Is Not Slowing Down

The numbers tell the story. GitHub's trending page in August 2026 was dominated by agent infrastructure — harnesses, skills, memory layers. Models took a back seat. The machinery around the model is where the value has shifted.

View the GitHub trending analysis on Analytics Vidhya →

Some observers go further. An OODA Loop analysis argues that skills may be a bigger deal than MCP itself, because skills encode workflow knowledge — the kind of institutional expertise that usually lives in a senior engineer's head and gets lost when they leave.

If you are building in this space, see our previous coverage:

• Agent Skills Are the New Dotfiles — how skills repos became the fastest-growing GitHub category
• Config Files That Run Code: The Agent Skill Supply Chain — the security implications of importing someone else's SKILL.md
• It Fails on the Harness, Not the Model — why infrastructure matters more than model choice

Read the full Substack post on skill best practices →

Contrarian Corner: Skills Are Not "Just Markdown"

⚠️ The Counter-Argument Nobody Makes — The open skills ecosystem has a dark side. When you install a skill from a GitHub repo, you are giving someone else's instructions direct access to your codebase, your file system, and your shell. A malicious SKILL.md could instruct Claude to exfiltrate environment variables, modify .gitignore to hide changes, or inject code into your build pipeline. The convenience of claude skills install is real. So is the attack surface. Vet every skill you install the way you would vet a dependency in package.json — because that is exactly what it is.

The "just markdown" framing also obscures the real skill involved in writing good skills. The description field is a prompt engineering problem. The body structure is a workflow design problem. The file layout is a systems integration problem. Treating skills as trivial is why 90% of the 24,000 skill repos on GitHub contain skills that do not reliably trigger.

The Checklist

Before you publish or install a skill, run through this:

Check	What to Verify
Filename	Exactly SKILL.md — case-sensitive
Location	Inside .claude/skills/<name>/ or ~/.claude/skills/<name>/
Frontmatter	Valid YAML with name and description between --- markers
Name	Lowercase, hyphens only, no reserved keywords
Description	Contains trigger phrases a real user would type
Body length	Under 500 lines; reference material in references/
Scope	One skill, one job — no multi-workflow skills
Guards	Explicit "when to use" and "when NOT to use" sections
Scripts	Deterministic work in scripts/, not in instructions
Testing	Tested with 5+ phrasings including casual language
Session	New session started after any changes

What This Means for Builders

Skills are not a nice-to-have feature for power users. They are becoming the primary way teams encode their engineering workflows — deploy procedures, review standards, testing protocols, onboarding guides. The teams that invest in well-structured skills will compound their velocity. The teams that treat them as an afterthought will keep wondering why their AI assistant "doesn't understand the project."

The five rules are not complex. They are not even particularly demanding. But they require you to think about skills as software — with a contract, a specification, and a testing strategy — rather than as casual notes to a chatbot.

The 24,000 repos on GitHub prove the demand is real. The bug reports prove that most of them are broken. The gap between those two facts is your opportunity.

Start with one skill. Follow the five rules. Watch it load.

---

Originally published at AgentConn