agent-baseline

Generates the agent instructions and skills our repositories share, so an improvement made once reaches every repository that updates the package.

Use

Add it as a dev dependency, then generate and commit the result:

bun add -d agent-baseline
bunx agent-baseline generate

generate writes three things:

• A block in AGENTS.md between <!-- agent-baseline:start --> and <!-- agent-baseline:end -->. Everything outside the block belongs to the repository. A file without a block gets one at the end.
• An @AGENTS.md import at the top of CLAUDE.md. Claude Code skips AGENTS.md when a repository has a CLAUDE.md, so the import is what makes it load.
• The chosen skills in .agents/skills/, where Codex reads them, with links from .claude/skills/ for Claude Code. Every skill name agent-baseline ships belongs to it, so give a repository's own skills other names. .agents, .claude, and their skills folders must be real directories, not links.

Add bunx agent-baseline generate --check to the repository's check script. It exits with 1 and lists the files that differ when someone edits generated content by hand or updates agent-baseline without generating. Add .agents/skills/ to the formatter's ignore list at the same time; otherwise the formatter rewrites the copied skills and the two checks never pass together.

Claude Code prefers a personal skill over a project skill with the same name, and Codex lists both. On a machine that installs skills globally, remove the global copies of the skills its repositories install, such as with bunx skills remove -g <name>, so the repository's pinned copies take effect.

Config

A repository that uses the defaults needs no config. Otherwise, add agent-baseline.config.ts at the root with only what differs:

import { defaults, defineConfig } from "agent-baseline";

export default defineConfig({
  skills: [...defaults.skills, "shadcn"],
});

• sections and skills replace the defaults; spread defaults to add to them.
• commands names the package scripts the instructions tell agents to run, merged over the defaults. null removes one, and the instructions that need it are left out. generate fails when a chosen section names a script that package.json doesn't define.

The defaults are in src/config.ts and the section text in src/sections.ts.

Skills

skills/ holds the skills agent-baseline ships, and src/skill-names.ts lists them.

Requires Bun, which runs the CLI and loads the TypeScript config.