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. It deals with a familiar problem in AI coding: big “agentic” bundles promise a lot, but real projects still need crisp requirements and boring verification. The takeaway is simple: keep the spec deterministic, then let Claude Code, Anthropic’s coding agent, argue with it at the edges. The interesting Claude Code angle is how Yamlet makes the anthropic claude code 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.”

The trap is turning 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. The claude code 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 “claude code hooks events list 2026” as a pointer, not an authority.

A small hook boundary for a Yamlet repo might be:

The trap is using 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.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.

Practical starter checklist

- [ ] Name the Claude Code artifact first: a hook boundary, an MCP permission note, a slash-command workflow, a Claude skill outline, a review checklist, or a concise CLAUDE.md note when repository memory is the topic.
- [ ] Write the review checklist before generation starts: scope, owner, tests, rollback.
- [ ] Keep the first step small enough that a reviewer can inspect the receipt without replaying the whole chat.

Common questions

• What should teams know about claude code hooks?

  Start by writing down one visible team rule for Claude Code, not a loose preference. That is the practical core of claude code hooks. That usually means a short repository convention, a review checklist, and one owner who can reject agent output when the evidence is missing.

• Which Claude Code artifact should teams standardize first?

  Standardize the smallest artifact that reviewers already touch: a hook checklist, MCP permission rule, slash-command workflow, skill outline, or concise CLAUDE.md note. The point is not documentation volume; it is a shared place where scope, allowed tools, expected tests, and rollback notes are visible before generated code reaches review.

• How do teams know the convention is working?

  The convention is working when reviewers can approve or reject agent output from the artifact and evidence alone. Track whether pull requests name the rule used, include the promised checks, and avoid replaying long sessions just to understand what changed.

Best ways to use this research

• Best for: Claude Code teams deciding which hook, skill, MCP boundary, slash-command workflow, review habit, or repository-memory convention to standardize next around “Yamlet Makes Agent Specs Smaller.”
• Best first artifact: turn the named fix into a hook checklist, skill note, MCP permission note, review receipt, or concise CLAUDE.md convention when repository memory is the real topic before the next automated run.
• Best comparison angle: compare the workflow against the current Claude Code handoff, hook behavior, and MCP scope; keep the path that leaves the shortest auditable trail.

Further reading

• Yamlet — source
• Claude Code — hooks
• Anthropic — Claude Code product page
• Claude Code docs: en getting started

What to do next

Take this into the related training topic and test whether a new reviewer can defend the merge without replaying the chat.