AgentSkillsCN

docs-for-agents

在项目文档中创建并维护“面向编码Agent”的参考页面。为AI编码Agent量身定制、高度精炼且极具指导性的文档——包括架构图、决策分发表、约束目录、副作用矩阵、任务配方、变更预案，以及常见错误解析。当用户提出“创建Agent文档”“更新Agent参考”“为Agent添加文档”“撰写编码Agent文档”或“更新‘面向编码Agent’页面”时使用。也可触发“面向Agent的文档”“AI友好型参考”。切勿用于通用文档编写、API参考生成，或面向用户的教程制作。

SKILL.md
--- frontmatter
name: docs-for-agents
description: >-
  Create and maintain a "For Coding Agents" reference page in project documentation.
  Generates dense, prescriptive documentation optimized for AI coding agents — architecture
  maps, decision dispatch tables, constraints catalogs, side effects matrices, task recipes,
  change playbooks, and common mistakes. Use when asked to "create agent docs", "update agent
  reference", "add docs for agents", "write coding agent documentation", or "update the
  for-coding-agents page". Also triggers on "agent-oriented docs", "AI-friendly reference".
  Do NOT use for general documentation, API reference generation, or user-facing tutorials.
user-invocable: true
argument-hint: create | update

Docs for Agents

Generate or update a "For Coding Agents" reference page — a compressed, prescriptive reference optimized for AI coding agents working on or integrating with the project.

Principles

  • •Dense and declarative. Tables and code blocks over prose.
  • •Action-oriented. Constraint catalogs, decision dispatch, task recipes, change playbooks.
  • •Consistent terminology. Match the codebase exactly — no synonyms.
  • •Self-contained. An agent should not need to read other docs to act correctly.
  • •Cross-referenced. Link to existing docs where agents need deeper context.

Workflow

1. Analyze the codebase

Read all source files to extract:

  • •File layout and what each file contains
  • •Class/module hierarchy
  • •Import dependency graph
  • •Public API surface (__all__, exports, entry points)
  • •Constructor constraints and validation rules
  • •Method signatures, side effects, and state mutations
  • •Concurrency model and thread-safety rules
  • •Persistence behavior (what writes to disk, what resets state)
  • •Key invariants that are not obvious from type signatures

2. Check existing documentation infrastructure

Identify:

  • •Documentation framework and config (e.g., mkdocs.yml, zensical.toml, docs/ layout)
  • •Navigation structure — where to add the new page
  • •LLM doc generation scripts (e.g., gen_llms_full.py, llms.txt generators)
  • •Existing pages to cross-reference

3. Write the reference page

Create the page with these sections (omit any that don't apply to the project):

Architecture map

  • •File layout — table: file path → what it contains
  • •Class/module hierarchy — text tree showing inheritance/composition
  • •Import dependency flow — A → B → C diagram
  • •Public API exports — what's in __all__ or equivalent

Decision dispatch

  • •Tables mapping use-case → class/function/method
  • •One table per decision axis (e.g., "which class?", "which method?", "which config?")

Constraints and invariants

  • •Concurrency rules
  • •Input constraints (types, ranges, alignment, dtypes)
  • •Key/ID constraints
  • •State machine semantics (counters, flags, lifecycle)
  • •Resource management rules

Side effects catalog

  • •Table: method → disk writes, state mutations, cache updates, counter changes
  • •Cover all public methods that mutate state

Task recipes

  • •Step-by-step code examples for common integration tasks
  • •Patterns for typical workflows

Change playbook

  • •"If modifying X → also update Y, Z" checklists
  • •Cover every module/subsystem where a change has non-obvious ripple effects

Common mistakes

  • •NEVER / ALWAYS format
  • •Concrete negative examples with corrections
  • •Each mistake separated by a horizontal rule for scannability

4. Register the page

  • •Add to documentation navigation config
  • •Add to LLM doc generation scripts if they exist
  • •Verify build succeeds

5. Verify

  • •Build the docs site — confirm the page renders and nav link works
  • •Run any LLM doc generators — confirm the page is included in output
  • •Review for accuracy against the source code

Updating an existing page

When updating rather than creating:

  1. •Read the current for-coding-agents page
  2. •Read all source files to identify what changed since the page was written
  3. •Update affected sections — do not rewrite sections that are still accurate
  4. •Verify the build still passes

File naming

Use for-coding-agents.md as the filename to avoid conflicts with the AGENTS.md convention (which serves a different purpose at the repo root).