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.
A practical tension surfaced around when a Skill is actually the right tool versus a plain SOP document. One experience report found that an Agent skipped steps when executing a deployment Skill, performing worse than when pointed at an SOP. The reply argues the two approaches are theoretically equivalent if the Skill body matches the SOP, and the likely culprit is an incomplete Skill description that needs stricter guardrails. A secondary question about language influence drew the advice that a Chinese description paired with an English body may improve instruction following, though the author personally writes full-Chinese Skills and iterates on them.
Learned a lot, thanks to the big shot [shy][shy] I have a more practical question about Skill usage scenarios: I have a process for deploying a project to a test server. Previously, I always managed it with an SOP document, detailing steps like local packaging, backing up old files, uploading, replacing, restarting, and verification. Since this process is fairly fixed and each step has a clear sequence, I felt the original SOP was sufficient. But later, when I tried to write this process as a Skill, I 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 the 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, would there be some difference in instruction following? [grin]
Just like 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 implementing it by writing a Skill. Regarding the two methods you mentioned, the essence is both having the agent refer to a standard process for deployment. The difference is that a Skill can be automatically triggered by semantics, while having the agent deploy according to an SOP document requires entering the prompt each time: 'Deploy the project according to the SOP document.' Theoretically, if the body of SKILL.md contains the same content as the SOP document, writing a Skill and directly saying 'Deploy the project according to the SOP document' in the prompt should have the same effect. Both will load the process content into the context for the agent to execute. I suspect the issue you encountered is that SKILL.md simply describes: 'Execute according to 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: 'Execute strictly according to the process. If an error occurs at an intermediate step, do not skip it. Check the log, output the reason and solution, and let the user decide which step to take next.' As I mentioned 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 recommend using a Chinese description + English body combination. I usually write Skills entirely in Chinese, which is more friendly for me to write. 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.