agentsnippet: Reuse AGENTS.md and CLAUDE.md instructions

Most reusable coding-agent instructions should be packaged as skills, but AGENTS.md still has a job. It tells the agent which skills the project expects it to use and when to use them. A repository may have a rule like this:

Before committing, use the `$branch-review-subagent-loop` skill to review the
complete branch diff.

The skill holds the review workflow. AGENTS.md connects that workflow to the repository's delivery policy. When the same rule applies to several projects, I end up copying it into each instruction file. The duplication grows when repositories share several skill invocations and approval rules.

That works until one copy changes. I improve the rule in one project, forget the others, and eventually have several versions of what was supposed to be the same instruction.

Plain Markdown is part of the appeal of AGENTS.md and CLAUDE.md, but Markdown has no standard include mechanism. I wanted to reuse source text while keeping the instruction files that coding agents already understand.

Generate instruction files from snippets

I made agentsnippet for this job. It reads AGENTS.template.md and CLAUDE.template.md, expands snippet directives, and writes ordinary AGENTS.md and CLAUDE.md files beside the templates.

The template holds the source text, while the coding agent reads the generated file. agentsnippet uses the template itself instead of a separate configuration file. The coding agent needs no special support for includes.

A small example using the magic folder

Create a personal snippet at ~/.agents/agentsnippets/review.md:

## Review gate

Before committing, use the `$branch-review-subagent-loop` skill to review the
complete branch diff.

Then create AGENTS.template.md:

# Project instructions

This repository contains the application source.

<!-- @agentsnippet "@/review.md" -->

The @/ prefix points to the agentsnippet magic folder at ~/.agents/agentsnippets, so the same personal snippet can be included from templates in different projects.

Run agentsnippet from the project directory:

npx agentsnippet

It writes AGENTS.md with the directive replaced by the contents of review.md:

# Project instructions

This repository contains the application source.

## Review gate

Before committing, use the `$branch-review-subagent-loop` skill to review the
complete branch diff.

The same command also handles CLAUDE.template.md. If both templates exist in a directory, it generates both outputs in one run.

For a repository with templates in several folders, use recursive discovery:

npx agentsnippet -r

You can also check whether generated files are current without changing them:

npx --yes agentsnippet@latest --check -r

In CI, that command catches a changed template or snippet whose generated instruction file was not updated.

Let your coding agent manage agentsnippet

The repository also has an optional agentsnippet skill for coding agents. Install it globally for Codex:

npx skills add favoyang/agentsnippet -g -a codex -y

The skill teaches the agent to work from authoritative templates, generate the output files, and verify that they are current. When setting up agentsnippet in a repository, the agent can use the skill to decide whether an instruction belongs in the local template, the magic folder, or a remote source. It also checks for direct edits before generation so existing work is preserved.

Choose where shared snippets live

Use a relative path such as ./.agents/testing.md when the snippet belongs to the repository. agentsnippet resolves it from the file containing the include. Absolute paths and paths beginning with ~/ point to snippets elsewhere on the same machine, while the @/ magic folder gives personal snippets a shorter name. If the instructions need to travel with a team or across machines, use an HTTP or Git source. Snippets can include other snippets too.

The agentsnippet README documents installation, source formats, recursive discovery, CI checks, and the optional agent skill. The v1 specification covers the exact directive grammar, limits, error behavior, and security model.

Each project keeps a plain AGENTS.md or CLAUDE.md that compatible coding agents can read. The shared instructions have one home in reusable Markdown snippets. When a rule changes, I regenerate the ordinary instruction files instead of hunting down every copy by hand.

To comment and continue discussing this article, please comment on the X Article.