shield_lock
JinDaGe
← Back to skills
extension
Category: AI Agent CapabilitiesNo API key required

init-agents

Initialize or update AGENTS.md (or CLAUDE.md for Claude Code) with AI agent guidance. Use when user says 'init agents', 'create AGENTS.md', 'setup agent instructions', or wants project-specific AI coding assistant configuration.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Init Agents

Initialize or update AGENTS.md at project root — the instruction manual that tells AI coding assistants exactly how to work in this project.

What AGENTS.md Is

A vendor-agnostic markdown file that provides persistent, project-specific guidance to AI coding agents. Codex, OpenCode, Cursor, and GitHub Copilot read it. Claude Code uses CLAUDE.md instead — use the same content; the filename differs by tool.

Contains:

  • Clear dos and don'ts (tech stack, versions, patterns)
  • Executable commands (file-scoped type-check, lint, format, test)
  • Project structure hints and key file locations
  • Safety and permission boundaries
  • Code style examples (good vs bad)
  • Git workflow and PR checklist

Does NOT contain:

  • Business rules (that belongs in KNOWLEDGE.md)
  • Product roadmap (not included in this document)

Tool Conventions

| Tool | File | Location | |------|------|----------| | Codex | AGENTS.md | Project root, ~/.codex/AGENTS.md global | | OpenCode | AGENTS.md | ~/.config/opencode/AGENTS.md global | | Cursor | AGENTS.md or .cursor/rules/ | Project root | | Claude Code | CLAUDE.md | Project root | | GitHub Copilot | AGENTS.md | .github/agents/*.md for specialized agents |

Project root AGENTS.md applies to Codex, Cursor, Copilot. Claude Code expects CLAUDE.md. When user mentions Claude Code specifically, create/update CLAUDE.md; otherwise use AGENTS.md.

Six Core Areas (Best Practice)

Effective agent files cover all six:

  1. Commands — Executable commands with flags (put early in the file)
  2. Testing — How to run tests, test-first expectations
  3. Project structure — Key paths, where things live
  4. Code style — Naming, formatting, patterns with examples
  5. Git workflow — Commit format, PR checklist
  6. Boundaries — Allowed / ask first / never

Format

# AGENTS.md

This file provides guidance to AI coding agents working in this repository.

## Project Overview
[1-2 sentences: what this project is, key stack]

## Commands
# Type-check single file
npm run tsc --noEmit path/to/file.ts

# Lint single file
npm run eslint --fix path/to/file.ts

# Format single file
npm run prettier --write path/to/file.ts

# Run tests (single file or suite)
npm test -- path/to/file.test.ts

## Project Structure
- `src/` — [purpose]
- `docs/` — [purpose]
- [key files that define architecture]

## Do
- [specific rule with versions/libraries]
- [specific rule]

## Don't
- [specific prohibition]
- [specific prohibition]

## Safety and Permissions
**Allowed without prompt:** [read files, run lint/format on single file, run single test]
**Ask first:** [package installs, git push, full build, schema changes]
**Never:** [commit secrets, edit vendor/, modify production configs]

## When Stuck
- Ask a clarifying question or propose a short plan
- Do not push large speculative changes without confirmation

Process

Step 1: Explore Project

Gather in parallel:

  • Tech stack (package.json, composer.json, requirements.txt, go.mod, etc.) — versions matter
  • Build/lint/test commands from scripts
  • Project structure and key entry points
  • Existing rules (.cursorrules, .cursor/rules/, .github/copilot-instructions.md, CONTRIBUTING.md)
  • KNOWLEDGE.md, if it exists — reference it, don't duplicate

Step 2: Extract Commands

Find file-scoped commands (prefer over full-project builds):

  • Type-check: tsc --noEmit, pyright, etc.
  • Lint: eslint --fix, ruff check --fix, etc.
  • Format: prettier --write, black, etc.
  • Test: vitest run, pytest, jest, etc.

Include exact flags. Put commands early in the file.

Step 3: Define Boundaries

Three tiers:

  • Always do — Run lint/test on changed files, follow style examples
  • Ask first — Package installs, git push, full builds, schema changes
  • Never — Commit secrets, edit vendor/node_modules, modify production configs

Step 4: Add Code Examples

Point to real files that demonstrate good patterns. Call out legacy code to avoid. Examples beat paragraphs of description.

Step 5: Write or Merge

If AGENTS.md (or CLAUDE.md) exists:

  1. Read existing content
  2. Merge new sections (don't duplicate)
  3. Update outdated commands and structure
  4. Preserve user customizations

If it doesn't exist:

  1. Create from template above
  2. Fill with discovered project context
  3. Keep it concise — expand over time based on agent mistakes

Companion Documents

| Document | Use When | |----------|----------| | KNOWLEDGE.md | Business context, domain rules, gotchas — suggest init-knowledge if missing |

When running init-agents, if companion docs exist, reference them in AGENTS.md (e.g. "See KNOWLEDGE.md for business context"). Don't duplicate their content.

Rules

  • Just do it — no approval needed, write directly
  • Be specific — "React 18 with TypeScript and Vite" not "React project"
  • Commands first — put executable commands early, with flags
  • Code examples over prose — one real snippet beats three paragraphs
  • File-scoped commands — prefer single-file validation over full builds
  • Never commit secrets — most common and valuable boundary
  • Hierarchy — project AGENTS.md overrides global; nested AGENTS.override.md for subdirs (Codex)
  • Iterate — start minimal, add detail when agents make mistakes