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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.7 KB |
| resources/transformation.md | markdown | 3.8 KB |
| resources/workflow-steps.md | markdown | 8.7 KB |
| schemas/input.schema.json | config | 836 B |
| schemas/output.schema.json | config | 1.8 KB |
SKILL.md
View on GitHub---
name: external-spec-integration
description: Process external specifications through transformation, classification, gap analysis, component discovery, and decomposition. Creates workflow items with classified context.
user-invocable: false
---
# 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 spec` when external spec is provided
## Input
Schema: [`schemas/input.schema.json`](./schemas/input.schema.json)
Accepts path to external spec file, target directory, workflow ID, and optional domain.
## Output
Schema: [`schemas/output.schema.json`](./schemas/output.schema.json)
Returns archived spec path, workflow ID, hierarchical flag, and list of created workflow items.
## Workflow Overview
1. **Archive** external spec to `sdd/archive/external-specs/` via system CLI
2. **Detect large specs** (>15K tokens) and chunk if needed
3. **Transform** product spec: classify information, identify gaps, ask clarifying questions
4. **Discover components** via component-discovery skill (once for entire spec)
5. **Present outline** to user with hierarchical decomposition if applicable
6. **Thinking step** — domain analysis, specs impact, gap analysis, API-first ordering
7. **Display thinking** output for user review
8. **Create workflow items** via workflow-state skill
9. **Create context files** (`context.md`) for each leaf item
10. **Return summary** with transformation, components, items, and thinking output
## Resource Files
For detailed guidance, read these on-demand:
- [workflow-steps.md](resources/workflow-steps.md) — Detailed steps 1-10 with YAML examples
- [transformation.md](resources/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 items
- `component-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: 322k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |