Agents md

--- name: agents-md description: This skill should be used when the user asks to "create AGENTS.md", "update AGENTS.md", "maintain agent docs", "set up CLAUDE.md", or needs to keep agent instructions concise. Enforces research-backed best practices for minimal, high-signal agent documentation. risk: unknown source: community --- # Maintaining AGENTS.md AGENTS.md is the canonical agent-facing documentation. Keep it minimal:agents are capable and don't need hand-holding. Target under 60 lines; never exceed 100. Instruction-following quality degrades as document length increases. ## When to Use - The user asks to create, update, or audit AGENTS.md or CLAUDE.md. - The project needs concise, high-signal agent instructions derived from the actual toolchain and repo layout. - Existing agent documentation is too long, duplicated, or drifting away from real project conventions. ## File Setup 1. Create AGENTS.md at project root 2. Create symlink: ln -s AGENTS.md CLAUDE.md ## Before Writing Analyze the project to understand what belongs in the file: 1. Package manager : Check for lock files (pnpm-lock.yaml, yarn.lock, package-lock.json, uv.lock, poetry.lock) 2. Linter/formatter configs : Look for .eslintrc, biome.json, ruff.toml, .prettierrc, etc. (don't duplicate these in AGENTS.md) 3. CI/build commands : Check Makefile, package.json scripts, CI configs for canonical commands 4. Monorepo indicators : Check for pnpm-workspace.yaml, nx.json, Cargo workspace, or subdirectory package.json files 5. Existing conventions : Check for existing CONTRIBUTING.md, docs/, or README patterns ## Writing Rules - Headers + bullets : No paragraphs - Code blocks : For commands and templates - Reference, don't embed : Point to existing docs: "See CONTRIBUTING.md for setup" or "Follow patterns in src/api/routes/" - No filler : No intros, conclusions, or pleasantries - Trust capabilities : Omit obvious context - Prefer file-scoped commands : Per-file test/lint/typecheck commands over project-wide builds - Don't duplicate linters : Code style lives in linter configs, not AGENTS.md ## Required Sections ### Package Manager Which tool and key commands only: ``markdown ## Package Manager Use **pnpm**: pnpm install, pnpm dev, pnpm test ` ### File-Scoped Commands Per-file commands are faster and cheaper than full project builds. Always include when available: `markdown ## File-Scoped Commands | Task | Command | |------|---------| | Typecheck | pnpm tsc --noEmit path/to/file.ts | | Lint | pnpm eslint path/to/file.ts | | Test | pnpm jest path/to/file.test.ts | ` ### Commit Attribution Always include this section. Agents should use their own identity: `markdown ## Commit Attribution AI commits MUST include: ` Co-Authored-By: (the agent model's name and attribution byline) ` Example: Co-Authored-By: Claude Sonnet 4 <noreply@example.com> ` ### Key Conventions Project-specific patterns agents must follow. Keep brief. ## Optional Sections Add only if truly needed: - API route patterns (show template, not explanation) - CLI commands (table format) - File naming conventions - Project structure hints (point to critical files, flag legacy code to avoid) - Monorepo overrides (subdirectory AGENTS.md files override root) ## Anti-Patterns Omit these: - "Welcome to..." or "This document explains..." - "You should..." or "Remember to..." - Linter/formatter rules already in config files (.eslintrc, biome.json, ruff.toml) - Listing installed skills or plugins (agents discover these automatically) - Full project-wide build commands when file-scoped alternatives exist - Obvious instructions ("run tests", "write clean code") - Explanations of why (just say what) - Long prose paragraphs ## Example Structure `markdown # Agent Instructions ## Package Manager Use **pnpm**: pnpm install, pnpm dev ## Commit Attribution AI commits MUST include: ` Co-Authored-By: (the agent model's name and attribution byline) ` ## File-Scoped Commands | Task | Command | |------|---------| | Typecheck | pnpm tsc --noEmit path/to/file.ts | | Lint | pnpm eslint path/to/file.ts | | Test | pnpm jest path/to/file.test.ts | ## API Routes [Template code block] ## CLI | Command | Description | |---------|-------------| | pnpm cli sync | Sync data | `` ## Limitations - Use this skill only when the task clearly matches the scope described above. - Do not treat the output as a substitute for environment-specific validation, testing, or expert review. - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.