Skills: a markdown file that decides when it loads

This site's own content/skills.ts states what a Skill is in its opening comment, plainly enough to quote whole: "A skill is a markdown file with frontmatter. The description decides when it loads, so it is written as a trigger condition rather than a summary." That one sentence is the entire mechanism. There's no separate registry deciding which skill applies to which task — the model reads a list of descriptions and matches the current situation against them, the same way it would match a person's request against a list of job titles. A description that reads like ad copy ("Helps with course content!") matches almost nothing reliably. A description written as a list of exact triggering situations matches the moment it's actually needed.

Look at how agent-orchestration's real SKILL.md writes its own description, because the difference from a summary is visible in the sentence structure itself: "Use when writing or reviewing a Workflow script, deciding whether a task needs multiple agents at all or how many, an agent keeps failing on a content-heavy task, or coordinating background workflows that might touch the same files." Four separate, concrete situations, joined by "or" — not "this skill explains multi-agent orchestration." The same convention runs through every skill this site has written. micro-polish's description names the failure mode it exists to catch ("hairline visual inconsistencies, duplicated/redundant copy fragments, silent data mismatches, off-by-one UI states") and then explicitly distinguishes itself from a neighbor skill that sounds similar but isn't ("Separate from veridian-quality-loop... this audits whether the details are actually RIGHT"). A skill's description is doing real disambiguation work, not just advertising.

#Same file, three places it can live

The comment block in content/skills.ts names all three: "Same file works in Claude Code (~/.claude/skills/), on claude.ai (Settings → Capabilities), and committed into a repo." That portability is the whole point of writing a skill as a plain markdown file with frontmatter instead of anything more exotic — no separate compilation step, no platform-specific format. knowledge/README.md describes the project-level case directly: most directories under knowledge/skills/ have a symlink at .claude/skills/<name> pointing back into the plugin, "so the skills load with no install step and there is still only one copy of each file." research-index is the deliberate exception — linked into ~/.claude/skills/ instead, "so it loads in every project on the machine, not just this one," because it's the entry point for research that's genuinely reusable well beyond this one codebase.

#The compact default and the exhaustive sibling

Several of this site's skills come in pairs: a fast default meant for routine work, and an exhaustive sibling meant for the rare case where the build has to be the best in its category. course-max's own frontmatter names the relationship without hedging: "course-builder is the fast default — eighteen rules and a process, enough to run a normal course-building session without reinventing commerce or skipping the pilot step. course-max exists for the" build that's explicitly ambitious — "a flagship or premium relaunch," a build that "has to survive an adversarial review council." The exhaustive version isn't a rewrite of the compact one; it's the research and reusable prompts sitting underneath it, unpacked in full rather than distilled down to eighteen rules. The same shape shows up one layer up: meta-improvement-loop doesn't audit a course build at all — it audits "the AUDITORS: does the same class of finding keep recurring across separate review passes because nobody ever fixed the prompt that keeps producing it." A skill can exist to fix another skill's blind spot, which is a different kind of thing than a skill that does a task.

#What determines whether something becomes a skill at all

Not every reusable instruction earns a SKILL.md. The ones on this site's own /skills page share a pattern worth naming: each one exists because a specific failure recurred more than once and cost something real when it did. source-finder's own "why" states the mechanism plainly: "Search ranks by reach, and reach correlates with production quality far more than with accuracy." human-prose exists because "LLM prose is recognisable because it is even... Human writing is lumpy," and is explicit about where it stops: "not for disguising authorship of submitted work." course-builder exists to prevent "a course build that reinvents commerce or auth the platform already has, spends its whole budget on one subject before validating the lesson pattern on a single pilot, or treats retrieval practice as prose pasted into markdown when the platform needs typed data to grade against it" — distilled, its own entry says, "from rebuilding Meridian end to end in one long session, including a production-deploy crisis root-caused live against the database and a copyright flag on an official question bank handled explicitly rather than skipped." None of these read like documentation written in advance of a problem. They read like a scar, because that's what they are.

#The incident that shows why "committed into a repo" isn't optional

knowledge/README.md is direct about the one case where this went wrong: "A skill kept as a loose untracked directory under .claude/skills/ is invisible to git — it does not show in a diff, it is not in any commit, and deleting it destroys it silently. That is exactly how course-creator was lost on 2026-08-20: it was the one skill that never made this migration, a background agent removed it, and it survived only because an unrelated WIP commit on a retired branch happened to have captured it the day before." Nothing about that failure required a bug in the skill itself. The skill's content was fine. What failed was that it lived somewhere git couldn't see, so an ordinary cleanup action — the kind that happens constantly in any long session — deleted it with nothing to revert. The fix wasn't a smarter agent; it was moving the file to a place the ordinary safety net (version control) already covers. That's the same lesson the Workflows module draws from a different incident, in a different form: the tooling that catches a mistake has to actually be watching the thing that broke.