ef285b5c97
* fix: stabilize validation and tests on Windows * test: add Windows smoke coverage for skill activation * refactor: make setup_web script CommonJS * fix: repair aegisops-ai frontmatter * docs: add when-to-use guidance to core skills * docs: add when-to-use guidance to Apify skills * docs: add when-to-use guidance to Google and Expo skills * docs: add when-to-use guidance to Makepad skills * docs: add when-to-use guidance to git workflow skills * docs: add when-to-use guidance to fp-ts skills * docs: add when-to-use guidance to Three.js skills * docs: add when-to-use guidance to n8n skills * docs: add when-to-use guidance to health analysis skills * docs: add when-to-use guidance to writing and review skills * meta: sync generated catalog metadata * docs: add when-to-use guidance to Robius skills * docs: add when-to-use guidance to review and workflow skills * docs: add when-to-use guidance to science and data skills * docs: add when-to-use guidance to tooling and automation skills * docs: add when-to-use guidance to remaining skills * fix: gate bundle helper execution in Windows activation * chore: drop generated artifacts from contributor PR * docs(maintenance): Record PR 457 sweep Document the open issue triage, PR supersedence decision, local verification, and source-only cleanup that prepared PR #457 for re-running CI. --------- Co-authored-by: sickn33 <sickn33@users.noreply.github.com>
127 lines
4.3 KiB
Markdown
127 lines
4.3 KiB
Markdown
---
|
|
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 |
|
|
```
|