AI
The Context-Loading Tax
Every agent conversation starts from zero. There is no memory of last week’s project, no awareness of your toolchain. Reloading that context manually eats time and produces different results every run. CLAUDE.md files help, but they bloat the context window unconditionally and are not portable across repos.
A skill is a small markdown file that encodes exactly what you want the agent to know for a specific task. It loads only when the task matches. As little as 30 lines of markdown can turn a generic code review into one that knows your routing conventions, commit format, and readme standards.
Skill Anatomy: Structure, Descriptions, and Constraints
A skill is a folder with a skill.md file inside, plus any supporting scripts or reference files. The frontmatter has a name and a description. That description is the critical field: the LLM reads it at runtime to decide when to invoke the skill. Write it for the model, not for humans. If the description is wrong, the skill either misfires or never loads.
Three firm constraints outperform a verbose procedure. Overly prescriptive skills are a common failure mode. The repo roast skill they built in the workshop demonstrates both: 30 lines targeting commit style and readme drift.
Loading, Distribution, and Governance at Scale
Skills live in a .claude/skills/ directory inside a repo, or in your home directory for global use. Codex, Cursor, and Claude Desktop all support them. A skill folder zipped and renamed .skill installs by drag-and-drop into Claude Desktop. The repo roast skill live run (42:38) shows an audience-submitted skill flagging stale todos and hotspot files using git-backed evidence.
Governance is unsolved. An audience member described 60 engineers already diverging: shared skills accumulate merge-request overhead, forking produces near-identical duplicates, and model upgrades can make verbose skills actively worse. Nick’s rule: keep CLAUDE.md tiny; put task-specific context in skills that load only when needed.
Making Skills Smarter: Progressive Disclosure and Confidence Scoring
Progressive disclosure keeps context windows clean. A skill can reference sub-documents by path and instruct the model to load them only when the current task requires it. WorkOS uses this in their public skills repo: a skill router maps “installing AuthKit into Next.js” to the specific reference file, loading nothing else.
Nick’s ideation plugin adds confidence scoring. The ideation skill confidence scoring demo (01:01:01) shows the model scoring itself across problem clarity, goal definition, and scope boundaries before starting work. One-sentence prompt yielded a score of 90 out of 100; two clarifying questions pushed it to 96, then it generated a full spec.
Skills Beyond Code: Evals, Automation, and Cross-Team Use
Skills are not only for developers. WorkOS ran one with a recruiting team in Claude Desktop: the skill pulled candidate data from Slack, Notion, and their ATS, then assembled a structured report. Non-technical teammates loaded and ran it without a terminal. Blog writing, CI/CD pipelines, and image generation all follow the same pattern.
Evals matter. WorkOS ships an eval framework that runs Claude with and without the skill, then fails the build if accuracy drops. Nick found over-prescribing Next.js behavior caused a 30% drop. The Nana Banana image-to-video animation demo (01:10:41): a 30-line skill chains Imagen3 and Veo to produce a finished animation in 30 seconds.
Q&A
Where do you draw the line between putting something in CLAUDE.md versus making it a skill? Keep CLAUDE.md tiny and universal (e.g., one line: ‘use pnpm’); move anything task-specific to a skill so it only loads when actually needed, and let Claude’s own skill-builder analyze past sessions to suggest what to split out. ▶ 20:09
How do 60 engineers share and govern a growing library of skills — who reviews changes and keeps them from proliferating? WorkOS publishes generic skills via a public GitHub repo installable with npx, keeps internal skills in a monorepo, and accepts that forking is sometimes the right answer; they acknowledged governance tooling is still evolving and painful. ▶ 22:34
Do you run formal skill evaluations, and how do you handle models ignoring a skill when too many are loaded? WorkOS runs an eval framework that grades Claude with and without the skill on a rubric and tracks whether the skill adds at least 1-2% accuracy; for skill pickup, they rely on precise descriptions plus explicit slash-command invocation as a fallback. ▶ 29:31
Notable Quotes
And skills are that next step. Zack Proser · ▶ 5:10
That’s what a skill is. You’re teaching Nick Nisi · ▶ 7:36
This is my cla.md. It’s extremely small. Nick Nisi · ▶ 21:12
Key Takeaways
- Skills encode repeatable work as versioned markdown files that load only when the task matches, keeping context windows small.
- Descriptions are routing rules for the LLM, not documentation for humans — a precise description is what triggers automatic skill selection.
- Progressive disclosure and confidence scoring let skills load sub-documents on demand and block execution until the model has enough clarity to proceed.