copilot-agent-factory documentation.instructions.md

Documentation Instructions

Domain: Markdown Documentation (README, guides, examples)
Applies To: README.md, docs/MCP-SERVERS.md, planning artifacts, examples

Documentation Standards

Keep It Concise

• README.md: Target 900 lines, max 1000 lines
• Other docs: As long as needed, but favor clarity over verbosity
• Examples: Short, focused, working code

Examples First

Always show concrete examples before explaining theory:

❌ Don't do this:

## Placeholder System

The placeholder system uses a template-based approach with variable substitution
enabling dynamic content generation through marker replacement...

✅ Do this instead:

## Placeholder System

Templates use `{{placeholder}}` markers that get replaced:

```markdown
**Tech Stack:** {{tech_stack}}

Becomes:

**Tech Stack:** Python 3.10, FastAPI, PyTorch

### Structure for Readability

Use tables, lists, and headings effectively:

**For comparisons:**
| Aspect | Agents | Skills |
|--------|--------|--------|
| Purpose | Role-based experts | Workflow procedures |
| Invocation | `@agent-name` | Auto-activates |

**For steps:**
1. First step
2. Second step
3. Third step

**For categories:**
- **Category 1:** Items with bold labels
- **Category 2:** Items with bold labels

## README.md Structure

Maintain this structure in README.md:

1. **Title & Tagline**
2. **What is this?** (quick overview with bullets)
3. **Quick Start** (3 steps)
4. **Agents vs Skills** (comparison table)
5. **MCP Server Auto-Detection**
6. **Global Instruction Files**
7. **Feature Development Workflow**
8. **Directory Structure**
9. **Available Agent Templates** (46 total)
10. **Available Skills** (7 total)
11. **MCP Server Integrations**
12. **Detection Rules**
13. **Template Placeholders**
14. **Customization**
15. **Best Practices**
16. **Agent Capabilities**
17. **Example Generated Output**
18. **Contributing**
19. **References**

### Updating Sections