--- name: agent-instructions-f1011c11f6b7 description: > Use whenever creating OR editing CLAUDE.md, AGENTS.md, GEMINI.md, a SKILL.md, or any other file whose job is to instruct an AI coding agent, at any scope level (user/global, project root, parent folder, subdirectory, or a skill/runbook in a plugin repo). Covers scope diagnosis, content taxonomy, multi-tool compatibility for Claude Code, Codex, Gemini CLI, and OpenCode, cookbook templates for Python, TypeScript, monorepo, agent/MCP, and minimal projects, and the RED-GREEN editing discipline for revising instructions/skills/ runbooks that already exist. Invoke when the user asks to "create a CLAUDE.md", "set up Claude for this project", "what should go in my AGENTS.md", "write agent instructions", "help me set up my global Claude configuration", "edit this skill", "update this runbook", "add a rule to AGENTS.md", or any similar request — even without explicit mention of CLAUDE.md or AGENTS.md. If the user is starting a new project or onboarding into an existing one and no instruction file exists, proactively suggest creating one. metadata: last_updated: "2026-08-23" --- # Agent Instructions Builder A builder skill for creating and editing `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `SKILL.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 - Is **editing** an existing `CLAUDE.md`/`AGENTS.md`, `SKILL.md`, or runbook — adding a rule, correcting one, or moving content between files ## 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` | | **Editing** an existing instruction file, skill, or runbook | `references/editing-discipline.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. ### Editing an Existing Instruction File, Skill, or Runbook Creating from scratch and revising something that already exists are different jobs. Before adding, correcting, or moving a rule in a `CLAUDE.md`/`AGENTS.md`, a `SKILL.md`, or a `references/*.md` runbook, read [`references/editing-discipline.md`](references/editing-discipline.md) — the RED-GREEN discipline for doc edits (a check that the guidance is actually missing before writing it, one incident citation per rule, and where a fix belongs: local file vs. the global instruction files loaded into every session). For creating a genuinely new skill from nothing, use `superpowers:writing-skills` instead — its pressure-scenario testing is the heavier tool for guidance that doesn't exist yet. --- ## 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/.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; make `GEMINI.md` a **symlink** to `AGENTS.md` (`ln -sf AGENTS.md GEMINI.md` — Gemini has no imports, and a symlink means zero sync drift). OpenCode reads `AGENTS.md` directly. - **Claude-only tool wiring** (which skill/hook to invoke) → keep it in a separate `claude-extras.md`, and set `CLAUDE.md` = `@AGENTS.md` + `@claude-extras.md` so the shared `AGENTS.md` stays universal. Prefer symlinks from a canonical source over copies; see `references/multi-tool-compat.md`. --- Source attribution: joeblackwaslike Original project: https://github.com/joeblackwaslike/agent-skills/blob/5ee9024524879d0fa619846a5a1e092964561dcf/skills/agent-instructions/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2026 Joe Black Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: joeblackwaslike Original project: https://github.com/joeblackwaslike/agent-skills/blob/5ee9024524879d0fa619846a5a1e092964561dcf/skills/agent-instructions/SKILL.md Attribution basis: Source repository record Fields of work: Data & Analytics, Development & Engineering, Product Management Roles: Data Scientist, Growth Product Manager, ML / AI Engineer, Product Manager, Technical Product Manager Specialties: API Tools: Claude, Codex, Gemini, Opencode Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 73516da46861da84137434ebb19e149c0d89fe55f7f0b3d696a174f6c2f4b905