🧭 When a skill is worthwhile (and the anti-patterns)
The complete decision tree: repeatable workflow or one-off? Skill, CLAUDE.md, MCP, or subagent? And the three anti-patterns that kill skills before they even trigger.
A skill is justified when there’s a repeatable workflow, team context knowledge, verifiable output, and a multi-step task. When ≥2 of these signals appear, it’s worth packaging.
A poorly applied skill becomes noise in context. Knowing the green flags helps you avoid creating skills that nobody triggers—and that clutter the catalog.
repeatable workflow · contextual knowledge · verifiable output · multi-step
A one-off task, something the model already does well on its own, or a simple one-step query doesn't need a skill. A skill here is over-engineering.
Most bad skills are created for problems that didn’t exist. Recognizing the anti-case saves effort and keeps the agent lightweight.
one-off task · model's native capability · one-step query
Four tools, four purposes: CLAUDE.md for always-active rules, MCP to connect external services, subagent for isolated parallel work, and skill for knowledge that loads on demand.
Using the wrong tool is the most common mistake. A skill isn’t MCP, and a global rule isn’t a skill. The decision tree gives you the answer in seconds.
always active vs. on demand · knowledge vs. connection vs. isolation
The 800-line "everything-about-react" skill that tries to cover it all. The agent absorbs it poorly, the description stays vague, and the trigger never fires. Split it into atomic skills.
An enormous scope is the most tempting anti-pattern—it seems efficient, but degrades both the trigger and the quality of the response.
atomicity · one responsibility · <500 lines · split by trigger
Filling the skill with uppercase "YOU MUST" instructions and overly specific examples. The model memorizes the cases and fails outside them. Explain WHY and generalize beyond the examples.
Overfitting is silent: the skill passes your tests and breaks in real life. Understanding why makes the instruction robust.
explain why · generalization · calm imperative · avoid overfitting
The description is the trigger. If it's vague ("helps with code"), the skill never triggers — or triggers incorrectly, in the wrong context. Say WHAT it does AND WHEN to use it.
A brilliant skill with a poor description is invisible. The trigger is the only layer that’s always in context—it’s worth investing in.
what + when · a little pushy · avoid under-triggering · explicit triggers
🚀 Publish, Version, and Measure
From a GitHub repo to skills.sh: folder structure, versioning via git, getting listed in the directory, measuring triggering, security, and the full skill lifecycle.
A publishable repo has a folder skills/, and inside it each skill with its SKILL.md plus the resources (scripts/, references/, assets/). Convention understood by the CLI and skills.sh.
A nonstandard structure means the skill won't be indexed or installable. The convention is your passport to the ecosystem.
skills/ folder · SKILL.md · scripts/ references/ assets/ · progressive disclosure
Skills live in git. Because they’re installed as symlinks, a git push + npx skills update propagates the new version to everyone who installed it. Good versioning matters.
You don’t just control your repo — you control the behavior of people who installed it. Careless versioning breaks other people’s agents.
git as source · symlink · npx skills update · changelog
skills.sh indexes public repos and shows install count as a social metric. It’s the showcase: of the catalog’s 39,366 skills, only 0.3% have more than 100k installs.
Discovery is half the game. Understanding the catalog’s power law calibrates expectations and naming/description strategy.
install count · leaderboard · power law · 53,9M combined installs
Does the description trigger in the right cases? You measure this with trigger evals: lists of should-trigger and should-not-trigger queries, plus the near-misses that cause confusion.
Triggering is the most overlooked KPI. Without measuring it, you don’t know whether the skill disappears in the right context or intrudes in the wrong one.
should-trigger · should-not-trigger · near-miss · trigger precision/recall
A skill shouldn’t do anything the user wouldn’t expect from its description—no deleting files, sending data, or running surprise destructive commands.
Skills run with the user’s trust. One destructive surprise burns the reputation of the entire repo—and ecosystem.
no surprises · least privilege · transparency · audit resources
Publishing isn’t the end: it’s publish → monitor installs and feedback → iterate on the description and body → republish. And where to keep learning: the INEMA.CLUB portal.
A skill is a living product. Its lifecycle wraps up the course and gives you a roadmap for where to go after your first skill.
publish · observe · iterate · INEMA.CLUB
⭐ The Best Process Skills
The most loved skills don’t teach a domain — they teach you HOW to think and work. test-driven-development, the superpowers family, and the process skills pattern (rigid vs. flexible).
A domain skill encodes “what to know about X” (React, Postgres). A process skill encodes HOW to work—regardless of the subject or stack.
Process has a larger total market and is what agents lack by default—so it dominates the top installs.
domain vs. process · stack-agnostic · trigger by task type
The most installed process skill in Testing (obra/superpowers). It requires you to write the failing test BEFORE implementing the code.
Changes the agent’s lazy default behavior: every feature starts with real test coverage, and “passes the tests” stops being theater.
red · green · refactor · verifiable output
brainstorming, systematic-debugging, writing-plans, and verification-before-completion — each changes the agent's behavior at a specific moment.
These are the model for atomic process skills that invoke one another — the opposite of an "everything-about-X" skill.
brainstorming · systematic-debugging · writing-plans · verification
The process skill spectrum: rigid (a fixed sequence that allows no deviation) vs. flexible (principles the agent adapts to the context).
Choosing the wrong point on the spectrum is an anti-pattern: rigidity where cases vary creates friction; flexibility with MUSTs leads to overfitting.
rigid · flexible · mistakes are costly → rigid · value lies in judgment → flexible
Correct the lazy default, work with any language/project (enormous total market), and the gains add up across all work.
Understanding why people love it tells you what kind of skill is worth creating—a well-made process skill outperforms the average of a mediocre group.
fix the default · total market · compounding effect · Testing&QA
The patterns that make a process skill well-loved: atomic, triggered by task type, explains why, and composes with others.
You don’t need to publish the next superpowers — just apply these patterns to your skill.
atomic · stack-agnostic · explains why · composable
🛠️ How to Create: From Decision to Publish
The concrete path: the decision checklist before creating, structuring the repo, versioning with git, and the exact commands — npx skills add / update — to go live on skills.sh.
Four questions (repeatable? context? verifiable? multi-step?) and the tree that chooses between skill, CLAUDE.md, MCP, and subagent.
Using the wrong tool is the most common mistake. The filter separates useful skills from catalog clutter.
≥2 yeses → worth it · always-on vs. on-demand · knowledge vs. connection
The convention understood by the CLI and skills.sh: a skills/ folder at the root, each skill with SKILL.md (frontmatter + body) + scripts/ references/ assets/.
Outside the standard = the skill is neither indexed nor installable. The convention is your passport to the ecosystem.
skills/ · SKILL.md · frontmatter name+description · resources
Git is the source of truth. Symlinks make pushes propagate to everyone who installed it—treat main as production, use a branch + PR + CHANGELOG.
You control the behavior of people who installed it, not just your repo. Careless versioning breaks other people’s agents.
git source · symlink · main = production · CHANGELOG
npx skills add ./local to test first, add owner/repo for production and update to pull the latest versions.
The symlink makes the test loop fast: edit the local SKILL.md and the changes show up right away. That’s how you iterate before publishing.
add ./local · add owner/repo · update · with-skill vs baseline
Public repo with the skills/ folder in the right convention; skills.sh indexes it and exposes the install count. name + description are the storefront.
Discovery is half the game. The same text that triggers the skill sells it in search — two birds with one stone.
public repo · indexing · install count · naming sells
Decide → structure → test locally → refine the trigger → version → go live → measure. The single sequence you follow today.
Bring it all together in an actionable plan—from the decision to a running install count.
decide · structure · test · fine-tune · version · publish · measure
🚀 Advanced Tips: Governance, Security, and Scale
The professional level: internal skills, the principle of least surprise, versioning strategy, team rollout, measuring adoption, and keeping dozens of skills alive.
Proprietary knowledge and team workflows become skills tagged with metadata.internal, installed only with the INSTALL_INTERNAL_SKILLS.
Prevents sensitive context from leaking into the public catalog and keeps skills.sh from getting cluttered with noise that's only relevant to you.
metadata.internal · INSTALL_INTERNAL_SKILLS · explicit opt-in
The skill never does anything the description doesn’t promise: no exfiltration, hidden rm -rf, or access to secrets without asking. Least privilege.
A symlink + update propagates to many people. One breach of trust can burn the entire repo and spill over into the ecosystem.
no surprises · least privilege · audit resources · no malware
Classify each change by risk. Changing the description may be a major change because it affects when the skill triggers for everyone.
At scale, pushing to main without a strategy creates instability. Versioning discipline separates what's safe from what's risky.
patch · minor · major · description = trigger change · tags
Centralize approved skills in a curated repo, pilot them with a subgroup before rolling them out to everyone, and communicate before each trigger update.
Sharing with a team calls for consistency and control—different from publishing to the open world.
curated repo · pilot · communicate update · onboarding via README
Two metrics intersect in a matrix: install count (discovery) and triggering (trigger precision). The worst case is lots of installs with poor triggering.
A skill at scale is a product, and products are measured. Each quadrant calls for a different action.
install count · triggering · adoption matrix · evals
Run evals in CI, audit trigger overlap, retire dead skills, and keep the body lean — so a portfolio of dozens doesn't rot.
One skill is easy; twenty are a product. And that’s where the course ends—from here on, it’s practice and the INEMA.CLUB portal.
evals in CI · overlap · retire · lean · INEMA.CLUB
📏 2026 rules: the skill for 5.5 models
What was missing: degrees of freedom, third-person descriptions and their limits, hooks inside the skill, the 5,000-token cutoff, not asking for reasoning, a checklist with a return path, and the 10-rule checklist with the validator. Wraps up the course.
The basic rules in Anthropic's skills guide have been stable for about a year; what's changed are the 5.5 models, which follow instructions more closely.
According to the prompting guide cited by skill-creator-plus, older skills are often too prescriptive for 5.5 models—a hypothesis to test with your skill.
stable rules · 5.5 models · too prescriptive · test
How much you specify each step depends on how fragile it is: free-form text, a model with variation, or an exact script.
Lock everything down and the skill becomes rigid; leave everything open and the risky step is left to chance. The test: “What if the agent does this another way?”
high · medium · low · narrow bridge × open field
The description goes into the system prompt: third person, what it does, and “Use when…,” up to 1,024 characters.
Claude Code truncates description + when_to_use at 1,536 characters in the listing; anything beyond that isn’t read by the agent.
third person · Use when · 1.024 · 1.536 · when_to_use
A skill can declare hooks in its own frontmatter; they log when it's called.
A rule that must not be broken needs to apply every time, and a hook is always followed, through the end of the session.
hooks: · PreToolUse · once: true · hard rule
After compaction, Claude Code reattaches only the first 5,000 tokens of each skill.
An important rule at the end of a long SKILL.md gets lost in a long session.
order = importance · 5,000 tokens · permanent instructions
Asking it to write out its reasoning may be refused by 5.5 models (reasoning_extraction).
The skill stops halfway; asking for the answer, a short explanation, or a summary of the actions fixes it.
reasoning_extraction · result · summary of actions · give the reason
A list the agent copies into its response and checks off, with “done when…” for each step.
Prevents skipped steps and declaring success too early; the fallback line says what to do when the check fails.
checklist · done when · return to step X · verification loop
auditar-skills (a mirror of skill-creator-plus, MIT) includes a Python validator that checks all your skills in one second.
On a real machine: 123 skills, 358 errors, only 15 clean. Measure before rewriting.
validate_skill.py --all · ST5 · ST4 · DS3 · five at a time
Learning path overview
Decide in 30 seconds: skill or not? And stop accidentally killing your skills.
From git to skills.sh. Publish, measure triggering, and iterate like a living product.
The most loved ones don’t teach a domain — they teach you how to think and work.
From asking “is it worth it?” to running npx skills add on skills.sh.
Internal skills, least surprise, and a living portfolio.
What 5.5 models require from a skill, in a 10-rule checklist. The course wrap-up.
🎓 End of the journey — and the beginning of yours
This is the course's final track. You already know the landscape, quality, anatomy, creation loop, and now the mental models for decision-making and publishing. The next step is to publish your first skill — and keep learning on the portal.