agent-instructions

Files (11)

• SKILL.md
• content-taxonomy.md · references/
• agent-mcp-project.md · references/cookbook/
• minimal-project.md · references/cookbook/
• monorepo.md · references/cookbook/
• python-project.md · references/cookbook/
• typescript-project.md · references/cookbook/
• user-global.md · references/cookbook/
• editing-discipline.md · references/
• multi-tool-compat.md · references/
• scope-hierarchy.md · references/

SKILL.md (first lines)

# 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/<name>.md with paths: frontmatter
└── Multi-tool (2+ AI assistants)
    └── See references/multi-tool-compat.md

From joeblackwaslike/agent-skills, MIT.

More from joeblackwaslike/agent-skills