Skip to content

SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist

documentation-specialist

Verified

This skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".

FileKindSize
SKILL.mdskill md10.0 KB
references/examples/TOC.mdmarkdown6.5 KB
references/examples/brownfield/database-failover-runbook.mdmarkdown8.1 KB
references/examples/brownfield/spring-boot-sdd.mdmarkdown5.6 KB
references/examples/greenfield/adr-microservices.mdmarkdown6.3 KB
references/examples/greenfield/architecture-doc.mdmarkdown3.7 KB
references/examples/greenfield/billing-srs.mdmarkdown12.4 KB
references/examples/greenfield/cli-getting-started.mdmarkdown9.3 KB
references/examples/greenfield/collaboration-prd.mdmarkdown13.8 KB
references/examples/greenfield/document-specialist-sdd.mdmarkdown15.4 KB
references/examples/greenfield/ecommerce-sdd.mdmarkdown7.8 KB
references/examples/greenfield/rest-api-tutorial.mdmarkdown13.8 KB
references/examples/greenfield/task-api-openapi.yamlconfig19.0 KB
references/examples/greenfield/taskmanager-user-manual.mdmarkdown8.7 KB
references/examples/greenfield/ui-wireframes.mdmarkdown5.8 KB
references/guides/requirements/README.mdmarkdown3.7 KB
references/mappings/backend/fastapi-mapping.yamlconfig9.7 KB
references/mappings/backend/spring-boot-mapping.yamlconfig24.1 KB
references/reference/01-philosophy.mdmarkdown2.0 KB
references/reference/02-requirements-srs-vs-prd.mdmarkdown1.2 KB
references/reference/02-requirements-traceability.mdmarkdown1.7 KB
references/reference/02-requirements-writing.mdmarkdown1.4 KB
references/reference/03-design-adrs.mdmarkdown2.2 KB
references/reference/03-design-arc42.mdmarkdown2.6 KB
references/reference/03-design-requirements-matrix.mdmarkdown1.3 KB
references/reference/04-diagrams-c4-hierarchy.mdmarkdown2.0 KB
references/reference/04-diagrams-selection.mdmarkdown5.1 KB
references/reference/04-diagrams-state-vs-activity.mdmarkdown2.3 KB
references/reference/05-api-checklist.mdmarkdown2.0 KB
references/reference/05-api-openapi.mdmarkdown3.4 KB
references/reference/05-api-stripe-gold-standard.mdmarkdown1.8 KB
references/reference/06-deployment-diagrams.mdmarkdown1.8 KB
references/reference/06-deployment-documentation.mdmarkdown2.9 KB
references/reference/06-deployment-runbooks.mdmarkdown2.5 KB
references/reference/06-operational-docs.mdmarkdown2.7 KB
references/reference/07-user-kb-approach.mdmarkdown1.8 KB
references/reference/07-user-kb-template.mdmarkdown3.1 KB
references/reference/07-user-writing-style.mdmarkdown2.0 KB
references/reference/08-agile-process.mdmarkdown3.2 KB
references/reference/08-tutorial-writing.mdmarkdown7.4 KB
references/reference/09-code-to-docs-detection.mdmarkdown2.5 KB
references/reference/09-code-to-docs-example.mdmarkdown3.2 KB
references/reference/09-code-to-docs-when.mdmarkdown1.7 KB
references/reference/09-code-to-docs-workflow.mdmarkdown2.0 KB
references/reference/10-quality-bonsai-pruning.mdmarkdown2.4 KB
references/reference/10-quality-checklist.mdmarkdown2.6 KB
references/reference/10-quality-metrics.mdmarkdown3.1 KB
references/reference/11-voice-and-style.mdmarkdown1.5 KB
references/reference/comprehensive-guide.mdmarkdown7.3 KB
references/templates/markdown/DESIGN_DOC.mdmarkdown4.5 KB
references/templates/markdown/api-openapi.yamlconfig17.7 KB
references/templates/markdown/architecture.mdmarkdown1.6 KB
references/templates/markdown/design-sdd.mdmarkdown143 B
references/templates/markdown/developer-tutorial.mdmarkdown7.1 KB
references/templates/markdown/getting-started.mdmarkdown6.5 KB
references/templates/markdown/howto-guide.mdmarkdown4.1 KB
references/templates/markdown/requirements-prd.mdmarkdown10.2 KB
references/templates/markdown/requirements-srs.mdmarkdown17.0 KB
references/templates/markdown/runbook.mdmarkdown8.8 KB
references/templates/markdown/user-manual.mdmarkdown4.8 KB
references/workflows/TOC.mdmarkdown1.9 KB
references/workflows/audit-workflow.mdmarkdown2.5 KB
references/workflows/brownfield-workflow.mdmarkdown3.6 KB
references/workflows/brownfield/fastapi-guide.mdmarkdown1.8 KB
references/workflows/brownfield/pulumi-guide.mdmarkdown1.9 KB
references/workflows/brownfield/springboot-guide.mdmarkdown2.2 KB
references/workflows/convert-workflow.mdmarkdown1.4 KB
references/workflows/design-workflow.mdmarkdown3.0 KB
references/workflows/diagram-workflow.mdmarkdown3.7 KB
references/workflows/greenfield-workflow.mdmarkdown3.4 KB
references/workflows/greenfield/advanced.mdmarkdown1.9 KB
references/workflows/greenfield/openapi-guide.mdmarkdown2.5 KB
references/workflows/greenfield/prd-guide.mdmarkdown2.0 KB
references/workflows/greenfield/srs-guide.mdmarkdown2.0 KB
references/workflows/runbook-workflow.mdmarkdown2.4 KB
references/workflows/tutorial-workflow.mdmarkdown2.3 KB
references/workflows/user-docs-workflow.mdmarkdown2.3 KB

references/templates/markdown/api-openapi.yaml

View on GitHub
openapi: 3.0.3
info:
  title: [API Name]
  description: |
    # [API Name] REST API

    This API provides [brief description of what the API does].

    ## Base URL
    - **Production**: `https://api.example.com/v1`
    - **Staging**: `https://staging-api.example.com/v1`

    ## Authentication
    All API requests require authentication using JWT Bearer tokens.
    Include the token in the `Authorization` header:
    ```
    Authorization: Bearer <your_jwt_token>
    ```

    ## Rate Limiting
    - **Authenticated requests**: 1000 requests per hour
    - **Unauthenticated requests**: 100 requests per hour

    Rate limit information is included in response headers:
    - `X-RateLimit-Limit`: Maximum requests per hour
    - `X-RateLimit-Remaining`: Remaining requests
    - `X-RateLimit-Reset`: Unix timestamp when limit resets

    ## Pagination
    List endpoints support pagination using query parameters:
    - `page`: Page number (default: 1)
    - `per_page`: Items per page (default: 50, max: 100)

    Pagination metadata is included in the response under `meta`.

    ## Error Handling
    The API uses conventional HTTP response codes:
    - `2xx`: Success
    - `4xx`: Client errors (invalid request)
    - `5xx`: Server errors

    Error responses include a JSON body with `code` and `message` fields.

    ## Versioning
    The API is versioned via the URL path (`/v1`, `/v2`). Breaking changes will result in a new version.

  version: 1.0.0
  contact:
    name: API Support
    email: api-support@example.com
    url: https://example.com/support
  license:
    name: Proprietary
    url: https://example.com/terms

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
  - url: http://localhost:3000/v1
    description: Local development server

tags:
  - name: Authentication
    description: User authentication and authorization
  - name: Users
    description: User account management
  - name: Tasks
    description: Task management operations
  - name: Projects
    description: Project management operations

# ============================================================================
# REUSABLE COMPONENTS
# ============================================================================
components:

  # Security Schemes
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token obtained from the `/auth/login` endpoint.
        Include in the Authorization header as: `Bearer <token>`

  # Reusable Schemas (Data Models)
  schemas:

    # User Model
    User:
      type: object
      required:
        - id
        - email
        - name
      properties:
        id:
          type: string
          format: uuid
          description: Unique user identifier
          example: "550e8400-e29b-41d4-a716-446655440000"
        email:
          type: string
          format: email
          description: User's email address
          example: "user@example.com"
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: User's full name
          example: "John Doe"
        role:
          type: string
          enum: [user, admin, superadmin]
          description: User's role in the system
          example: "user"
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp
          example: "2025-01-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: "2025-01-15T14:45:00Z"

    # Task Model
    Task:
      type: object
      required:
        - id
        - title
        - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique task identifier
          example: "660e8400-e29b-41d4-a716-446655440001"
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Task title
          example: "Implement user authentication"
        description:
          type: string
          maxLength: 2000
          description: Detailed task description
          example: "Add JWT-based authentication with refresh tokens"
        status:
          type: string
          enum: [pending, in_progress, in_review, completed, archived]
          description: Current status of the task
          example: "in_progress"
        priority:
          type: string
          enum: [low, medium, high, urgent]
          description: Task priority level
          example: "high"
        assignee_id:
          type: string
          format: uuid
          nullable: true
          description: ID of the assigned user
          example: "550e8400-e29b-41d4-a716-446655440000"
        project_id:
          type: string
          format: uuid
          description: ID of the parent project
          example: "770e8400-e29b-41d4-a716-446655440002"
        due_date:
          type: string
          format: date
          nullable: true
          description: Task deadline
          example: "2025-02-01"
        created_at:
          type: string
          format: date-time
          example: "2025-01-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2025-01-16T09:15:00Z"

    # Request/Response Models
    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          example: "user@example.com"
        password:
          type: string
          format: password
          minLength: 8
          example: "SecureP@ssw0rd"

    LoginResponse:
      type: object
      required:
        - access_token
        - token_type
        - expires_in
      properties:
        access_token:
          type: string
          description: JWT access token
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        refresh_token:
          type: string
          description: Refresh token for obtaining new access tokens
          example: "dGVzdF9yZWZyZXNoX3Rva2VuXzEyMzQ1..."
        token_type:
          type: string
          example: "Bearer"
        expires_in:
          type: integer
          description: Token expiration time in seconds
          example: 3600
        user:
          $ref: '#/components/schemas/User'

    CreateTaskRequest:
      type: object
      required:
        - title
        - project_id
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          example: "Design new landing page"
        description:
          type: string
          maxLength: 2000
          example: "Create a modern, responsive landing page with hero section and feature showcase"
        priority:
          type: string
          enum: [low, medium, high, urgent]
          default: medium
        assignee_id:
          type: string
          format: uuid
          nullable: true
        project_id:
          type: string
          format: uuid
        due_date:
          type: string
          format: date
          nullable: true

    UpdateTaskRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 2000
        status:
          type: string
          enum: [pending, in_progress, in_review, completed, archived]
        priority:
          type: string
          enum: [low, medium, high, urgent]
        assignee_id:
          type: string
          format: uuid
          nullable: true
        due_date:
          type: string
          format: date
          nullable: true

    # Generic Response Models
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: "invalid_request"
        message:
          type: string
          description: Human-readable error message
          example: "The 'title' field is required"
        details:
          type: object
          additionalProperties: true
          description: Additional error context

    PaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items: {}
          description: Array of resources
        meta:
          type: object
          required:
            - page
            - per_page
            - total
            - total_pages
          properties:
            page:
              type: integer
              example: 1
            per_page:
              type: integer
              example: 50
            total:
              type: integer
              example: 237
            total_pages:
              type: integer
              example: 5

  # Reusable Parameters
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number for pagination
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
        example: 1

    PerPageParam:
      name: per_page
      in: query
      description: Number of items per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
        example: 50

    TaskIdParam:
      name: task_id
      in: path
      description: Unique task identifier
      required: true
      schema:
        type: string
        format: uuid
        example: "660e8400-e29b-41d4-a716-446655440001"

  # Reusable Responses
  responses:
    UnauthorizedError:
      description: Authentication credentials missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "unauthorized"
            message: "Invalid or expired authentication token"

    ForbiddenError:
      description: Authenticated but not authorized to access resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "forbidden"
            message: "You do not have permission to perform this action"

    NotFoundError:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "not_found"
            message: "Task with id '660e8400-e29b-41d4-a716-446655440001' not found"

    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "validation_error"
            message: "Validation failed"
            details:
              title: "Title is required"
              due_date: "Must be a future date"

    RateLimitError:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "rate_limit_exceeded"
            message: "Too many requests. Please try again later."
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per hour
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp when limit resets

# ============================================================================
# API ENDPOINTS
# ============================================================================
paths:

  # ========================================
  # Authentication Endpoints
  # ========================================
  /auth/login:
    post:
      summary: User login
      description: Authenticate a user and obtain access tokens
      operationId: loginUser
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "invalid_credentials"
                message: "Invalid email or password"
        '429':
          $ref: '#/components/responses/RateLimitError'

  /auth/logout:
    post:
      summary: User logout
      description: Invalidate the current access token
      operationId: logoutUser
      tags:
        - Authentication
      security:
        - BearerAuth: []
      responses:
        '204':
          description: Logout successful (no content)
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  # ========================================
  # Task Endpoints
  # ========================================
  /tasks:
    get:
      summary: List tasks
      description: Retrieve a paginated list of tasks
      operationId: listTasks
      tags:
        - Tasks
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: status
          in: query
          description: Filter by task status
          required: false
          schema:
            type: string
            enum: [pending, in_progress, in_review, completed, archived]
        - name: assignee_id
          in: query
          description: Filter by assigned user ID
          required: false
          schema:
            type: string
            format: uuid
        - name: project_id
          in: query
          description: Filter by project ID
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of tasks
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'

    post:
      summary: Create a task
      description: Create a new task
      operationId: createTask
      tags:
        - Tasks
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
      responses:
        '201':
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'

  /tasks/{task_id}:
    get:
      summary: Get a task
      description: Retrieve a specific task by ID
      operationId: getTask
      tags:
        - Tasks
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      responses:
        '200':
          description: Task details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'

    put:
      summary: Update a task
      description: Update a specific task by ID
      operationId: updateTask
      tags:
        - Tasks
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'

    delete:
      summary: Delete a task
      description: Delete a specific task by ID
      operationId: deleteTask
      tags:
        - Tasks
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      responses:
        '204':
          description: Task deleted successfully (no content)
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'

# ============================================================================
# GLOBAL SECURITY (Applied to all endpoints unless overridden)
# ============================================================================
security:
  - BearerAuth: []
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall