Turn Vague "Vibes" into Industrial-Grade, Interactive, Bulletproof Artifacts.
Building LLM Agents is easy. Building reliable LLM Agents is a nightmare. You know the drill:
- Vague Instructions: "Write a summary" leads to random results.
- Fragile Logic: The agent crashes on edge cases.
- Spaghetti State: Context gets lost in a sea of unstructured dictionaries.
- Happy Path Only: It works for the demo, but fails in production.
Skill-Spec is the "Adult in the Room" for your AI workflow. It forces LLMs to adhere to strict Quality Standard Alignment. We don't just "prompt" models; we architect behaviors.
This is a framework for Defensive Agent Engineering.
We believe in the "Do vs. Don't" paradigm:
| The Old Way (Vague Guidance) | The Skill-Spec Way (Specific Specs) |
|---|---|
| "Be helpful and concise." | Forbidden Pattern Scan: Reject "filler words". |
| "Handle errors." | Mandatory Edge Cases: Define logic for timeouts & bad data. |
| "Output the result." | Output Contract: Enforce strict JSON Schema. |
You don’t need another "system prompt." You need a Tool. Standard prompts are passive—they wait for input and hope for the best.
- The "Yes-Man" Problem: You ask for a critique; the AI just compliments you.
- The Context Black Hole: One complex request later, the AI forgets constraints.
- Zero Interactivity: The AI guesses what you mean instead of asking.
Skill-Spec is your dedicated Claude Skill Manufacturing Plant. We treat Prompt Engineering as Software Engineering. You give us the raw intent; we manufacture a deployed Interactive Skill ready for your Claude Projects.
A Skill-Spec generated skill isn't a passive responder; it is an Active Partner.
- The Interviewer Mode: If input is vague, the Skill halts execution and interviews you.
- The Guardrail Enforcer: It actively rejects inputs that violate the schema before processing.
- The Step-by-Step Navigator: It guides users through complex workflows.
See the difference between a "Chat" and a "Skill-Spec Artifact":
| The "Vibes" Approach | The Skill-Spec Artifact |
|---|---|
| User: "Review this code." | Trigger: run_architecture_audit |
| AI: "Looks good! Maybe add comments." | Protocol: 1. Scan: Identify Dependency Inversion violations. 2. Reject: If no unit tests, STOP and request them. 3. Output: Generate Markdown table classifying risks. 4. Interactive: "Found security flaw. Want me to write a patch?" |
| The "Vibes" Approach | The Skill-Spec Artifact |
|---|---|
| User: "Write a press release." | Trigger: generate_press_kit |
| AI: Writes generic fluff with emojis. | Protocol: 1. Interview: "Who is the target audience? What is the USP?" 2. Forbidden Patterns: Ban words like "Revolutionary," "Game-changing." 3. Critique: Self-grade draft against viral hooks. |
Don't just write a prompt. Build a Skill.
# Clone the repository
git clone https://github.com/bethneyQQ/skill-spec/skill-spec.git
cd skill-spec
# Install from source
pip install -e .cd my-project
skillspec setupThis command automatically:
- Detects your AI tools (Claude Code, Cursor, Cline, Codex)
- Creates
skillspec/directory structure - Installs slash commands for interactive skill creation
- Creates
project.yamlfor configuration
In Claude Code (or your AI tool), type:
/skill-spec:proposal my-skill
The AI will:
- Ask about purpose, inputs, decision rules, edge cases
- Generate complete
spec.yamlfrom your answers - Validate with
--strictand save toskillspec/drafts/my-skill/
skillspec setup # Initialize project
|
v
/skill-spec:proposal <name> # AI-assisted creation + validation
|
v
/skill-spec:apply <name> # Generate SKILL.md
|
v
/skill-spec:deploy <name> # Publish skill
| Command | Description |
|---|---|
/skill-spec:proposal <name> |
Interactive skill creation + validation |
/skill-spec:apply <name> |
Generate SKILL.md from spec |
/skill-spec:deploy <name> |
deploy your skill to dir/ eg. .claude/skills |
/skill-spec:migrate <path> |
Migrate existing skill |
| Command | Description |
|---|---|
skillspec setup |
Initialize project |
skillspec list |
List all skills |
skillspec validate <name> --strict |
Validate spec |
skillspec report <name> |
Quality report (text output) |
skillspec report <name> --format json |
Quality report (JSON output) |
skillspec report <name> --format markdown |
Quality report (Markdown output) |
skillspec convert-report <json> |
Convert JSON report to Markdown |
my-project/
+-- .claude/commands/skill-spec/ # Slash commands
+-- skillspec/
| +-- drafts/ # Work in progress
| +-- skills/ # Published
+-- project.yaml # Configuration
- Mandatory Section Taxonomy: 8 Core + 1 Coverage sections
- Forbidden Pattern Detection: Catches vague language
- Coverage Analysis: Ensures complete specification
- Consistency Validation: Cross-references all components
- Structured Templates: Pre-defined spec.yaml templates
- Clear Validation Feedback: Actionable error messages
- Quality Reports: Structural and behavioral coverage scores
- Migration Tools: Convert existing SKILL.md files
- Custom Policy Rules: Organization-specific requirements
- Tag Taxonomy: Data classification (PII, financial, auth)
- Compliance Validation: GDPR, security rules
- Audit Evidence: Diary system for compliance audits
spec.yaml
|
v
Layer 1: Schema # Structure, required fields
|
v
Layer 2: Quality # Forbidden patterns
|
v
Layer 3: Coverage # Edge cases, decision rules
|
v
Layer 4: Consistency # Cross-references
|
v
Layer 5: Compliance # Enterprise policies (optional)
# Chinese output
skillspec --locale=zh validate my-skill
# Chinese patterns
skillspec --patterns=zh validate my-skill
# Combined patterns (strictest)
skillspec --patterns=union validate my-skillConfiguration in project.yaml:
skill_spec:
report_locale: en # en | zh
patterns_locale: union # en | zh | union
template_locale: en # en | zhMIT