Rules Create Global

Create Rules: Set Up Your Project's Global Rules

Inputs: wire the arguments first

This skill takes up to two optional paths and uses them to pick your lane. Read whatever was passed and classify each by its content:

• $path1: the first path, if any.
• $path2: the second path, if any.

Pick the lane from what you were given:

• Greenfield if a PRD and/or architecture path was passed, or the workspace is a bare scaffold: derive what should be from the architecture decisions ($path2, or $path1 if that is where they live).
• Brownfield if no path was passed, or a codebase-analysis path was: derive what is from the analysis doc if one was passed, otherwise from the primed codebase in this conversation.

Brownfield, not primed yet? If no path was passed and this conversation has not been primed on the code, run /prime-codebase first (or offer to) so you derive from real files, then continue. Never invent rules from nothing.

What global rules are (30-second intro)

Your global rules — CLAUDE.md (Claude-native) or AGENTS.md (the open cross-tool standard) — are the always-on steering document, read on every task. Four kinds of content earn that always-on slot:

1. A map of the codebase — the dirs/files that matter, each with a one-line what it is + why it lives there.
2. Ground rules — the specific conventions this project follows (how you do type safety, your error philosophy, your git workflow). State the choice, not a slogan.
3. Commands the agent should run itself — the real lint / type-check / test / tooling CLIs (with their flags), so it can check its own work. (Not slash-commands — those are skills.)
4. Working principles (agent steering) — how you want the agent to operate here: its thinking/reasoning posture (plan before non-trivial work, ask when ambiguous instead of guessing, keep scope tight) and the engineering primitives you hold (fail fast, explicit errors, single responsibility, simplest thing that works). These don't live in the code — you state them. They're the part deriving-from-the-codebase can never produce — and the part an agent won't reliably follow unless you make it explicit.

It's all composition. Rules, references, and skills are just markdown the agent loads when it needs them — so any of the above can live always-on or in an on-demand references/ doc or in a skill; you choose where each piece lives. Everything not needed every task loads on demand, or belongs in a per-task plan — not here.

Two situations, one motion

Global rules encode technical truth — so you derive them from technical decisions, never from a product spec:

Greenfield note: your rules come from your architecture decisions (the spec), not the PRD. The flow: discuss what you're building with the AI and capture it as a PRD (plan-create-prd), then settle the architecture with plan-architecture (stack, patterns, directory structure, conventions). Those decisions are what this skill derives rules from. A PRD captures the product (what/why): useful context, but technical rules don't live there.

Brownfield note: this skill does not explore the codebase for you. Prime first: run /prime-codebase so the structure, key files, and conventions are loaded into this conversation, then run this skill with no path. (Large repo? Optionally fan out a few built-in subagents to explore areas in parallel, aggregate a short codebase-analysis.md, and pass that path instead.) This skill packages the derive → extract → seams → prune → check steps, not the exploration.

Before you run this — protect any existing rules. If the project already has a CLAUDE.md / AGENTS.md, copy or rename it first (e.g. CLAUDE.md.bak) so this skill doesn't overwrite something you want to keep. Even better, feed it in as input — point the skill at it ("read my existing CLAUDE.md first") so the derivation builds on what's already there instead of starting from scratch.

Required reading (do this first) — and pick the file

First, which rules file does this project use? Detect it, then read the matching guidance (don't rely on a snapshot):

• CLAUDE.md (Claude Code's native file) → Anthropic memory + best practices: https://code.claude.com/docs/en/memory · https://code.claude.com/docs/en/best-practices
• AGENTS.md (the open cross-tool standard, read by dozens of agents) → the AGENTS.md spec: https://agents.md
• Both present? Usually the shared content lives in AGENTS.md and CLAUDE.md is a single line — @AGENTS.md — so Claude Code auto-loads AGENTS.md and there's one source of truth. In that case, write to AGENTS.md.
• Neither yet? CLAUDE.md for a Claude-Code-only project; AGENTS.md if the team is multi-tool.

Content + structure are ~90% identical either way — everything below is "your rules file," not one vendor's. Use the structure laid out below (it works as an AGENTS.md just as well).

The methodology (bake this in)

• What goes always-on: the map + ground rules (specific conventions) + the working principles (agent steering). Everything true project-wide, every task.
• Working principles are elicited, not derived. The map + ground rules come from the code/decisions; the working principles come from you — so ask: "how should the agent work here — plan-first? clarify before coding? scope discipline? which engineering primitives do you hold?" Keep only the ones that actually change behavior and reflect your stance — not a generic lecture the model already follows.
• The four destinations — sort every candidate line:
  • Keep always-on → map / ground rules.
  • Push to on-demand → a recurring but task-type-specific pattern → an on-demand reference (.claude/references/<topic>.md on Claude Code; anywhere your tool looks — e.g. .agent/ — it's just markdown) or a skill.
  • Move to a plan → task-specific "what to build next" content → it was never a rule.
  • Delete → redundant, or a slogan the model already follows ("write clean code", "KISS/DRY").
• State the choice, not the slogan: "derive types with z.infer", not "type safety is critical".
• Brownfield = "what is", not "what should be": every rule must point to the file that proves it; if you can't, leave it out. Aspirational rules make the agent fight the codebase.
• Lean: don't bloat it to the point it eats context or the agent starts ignoring its own rules. No magic line number — cut anything that wouldn't cause a mistake if removed.