AgentSkillsCN

agents-md

当用户提出“创建AGENTS.md”“更新AGENTS.md”“添加到AGENTS.md”“记录仓库”“编写仓库文档”“创建仓库指南”“记录模式”“记录约定”“添加编码指南”，或在实现新功能后，为新增的模式、约定、命令或注意事项添加到AGENTS.md时，应使用此技能。此外，当发现未记录的模式、反复出现的注意事项，或缺少工作流文档时，也应触发此技能。

SKILL.md
--- frontmatter
name: agents-md
description: "This skill should be used when the user asks to 'create AGENTS.md', 'update AGENTS.md', 'add to AGENTS.md', 'document the repo', 'write repo documentation', 'create repository guide', 'document patterns', 'document conventions', 'add coding guidelines', or after implementing features to document new patterns, conventions, commands, or gotchas that should be added to AGENTS.md. Also triggers when noticing undocumented patterns, repeated gotchas, or missing workflow documentation."
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite
model: sonnet

AGENTS.md Skill

Create or update AGENTS.md to help LLM coding agents work effectively in this repository.

Purpose

AGENTS.md is repository-specific guidance for LLM agents. Unlike README (for humans), AGENTS.md focuses on:

  • •Exact commands with flags (pytest -v not "run tests")
  • •Common gotchas with specifics ("Mock HOME needs both environ and Path.home patches")
  • •Task-to-file mapping ("Add CLI command → src/cli.py")
  • •Patterns with ✅/❌ code examples

Target audience: LLM agents starting fresh Quality: Under 100 lines, actionable, specific Location: Repository root only

Workflow

Step 1: Determine Mode

Check if AGENTS.md exists at repository root:

  • •CREATE: Generate new AGENTS.md from scratch
  • •UPDATE: Read existing file, add/update sections preserving user customizations

Step 2: Invoke prompt-engineer Skill

REQUIRED: Use Skill tool to invoke prompt-engineer skill.

Why: AGENTS.md is for LLM agents. Apply prompt engineering principles: explicit instructions, important info first (primacy bias), specific over vague, examples over explanations.

Step 3: Systematic Exploration

Explore repository to gather content for AGENTS.md sections:

PRIORITY 1: Commands (document first)

  • •Check Makefile (make help), Justfile (just --list), package.json (scripts)
  • •Read README.md Getting Started section
  • •Check CI config (.github/workflows/) for canonical commands
  • •Document: setup, build, run, test (full + file), lint, format

PRIORITY 2: Common Gotchas (high value)

  • •Search for comments with "NOTE:", "WARNING:", "FIXME:", "HACK:"
  • •Read existing AGENTS.md/CLAUDE.md if present
  • •Complex setup requirements (env vars, external services)
  • •Version-specific issues

Additional discovery:

  • •Project identity: name, description, type (library/CLI/webapp)
  • •Project structure: source, tests, config directories
  • •Tech stack: language+version, framework+version, key libraries
  • •Key patterns: architecture (MVC/components), naming conventions
  • •Testing: framework, locations, commands
  • •Key files by task: map tasks to specific files

Step 4: Write or Update AGENTS.md

Generate AGENTS.md using this structure (see references/templates.md for full template):

Sections (in order):

  1. •Quick Commands - Most important, goes first
  2. •Project Structure - Directory tree with annotations
  3. •Tech Stack - Versions and key libraries
  4. •Key Patterns - ✅/❌ code examples required
  5. •Testing - Commands and structure
  6. •Common Gotchas - Specific, numbered list
  7. •Key Files by Task - Task-to-file mapping table

Quality standards:

  • •Under 100 lines (60 ideal, complex repos up to 100)
  • •Specific: Include versions ("React 18"), exact commands, actual paths
  • •Examples over prose
  • •Commands first (most used)
  • •No sensitive info (no API keys, credentials, tokens)

Step 5: File Operations

CREATE mode:

  1. •Generate complete AGENTS.md
  2. •Write to {git_root}/AGENTS.md
  3. •Validate: <100 lines, commands first, all sections, no secrets
  4. •Report: path, line count, key sections

UPDATE mode:

  1. •Compare existing vs new findings
  2. •Preserve user customizations
  3. •Add new findings, update outdated info
  4. •Use Edit tool for precise changes
  5. •Report: what was added/updated

Post-Implementation Checklist

After implementing features, check if AGENTS.md needs updating:

Add when:

  • • New commands added (make/just targets, npm scripts)
  • • New patterns established (new base class, convention)
  • • Gotcha discovered (environment setup, mocking, timing)
  • • Task-to-file mapping changed (new entry points)
  • • Tech stack updated (new framework version, library added)

Examples:

  • •Implement new CLI command → Add to "Quick Commands" + "Key Files by Task"
  • •Discover HOME mocking issue → Add to "Common Gotchas"
  • •Establish naming convention → Add to "Key Patterns" with ✅/❌ examples
  • •Add new test fixture pattern → Update "Testing" section

Boundaries

✅ Always:

  • •Read actual files (don't guess)
  • •Run commands to verify (make help, just --list)
  • •Include ✅/❌ code examples for patterns
  • •Preserve user customizations in UPDATE mode

⚠️ Ask first:

  • •Major restructuring of existing AGENTS.md
  • •Removing user-added content

🚫 Never:

  • •Include sensitive info (API keys, credentials, tokens)
  • •Write AGENTS.md to subdirectories (root only)
  • •Duplicate content already in README
  • •Add generic advice ("write good code")

Tips

  • •Commands most important - Put first, use exact syntax with flags
  • •Gotchas are high-value - Specific details beat vague warnings
  • •Examples beat prose - user_email = get_email() not "get the email"
  • •Focus on what's NOT in README - Assume agents read README first
  • •Update mode: merge, don't replace - Preserve user customizations

See references/templates.md for the complete AGENTS.md structure template.