LiorCohen/sdd / plugin/core/skills/external-spec-integration
external-spec-integration
VerifiedProcess external specifications through transformation, classification, gap analysis, component discovery, and decomposition. Creates workflow items with classified context.
External Spec Integration Skill
Processes external specification files into the SDD workflow structure. Transforms product specs into classified tech spec context - specs are created interactively one at a time.
Purpose
When a user provides an external specification via /sdd I want to import an external spec:
- Archive the external spec to
sdd/archive/external-specs/(single copy, yyyymmdd-HHmm-filename format) - TRANSFORM the spec: classify information, identify gaps, ask clarifying questions
- DISCOVER required components through targeted questions
- DECOMPOSE into workflow items with classified context
- Create workflow items with context in
sdd/workflows/<id>-<name>/ - DO NOT create SPEC.md or PLAN.md files - those are created interactively
CRITICAL: External specs are product specs (WHAT/WHY). This skill transforms them into tech spec context (HOW) before decomposition.
Key Insight: External Specs Are Inherently Incomplete
Always assume external specs are lacking:
- Details not thought through by product people
- Technical implications not considered by non-engineers
- Missing edge cases, error handling, and non-functional requirements
- Implicit assumptions never made explicit
Critical asymmetry:
| Area | Typical Detail Level | Action Required |
|---|---|---|
| User-Facing Interface | High | Extract and classify |
| UX/Design | High | Extract and classify |
| Integration Contracts | Low | Must be DERIVED from interface |
| Business Logic | Very Low | Must be extracted through questions |
| Persistence/Data | Very Low | Must be discovered from interface + actions |
| Non-Functional | Absent | Must be explicitly asked |
When to Use
- During
/sdd I want to import an external specwhen external spec is provided
Input
Schema: schemas/input.schema.json
Accepts path to external spec file, target directory, workflow ID, and optional domain.
Output
Schema: schemas/output.schema.json
Returns archived spec path, workflow ID, hierarchical flag, and list of created workflow items.
Workflow Overview
- Archive external spec to
sdd/archive/external-specs/via system CLI - Detect large specs (>15K tokens) and chunk if needed
- Transform product spec: classify information, identify gaps, ask clarifying questions
- Discover components via component-discovery skill (once for entire spec)
- Present outline to user with hierarchical decomposition if applicable
- Thinking step — domain analysis, specs impact, gap analysis, API-first ordering
- Display thinking output for user review
- Create workflow items via workflow-state skill
- Create context files (
context.md) for each leaf item - Return summary with transformation, components, items, and thinking output
Resource Files
For detailed guidance, read these on-demand:
- workflow-steps.md — Detailed steps 1-10 with YAML examples
- transformation.md — Classification, gap analysis, clarification process
Key Differences from Previous Version
| Before | After |
|---|---|
| Created SPEC.md + PLAN.md immediately | Creates workflow items with context only |
Archived to archive/ | Archives to sdd/archive/external-specs/ |
| No domain analysis | Comprehensive thinking step with domain extraction |
| No transformation | NEW: Transformation classifies and identifies gaps |
| No component discovery | NEW: Component discovery before decomposition |
| Order in session only | Order persisted in workflow.yaml |
| All specs created upfront | Specs created one at a time through solicitation |
| Modal dialogs for questions | NEW: Non-blocking conversational questions |
Dependencies
This skill orchestrates:
workflow-state- Creates workflow and itemscomponent-discovery- Identifies needed components (NEW)spec-decomposition- Analyzes spec structure with thinking step
Trigger: /sdd I want to import an external spec command.
Workflow Steps Summary
| Step | Action | Output |
|---|---|---|
| 1 | Archive External Spec | sdd/archive/external-specs/... |
| 2 | Detect Large Specs | Size estimation, chunking plan |
| 3 | Transformation | Classification, gaps, clarifications |
| 4 | Component Discovery | Components list (not applied) |
| 5 | Present Outline | User reviews structure |
| 6 | Thinking Step | Domain analysis, dependencies |
| 7 | Display Thinking | User confirms analysis |
| 8 | Create Workflow Items | Items in workflow.yaml |
| 9 | Create Context Files | context.md for each item |
| 10 | Return Summary | Complete output |
Notes
- External specs are product specs - they are transformed, not copied
- Transformation happens BEFORE decomposition
- Component discovery runs ONCE for entire spec (not per-item)
- Questions are non-blocking and conversational (no modal dialogs)
- All Q&A is preserved and flows into SPEC.md Requirements Discovery section
- Context files contain classified content for use during solicitation
- Items are processed one at a time - user reviews each spec before moving to next
- Hierarchical decomposition is mandatory for specs meeting criteria (2+ H1 with H2+)
- Numbers indicate implementation order based on API-first dependency sort
- Large specs (>15K tokens) use chunked processing with per-section progress
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |