{"id":96617,"date":"2026-10-04T09:01:00","date_gmt":"2026-10-04T13:01:00","guid":{"rendered":"https:\/\/overcentral.com\/en\/?p=96617"},"modified":"2026-09-26T09:54:21","modified_gmt":"2026-09-26T13:54:21","slug":"claude-code-skills-96617","status":"publish","type":"post","link":"https:\/\/overcentral.com\/en\/claude-code-skills-96617\/","title":{"rendered":"Claude Code Skills: A Practitioner’s Guide"},"content":{"rendered":"

You know the difference between a junior leaning on Claude Code<\/a> and someone who makes it hum. The junior types commands, gets something that works, and calls it done. The senior builds a skill \u2014 a reference file the agent can follow instead of reasoning from scratch each time. No more inconsistent output, no more watching the same model hallucinate different structures on the same request.<\/p>\n

A skill is a markdown file (typically skill.md<\/code>codecode) sitting inside your project’s .claude\/skills\/<\/code>codecode directory. It opens with YAML front matter: the name, a one-line description that acts as the trigger, and tags. The description is what the agent scans when deciding whether to invoke this skill. Below that, the body: markdown instructions, optional script references, and a template for the output. The entire file is only loaded when the agent’s job matches that description \u2014 so you can stack hundreds of them without slowing a run.<\/p>\n

The problem most people hit: they write a skill that describes<\/em> the outcome but fails to encode the process<\/em>. The agent still guesses at half the steps. That’s where a structured methodology pays off. I’ve iterated through dozens of skills across Claude Code and its siblings, and six patterns consistently separate a skill that works from one that wastes tokens.<\/p>\n

Step 1: Reverse-Engineer the Output<\/h2>\n

Start with a known-good result. Don’t write the skill first and hope the agent lands close. Execute the task manually \u2014 or get a previous version of the output you already approved \u2014 and feed that into the agent with a prompt: “Analyze this output. Reverse-engineer the steps required to produce it from the raw inputs.”<\/p>\n

This forces the model to infer the implicit decision points. You’ll see it surface formatting rules, prioritization logic, and verification steps you never consciously wrote down. Capture those as the skill’s body. If you start from a vague goal (“write a research brief”), you get a vague skill. If you start from a concrete artifact, you get a concrete procedure.<\/p>\n

Step 2: Atomic Tasks, Specific Triggers<\/h2>\n

A skill should own one task, not a department. “Manage the marketing pipeline” is too broad. “Write a weekly social media post from a YouTube transcript” is right. The YAML description must be tight enough that the agent knows exactly when to invoke it. I use a naming convention: research-brief<\/code>codecode, x-article-from-video<\/code>codecode, email-draft-in-style<\/code>codecode. Each gets its own file.<\/p>\n

Inside the body, break the procedure into numbered steps. Each step should produce a checkable artifact \u2014 a file, a summary, a screenshot \u2014 so the agent has a clear milestone. This granularity also makes it easier to chain skills later. You can call one skill to transcribe a video and pipe that output into another skill that formats it as a tweet thread.<\/p>\n

Step 3: Calibrate the Freedom Level<\/h2>\n

Not all skills need the same degree of prescription. A deterministic task \u2014 data extraction, format conversion \u2014 benefits from rigid step-by-step instructions. “Open file X, read column Y, write to CSV with headers A, B, C.” No wiggle room.<\/p>\n

A non-deterministic task \u2014 writing an article, summarizing a debate \u2014 needs guardrails, not scripts. Tell the agent what constraints apply (target audience, tone, source priority) and what a good output looks like, but leave room for judgment. Over-constraining a creative task makes the output generic; under-constraining a mechanical one invites drift.<\/p>\n

The key insight: the same skill file can mix deterministic and non-deterministic sections. You might say “Step 4: Identify the top three sources. Use the following method for ranking. Step 5: Write a 300-word summary. Follow the style guide but adapt to the source material.” The model respects the boundary because you defined it.<\/p>\n

Step 4: Build Verification Into the Skill<\/h2>\n

The most common failure mode: the skill produces output that looks plausible but fails a basic quality check. A skill without a verification step is a half-baked tool.<\/p>\n

Add a section at the end: “After completing the output, run the following checks. For each check, either pass\/fail or report the result.” Objective checks are easy: “Confirm every claim has a citation.” “Verify the word count is between 500 and 600.” Subjective checks require a prompt: “Read the article aloud. Does it flow logically? If not, rewrite the transitions.”<\/p>\n

You can go further: have the same agent or a second agent review the output against the original skill instructions. This “LLM-as-judge” loop catches both formatting errors and logical gaps. I often include a boilerplate verification step: “Open the output file, render it, and take a screenshot. Confirm no visual artifacts.” The agent can use browser tools to do this.<\/p>\n

Over time, you’ll update the verification section based on observed failures. Every time you notice the agent made a mistake, add a line to the pitfalls area. That list becomes the institutional memory of your skill.<\/p>\n

Step 5: Down-Model Aggressively<\/h2>\n

Most people run every skill on the largest model they can access. That’s expensive and often unnecessary. A well-written skill \u2014 one that encodes the procedure precisely \u2014 can produce acceptable results on a cheaper model.<\/p>\n

Build and debug the skill on a capable model (Claude Opus or GPT-4 class). Once it works consistently, drop down to a smaller model (Claude Haiku, GPT-4o-mini). Run the same test cases. If the output degrades \u2014 less structure, more hallucination \u2014 move up one tier. I’ve seen skills that require Opus for the verification loop but run the main generation on Haiku with no loss.<\/p>\n

This isn’t one-size-fits-all. A skill heavy on browser interaction or dynamic code execution may need a larger model’s context window. But the principle holds: test the floor before settling on the ceiling.<\/p>\n

Step 6: Treat Every Run as a Training Cycle<\/h2>\n

A skill is never “done.” Each time you run it, scan the output for improvements. Did it format the report correctly but miss the executive summary? Tell it: “Update the skill to always include an executive summary as the first section.” Then ask the agent to edit the skill file itself.<\/p>\n

This “bike method” \u2014 analogous to teaching a kid to ride, with constant feedback and incremental adjustments \u2014 compounds over time. After ten iterations, the skill encodes not just the process but the edge cases you’ve encountered. It learns from its mistakes because you recorded them in the file.<\/p>\n

I use a simple protocol: after each run, type “Feedback for skill: [what worked, what didn’t]. Update the skill file accordingly.” The agent reads its own output, identifies the gap, and rewrites the relevant section. Next run, the fix is permanent.<\/p>\n

Where Skills Live and How to Deploy<\/h2>\n

In Claude Code, skills live under .claude\/skills\/<\/code>codecode. Each skill is a subdirectory with a skill.md<\/code>codecode file. You can also include a scripts\/<\/code>codecode folder for helper code and a templates\/<\/code>codecode folder for output skeletons. The agent loads them lazily \u2014 it only reads the description front matter of all skills until a job matches, then it opens the full file.<\/p>\n

Deployment is as simple as copying the folder into your project. For shared teams, you can version-control<\/a> the skills directory. Alternatively, Claude Code supports global skills stored in a user-level configuration path, so the same skills are available across all your projects.<\/p>\n

To test a new skill, run a known input and compare the output to your manual baseline. I keep a test suite of three to five cases that cover the range of inputs the skill should handle. If the skill passes all of them on two different models, it’s ready for production.<\/p>\n

Common Failure Modes<\/h2>\n

Description too vague.<\/strong> The agent doesn’t invoke the skill because the one-liner doesn’t match the job it parsed. Write the description as a beam \u2014 “Use this skill when the user asks to convert a YouTube video into an X (Twitter) article” \u2014 not a fuzzy category.<\/p>\n

Instructions too loose.<\/strong> The agent follows the letter but not the intent. Tighten the procedural steps. If the output still varies, add a verification step that enforces a fixed structure.<\/p>\n

No edge-case handling.<\/strong> The skill works on the happy path but breaks on empty inputs, conflicting sources, or missing data. The pitfalls section is the right place to document these. Each failure you catch becomes a guardrail.<\/p>\n

Over-optimization too early.<\/strong> Don’t fine-tune the skill for the 5% edge case before it works consistently on the 95% common case. Ship the 80% version, run it for a week, then iterate.<\/p>\n

Where the Field Is Going<\/h2>\n

The next evolution is skill composability \u2014 chaining multiple skills into a workflow that runs unsupervised. Claude Code now supports a runbook<\/code>codecode concept where you sequence skills with conditional branching. Instead of a single monolithic skill, you write small, testable modules and wire them together.<\/p>\n

The teams that master this will build internal agent libraries that encode their entire standard operating procedures. New hires don’t need to learn tribal knowledge from a human; they invoke the same skills the senior team uses. The bottleneck shifts from knowing what<\/em> to do to knowing which<\/em> skills to compose and when<\/em> to override them.<\/p>\n

That’s a much more interesting problem \u2014 and one that no skill file can solve alone.<\/p>\n","protected":false},"excerpt":{"rendered":"

You know the difference between a junior leaning on Claude Code and someone who makes it hum. The junior types commands, gets something that works, and calls it done. The senior builds a skill \u2014 a reference file the agent can follow instead of reasoning from scratch each time. No more inconsistent output, no more […]<\/p>\n","protected":false},"author":7,"featured_media":99120,"comment_status":"closed","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"fifu_image_url":"https:\/\/cards.overcentral.com\/cards\/en\/96617.png","fifu_image_alt":"Claude Code Skills: A Practitioner's Guide","footnotes":""},"categories":[31],"tags":[],"class_list":["post-96617","post","type-post","status-publish","format-standard","has-post-thumbnail","category-technology"],"fifu_image_url":"https:\/\/cards.overcentral.com\/cards\/en\/96617.png","fifu_image_alt":"Claude Code Skills: A Practitioner's Guide","_links":{"self":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts\/96617","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/users\/7"}],"replies":[{"embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/comments?post=96617"}],"version-history":[{"count":0,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts\/96617\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/media\/99120"}],"wp:attachment":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/media?parent=96617"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/categories?post=96617"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/tags?post=96617"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}