// the find
mgechev/skills-best-practices
Write professional-grade skills for agents, validate them using LLMs, and maintain a lean context window.
A documentation repo (not a library) laying out conventions for writing Claude-style agent Skills — SKILL.md structure, frontmatter rules for discoverability, and a step-by-step LLM-driven validation workflow. It's aimed at developers building or maintaining Skills for Claude or similar agent frameworks, not at end users of any agent.
The structural rules are concrete and checkable rather than vague advice — 500-line cap on SKILL.md, one-level-deep references/, exact naming regex for the frontmatter name field. The validation section is the most useful part: it gives copy-pasteable prompts for discovery testing, logic simulation, and adversarial edge-case hunting with a fresh LLM, which is a practical substitute for unit tests on something as fuzzy as a prompt file. It also points to a companion eval tool (skillgrade) instead of pretending prose guidance alone is sufficient.
There's almost no code here — scripts/ contains a single metadata linter (validate-metadata.py), so the repo is really a README with a template, and most of its content duplicates Anthropic's own public Skills docs that it links to in the first paragraph. None of the validation workflow is automated or wired into CI; it's manual copy-paste prompts, so nothing stops the guide's own advice from drifting out of date. The opinionated bans (no README.md, no CHANGELOG.md in a skill folder) aren't reconciled with skills that need to be reviewed or maintained by humans, not just loaded by agents.