Skills

Skills are reusable instruction bundles that Claude loads on demand rather than upfront. At startup only the skill's name and description are read, roughly 100 tokens each, so you can maintain dozens of skills without bloating your context window. When Claude judges a task relevant to a skill, it pulls the full instructions in. That's the core idea: progressive disclosure keeps idle knowledge cheap and active knowledge precise.

A skill lives in a SKILL.md file (with YAML frontmatter) inside a .claude/skills/ directory: user-level at ~/.claude/skills/ for skills that follow you everywhere, project-level at .claude/skills/ for skills scoped to a repo. Claude reads the description at session start and decides on its own when to invoke, so engineers using the project don't need to know the skill exists. Skills go beyond code: database query patterns, API call conventions, meeting templates, personal workflows, any repeated context you'd otherwise re-explain each session.

How you use it day-to-day

• Create a skill file. Add a SKILL.md in .claude/skills/<name>/SKILL.md. Write a YAML frontmatter block with at minimum a name and description (the description is the trigger signal Claude uses to match), then put the full instructions in the body.
• Write precise descriptions. The description is what Claude reads to decide if this skill applies. Vague descriptions miss matches; overly broad ones fire on everything. Aim for a single crisp sentence that names the domain and the condition.
• Use strong directives in the body. Write MUST, ALWAYS, NEVER rather than "consider" or "try to." Claude follows directives; it negotiates suggestions.
• Invoke by name for guaranteed activation. Reference the skill name directly in your prompt (/my-skill) to force-load it when you know it's relevant and don't want to rely on Claude's match.
• Distribute via shared directories or a repo. At Hedgineer, domain teams own skill files in a shared repo organized by vertical (AI, Data, Infra, UI); engineers symlink or clone them into their user-level ~/.claude/skills/. Best practices scale with encoding quality, not headcount.
• Let skills reference each other. A UI skill can point to a Data skill for schema conventions, and Claude follows the chain. This builds a network of expertise that activates automatically.
• Learn from published skill sets. Matt Pocock open-sourced his own .claude skills, including a TDD skill that forces only the tests which validate real behavior (not implementation-coupled noise) and a /teach skill that turns Claude into a tutor on any topic. Reading working skills is the fastest way to calibrate your own. Claude Code also ships built-in skills like /simplify and /batch (see Slash Commands).

Gotchas

• Description quality is everything. A weak description means the skill never fires, or fires at the wrong time. Treat it like a search query; test it against real tasks you'd expect to trigger it.
• Maintenance is real. Skills drift as patterns change. Establish a feedback loop: when a skill produces wrong output, update it immediately. Stale skills are worse than no skills: they silently inject outdated guidance.
• Skills are loaded per session, not per message. If you add a new skill file mid-session, restart the session to pick it up.
• Don't over-scope. One skill per domain concern is cleaner than one omnibus skill. Narrow skills compose; giant skills conflict.

Skills vs CLAUDE.md: CLAUDE.md is always-on context (project conventions, personas, standing instructions). Skills are on-demand; they activate when relevant. If something should always be in scope, put it in CLAUDE.md. If it's only needed for a class of tasks, make it a skill.