القائمة
Use when writing documentation optimized for AI agent consumption - SKILL.md files, README files, API docs, or any documentation that will be read by LLMs in context windows.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Enforce staged execution discipline on large tasks: written stage plan, parallel sub-agent delegation, failable verification at each stage, and skeptical self-review before delivery. Use when tasks span multiple files, multiple sources, or multiple sessions. Also triggers on "do this thoroughly", "be systematic", "deep work mode", "be thorough".
Write production-quality code from specs — reads requirements, researches patterns, implements with tests, and iterates until verification passes. Use when implementing features, fixing bugs with known root causes, or building new modules.
Ship code to production through a controlled pipeline with verification gates and rollback plans. Use when deploying features, managing CI/CD, running database migrations, or performing post-incident hotfix recovery.
Investigate topics deeply with cross-referenced sources and produce evidence-backed findings. Use when evaluating technologies before adoption, analyzing competitors, or investigating bug root causes across docs and issues.
Read code changes with adversarial intent to find bugs, security holes, logic errors, and performance traps. Use when reviewing PRs, auditing refactoring for regressions, or running pre-deploy safety checks.
Detect and fix code style violations, enforce project conventions, and ensure consistent formatting across the codebase. Use when cleaning lint errors before PRs, migrating linters, or bulk-applying new rules.
| name | agent-docs |
| description | Use when writing documentation optimized for AI agent consumption - SKILL.md files, README files, API docs, or any documentation that will be read by LLMs in context windows. |
| domain | core |
| tags | ["agent","ai-agent","api","docs","infrastructure","memory","self-improvement"] |
persona: name: "Don Knuth" title: "The Documentation Master - Literate Programming Pioneer" expertise: ['Technical Writing', 'Documentation Systems', 'Literate Programming', 'Knowledge Management'] philosophy: "Code should be written for humans to read, and only incidentally for machines to execute." credentials: ["Author of 'The Art of Computer Programming'", 'Created TeX typesetting system', 'Turing Award winner'] principles: ['Document as you code', 'Write for your future self', 'Examples over abstractions', 'Maintainability first']
Write documentation that AI agents can efficiently consume. Based on Vercel benchmarks and industry standards (AGENTS.md, llms.txt, CLAUDE.md).
Trigger phrases:
"agent docs"
"Writing SKILL"
"Creating README files for agent consumption"
"Building API documentation"
Writing SKILL.md files that will be loaded by agents
Creating README files for agent consumption
Building API documentation
Any documentation that will be read by LLMs in context windows
Three-layer architecture for optimal agent performance:
Always in context. 2,000–4,000 tokens max.
# AGENTS.md
> Context: Next.js 16 | Tailwind | Supabase
## 🚨 CRITICAL
- NO SECRETS in output
- Use `app/` directory ONLY
## 📚 DOCS INDEX (use read_file)
- Auth: `docs/auth/llms.txt`
- DB: `docs/db/schema.md`
Include:
Fetched on demand. 1K–5K token chunks.
Gated by allow-lists. Edge cases only.
Vercel Benchmark (2026):
| Approach | Pass Rate |
|---|---|
| Tool-based retrieval | 53% |
| Retrieval + prompting | 79% |
| Inline AGENTS.md | 100% |
Root cause: Meta-cognitive failure. Agents don't know what they don't know—they assume training data is sufficient. Inline docs bypass this entirely.
This section covers core principles for the agent-docs skill. Key operations include input validation, core processing, and output verification. Refer to the skill overview for detailed usage instructions.
An 8KB compressed index outperforms a 40KB full dump.
Compress to:
RAG systems split at headers. Each section must be self-contained:
## Database Setup ← Chunk boundary
Prerequisites: PostgreSQL 14+
1. Create database...
Rules:
Agents can't autonomously browse. Each link = tool call + latency + potential failure.
| Approach | Token Load | Agent Success |
|---|---|---|
| Full inline | ~12K | ✅ High |
| Links only | ~2K | ❌ Requires fetching |
| Hybrid | ~4K base | ✅ Best of both |
LLMs have U-shaped attention:
Solution: Put critical rules at TOP of AGENTS.md. Governance first, details later.
Strip everything that isn't essential:
Formats like llms.txt and AGENTS.md mechanically increase SNR.
Machine-readable doc index for agents:
# Project Name
> One-line project description.
## Authentication
- Setup: Environment vars and init
- Server: Cookie handling
## Database
- Schema: Full Prisma schema
Location: /llms.txt at domain root
Companion: /llms-full.txt — full concatenated docs, HTML stripped
This section covers security considerations for the agent-docs skill. Key operations include input validation, core processing, and output verification. Refer to the skill overview for detailed usage instructions.
AGENTS.md is part of your codebase. Controlled, version-pinned.
Mitigation: Domain allow-lists, human-in-the-loop for external retrieval.
For detailed guidance on RAG optimization, multi-framework docs, and API templates, see references/advanced-patterns.md.
| Rationalization | Reality |
|---|---|
| "I'll do this later" | Explain why this excuse is wrong for this skill |
| "This is simple, skip steps" | Even simple tasks benefit from process |
After completing this skill, confirm: