technical-spec-design

Transforms product requirements into structured technical specifications. Auto-triggers when requirements are unclear, multiple implementation approaches exi...

Security Scan

The skill's code, templates, and runtime instructions are consistent with its stated purpose (generating technical specifications); there are no network calls, secret access, or obvious exfiltration behaviors, but there are minor repository/metadata inconsistencies worth noting before installation.

Purpose & Capability

Name/description (technical-spec-design) align with included files (templates, examples, generate_spec.py, validate.py). The scripts and resources are appropriate for generating specs and validating skill structure.

Instruction Scope

SKILL.md instructs only on spec generation, clarify/check modes, and installation. Runtime instructions and scripts operate on local files and interactive input; they do not request or read unrelated system files or environment secrets.

Install Mechanism

No formal install spec (instruction-only). A manual git clone URL is provided (github.com/wjszxli/technical-spec-design). Scripts are small, use only the Python standard library, and do not download or execute remote payloads. Verify the GitHub source before cloning from an unknown owner.

Credentials

The skill declares no required environment variables, credentials, or config paths. Python scripts read local resource files and user input only; no access to external secrets or network endpoints is present in the code.

Persistence & Privilege

always is false and the skill does not request persistent/system-wide privileges. It does not modify other skills or system configs. Autonomous invocation by the agent is allowed by default (normal), and nothing in the skill indicates elevated persistence.

Assessment

This skill appears to do what it says: generate and validate technical-spec documents using local templates. Before installing, confirm the source (the manual install URL points to a personal GitHub account), and prefer installing from your platform's official registry if available. Note minor inconsistencies in the package: file-name casing (SKILL.md vs expected skill.md) and mixed platform names (OpenClaw / ClawdHub / Claude) — these are likely editorial issues but could cause validation scripts to warn or fail on case-sensitive systems. If you proceed, review the repository contents locally and run scripts in a sandbox (or inspect generate_spec.py/validate.py) to ensure they meet your policies.

Installation

OpenClaw Setup (Recommended)

OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading.

Via ClawdHub (recommended):

clawdhub install technical-spec-design

Manual:

git clone https://github.com/wjszxli/technical-spec-design ~/.openclaw/skills/technical-spec-design

Technical Specification Design Skill

1. Input Contract

Accepts the following input types:

1. Complete PRD document
2. Brief requirements description (may be incomplete)
3. Existing technical specification (for optimization/review)

---

2. Available Resources

Core Templates

Resource	Purpose	Usage Scenario
spec_template.md	Main spec template	Starting new technical specs
component_template.md	Component design	Designing individual components
requirements_analysis_template.md	Requirements analysis	Breaking down requirements

Examples

Resource	Purpose
examples/sample_input.md	Sample PRD input
examples/sample_output.md	Complete spec example

Scripts

Script	Purpose	Usage
scripts/generate_spec.py	Generate spec from template	python scripts/generate_spec.py --interactive -o my_spec.md
scripts/validate.py	Validate skill structure	python scripts/validate.py

---

3. Output Contract

Output must be Markdown and strictly include the following structure (may be trimmed by mode):

Standard Structure

1. Requirements Clarification (if needed)
2. Requirements Analysis (the trifecta)
3. Technical Specification Design
4. Component/Module Design
5. Technology Selection Comparison (if applicable)
6. Risk and Boundary Analysis
7. Pending Questions

---

4. Mode System (Auto-selected)

Mode A: Requirements Clarification Mode

Trigger conditions:

• Insufficient input information
• Key uncertainties exist

Output:

• Only output "Requirements Clarification Questions"
• Do not proceed with any design work

---

Mode B: Lightweight Specification Mode

Trigger conditions:

• Simple features
• Implementation path is relatively clear

Output:

• Simplified requirements analysis
• Core specification design
• Brief component breakdown

---

Mode C: Full Technical Specification Mode (Default)

Trigger conditions:

• Medium to large requirements
• Involves architecture/component design/technology selection

Output complete structure

---

5. Execution Flow (Must Follow Strictly)

Step 1: Requirements Completeness Check

Check for missing information:

• User goals
• Requirements context
• Inputs and outputs
• Constraints
• Edge cases

If missing: → Enter Mode A, output only clarification questions

---

Step 2: Requirements Analysis (The Trifecta)

1. Feature Breakdown

Format: Product requirement → Page/Module → Change points

2. Use Case Analysis

Describe complete user paths (cross-page)

3. Page Operation Specification

Format: Action + Condition + Object + Behavior

---

Step 3: Technical Specification Design

Include:

• Architecture breakdown (frontend/backend/services)
• Data flow design
• State management
• Core processes (pseudocode acceptable)

---

Step 4: Component/Module Design

Requirements:

• Must drill down to component/module level
• Clear responsibility boundaries
• Describe dependencies

---

Step 5: Technology Selection Comparison (If Multiple Options)

Must use table format:

| Approach | Description | Pros | Cons | Use Cases |

---

Step 6: Risk and Boundary Analysis

Must include:

• Edge cases
• Performance concerns
• Scalability
• Exception handling

---

Step 7: Output Pending Questions

List all issues still requiring product/business confirmation

---

6. Output Constraints (Mandatory)

Prohibited

• ❌ Output runnable code (JS / TS / Java / SQL, etc.)
• ❌ Skip requirements analysis and write specs directly
• ❌ Make assumptions based on "common cases"
• ❌ Use vague language (e.g., "maybe", "typically")

---

Required

• ✅ Use structured expression
• ✅ Use pseudocode for process descriptions
• ✅ All changes must map to components/modules
• ✅ Explicit boundaries and exceptions

---

7. Technology Research Guidelines

When multiple approaches exist, must use comparison tables—plain text descriptions are not allowed.

---

8. Red Flags (Must Stop)

If any of these thoughts occur, must stop and return to the process:

• "Just write a rough spec first"
• "Handle it the common way"
• "Design while coding"
• "This requirement is simple, no analysis needed"

---

9. Quick Checklist

Before output, must confirm:

• Requirements clarified
• Trifecta complete
• Component design included
• Pseudocode used
• Edge cases analyzed
• Pending questions documented

---

10. Examples (Few-shot)

Example 1: Ambiguous Requirements (Mode A)

Input: "Build a comment feature"

Output:

• Do comments support replies?
• Is pagination needed?
• Is liking/upvoting needed?
• Is moderation required?

---

Example 2: Simple Requirements (Mode B)

Input: "Show success message after form submission"

Output:

• Brief feature breakdown
• State transitions
• Toast/notification component design

---

Example 3: Complex Requirements (Mode C)

Input: "Design an admin system with multi-role permissions"

Output: Complete technical specification structure (including technology comparison)

---

Core Principles (Summary)

The essence of technical specifications: eliminate uncertainty before coding.