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>
4.3 KiB
4.3 KiB
name, description, risk, source
| name | description | risk | source |
|---|---|---|---|
| agents-md | 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. | unknown | 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.mdorCLAUDE.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
- Create
AGENTS.mdat project root - Create symlink:
ln -s AGENTS.md CLAUDE.md
Before Writing
Analyze the project to understand what belongs in the file:
- Package manager — Check for lock files (
pnpm-lock.yaml,yarn.lock,package-lock.json,uv.lock,poetry.lock) - Linter/formatter configs — Look for
.eslintrc,biome.json,ruff.toml,.prettierrc, etc. (don't duplicate these in AGENTS.md) - CI/build commands — Check
Makefile,package.jsonscripts, CI configs for canonical commands - Monorepo indicators — Check for
pnpm-workspace.yaml,nx.json, Cargo workspace, or subdirectorypackage.jsonfiles - 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.mdfor setup" or "Follow patterns insrc/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:
## 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:
## 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:
## 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.mdfiles 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
# 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 |