schemas/output.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://agentic-qe.dev/schemas/skills/technical-writing/output.json",
"title": "Technical Writing Skill Output Schema",
"description": "Schema for technical-writing skill output. Clear, engaging technical documentation with structure and clarity assessment.",
"type": "object",
"required": ["skillName", "version", "timestamp", "status", "trustTier", "output"],
"properties": {
"skillName": {
"type": "string",
"const": "technical-writing"
},
"version": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": ["success", "partial", "failed", "skipped"]
},
"trustTier": {
"type": "integer",
"const": 3
},
"output": {
"type": "object",
"required": ["summary", "documentStructure", "clarity", "completeness"],
"properties": {
"summary": {
"type": "string",
"minLength": 20,
"maxLength": 2000
},
"documentStructure": {
"$ref": "#/$defs/documentStructure"
},
"clarity": {
"$ref": "#/$defs/clarity"
},
"completeness": {
"$ref": "#/$defs/completeness"
},
"content": {
"type": "string",
"maxLength": 100000,
"description": "The generated documentation content"
},
"sections": {
"type": "array",
"items": {
"$ref": "#/$defs/section"
}
},
"styleAnalysis": {
"$ref": "#/$defs/styleAnalysis"
},
"recommendations": {
"type": "array",
"items": {
"$ref": "#/$defs/recommendation"
},
"maxItems": 50
},
"readabilityMetrics": {
"$ref": "#/$defs/readabilityMetrics"
},
"qualityScore": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"grade": {
"type": "string",
"pattern": "^[A-F][+-]?$"
},
"metrics": {
"$ref": "#/$defs/metrics"
}
}
},
"metadata": {
"$ref": "#/$defs/metadata"
},
"validation": {
"$ref": "#/$defs/validationResult"
},
"learning": {
"$ref": "#/$defs/learningData"
}
},
"$defs": {
"documentStructure": {
"type": "object",
"required": ["type", "hasIntroduction", "hasConclusion"],
"properties": {
"type": {
"type": "string",
"enum": ["tutorial", "reference", "guide", "api-docs", "readme", "adr", "specification", "report", "proposal"]
},
"hasIntroduction": { "type": "boolean" },
"hasConclusion": { "type": "boolean" },
"hasTableOfContents": { "type": "boolean" },
"sectionCount": { "type": "integer", "minimum": 0 },
"headingDepth": { "type": "integer", "minimum": 1, "maximum": 6 },
"hasCodeExamples": { "type": "boolean" },
"hasDiagrams": { "type": "boolean" },
"structureScore": { "type": "number", "minimum": 0, "maximum": 100 },
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": { "type": "string" },
"message": { "type": "string" },
"severity": { "type": "string", "enum": ["error", "warning", "suggestion"] }
}
}
}
}
},
"clarity": {
"type": "object",
"required": ["score"],
"properties": {
"score": { "type": "number", "minimum": 0, "maximum": 100 },
"grade": { "type": "string", "pattern": "^[A-F][+-]?$" },
"dimensions": {
"type": "object",
"properties": {
"sentenceClarity": { "type": "number", "minimum": 0, "maximum": 100 },
"terminologyConsistency": { "type": "number", "minimum": 0, "maximum": 100 },
"ambiguityFree": { "type": "number", "minimum": 0, "maximum": 100 },
"logicalFlow": { "type": "number", "minimum": 0, "maximum": 100 }
}
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": { "type": "string" },
"issue": { "type": "string" },
"suggestion": { "type": "string" },
"location": { "type": "string" }
}
}
}
}
},
"completeness": {
"type": "object",
"required": ["score"],
"properties": {
"score": { "type": "number", "minimum": 0, "maximum": 100 },
"requiredSections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"present": { "type": "boolean" },
"quality": { "type": "number", "minimum": 0, "maximum": 100 }
}
}
},
"missingTopics": { "type": "array", "items": { "type": "string" } },
"incompleteSections": { "type": "array", "items": { "type": "string" } }
}
},
"section": {
"type": "object",
"required": ["title", "content"],
"properties": {
"id": { "type": "string" },
"title": { "type": "string" },
"content": { "type": "string" },
"level": { "type": "integer", "minimum": 1, "maximum": 6 },
"wordCount": { "type": "integer", "minimum": 0 },
"subsections": {
"type": "array",
"items": { "$ref": "#/$defs/section" }
}
}
},
"styleAnalysis": {
"type": "object",
"properties": {
"voice": { "type": "string", "enum": ["active", "passive", "mixed"] },
"tone": { "type": "string", "enum": ["formal", "informal", "technical", "conversational"] },
"audienceLevel": { "type": "string", "enum": ["beginner", "intermediate", "advanced", "expert"] },
"consistency": { "type": "number", "minimum": 0, "maximum": 100 },
"styleGuideCompliance": {
"type": "object",
"properties": {
"guide": { "type": "string" },
"compliance": { "type": "number", "minimum": 0, "maximum": 100 },
"violations": { "type": "array", "items": { "type": "string" } }
}
}
}
},
"readabilityMetrics": {
"type": "object",
"properties": {
"fleschKincaid": { "type": "number" },
"fleschReadingEase": { "type": "number" },
"gunningFog": { "type": "number" },
"smog": { "type": "number" },
"avgSentenceLength": { "type": "number" },
"avgWordLength": { "type": "number" },
"wordCount": { "type": "integer" },
"sentenceCount": { "type": "integer" },
"paragraphCount": { "type": "integer" }
}
},
"recommendation": {
"type": "object",
"required": ["id", "title", "priority"],
"properties": {
"id": { "type": "string", "pattern": "^REC-\\d{3,6}$" },
"title": { "type": "string", "maxLength": 200 },
"description": { "type": "string", "maxLength": 2000 },
"priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
"category": { "type": "string", "enum": ["structure", "clarity", "completeness", "style", "formatting"] },
"example": { "type": "string" }
}
},
"metrics": {
"type": "object",
"properties": {
"wordCount": { "type": "integer", "minimum": 0 },
"sectionCount": { "type": "integer", "minimum": 0 },
"codeExampleCount": { "type": "integer", "minimum": 0 },
"linkCount": { "type": "integer", "minimum": 0 },
"imageCount": { "type": "integer", "minimum": 0 }
}
},
"metadata": {
"type": "object",
"properties": {
"executionTimeMs": { "type": "integer", "minimum": 0 },
"toolsUsed": { "type": "array", "items": { "type": "string" } },
"agentId": { "type": "string", "pattern": "^qe-[a-z][a-z0-9-]*$" },
"documentType": { "type": "string" },
"targetAudience": { "type": "string" }
}
},
"validationResult": {
"type": "object",
"properties": {
"schemaValid": { "type": "boolean" },
"contentValid": { "type": "boolean" },
"confidence": { "type": "number", "minimum": 0, "maximum": 1 }
}
},
"learningData": {
"type": "object",
"properties": {
"patternsDetected": { "type": "array", "items": { "type": "string" } },
"reward": { "type": "number", "minimum": 0, "maximum": 1 }
}
}
}
}
SKILL.md
---
name: technical-writing
description: "Write clear, engaging technical content from real experience. Use when writing blog posts, documentation, tutorials, or technical articles."
category: communication
priority: medium
tokenEstimate: 800
agents: [qe-quality-analyzer, qe-api-contract-validator]
implementation_status: optimized
optimization_version: 1.0
last_optimized: 2025-12-03
dependencies: []
quick_reference_card: true
tags: [writing, documentation, communication, blogs, tutorials]
trust_tier: 1
validation:
schema_path: schemas/output.json
---
# Technical Writing
<default_to_action>
When writing technical content:
1. LEAD with value (what will reader learn/gain?)
2. SHOW, don't tell (specific examples, code, numbers)
3. STRUCTURE for scanning (headers, bold, short paragraphs)
4. CUT ruthlessly (every sentence must earn its place)
5. BE honest about trade-offs
**Blog Post Structure:**
```markdown
# Title (specific promise)
## Opening (2-3 paragraphs)
- Hook: The problem or insight
- Context: Why this matters
- Promise: What they'll learn
## Body (3-5 sections)
- One clear idea per section
- Support with examples/code/data
## Closing
- Key takeaway (1-2 sentences)
- Action reader can take
```
**Before/After:**
❌ "We implemented a comprehensive testing strategy..."
✅ "We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement."
</default_to_action>
## Quick Reference Card
### Core Principles
| Principle | Bad | Good |
|-----------|-----|------|
| **Lead with value** | "In today's landscape..." | "Here's how we cut bugs 60%" |
| **Show, don't tell** | "We improved testing" | "Bug detection: 12→47 per sprint" |
| **Be specific** | "Performance improved" | "Response time: 2.3s→180ms" |
| **Honest trade-offs** | "This approach is best" | "TDD slowed velocity 20%, reduced bugs 75%" |
### Words to Cut
| Kill | Reason |
|------|--------|
| basically, actually, probably | Hedge words |
| leverage, synergy, paradigm | Corporate speak |
| very, really, quite | Unnecessary qualifiers |
| it should be noted that | Just note it |
---
## Audience-Specific Writing
### For Developers
- Lead with code or concrete problem
- Show implementation details
- Discuss trade-offs and alternatives
- Link to repos or examples
### For QA/QE
- Start with testing challenge
- Show strategy, not just tools
- Include risk assessment
- Provide adaptable heuristics
### For Leadership
- Open with business impact
- Use metrics that matter
- Connect technical to outcomes
- Keep technical details concise
---
## Editing Checklist
Before publishing:
- [ ] Title promises something specific
- [ ] Opening hooks in 30 seconds
- [ ] Claims backed by examples
- [ ] All unnecessary words cut
- [ ] Code examples tested and correct
- [ ] Takeaway crystal clear
- [ ] Would send to respected colleague
---
## Example Transformations
**Before:**
"We decided to implement a more comprehensive testing strategy that would allow us to catch bugs earlier in the development lifecycle."
**After:**
"We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement, identifying risks before code is written."
---
**Before:**
"The benefits of this approach are numerous and include improved quality, faster feedback loops, and better team collaboration."
**After:**
"Three outcomes: bugs found 2 days earlier on average, 30% fewer regression issues, and devs now ask QE for input during design."
---
## Agent Integration
```typescript
// Generate documentation from code
const docs = await Task("Generate Docs", {
source: 'src/services/PaymentService.ts',
format: 'markdown',
includeExamples: true
}, "qe-quality-analyzer");
// Review documentation quality
const review = await Task("Review Docs", {
files: ['README.md', 'docs/api.md'],
checkClarity: true,
checkCodeExamples: true
}, "qe-quality-analyzer");
```
---
## Agent Coordination Hints
### Memory Namespace
```
aqe/technical-writing/
├── generated-docs/* - Auto-generated documentation
├── reviews/* - Documentation review findings
└── templates/* - Reusable doc templates
```
### Fleet Coordination
```typescript
const docsFleet = await FleetManager.coordinate({
strategy: 'documentation',
agents: [
'qe-quality-analyzer', // Generate and review
'qe-api-contract-validator' // API doc accuracy
],
topology: 'sequential'
});
```
---
## Related Skills
- [bug-reporting-excellence](../bug-reporting-excellence/) - Technical bug writing
- [code-review-quality](../code-review-quality/) - Review documentation
---
## Remember
**You're not writing to impress.** You're writing to help people solve problems you've already solved. Be the colleague you wish you'd had.
**Write from experience.** Only write about what you've done in production. If exploring, say so.