init-public-rules

Generate AGENTS.md (public agent instructions) in the project root and set up bridge files for agents that cannot natively read it.

AGENTS.md is a tool-neutral standard adopted by over 60,000 open-source projects. Write it once and 30+ agents -- Cursor, GitHub Copilot, Windsurf, Codex CLI, and more -- automatically pick it up. Even for solo developers, AGENTS.md helps agents understand the project more accurately.

Scope

This skill creates a minimal, shallow AGENTS.md with at most four sections:

Section	Generated when
# {Name} + 1-3 sentence overview	Always
## Project Structure	User reports non-trivial contract/flow/forbidden zones
## Code Style	User reports rules the linter cannot catch
## Testing	User reports conventions beyond the runner name

The following sections are intentionally not generated here. They are owned by dedicated skills and the user can add them later:

Section	Dedicated skill
## External Tools	/manage-tools (future)
## Git Workflow	/git-workflow (future)
## Boundaries	/refine-boundaries (future)
## References	/manage-refs (future)

Until those skills exist, users can edit AGENTS.md by hand. This skill will not block on missing sections.

Guardrails

#	Check	On failure
1	CWD is a Git repository	"Please run this inside a Git repository."
2	AGENTS.md already exists	"AGENTS.md already exists. Overwrite or merge?"
3	Other agent config files also exist (.cursorrules, etc.)	"Other agent config files were found. Consider consolidating them with /migrate-rules."
-	Skill update check	Let SELF be the value of the name field in this SKILL.md's frontmatter (e.g., init-public-rules). Let LOCAL be metadata.version from this same frontmatter. Fetch https://raw.githubusercontent.com/dev-goraebap/agent-collabo/main/manifest.json (1 HTTP request, fail silently on network error). Then evaluate exactly one case in this order: Case A — outdated: if manifest.skills[SELF] exists and LOCAL < manifest.skills[SELF], tell the user (in their language) "agent-collabo {SELF} has a new version ({LOCAL} → {manifest.skills[SELF]}). Run /agent-collabo-updater when convenient. Continuing with the current task." then proceed. Case B — up to date: if manifest.skills[SELF] exists and LOCAL === manifest.skills[SELF], proceed silently. Case C — renamed away: if SELF does NOT exist as a key in manifest.skills AND SELF exists as a key in manifest.deprecated (note: check the keys of deprecated, not the renamedTo values), tell the user "This skill {SELF} was renamed to {manifest.deprecated[SELF].renamedTo} since v{manifest.deprecated[SELF].since}. Run /agent-collabo-updater to migrate." then proceed. Case D — unknown: if SELF is not in manifest.skills and not in manifest.deprecated, tell the user "Skill {SELF} is no longer maintained. Run /agent-collabo-updater to clean up." then proceed with caution. Important: manifest.deprecated maps OLD names → NEW names. Never warn about a skill whose name is currently in manifest.skills just because that name appears as a renamedTo value somewhere in deprecated. CDN cache caveat: GitHub raw enforces Cache-Control: max-age=300, so right after a new release is pushed the manifest may be stale for up to 5 minutes via Fastly PoPs. If the user explicitly mentions they just released a new version (e.g., "I just pushed v0.X.Y") and this check still reports up-to-date or shows an older manifest.version, do not insist the local install is current — instead mention the 5-minute CDN window and suggest retrying shortly. For all other users this is invisible because they fetch long after the cache expires.

Language Policy

Conduct all user-facing communication in the user's language: interview questions, follow-up prompts, status messages, diagnostic reports, and summaries. Detect the language from (in order):

1. The language of the user's most recent messages in the current session
2. Declarations in their local rules file (e.g., CLAUDE.local.md, .cursor/rules/local.mdc) — look for instructions like "respond in Korean"
3. OS locale ($LANG, $LC_ALL)
4. English as fallback

Generated file content follows the file's audience: team-shared files (AGENTS.md, CHANGELOG.md) stay in English regardless of the user's language; personal files (CLAUDE.local.md, GEMINI.local.md, etc.) use the user's language unless they specify otherwise.

When merge is chosen: Read the existing AGENTS.md and compare it section-by-section with the newly analyzed content. Add only sections that are missing and keep existing ones intact. For conflicting content (e.g., different rules in the same section), ask the user which version to keep.

Workflow

Step 1: Automated project analysis

Do not put anything in AGENTS.md that an agent can infer by reading the code. The purpose of automated analysis is to decide whether optional sections are needed -- not to copy analysis results verbatim.

Items to collect:

Source	What to collect
package.json / pom.xml / build.gradle / pyproject.toml, etc.	Package manager, key dependencies (informational only; do not list them)
Directory structure (ls, tree)	Monorepo? Build output directories? Generated code paths? (used to decide whether Project Structure is warranted)
.eslintrc / prettier / tsconfig, etc.	Linter/formatter presence (if present, omit style rules the linter already catches from Code Style)
Test runner config (jest.config.*, vitest.config.*, pytest.ini, etc.)	Testing infrastructure presence (informational only; do not list "runner: vitest")
Existing README.md	Project description for the overview (paraphrase, don't copy)

Step 2: User interview

Ask the user which optional sections apply. Present as a checklist; follow up only on selected items.

A minimal AGENTS.md will be created with a short project header.
Which of these optional sections should also be included?

[ ] Project Structure — the agent needs to understand a non-trivial
    contract, build flow, or forbidden zones
    (e.g., "src/ → build → dist/, never edit dist/")
[ ] Code Style — there are coding rules the linter/formatter cannot catch
    (e.g., "use early return", "avoid `any` type", "no class components")
[ ] Testing — there are testing conventions beyond "we use Vitest"
    (e.g., "no DB mocks", "fixtures in __fixtures__/", "how to run a single test")
[ ] None of the above — just create the header

If "None of the above" is selected, skip Steps 2a–2c and generate only the header.

Step 2a: Project Structure follow-up

Only when selected. This section is strict: if the user cannot answer the four questions below with meaningful content, skip the section entirely.

Project Structure answers four questions. Fill in any that apply
(leave blank if not applicable):

1. Contract — what is source of truth vs generated/derived output?
   (e.g., "schema.prisma is source; prisma/generated/ is output")

2. Flow — what transforms happen and in what order?
   (e.g., "src/ → npm run build → dist/ + manifest.json")

3. Forbidden zones — which paths must never be edited, and why?
   (e.g., "never edit dist/ — build output, overwritten on every build")

4. Special markers — any inline syntax or conventions?
   (e.g., "double-brace tokens in templates are expanded at build time")

Anti-pattern guard: If the user starts listing directory contents (src/, tests/, docs/), stop and redirect: "Please answer the four contract/flow/forbidden/marker questions instead. A directory listing is something the agent can see with ls — we don't need it here." If they cannot reframe, skip the section.

Step 2b: Code Style follow-up

Only when selected. Ask for rules the linter cannot catch.

Which of these apply?

[ ] There are naming or pattern rules (e.g., "early return",
    "no class components", "no `any` type")
[ ] There are specific anti-patterns to avoid
    (e.g., "don't nest ternaries", "don't mutate props")
[ ] There are library-specific conventions
    (e.g., "always use zod for API input", "prefer server components")

For each selected item, ask for one or two concrete code examples (good/bad pair preferred).

Anti-pattern guard: If the user provides rules already covered by ESLint/Prettier/Biome (indentation, semicolons, quote style), skip them: "ESLint/Prettier already handles this — no need to repeat in AGENTS.md."

Step 2c: Testing follow-up

Only when selected. Ask for conventions, not runner names.

Which of these apply?

[ ] There is a mock policy (e.g., "no DB mocks — use a real test DB")
[ ] Fixtures have a specific location (e.g., "__fixtures__/ next to tests")
[ ] Running a single test has a non-obvious command
[ ] There are forbidden test patterns (e.g., "no snapshot tests")

Anti-pattern guard: If the user only answers "we use Vitest" or "tests are in tests/", skip the section: "That's derivable from your config files — no need to document it in AGENTS.md."

Step 3: Generate AGENTS.md

Read references/agents-md-template.md for structure and principles, then generate the file with the sections the user selected.

Section order (when present):

1. # {Project Name} + overview (always)
2. ## Project Structure (if selected)
3. ## Code Style (if selected)
4. ## Testing (if selected)

Note: the four sections owned by other skills (External Tools, Git Workflow, Boundaries, References) are not inserted. After generation, print guidance on how to add them (see Step 5).

Writing principles:

• Do not write what an agent can learn by reading code, package.json, or git history
• Show code snippets instead of explanations for Code Style
• Project Structure is contract, flow, forbidden zones — never a directory listing
• Testing is conventions, not runner names
• Start under 100 lines; never exceed 300
• Do not include truisms like "write clean code" or "follow best practices"

Step 4: Generate bridge files

Create bridge files for major agents that cannot natively read AGENTS.md.

Claude Code -- CLAUDE.md location choice

Ask the user where to place the CLAUDE.md file:

Where should CLAUDE.md be created?
1. .claude/CLAUDE.md (keeps project root clean; .gitignore target)
2. CLAUDE.md (project root; tracked by git)

If .claude/CLAUDE.md is chosen:

@../AGENTS.md

Created inside .claude/, so the relative path @../AGENTS.md is used. If .claude/ is not in .gitignore, add it. Each contributor generates their own bridge file; connectivity can be verified with /audit-rules.

If CLAUDE.md (root) is chosen:

@AGENTS.md

Created at the root, so @AGENTS.md is the reference. This file will be tracked by git.

Gemini CLI -- guidance message

Gemini CLI reads GEMINI.md by default. Since settings.json is an external file, do not modify it directly -- just print guidance:

Tip: Gemini CLI users can add the following setting to auto-read AGENTS.md:
   ~/.gemini/settings.json -> "context": { "fileName": ["AGENTS.md", "GEMINI.md"] }

   Alternatively, create a GEMINI.md file that references the AGENTS.md content.

.gitignore handling

If .claude/CLAUDE.md was chosen, .claude/ is a local config directory and should be in .gitignore. Add .claude/ if it is missing.

If root CLAUDE.md was chosen, no .gitignore changes are needed.

Step 5: Summary and next-skill guidance

After creating the file, print a summary that points users to the dedicated skills for the sections this skill intentionally does not manage.

Done:
  - AGENTS.md (public agent instructions)
  - CLAUDE.md (Claude Code bridge -- created at the chosen location)

Tip: Gemini CLI user setup guidance printed above.

Your AGENTS.md is deliberately minimal. Add these sections as needed:

  - ## External Tools   (MCP servers, shared CLIs, frequently used skills)
      → /manage-tools
  - ## Git Workflow     (branching, commits, PR rules)
      → /git-workflow
  - ## Boundaries       (Always do / Ask first / Never do)
      → /refine-boundaries
  - ## References       (links to design docs, ADRs, specs)
      → /manage-refs

(These dedicated skills may not be available yet; you can also edit
AGENTS.md by hand at any time.)

For private settings (response language, personal workflow preferences),
run /init-private-rules — those do NOT belong in AGENTS.md.

Agent compatibility matrix

Agent	Reads AGENTS.md	Bridge method
Cursor	Auto	Not needed
GitHub Copilot	Auto	Not needed
OpenAI Codex CLI	Auto	Not needed
Windsurf	Auto	Not needed
JetBrains Junie	Auto	Not needed
Roo Code	Auto	Not needed
Amp	Auto	Not needed
Devin	Auto	Not needed
Claude Code	Not supported	.claude/CLAUDE.md or root CLAUDE.md (user's choice)
Gemini CLI	Needs config	Guidance message printed