القائمة
Generates a technical specification document for a new feature or product.
| name | create-technical-spec |
| description | Generates a technical specification document for a new feature or product. |
This skill guides the creation of technical specification documents using a standardized template.
Analyze the Requirement: Understand the feature or product being requested.
Determine Output Mode: The spec can be written as a local file (default), created directly as a GitHub issue on the current repo, or promoted from an existing local file to a GitHub issue. See Output Modes below.
Generate Content: Use the template below to structure the document.
Write the Spec: Save or publish according to the selected mode.
QA Test Plan: After the spec is written, propose a QA test plan to the user. Draft a suggested plan based on the spec's goals, API design, and any Figma references, then present it with the following structure:
Ask the user to confirm, adjust, or skip the test plan. If confirmed or adjusted, add the finalised plan as a ## QA Test Plan section in the spec (update the file/issue accordingly). If skipped, leave the section out — do not add a placeholder.
The skill supports three modes. Detect the mode from the user's request — accept both explicit tokens and natural phrasing. Default to Local when no issue-related intent is expressed.
The spec is saved as a markdown file in the workspace.
specs/ at the root of the workspace (create if missing)<feature-name>.md (e.g., specs/user-authentication.md)Skip the local file and create a GitHub issue on the current repo. Use this when the user wants the spec to be reachable by cloud sessions from the outset.
Triggers — either is sufficient:
--issue or --as-issue appearing in the user's requestSteps:
gh repo view).spec label exists on the repo without overwriting an existing one: gh label create spec --color 4C47EA --description "technical or product spec that can be picked up by an agent" 2>/dev/null || true. This creates the label if missing and is a no-op if it already exists (regardless of the existing color or description)./tmp (e.g. /tmp/spec-<feature-name>-<timestamp>.md). /tmp is cleared on reboot, so no manual cleanup is required.gh issue create --title "<Feature Name> — Technical Spec" --label spec --body-file /tmp/spec-<feature-name>-<timestamp>.md.Take an existing local spec file and publish it as a GitHub issue. The local file is kept and stamped with the issue number and URL so it can be re-fetched later.
Triggers — either is sufficient:
--promote appearing in the user's request, typically with a path (e.g. --promote specs/foo.md)<path> to an issue", or similar phrasing that explicitly uses "promote"Steps:
Read the local spec file.
Ensure the spec label exists on the repo without overwriting an existing one: gh label create spec --color 4C47EA --description "technical or product spec that can be picked up by an agent" 2>/dev/null || true. This creates the label if missing and is a no-op if it already exists (regardless of the existing color or description).
Create the issue: gh issue create --title "<Title> — Technical Spec" --label spec --body-file <path-to-local-spec>. The local spec file itself is used as the body source — no tempfile needed.
Stamp the local file by inserting an HTML comment at the top of the body (below the title), e.g.:
<!-- github-issue: #42 https://github.com/<owner>/<repo>/issues/42 -->
Report the issue URL and confirm the local file has been stamped.
Once a spec lives as an issue, treat the issue body as the source of truth. Local copies may go stale — that's expected.
gh issue edit <num> --body-file <new> locally, or through the issue UI in any cloud session).gh issue view <num> --json body -q .body and overwrite the local file (preserving the stamp line).# Technical Spec
**Title**: [Feature/Product Name] - Technical Spec
**Author**: [Tech Lead] | **Status**: Draft/Approved/Implemented | **Date**: [YYYY-MM-DD]
**Product Spec**: [Link]
---
## Overview
**Product Context**: 1-2 sentences on WHAT we're building (link to product spec if any)
**Technical Approach**: 2-3 sentences on HOW we'll build it
**Key Technologies**: Languages, frameworks, databases, infrastructure
---
## Figma References (when translating designs to code)
Group Figma frame URLs by purpose, e.g.:
- Full-page layouts
- Component references
- Asset nodes (icons, images to export)
Each entry is a clickable Markdown link to the user-provided URL with a short label. No node IDs in body text — the URL is enough.
When this section is present, add "Pixel-perfect parity with the Figma full-layout frames" as a Goal.
---
## Goals & Non-Goals
**Goals**: Technical objectives (scalability, performance targets, app builds fine with no introduced lint or type errors, etc.)
**Non-Goals**: What we're explicitly not doing in this iteration
---
## Current System
**Existing Architecture**: Brief description or diagram of relevant current state
**Limitations**: What doesn't work today
**What We'll Leverage**: Existing code, patterns, infrastructure we can reuse
---
## Proposed Architecture
**Diagram**: High-level architecture showing major components and data flow
**Component Overview**: Table of components, their technology, responsibility, scaling strategy
---
## API Design
For each endpoint:
- **`METHOD /path`**: Purpose, auth requirements
- **Request**: Schema/format
- **Response**: Success and error formats
- **Validation**: What's checked
- **Error Codes**: 400, 401, 404, 500, etc.
---
## Data Models
For each model:
- **Schema**: Table/collection structure with types and constraints
- **Indexes**: Which columns/fields, for what query patterns
- **Migrations**: What needs to change in the database
---
## Architecture Decisions (ADRs)
For each major decision:
- **Decision**: What we're deciding
- **Options**: 2-3 alternatives considered with pros/cons
- **Choice**: Which we chose and why
- **Trade-offs**: What we're accepting
---
## Security
- **Auth/Authz**: How users authenticate, what permissions exist
- **Input Validation**: Server-side validation approach
- **Data Protection**: Encryption at rest/transit, PII handling
- **Security Testing**: OWASP checks, dependency scanning
---
## Performance & Scale
- **Targets**: Response time, throughput, uptime SLAs
- **Optimization**: Caching strategy, database optimization, API efficiency
- **Scaling**: How we scale horizontally/vertically, bottlenecks and mitigation
---
## Error Handling & Reliability
- **Error Categories**: User errors (4xx) vs system errors (5xx)
- **Retry Strategy**: When to retry, backoff configuration
- **Fallback Behavior**: What happens when dependencies fail
---
## Monitoring
- **Key Metrics**: Request rate, error rate, latency (with alert thresholds)
- **Logging**: What to log, what NOT to log, retention
- **Dashboards**: Links to system health and feature analytics dashboards
- **Alerts**: Critical vs warning alerts and routing
---
## Testing
- **Unit Tests**: Coverage targets, what to test
- **Integration Tests**: API flows, database operations
- **E2E Tests**: Critical user flows
- **Performance Tests**: Load/stress/soak test scenarios
---
## QA Test Plan
> Added after spec creation by agreement with the author. Omit this section if no test plan was agreed upon.
- **Scope**: Features and flows covered by this test run
- **Scenarios**:
1. [Happy path scenario — step-by-step]
2. [Edge case or error scenario — step-by-step]
*(add as many scenarios as needed)*
- **Expected Outcomes**: What "pass" looks like for each scenario
---
## Implementation Plan
For each phase:
- **Goal**: What we achieve in this phase
- **Tasks**: Key work items
- **Deliverables**: What's shipped
- **Acceptance Criteria**: How we know it's done
---
## Deployment
- **Environments**: Dev, staging, production setup
- **Process**: Automated steps from merge to production
- **Feature Flags**: Gradual rollout strategy
- **Rollback Plan**: When to rollback and how
---
## Database Migrations
For each migration:
- **Forward**: Script to apply changes
- **Rollback**: Script to undo changes
- **Data Migration**: How to backfill/transform existing data
- **Validation**: How to verify success
---
## Operations & Runbook
- **Common Operations**: Scaling, cache clearing, etc.
- **Incident Response**: Symptoms, likely causes, first steps
---
## Dependencies & Risks
- **External Dependencies**: Services we rely on, SLAs, fallback strategies
- **Technical Risks**: Risk | Impact | Likelihood | Mitigation
- **Timeline Risks**: Critical path items, mitigation strategies
---
## Documentation
- [ ] API docs (OpenAPI/Swagger)
- [ ] Architecture diagrams
- [ ] Runbook for on-call
- [ ] Developer guide
React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.
Reviews code changes for correctness, quality, security, and rule compliance. Works on local files or a GitHub PR. Produces a structured report with severity levels and a pass/fail verdict.
Implements a feature based on a provided technical specification, ensuring build stability and strict adherence to the spec through a sub-agent code review. Creates a feature branch, commits changes, and raises a PR on completion.
QA skill for browser-based UI validation and functional test plan execution. Handles authentication and routes to the appropriate reference based on the task.
Sets up a Git worktree for a task or feature. Derives a branch name from the task description, creates an isolated worktree directory, copies env files, and installs dependencies. Use when starting work on a new feature or task in isolation.
Autonomously plans, specs, implements, and raises a PR for a task — without requiring the human to be present for the planning phase. Use this skill when the user hands off a task and asks you to handle it end-to-end, or when phrases like "auto-implement", "handle this autonomously", "fire and forget", or "work on this without me" appear. Also use when the user provides a task description and signals they want to review the output rather than participate in the planning.