Claude Code Skills Are Just Markdown Files—Here's How to Write One That Actually Works
Claude Code's Skill system turns one-off prompting into reusable, version-controlled workflows, but its probabilistic trigger means developers who treat it like a deterministic config system will ship unreliable automation. Understanding the boundary between Skills and hooks—and the maintenance discipline that makes a Skill improve over time—is what separates a working setup from a context-burning mess.
Claude Code Skills package a repeatable workflow into a single markdown file stored in `.claude/skills/`. The mechanism uses progressive disclosure: only the short `description` field loads into every conversation, and the full body—the actual instructions—loads only when semantic matching decides the Skill is relevant. That design makes context-window efficiency the first-order constraint; a Skill that tries to be comprehensive burns tokens and degrades matching accuracy.
The biggest beginner mistake is getting the trigger backwards. The `description` field controls when Claude invokes the Skill, not the body. Trigger words must be specific enough to match reliably but sparse enough to avoid false positives. Manual invocation via `/skillname` bypasses the probabilistic matching entirely and is the most reliable way to test.
A Skill is pure text with zero replication cost, so the real moat is the methodology around it: knowing which workflows are worth codifying, how to decompose them into model-actionable steps, and the discipline to manually feed execution results back into the file. The article draws a hard line between Skills (probabilistic, for reusable SOPs) and hooks (deterministic, for mandatory intercepts like blocking dangerous commands).
Progressive disclosure isn't just a performance optimization—it's a design constraint that forces Skills to be small. A long Skill body doesn't just waste tokens; it pollutes the context window and makes semantic matching less reliable, so verbosity directly undermines the mechanism.
The probabilistic nature of Skill triggering creates a category error risk: developers accustomed to deterministic config systems may treat Skills as guaranteed to fire, when in practice they require the same maintenance discipline as any ML-based classifier.
The claim that 'the Skill file itself has no moat' is correct but incomplete. The moat is the feedback loop—manually writing execution results back into the file—and that loop requires organizational discipline most teams lack, which is precisely why it's a moat.
The distinction between rules, Skills, and hooks maps cleanly to different failure tolerances: rules for norms you want always present, Skills for SOPs where occasional misses are acceptable, and hooks for anything where a miss is a security or data-loss event.
The discussion centers on whether a Skill offers advantages over a plain SOP document for a fixed deployment pipeline. The original commenter found that an Agent missed steps when using a Skill, questioning if forcing a Skill is pointless here. The reply argues both methods load the same context, so the gap likely comes from an incomplete Skill description rather than a fundamental flaw, and recommends adding strict error-handling instructions. A secondary question about language impact draws the advice to pair a Chinese description with an English body for maximum compliance, though the author personally maintains all-Chinese Skills and iterates on them.
Learned a lot, thanks big bro [seductive][seductive] Regarding the use cases for Skills, I have a more practical question: I currently have a process for deploying a project to a test server. Previously, I always managed it with an SOP document that details steps like local packaging, backing up old files, uploading, replacing, restarting, and verifying. Since this process is quite fixed and each step has a clear sequence, I felt the original SOP was sufficient. But later I tried writing this process as a Skill, and instead found that the Agent occasionally missed or skipped steps during execution. The execution effect felt worse than just having it follow the SOP directly. So in this scenario, is it actually unnecessary to force the use of a Skill? What types of problems are Skills better suited for? Also, a more curious question: Does the language of a Skill affect the Agent's compliance? For example, foreign models generally seem to follow English instructions more stably. If a Skill is written in Chinese, could there be some difference in instruction following? [grin]
It's like how a feature can have multiple implementations. The deployment task also has different approaches: CI/CD, having the agent deploy according to an SOP document, or writing a Skill. Regarding the two methods you mentioned, the essence is both involve having the agent refer to a standard process for deployment. The difference is that a Skill can be triggered automatically via semantics, whereas having the agent deploy according to an SOP document requires typing 'Deploy according to the SOP document' into the prompt each time. Theoretically, if the body of the SKILL.md is identical to the SOP document content, the effect of writing a Skill and directly saying 'Deploy according to the SOP document' in the prompt is the same. Both will load the process content into the context for the agent to execute. My guess for why this happened is that the SKILL.md simply described it as: 'Follow the process: local packaging, backup old files, upload, replace, restart, verify.' I suggest checking if the description is complete and accurate, and adding a description like: 'Follow the process strictly. If an error occurs at an intermediate step, do not skip it. Check the logs, output the reason and solution, and let the user decide which step to take next.' As I said in the article, Skills are suitable for recording the process of doing a certain type of thing, so you don't need to repeatedly emphasize the process next time. Using an agent and an SOP document to manage deployment shares a similar philosophy with Skills. As for whether the Skill's language affects the agent's compliance, most technical documentation used during model training is in English, so it is relatively more adaptable to English. If you usually use the agent in Chinese and have very high requirements for Skill instruction following, I suggest using a combination of a Chinese description + an English body. I personally write Skills entirely in Chinese, which is more friendly for me when writing Skills. Even if I encounter instruction non-compliance issues, I will optimize the Skill for that specific case—continuously maintaining and optimizing the Skill is key to writing a good Skill. And that is more advanced content.