Common skill mistakes

Claim-vs-content drift

The description or the opening paragraph promises something the body of the skill does not actually deliver. A skill that says it "handles the full release process" but whose instructions only cover writing a changelog entry is not lying exactly, but it is setting an expectation the content will not meet.

This drifts in slowly, usually because the description was written first as an ambition and the instructions were filled in later, more narrowly than planned, without anyone going back to trim the description to match.

Missing or contradictory frontmatter

• A description field that is empty, missing, or copied verbatim from a template and never edited.
• A name that does not match the folder it lives in, which confuses tooling that keys off one or the other.
• Frontmatter that says one thing and body text a few lines down that says another, for example a description that claims read-only behaviour while the instructions tell the agent to write files.

Frontmatter problems are cheap to find and cheap to fix, but they are also the easiest to miss just by reading the file once, because the eye skips past a header block to get to the "real" content.

Kitchen-sink skills that own no clear job

A skill that tries to cover code review, testing, deployment and documentation in one file usually ends up doing none of them well, and its description has to be so broad to cover all of it that it either over-triggers or reads as generic advice rather than a specific job.

The fix is almost always to split it: one skill per job, each with a description narrow enough to trigger correctly and instructions focused enough that the agent can actually follow them in order.

Instructions that assume tools the agent does not have

A skill written and tested inside one environment can quietly assume things that are not universal: a specific CLI is installed, a particular shell is available, network access is unrestricted, or a certain file already exists in the project. None of that is stated as a requirement; it is just assumed.

When the skill runs somewhere that assumption does not hold, the agent either fails partway through or improvises around a gap the skill never told it was there. Stating the requirement up front, or checking for it as a first step, is a small fix with a real effect on reliability.

Secrets left in files

A skill built by copying a working example sometimes carries along whatever the author had in that project at the time: an API key in a script, a token in a comment, a real database URL in a sample config left in for convenience.

This is the one mistake on this list that is not just a quality problem. It is worth checking any skill folder before sharing it, and stripping obvious secrets is a basic precaution any skill review should take before the content goes anywhere near a model.

A worked example