Yamlet Makes Agent Specs Smaller
Yamlet is Ricardo Monteiro Simões’s open-source toolkit for writing small YAML specs that agents can challenge, check, and turn into Gherkin feature files. Big “agentic” bundles promise a lot, but real projects still need crisp requirements and boring verification. Keep the spec deterministic, then let Claude Code argue with it at the edges. The interesting Claude Code angle is how Yamlet makes Anthropic's own hooks documentation feel concrete: hooks are useful when they guard a boundary, not when they try to replace judgment.
Yamlet is a minimal, single-source-of-truth spec format for spec-driven development with agents. As of July 31, 2026, the repository is mainly TypeScript, MIT licensed, and published as a self-contained binary for macOS and Linux, including Intel and Apple Silicon / arm64 builds. The README also describes it as a Claude Code plugin, which is where the project becomes more than “yet another YAML file.”
Why a tiny spec file got attention
The small trick in Yamlet is scope. One component gets one .yamlet.yaml file, one contract, a handful of requirements, and EARS-style acceptance criteria. That is a good constraint because agents are very good at expanding ambiguity and very bad at noticing when the expansion no longer matches the thing you meant.
A real example is something like email_service.yamlet.yaml. Instead of asking an agent to “design email sending,” the file narrows the work to one service contract, the requirements it must satisfy, and acceptance criteria that can become test material. Yamlet’s examples include generated feature files from those criteria, so the spec is not just prose for a chat transcript.
That is why the Show HN post landed with developers who are tired of all-in-one agent packs. The pitch is not “trust the agent.” It is closer to “give the agent a small surface to dispute, then make the result checkable.”
Don't turn the format into a new dumping ground. If a .yamlet.yaml file grows into a product brief, architecture decision record, and test plan at once, the useful constraint is gone.
Let the skill challenge the contract
Yamlet’s Claude Code piece is interesting because it treats the agent as a sparring partner. The human writes the minimum contract. The skill can then press on missing cases, fuzzy requirements, and acceptance criteria that sound testable but are not.
For example, a spec might say an email service “should retry failed sends.” A useful agent challenge is not to generate a retry implementation immediately. It should ask what failures count, how many attempts are allowed, whether duplicate delivery is acceptable, and what observable behavior proves the requirement.
That is a healthier use of Claude skills than packing a plugin with a giant instruction blob. Skills are best when they carry a repeatable workflow: inspect this artifact, challenge it in this way, produce this kind of output. Yamlet gives the skill a compact artifact to work against.
The objection is fair: YAML formats can become ceremony. Yamlet is worth trying only if the acceptance criteria actually flow into checks, feature files, or review evidence. If the file exists just to make agent prompting feel disciplined, a plain issue template may be enough.
Put Claude Code hooks around the boring checks
Claude Code hooks are deterministic commands that run at defined lifecycle points, such as before or after tool use, so a project can enforce local checks outside the model’s discretion. That matters for a project like Yamlet because the agent can debate requirements, but it should not get to decide whether a spec parses or whether generated files changed unexpectedly.
A clean boundary is: let Claude help write or revise *.yamlet.yaml, then use hooks to run the mechanical checks. Anthropic's hooks documentation and hooks reference are the right place to verify current hook types and event names, especially because teams often copy stale examples from old posts. As of August 2026, treat any unofficial list of hook events from 2026 as a pointer, not an authority.
A small hook boundary for a Yamlet repo might be:
| Boundary | Hook intent | Example check | Why it belongs outside the agent |
|---|---|---|---|
| Before editing specs | Protect generated files | Block direct edits to features/generated/** |
Generated output should come from the spec path |
After editing *.yamlet.yaml |
Validate structure | Run Yamlet’s validation command or project wrapper | Parsing is deterministic |
| Before commit | Detect drift | Regenerate feature files and fail on diff | The repo should not carry stale acceptance criteria |
| Before running tests | Keep scope small | Fail if one spec references unrelated components | Yamlet’s value depends on small contracts |
Don't use hooks as a second agent. A hook should be boring, fast, and explainable. If it needs taste, context, or product judgment, make Claude review it in chat or in a slash command instead.
This is also where Claude Code conventions help. Keep the durable rule small: “Specs live in specs/*.yamlet.yaml; generated feature files are not hand-edited.” Put that in the repo’s normal memory or contribution notes, then let the hook enforce the part a shell command can prove. For more patterns like this, see the related Claude Code team conventions topic.
Try Yamlet safely on one boundary
Do not start with your most complex domain model. Pick one component where the behavior is already half-known and annoying to restate: password reset email, invoice numbering, webhook signature validation, or CSV import error handling.
Create one .yamlet.yaml file and ask Claude Code to challenge only the acceptance criteria. Then generate the Gherkin feature file and review the diff as if it came from a junior developer: useful, maybe incomplete, never automatically correct.
A safe first experiment looks like this:
- Pick one component with a narrow public contract.
- Write no more than five requirements.
- Add EARS-style acceptance criteria for each requirement.
- Ask the Yamlet skill to find ambiguity, not to implement code.
- Regenerate feature files from the spec.
- Add one hook that fails when generated feature files drift from the spec.
- Delete the experiment if the spec is harder to read than the tests it creates.
Yamlet is a fit when acceptance criteria are valuable and repeated. It is probably overkill for throwaway scripts, UI copy tweaks, or codebases where tests already describe the behavior cleanly.
A related pattern showed up in agent-manager Puts AI Agents in tmux: the useful part was not more autonomy, but a smaller control surface. Yamlet has the same smell. It makes the work visible before the agent starts improvising.