Claude Agent Skills Best Practices: Writing SKILL.md Files That Actually Work
Claude Agent Skills let you give an agent reusable, model-invoked expertise through plain `SKILL.md` files. They are deceptively simple — and most of them fail for the same handful of reasons: vague descriptions, oversized scopes, and loading everything at once. These are the **Claude Agent Skills best practices** that separate skills the model actually invokes from files that just sit in a folder.
Claude Agent Skills Best Practices: Writing SKILL.md Files That Actually Work: Claude Agent Skills let you give an agent reusable, model-invoked expertise through plain `SKILL.md` files. They are deceptively simple — and most of them fail for the same handful of reasons: vague descriptions, oversized scopes, and loading everything at once. These are the **Claude Agent Skills best practices** that separate skills the model actually invokes from files that just sit in a folder. Designed as a zero-dependency, open-source TypeScript architecture under the MIT License with native Model Context Protocol (MCP) support and deterministic phase state machines.
- The description is the API: the model chooses a skill from its frontmatter description, so write it like a routing trigger.
- Progressive disclosure wins: keep SKILL.md small, push depth into referenced files loaded only when needed.
- One skill, one job: narrow scopes are invoked correctly far more often than sprawling "do-everything" skills.
- Know the boundaries: Skills vs MCP vs subagents vs commands each solve a different problem.
---name: deploy-previewdescription: Deploy the current branch to a preview URL and report it. Use when the user asks to preview, stage, or demo changes.---# Deploy Preview1. Confirm the branch builds (`npm run build`).2. Run `npm run deploy:preview`.3. Report the preview URL and status.## Rules- Never deploy the `main` branch without confirmation.- If the build fails, stop and surface the error.
Watch: Related Video Guides
Anthropic Just Built an Agentic OS — Open Source Harness Breakdown
Smoke Monkey
Everything You Know About Skills IS OUTDATED
Simon Scrapes
The Anatomy of a Great SKILL.md
Every Agent Skill is a folder containing a SKILL.md with YAML frontmatter and a markdown body. Two fields carry almost all the weight: `name` (a stable, kebab-case identifier) and `description`. The description is not documentation — it is the routing signal the model uses to decide whether to load the skill. Best practice is to state *what it does* and *when to use it* in one or two sentences, including the trigger phrases a user would actually say. A vague description like "helps with deployments" gets ignored; "Deploy the current branch to a preview URL... use when the user asks to preview or demo changes" gets invoked.
Write the Description for Retrieval, Not for Humans
If your description does not contain the words a user would say when they need the skill, the model will not reach for it. Include concrete trigger terms.
Progressive Disclosure and Context Engineering
The biggest mistake is dumping everything into SKILL.md. The model pays for every token it loads, and oversized skills crowd out the task itself. Treat the skill like a context-engineering hierarchy: keep SKILL.md to the core instructions and a map, then split deep reference material into sibling files the skill links to, so they load only when the task needs them. This mirrors how subcontext memory keeps long-running agents coherent. In 2026 the best skills read like a tight runbook, not a textbook.
Skills vs MCP vs Subagents vs Commands
These four primitives are constantly confused. Skills are reusable *knowledge and procedures* the model loads into context. MCP is a *transport and capability* layer that connects the agent to external tools and data. Subagents are *delegated workers* with their own context window. Commands are *explicit user-invoked* shortcuts. A deployment "how-to" is a Skill; the ability to actually call your CI API is MCP; running a long research task in isolation is a subagent. For a side-by-side breakdown, see Claude agent skills vs MCP.
Testing, Versioning, and Sharing Skills
A skill you have not tested is a rumor. Test skills the same way you test prompts: give five realistic prompts and confirm the model invokes the skill and follows it. Version them in git next to the code they operate on, and review changes like any other source. When sharing, prefer small, single-purpose skills over bundles; a directory of focused skills composes better and lets consumers load only what they need. If you are building a product that needs this exact pattern, Smoke Monkey Harness uses the same SKILL.md convention and pairs each skill with permission-gated tools so invoked skills cannot exceed their authority.
import { createAgent } from 'smoke-monkey-harness';// Skills load on demand; the model selects them by frontmatter descriptionconst agent = createAgent({provider: 'anthropic',model: 'claude-3-7-sonnet',workspacePath: process.cwd(),skillsDir: './.skills', // folder of SKILL.md filespermissions: { write_file: 'ask', run_command: 'ask' },});await agent.run('Please preview my current branch');
Frequently Asked Questions
Q:What is the single most important part of a Claude Agent Skill?
The frontmatter description. The model uses it to decide whether to load the skill, so it must state both what the skill does and the situations that should trigger it.
Q:How long should a SKILL.md file be?
Keep it short — a focused runbook. Push deep reference material into referenced files that load only when needed, following the progressive-disclosure pattern.
Q:When should I use a Skill instead of MCP?
Use a Skill for reusable knowledge and procedures loaded into context. Use MCP when the agent needs to actually call an external tool or data source. Many agents use both together.
Q:Does Smoke Monkey Harness support Claude Agent Skills?
Yes. Smoke Monkey Harness reads the same SKILL.md convention, loads skills on demand, and combines them with permission-gated local tools so skills stay within their intended authority.
Related Alternatives & Comparisons
Claude Agent Skills vs MCP: What Is the Difference? (Free Open Source Guide 2026)
Claude Code Runtime Alternative: Open Source Stdio MCP Agent Harness
LangChain TypeScript Alternative: Zero Dependencies & Deterministic Loops
Related Architecture Guides
View all guidesBest Open Source Coding Agents in 2026: Free, Local & Fully Hackable Harnesses
MCP Server Security Best Practices: Hardening Model Context Protocol Agents in 2026
Open Source Coding Agent Harness: Build a Forkable, Local AI Engineering Runtime
Build with Smoke Monkey Harness
Zero dependencies. 24 built-in tools. Human-in-the-loop safety. 100% open source under the MIT License.