How to write agent skills that don't hallucinate or hog tokens

What it does

This guide defines how to package domain expertise into agent “skills” — structured bundles of instructions, scripts, and references that LLM agents can discover and execute. It enforces a rigid directory layout with a single SKILL.md brain under 500 lines, supported by flat subdirectories for scripts/, references/, and assets/. The goal is to keep the context window pristine by loading details only when needed, while ensuring agents don’t hallucinate steps or fire on the wrong prompts.

The interesting bit

The unusual angle is using LLMs to adversarially validate LLM skills. The guide includes explicit prompt templates to make an LLM act as a QA tester, a logic validator, and an architecture refiner — essentially treating skill development like test-driven development where your test suite is another instance of the model. It also mandates “negative triggers” in metadata descriptions so agents know when not to use a skill, which is a rare bit of defensive API design.

Key highlights

• Rigid structure: SKILL.md must stay under 500 lines; supporting files live exactly one level deep in scripts/, references/, or assets/.
• Frontmatter rules: skill name must match the directory name exactly; descriptions must include negative triggers to avoid false positives.
• Progressive disclosure: instructions use just-in-time loading with explicit relative paths rather than stuffing context into the main prompt.
• Deterministic scripts: fragile or repetitive logic moves to tiny CLI scripts in scripts/ instead of asking the LLM to generate code from scratch.
• Validation by LLM: includes prompt templates for discovery testing, logic simulation, edge-case probing, and architecture refinement.

Caveats

• This is a concentrated guide, not a comprehensive spec; the README explicitly redirects readers to Claude’s official docs for full coverage.
• The validation steps are manual LLM prompts, not an automated framework — the repo itself contains no tooling to run the tests.
• The agentskills.io spec is referenced but not defined here; you’ll need external context to understand the underlying standard.

Verdict

Worth reading if you’re building agent platforms or authoring reusable skills for LLM agents and need a battle-tested structure. Skip it if you’re looking for a library or CLI tool; this is pure methodology and prompt templates.