agent-instructions

Agent Instructions Builder

A builder skill for creating CLAUDE.md, AGENTS.md, GEMINI.md, and related AI coding assistant instruction files at any scope level, for any tool.

When to Use

Invoke this skill when the user:

• Asks to create or write a CLAUDE.md, AGENTS.md, GEMINI.md, or similar file
• Says "set up Claude for this project" or "add agent instructions"
• Asks "what should go in my CLAUDE.md?" or "what belongs in AGENTS.md?"
• Wants a global/user-level configuration file (~/.claude/CLAUDE.md)
• Is starting a new project and wants instruction files from scratch
• Needs multi-tool support (Claude Code + Codex + Gemini + OpenCode reading the same repo)
• Is working in a monorepo and needs parent/child scoping

Quick Reference

Scope	File(s)	Reference
User/global	~/.claude/CLAUDE.md	references/scope-hierarchy.md, references/cookbook/user-global.md
Project root	CLAUDE.md or AGENTS.md	references/scope-hierarchy.md, project cookbook
Personal (gitignored)	CLAUDE.local.md	references/scope-hierarchy.md
Subdirectory / path-scoped	.claude/rules/*.md	references/scope-hierarchy.md, references/cookbook/monorepo.md
Multi-tool project	CLAUDE.md + AGENTS.md + GEMINI.md	references/multi-tool-compat.md

Workflow

Step 1: Diagnose Scope

Ask — or infer from the codebase and conversation context:

• Which level? User-global, project root, monorepo parent/child, or a combination?
• Which tool(s)? Claude Code only, or also Codex, Gemini CLI, OpenCode?

Use the Scope Decision Guide below if unsure.

Step 2: Gather Context

For project-level files, read the codebase first. Check package.json, pyproject.toml, Makefile, README.md — don't ask for things you can discover. Then determine:

• Project type (Python library? TypeScript API? monorepo? agent/plugin?)
• Key commands: build, test, lint, dev server
• Async stance (async-first, sync-first, or mixed)
• Non-obvious constraints or conventions the AI would need to know
• Team or solo? (If solo, personal preferences can go here; if team, use CLAUDE.local.md for personal preferences)

For user-global files, ask the user about:

• Role and primary languages/frameworks
• Communication preferences (verbosity, code vs. prose, etc.)
• Recurring tools and workflows that apply across all projects

Step 3: Select Cookbook Template

Read the relevant file from references/cookbook/ and adapt it to the actual project. Remove sections that don't apply; add project-specific content.

Project type	Template
Python (FastAPI, library, data)	references/cookbook/python-project.md
TypeScript (Next.js, API, CLI, agent)	references/cookbook/typescript-project.md
Monorepo (any language)	references/cookbook/monorepo.md
Agent, MCP server, or plugin	references/cookbook/agent-mcp-project.md
Side project / minimal	references/cookbook/minimal-project.md
User global (~/.claude/CLAUDE.md)	references/cookbook/user-global.md

Step 4: Generate and Write

Quality targets:

Scope	Target length	Key principle
User-global	100–200 lines	Comprehensive personal preferences
Project-level	20–80 lines	Concrete facts about this codebase
Subdirectory rule	5–20 lines	Path-scoped, laser-focused

Every line costs context on every session. Trim ruthlessly — if removing a line wouldn't confuse a new contributor, remove it.

If multiple tools are in use, read references/multi-tool-compat.md before generating.

Write the file(s) to disk at the correct paths, then tell the user where each one lives.

---

Scope Decision Guide

Need agent instructions for...
├── Every project on this machine → ~/.claude/CLAUDE.md  (user-global)
├── This specific project only
│   ├── Solo project                → CLAUDE.md at project root
│   ├── Team project (checked in)  → CLAUDE.md or AGENTS.md at project root
│   └── Personal prefs on a team   → CLAUDE.local.md  (add to .gitignore)
├── Monorepo with distinct sub-packages
│   ├── Spans all packages          → root CLAUDE.md
│   └── Package-specific rules      → CLAUDE.md in that package dir, or
│                                      .claude/rules/<name>.md with paths: frontmatter
└── Multi-tool (2+ AI assistants)
    └── See references/multi-tool-compat.md

---

Anti-Patterns

Avoid these — they make instruction files worse over time:

Anti-pattern	Why it fails	Alternative
Multi-step procedures ("to deploy, step 1...")	Bloats every session; hard to maintain	Move to a skill or a runbook
Large reference material	Expensive on every session	@import or a skill with references/
"Always use X" with no context	Gets ignored; no reasoning to generalize from	Explain the why: "Use X because Y"
Git history or incident notes	Stale fast; belongs in commits	Commit message or ADR
Duplicate content across scope levels	Diverges silently	Use @import to share a single source
Instructions for hypothetical scenarios	Not active constraints	Only write what shapes daily work
Personal preferences in a team file	Pollutes shared instructions	Put personal prefs in CLAUDE.local.md

---

Multi-Tool Quick Guide

For projects used with more than one AI coding tool, read references/multi-tool-compat.md for the full decision matrix. Quick summary:

• Claude Code only → write everything in CLAUDE.md, use @import freely
• Codex only → write everything in AGENTS.md (plain Markdown, no imports)
• Claude Code + Codex → write in AGENTS.md; CLAUDE.md = single line @AGENTS.md
• + Gemini / OpenCode → same as above; add GEMINI.md as a plain-Markdown copy of AGENTS.md (Gemini doesn't support imports)