TSD Skill

Create Technical Specification Documents (5-20 pages) that comprehensively define APIs, data models, interface contracts, error handling, versioning strategies, and technical implementation details.

Key principle: All information comes from the user. Do NOT scan the codebase to discover APIs or schemas. The Read tool is only for reading user-provided context files (existing specs, API definitions, tickets) that the user explicitly shares.

When to Use a TSD

• Defining new API endpoints or modifying existing ones
• Documenting data models and database schemas
• Specifying interface contracts between services
• Documenting integration points with external systems
• Capturing technical implementation details before or after development

Workflow

Phase 1: Gather Context

Parse what the user already provided in their initial request. Extract:

• Scope: What API, service, or data model is being specified?
• Purpose: What does this system do?
• Consumers: Who/what will use this API?
• Constraints: Auth, versioning, backward compatibility

Only ask for what's genuinely missing.

Essential questions (use references/question-bank.md patterns, ask only if not already provided):

1. System overview: "What does this service/API do? What problem does it solve?"
2. API endpoints (for APIs): "Walk me through the endpoints — what operations does it support? (e.g., CRUD, streaming, webhooks)"
3. Data models: "Describe the main data entities and their key fields. Any relationships between them?"
4. Authentication/Authorization: "How do clients authenticate? Are there different permission levels?"
5. Error handling: "What errors can occur? How should errors be communicated to consumers?"
6. Versioning: "How will this API be versioned? How will breaking changes be handled?"
7. Performance requirements: "Any latency, throughput, or SLA requirements?"
8. Related context (optional): "Existing specs, OpenAPI definitions, or service contracts I should reference?"

If user seems uncertain about design choices: Offer research assistance via agent:web-research-specialist for industry patterns (REST vs GraphQL, pagination approaches, etc.).

Rich context (accept at any point):

• OpenAPI/Swagger specs → use Read tool to load
• Existing service code → user should paste key interfaces
• Pasted schema definitions → incorporate directly

Phase 2: Generate & Iterate

Once sufficient context is gathered, generate the complete TSD draft using the template from assets/templates/template.md.

Content generation rules:

• Use section headings from template.md exactly
• Format API endpoints consistently: METHOD /path with request/response examples
• Use code blocks for JSON schemas, request/response bodies
• Use tables for field definitions (field, type, required, description)
• Use italicized placeholders for missing info: Define error codes
• Do NOT include checkboxes, HTML comments, guidance questions, or quality criteria in output

After presenting the full draft:

1. Internally validate against assets/templates/quality-checklist.md — never show to user
2. Ask targeted follow-ups for gaps (e.g., "Should I add example requests and responses for each endpoint?")
3. Iterate based on feedback
4. Save in requested format

Document Structure

Key sections (from assets/templates/template.md):

Section	Purpose
Abstract	Executive summary
Overview	Purpose, scope, system context
API Endpoints/Methods	Detailed specs per endpoint
Data Models/Schemas	Entity definitions and relationships
Interface Contracts	Inputs, outputs, preconditions, postconditions
Error Handling	Error types, codes, formats, retry logic
Versioning Strategy	Version scheme and backward compatibility
Security Considerations	Auth, encryption, data protection
Performance Requirements	Latency, throughput, SLAs
Testing Requirements	Unit, integration, contract testing
Examples	Complete request/response examples
References	Related docs and standards
Change Log	Version history

Quality Principles

• Every endpoint needs: method, path, description, request schema, response schema, error codes
• Field definitions must include: name, type, required/optional, description, validation rules
• Use concrete examples — abstract specs are hard to implement against
• Document what happens on errors, not just the happy path
• Be explicit about backward compatibility guarantees

Visual Aids

System context and data flow diagrams help consumers understand integration. When requested:

1. Ask what the diagram should show (system context, entity relationships, sequence flows)
2. Invoke common-engineering:mermaid skill
3. Integrate into Overview or relevant section

Integration Points

Capability	When to Use
agent:web-research-specialist	Research API design patterns, industry standards
common-engineering:mermaid	System context, ER diagrams, sequence diagrams
document-skills:docx	Export to Word format
document-skills:pdf	Export to PDF format

Reference Files

File	Purpose
references/writing-guidelines.md	Technical writing best practices
references/question-bank.md	AskUserQuestion patterns for this skill
assets/templates/template.md	Document structure (use for output)
assets/templates/guidance.md	Section-by-section guidance (read, never copy to output)
assets/templates/quality-checklist.md	Internal validation (never show to user)
assets/templates/examples.md	Completed examples for quality reference