القائمة
Write AGENTS.md files that serve as operating contracts for AI agents. Use when creating or updating AGENTS.md for a project. Trigger terms: AGENTS.md, agent instructions, agent contract, agent configuration, coding agent setup.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Write Architecture Decision Records when making significant technical choices. Use when selecting tools, patterns, frameworks, or making structural changes that future developers need to understand.
Quality rules for changelog entries. Use when validating, writing, or reviewing changelog content to ensure user-facing value communication.
Task completion sequence including verification, git, signaling, and handoff. Use when finishing a task or reporting status.
Architecture diagrams for documentation. Covers ASCII, Mermaid, C4, and D2. Applies C4 methodology by default. Trigger terms: diagram, flowchart, architecture diagram, sequence diagram, C4, mermaid, ascii diagram.
Classify documentation by audience and content type. Use when planning, auditing, or placing project documentation.
Audit project documentation for quality, completeness, and freshness. Use when assessing documentation health, planning cleanup, or measuring improvement.
| name | agents-md-authoring |
| description | Write AGENTS.md files that serve as operating contracts for AI agents. Use when creating or updating AGENTS.md for a project. Trigger terms: AGENTS.md, agent instructions, agent contract, agent configuration, coding agent setup. |
AGENTS.md is the entry point for AI agents working in a codebase. It is not a README — it is a contract between the author and machines-with-judgment. Its job is to encode decisions an agent should not have to rediscover.
Agents are executors, not readers. Every line competes for context budget. Omit what any competent agent would do by default; state only what is specific to this project.
Encode done, not just started. Verification criteria are the most important content. If the agent cannot tell whether its work is complete, it will stop too early or keep going forever.
Actionable over aspirational. "Write clean code" is noise. "No any types; run npm run check after every code change; fix all errors before committing" is a contract.
Progressive disclosure. Inline what's frequently needed; reference what's rarely needed. Link to .docs/ files with a one-line description of when to read them.
# AGENTS.md
## Project
<!-- 2-4 sentences: what it does, primary focus, non-obvious terminology -->
## Architecture
<!-- Key directories, package boundaries, how pieces connect -->
## Commands
<!-- Exact commands. Not "run the tests" — the actual invocation. -->
<!-- Include: what to run after code changes, what is FORBIDDEN -->
## Code Standards
<!-- Language-specific rules that deviate from defaults -->
<!-- Only rules that are enforced — aspirational conventions erode trust -->
## Workflow
<!-- When to ask vs proceed, commit/push rules, session completion -->
## Testing
<!-- Framework, how to run specific tests, what to do after modifying tests -->
## Verifying Work
<!-- What "done" means. Exact commands, expected output, what failure looks like. -->
## References
<!-- Links to .docs/ files with WHEN to read them -->
Effective range: 100-300 lines. The 530-line ceiling works only for large monorepos where every line is load-bearing.
Heuristic: If the agent needs it on any non-trivial task → inline. If only for a specific task class → link to .docs/. If the agent wouldn't need it → delete.
| File | Audience | Content |
|---|---|---|
| README.md | Humans | Project purpose, setup, usage |
| AGENTS.md | AI agents | Operating contract, commands, verification |
Never duplicate between them. Content written for one should not appear in the other.