spec
This skill guides an AI agent to collaboratively think through and create a detailed technical specification document via structured Q&A. It clarifies target, behavior, and design before generating the spec file.
About this skill
The `/eidos:spec` skill empowers an AI agent to facilitate the creation of comprehensive technical specifications. It operates by first gathering all relevant context, including existing 'seed' files, related specifications, claims, code implementations, and prior research or decisions. Following context gathering, the agent engages the user in an iterative, structured question-and-answer process. It starts with high-level orientation questions about the spec's purpose and target, then drills down into key behaviors, edge cases, boundaries, and design considerations. The agent follows up on critical aspects like interactions, verification, and potential friction points, building understanding progressively rather than asking everything at once. Finally, the skill drafts the spec file based on the collected information and Q&A, adhering to a predefined template. This ensures that all necessary sections are included with substantive content, resulting in a clear, well-defined specification. This skill is invaluable for any development process requiring thorough planning and documentation, helping to prevent ambiguity and ensure comprehensive design before coding begins.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/spec/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How spec Compares
| Feature / Agent | spec | Standard Approach |
|---|---|---|
| Platform Support | multi | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | easy | N/A |
Frequently Asked Questions
What does this skill do?
This skill guides an AI agent to collaboratively think through and create a detailed technical specification document via structured Q&A. It clarifies target, behavior, and design before generating the spec file.
Which AI agents support this skill?
This skill is compatible with multi.
How difficult is it to install?
The installation complexity is rated as easy. You can find the installation instructions above.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# /eidos:spec
Think through a spec collaboratively before writing it.
Asks questions to clarify target, behaviour, and design, then produces the spec file.
## Usage
```
/eidos:spec [topic or name]
```
## Instructions
### 1. Gather Context
If the target file already exists with `status: seed`, read it — its content is raw context that seeds the Q&A.
Use the seed's notes, links, and brain dumps as pre-answered context.
Skip questions the seed already covers.
Search for related artifacts:
- Existing specs in `eidos/` that touch the same domain
- Claims or concepts that relate
- Code that already implements parts of this (check Mapping sections)
- Prior research, decisions, or plans in `memory/`
If found, note them — they inform the questions and shape Interactions.
### 2. Clarify the Spec
Use AskUserQuestion to think through the spec iteratively.
Start with orientation:
- What is this spec about?
- What problem or goal does it target?
- Who or what is affected?
Then drill into behaviour:
- What are the key behaviours or claims?
- What happens in edge cases?
- What should explicitly NOT happen? (boundaries)
Then design if relevant:
- Are there architectural choices to make?
- What patterns should it follow?
- Any constraints from existing code or specs?
Follow up as needed on:
- **Interactions** — what does this depend on, what does it affect?
- **Verification** — how would you know this works?
- **Friction** — known trade-offs or rough edges?
Don't ask everything at once — build understanding progressively.
Skip questions the user already answered in their initial description.
### 3. Create Spec File
Read the template: [[template - spec - sections and conventions for spec files]]
Draft the spec from the Q&A.
Only include sections that have substance — don't add empty sections.
Write directly to `eidos/spec - <name> - <claim>.md`.
If it's a skill spec, write to `eidos/skills/spec - <name> - <claim>.md`.
Don't present a draft first — the user sees the diff and can request changes.
Commit immediately.
### 4. Offer Next Steps
Choose which options to present based on the spec's scope:
- **Small/focused spec** (single concern, clear implementation) → offer `/eidos:push`
- **Large/multi-concern spec** (new feature, multiple files, architectural) → offer `/eidos:plan` — implementation at this scale needs a plan, not a direct push
- Always offer `/eidos:refine` if there are open questions or `{{comments}}`
```
Spec created: [[spec - <name> - <claim>]]
Options:
1 - Plan implementation with /eidos:plan
2 - Implement directly with /eidos:push
3 - Refine further with /eidos:refine
4 - Done for now
```
## Output
- Creates: spec file in `eidos/` or `eidos/skills/`