AGENTS.md Generator Skill
Specialized knowledge for generating documentation that helps AI agents understand code in product context.
When to Use
-
Creating AGENTS.md for a component or feature
-
Documenting user flows and trust factors
-
Helping AI understand the "why" not just "what"
Core Principle
Product context > Technical details
AI agents need to understand:
-
What problem this solves
-
Who uses it and why
-
What success looks like
-
What breaks trust
-
How errors are recovered
Template Structure
[Component/Feature Name]
Product Context
Problem Solved
[Specific user pain this addresses]
Users Served
[Personas from personas.md]
Cognitive Load Eliminated
[What mental burden this removes]
User Personas
[Primary Persona]
- Needs: [From this feature]
- Fears: [What worries them]
- Success: [What success looks like]
Key User Flows
Flow: [Name]
- Trigger: [What starts this]
- Steps: 1 → 2 → 3
- Success Outcome: [End state]
- Failure Recovery: [How to recover]
- Metrics: [How measured]
Trust & Experience
What Builds Trust
- [Trust builder]
What Breaks Trust
- [Trust breaker]
Error Recovery
- [Recovery pattern]
Technical Context
Setup
[How to run/test]
Key Files
file- purpose
Conventions
- [Convention]
Related Components
component- relationship
AI Agent Guidelines
When working on this:
- [Guideline]
- [What to avoid]
Information Sources
To populate AGENTS.md, check:
Source What to Extract
pm-workspace-docs/initiatives/active/[name]/prd.md
Problem, personas, flows
pm-workspace-docs/initiatives/active/[name]/research.md
User quotes, pain points
pm-workspace-docs/company-context/personas.md
Persona details
Component stories (.stories.tsx ) States, interactions
Tests Expected behavior
Existing code Technical patterns
Quality Criteria
Good AGENTS.md documentation:
Criteria Check
Product-first Problem stated before code
Persona-aware Specific personas named
Flow-complete Entry → success → failure paths
Trust-conscious Build/break factors explicit
Actionable tech Setup instructions work
Save Location Pattern
Mirror source structure:
Source: elephant-ai/web/src/components/integrations/hubspot/ Docs: pm-workspace-docs/agents-docs/web/components/integrations/hubspot/AGENTS.md
Anti-Patterns
🚩 Code-first documentation - Always lead with user problem 🚩 Generic personas - Use specific names from personas.md 🚩 Happy path only - Document failure and recovery 🚩 Missing trust factors - AI features especially need trust context 🚩 Stale documentation - Update when features change