finds.dev

mgechev/skills-best-practices

Write professional-grade skills for agents, validate them using LLMs, and maintain a lean context window.

View on GitHub

★ 2,268Pythonupdated Jul 2026

// the take

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.

We read the README, the directory tree and a key source file in October 2026. Nobody pays to be listed. How we judge →

// at a glance

Stars
2,268
Forks
166
Language
Python
Last commit
27 Jul 2026

// nearby

If skills-best-practices isn't quite it.

All repos →