Initial commit
This commit is contained in:
Zhongwei Li
445
skills/skill-factory/SKILL.md
Normal file
445
skills/skill-factory/SKILL.md
Normal file
@@ -0,0 +1,445 @@
|
||||
---
|
||||
name: skill-factory
|
||||
description: >
|
||||
Research-backed skill creation workflow with automated firecrawl research gathering, multi-tier
|
||||
validation, and comprehensive auditing. Use when "create skills with research automation",
|
||||
"build research-backed skills", "validate skills end-to-end", "automate skill research and
|
||||
creation", needs 8-phase workflow from research through final audit, wants firecrawl-powered
|
||||
research combined with validation, or requires quality-assured skill creation following
|
||||
Anthropic specifications for Claude Code.
|
||||
---
|
||||
|
||||
# Skill Factory
|
||||
|
||||
Comprehensive workflow orchestrator for creating high-quality Claude Code skills with automated research, content
|
||||
review, and multi-tier validation.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use skill-factory when:
|
||||
|
||||
- **Creating any new skill** - From initial idea to validated, production-ready skill
|
||||
- **Research needed** - Automate gathering of documentation, examples, and best practices
|
||||
- **Quality assurance required** - Ensure skills meet official specifications and best practices
|
||||
- **Guided workflow preferred** - Step-by-step progression with clear checkpoints
|
||||
- **Validation needed** - Runtime testing, integration checks, and comprehensive auditing
|
||||
|
||||
**Scope:** Creates skills for ANY purpose (not limited to meta-claude plugin):
|
||||
|
||||
- Infrastructure skills (terraform-best-practices, ansible-vault-security)
|
||||
- Development skills (docker-compose-helper, git-workflow-automation)
|
||||
- Domain-specific skills (brand-guidelines, conventional-git-commits)
|
||||
- Any skill that extends Claude's capabilities
|
||||
|
||||
## Available Operations
|
||||
|
||||
The skill-factory provides 8 specialized commands for the create-review-validate lifecycle:
|
||||
|
||||
| Command | Purpose | Use When |
|
||||
|---------|---------|----------|
|
||||
| `/meta-claude:skill:research` | Gather domain knowledge using firecrawl API | Need automated web scraping for skill research |
|
||||
| `/meta-claude:skill:format` | Clean and structure research materials | Have raw research needing markdown formatting |
|
||||
| `/meta-claude:skill:create` | Generate SKILL.md with YAML frontmatter | Ready to create skill structure from research |
|
||||
| `/meta-claude:skill:review-content` | Validate content quality and clarity | Need content review before compliance check |
|
||||
| `/meta-claude:skill:review-compliance` | Run quick_validate.py on SKILL.md | Validate YAML frontmatter and naming conventions |
|
||||
| `/meta-claude:skill:validate-runtime` | Test skill loading in Claude context | Verify skill loads without syntax errors |
|
||||
| `/meta-claude:skill:validate-integration` | Check for conflicts with existing skills | Ensure no duplicate names or overlaps |
|
||||
| `/meta-claude:skill:validate-audit` | Invoke claude-skill-auditor agent | Get comprehensive audit against Anthropic specs |
|
||||
|
||||
**Power user tip:** Commands work standalone or orchestrated. Use individual commands for targeted fixes,
|
||||
or invoke the skill for full workflow automation.
|
||||
|
||||
**Visual learners:** See [workflows/visual-guide.md](workflows/visual-guide.md) for decision trees, state diagrams,
|
||||
and workflow visualizations.
|
||||
|
||||
## Quick Decision Guide
|
||||
|
||||
### Full Workflow vs Individual Commands
|
||||
|
||||
**Creating new skill (full workflow):**
|
||||
|
||||
- With research → `skill-factory <skill-name> <research-path>`
|
||||
- Without research → `skill-factory <skill-name>` (includes firecrawl research)
|
||||
- From knowledge only → `skill-factory <skill-name>` → Select "Skip research"
|
||||
|
||||
**Using individual commands (power users):**
|
||||
|
||||
| Scenario | Command | Why |
|
||||
|----------|---------|-----|
|
||||
| Need web research for skill topic | `/meta-claude:skill:research <name> [sources]` | Automated firecrawl scraping |
|
||||
| Have messy research files | `/meta-claude:skill:format <research-dir>` | Clean markdown formatting |
|
||||
| Ready to generate SKILL.md | `/meta-claude:skill:create <name> <research-dir>` | Creates structure with YAML |
|
||||
| Content unclear or incomplete | `/meta-claude:skill:review-content <skill-path>` | Quality gate before compliance |
|
||||
| Check frontmatter syntax | `/meta-claude:skill:review-compliance <skill-path>` | Runs quick_validate.py |
|
||||
| Skill won't load in Claude | `/meta-claude:skill:validate-runtime <skill-path>` | Tests actual loading |
|
||||
| Worried about name conflicts | `/meta-claude:skill:validate-integration <skill-path>` | Checks existing skills |
|
||||
| Want Anthropic spec audit | `/meta-claude:skill:validate-audit <skill-path>` | Runs claude-skill-auditor |
|
||||
|
||||
**When to use full workflow:** Creating new skills from scratch
|
||||
**When to use individual commands:** Fixing specific issues, power user iteration
|
||||
|
||||
For full workflow details, see Quick Start section below.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Path 1: Research Already Gathered
|
||||
|
||||
If you have research materials ready:
|
||||
|
||||
```bash
|
||||
# Research exists at docs/research/skills/<skill-name>/
|
||||
skill-factory <skill-name> docs/research/skills/<skill-name>/
|
||||
```
|
||||
|
||||
The skill will:
|
||||
|
||||
1. Format research materials
|
||||
2. Create skill structure
|
||||
3. Review content quality
|
||||
4. Review technical compliance
|
||||
5. Validate runtime loading
|
||||
6. Validate integration
|
||||
7. Run comprehensive audit
|
||||
8. Present completion options
|
||||
|
||||
### Path 2: Research Needed
|
||||
|
||||
If starting from scratch:
|
||||
|
||||
```bash
|
||||
# Let skill-factory handle research
|
||||
skill-factory <skill-name>
|
||||
```
|
||||
|
||||
The skill will ask about research sources and proceed through full workflow.
|
||||
|
||||
### Example Usage
|
||||
|
||||
```text
|
||||
User: "Create a skill for CodeRabbit code review best practices"
|
||||
|
||||
skill-factory detects no research path provided, asks:
|
||||
|
||||
"Have you already gathered research for this skill?
|
||||
[Yes - I have research at <path>]
|
||||
[No - Help me gather research]
|
||||
[Skip - I'll create from knowledge only]"
|
||||
|
||||
User: "No - Help me gather research"
|
||||
|
||||
skill-factory proceeds through Path 2:
|
||||
1. Research skill domain
|
||||
2. Format research materials
|
||||
3. Create skill structure
|
||||
... (continues through all phases)
|
||||
```
|
||||
|
||||
## When This Skill Is Invoked
|
||||
|
||||
**Your role:** You are the skill-factory orchestrator. Your task is to guide the user through creating
|
||||
a high-quality, validated skill using 8 primitive slash commands.
|
||||
|
||||
### Step 1: Entry Point Detection
|
||||
|
||||
Analyze the user's prompt to determine which workflow path to use:
|
||||
|
||||
**If research path is explicitly provided:**
|
||||
|
||||
```text
|
||||
User: "skill-factory coderabbit docs/research/skills/coderabbit/"
|
||||
→ Use Path 1 (skip research phase)
|
||||
```
|
||||
|
||||
**If no research path is provided:**
|
||||
|
||||
Ask the user using AskUserQuestion:
|
||||
|
||||
```text
|
||||
"Have you already gathered research for this skill?"
|
||||
|
||||
Options:
|
||||
[Yes - I have research at a specific location]
|
||||
[No - Help me gather research]
|
||||
[Skip - I'll create from knowledge only]
|
||||
```
|
||||
|
||||
**Based on user response:**
|
||||
|
||||
- **Yes** → Ask for research path, use Path 1
|
||||
- **No** → Use Path 2 (include research phase)
|
||||
- **Skip** → Use Path 1 without research (create from existing knowledge)
|
||||
|
||||
### Step 2: Initialize TodoWrite
|
||||
|
||||
Create a TodoWrite list based on the selected path:
|
||||
|
||||
**Path 2 (Full Workflow with Research):**
|
||||
|
||||
```javascript
|
||||
TodoWrite([
|
||||
{"content": "Research skill domain", "status": "pending", "activeForm": "Researching skill domain"},
|
||||
{"content": "Format research materials", "status": "pending", "activeForm": "Formatting research materials"},
|
||||
{"content": "Create skill structure", "status": "pending", "activeForm": "Creating skill structure"},
|
||||
{"content": "Review content quality", "status": "pending", "activeForm": "Reviewing content quality"},
|
||||
{"content": "Review technical compliance", "status": "pending", "activeForm": "Reviewing technical compliance"},
|
||||
{"content": "Validate runtime loading", "status": "pending", "activeForm": "Validating runtime loading"},
|
||||
{"content": "Validate integration", "status": "pending", "activeForm": "Validating integration"},
|
||||
{"content": "Run comprehensive audit", "status": "pending", "activeForm": "Running comprehensive audit"},
|
||||
{"content": "Complete workflow", "status": "pending", "activeForm": "Completing workflow"}
|
||||
])
|
||||
```
|
||||
|
||||
**Path 1 (Research Exists or Skipped):**
|
||||
|
||||
Omit the first "Research skill domain" task. Start with "Format research materials" or
|
||||
"Create skill structure" depending on whether research exists.
|
||||
|
||||
### Step 3: Execute Workflow Sequentially
|
||||
|
||||
For each phase in the workflow, follow this pattern:
|
||||
|
||||
#### 1. Mark phase as in_progress
|
||||
|
||||
Update the corresponding TodoWrite item to `in_progress` status.
|
||||
|
||||
#### 2. Check dependencies
|
||||
|
||||
Before running a command, verify prior phases completed:
|
||||
|
||||
- Review-compliance requires review-content to pass
|
||||
- Validate-runtime requires review-compliance to pass
|
||||
- Validate-integration requires validate-runtime to pass
|
||||
- Validate-audit runs regardless (non-blocking feedback)
|
||||
|
||||
#### 3. Invoke command using SlashCommand tool
|
||||
|
||||
```text
|
||||
/meta-claude:skill:research <skill-name> [sources]
|
||||
/meta-claude:skill:format <research-dir>
|
||||
/meta-claude:skill:create <skill-name> <research-dir>
|
||||
/meta-claude:skill:review-content <skill-path>
|
||||
/meta-claude:skill:review-compliance <skill-path>
|
||||
/meta-claude:skill:validate-runtime <skill-path>
|
||||
/meta-claude:skill:validate-integration <skill-path>
|
||||
/meta-claude:skill:validate-audit <skill-path>
|
||||
```
|
||||
|
||||
**IMPORTANT:** Wait for each command to complete before proceeding to the next phase.
|
||||
Do not invoke multiple commands in parallel.
|
||||
|
||||
#### 4. Check command result
|
||||
|
||||
Each command returns success or failure with specific error details.
|
||||
|
||||
#### 5. Apply fix strategy if needed
|
||||
|
||||
The workflow uses a three-tier fix strategy:
|
||||
|
||||
- **Tier 1 (Simple):** Auto-fix formatting, frontmatter, markdown syntax
|
||||
- **Tier 2 (Medium):** Guided fixes with user approval
|
||||
- **Tier 3 (Complex):** Stop and report - requires manual fixes
|
||||
|
||||
**One-shot policy:** Each fix applied once, re-run once, then fail fast if still broken.
|
||||
|
||||
**For complete tier definitions, issue categorization, examples, and fix workflows:**
|
||||
See [references/error-handling.md](references/error-handling.md)
|
||||
|
||||
#### 6. Mark phase completed
|
||||
|
||||
Update TodoWrite item to `completed` status.
|
||||
|
||||
#### 7. Continue to next phase
|
||||
|
||||
Proceed to the next workflow phase, or exit if fail-fast triggered.
|
||||
|
||||
### Step 4: Completion
|
||||
|
||||
When all phases pass successfully:
|
||||
|
||||
**Present completion summary:**
|
||||
|
||||
```text
|
||||
✅ Skill created and validated successfully!
|
||||
|
||||
Location: <skill-output-path>/
|
||||
|
||||
Research materials: docs/research/skills/<skill-name>/
|
||||
```
|
||||
|
||||
**Ask about artifact cleanup:**
|
||||
|
||||
```text
|
||||
Keep research materials? [Keep/Remove] (default: Keep)
|
||||
```
|
||||
|
||||
**Present next steps using AskUserQuestion:**
|
||||
|
||||
```text
|
||||
Next steps - choose an option:
|
||||
[Test the skill now - Try invoking it in a new conversation]
|
||||
[Create PR - Submit skill to repository]
|
||||
[Add to plugin.json - Integrate with plugin manifest]
|
||||
[Done - Exit workflow]
|
||||
```
|
||||
|
||||
**Execute user's choice:**
|
||||
|
||||
- **Test** → Guide user to test skill invocation
|
||||
- **Create PR** → Create git branch, commit, push, open PR
|
||||
- **Add to plugin.json** → Update manifest, validate structure
|
||||
- **Done** → Clean exit
|
||||
|
||||
### Key Execution Principles
|
||||
|
||||
**Sequential Execution:** Do not run commands in parallel. Wait for each phase to complete before proceeding.
|
||||
|
||||
**Context Window Protection:** You are orchestrating commands, not sub-agents. Your context window is safe
|
||||
because you're invoking slash commands sequentially, not spawning multiple agents.
|
||||
|
||||
**State Management:** TodoWrite provides real-time progress visibility. Update it at every phase
|
||||
transition.
|
||||
|
||||
**Fail Fast:** When Tier 3 issues occur or user declines fixes, exit immediately with clear guidance.
|
||||
Don't attempt complex recovery.
|
||||
|
||||
**Dependency Enforcement:** Never skip dependency checks. Review phases are sequential, validation
|
||||
phases are tiered.
|
||||
|
||||
**One-shot Fixes:** Apply each fix once, re-run once, then fail if still broken. This prevents infinite loops.
|
||||
|
||||
**User Communication:** Report progress clearly. Show which phase is running, what the result was,
|
||||
and what's happening next.
|
||||
|
||||
## Workflow Architecture
|
||||
|
||||
Two paths based on research availability: Path 1 (research exists) and Path 2 (research needed).
|
||||
TodoWrite tracks progress through 7-8 phases. Entry point detection uses prompt analysis and AskUserQuestion.
|
||||
|
||||
**Details:** See [references/workflow-architecture.md](references/workflow-architecture.md)
|
||||
|
||||
## Workflow Execution
|
||||
|
||||
Sequential phase invocation pattern: mark in_progress → check dependencies → invoke command →
|
||||
check result → apply fixes → mark completed → continue. Dependencies enforced (review sequential,
|
||||
validation tiered). Commands invoked via SlashCommand tool with wait-for-completion pattern.
|
||||
|
||||
**Details:** See [references/workflow-execution.md](references/workflow-execution.md)
|
||||
|
||||
## Success Completion
|
||||
|
||||
When all phases pass successfully:
|
||||
|
||||
```text
|
||||
✅ Skill created and validated successfully!
|
||||
|
||||
Location: <skill-output-path>/
|
||||
|
||||
Research materials: docs/research/skills/<skill-name>/
|
||||
Keep research materials? [Keep/Remove] (default: Keep)
|
||||
```
|
||||
|
||||
**Artifact Cleanup:**
|
||||
|
||||
Ask user about research materials:
|
||||
|
||||
- **Keep** (default): Preserves research for future iterations, builds knowledge base
|
||||
- **Remove**: Cleans up workspace, research can be re-gathered if needed
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
Present options to user:
|
||||
|
||||
```text
|
||||
Next steps - choose an option:
|
||||
[1] Test the skill now - Try invoking it in a new conversation
|
||||
[2] Create PR - Submit skill to repository
|
||||
[3] Add to plugin.json - Integrate with plugin manifest (if applicable)
|
||||
[4] Done - Exit workflow
|
||||
|
||||
What would you like to do?
|
||||
```
|
||||
|
||||
**User Actions:**
|
||||
|
||||
1. **Test the skill now** → Guide user to test skill invocation
|
||||
2. **Create PR** → Create git branch, commit, push, open PR
|
||||
3. **Add to plugin.json** → Update manifest, validate structure (for plugin skills)
|
||||
4. **Done** → Clean exit
|
||||
|
||||
Execute the user's choice, then exit cleanly.
|
||||
|
||||
## Examples
|
||||
|
||||
The skill-factory workflow supports various scenarios:
|
||||
|
||||
1. **Path 2 (Full Workflow):** Creating skills from scratch with automated research gathering
|
||||
2. **Path 1 (Existing Research):** Creating skills when research materials already exist
|
||||
3. **Guided Fix Workflow:** Applying Tier 2 fixes with user approval
|
||||
4. **Fail-Fast Pattern:** Handling Tier 3 complex issues with immediate exit
|
||||
|
||||
**Detailed Examples:** See [references/workflow-examples.md](references/workflow-examples.md) for complete walkthrough
|
||||
scenarios showing TodoWrite state transitions, command invocations, error handling, and success paths.
|
||||
|
||||
## Design Principles
|
||||
|
||||
Six core principles: (1) Primitives First (slash commands foundation), (2) KISS State Management (TodoWrite only),
|
||||
(3) Fail Fast (no complex recovery), (4) Context-Aware Entry (prompt analysis), (5) Composable & Testable
|
||||
(standalone or orchestrated), (6) Quality Gates (sequential dependencies).
|
||||
|
||||
**Details:** See [references/design-principles.md](references/design-principles.md)
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Delegation Architecture
|
||||
|
||||
skill-factory extends the proven skill-creator skill by adding:
|
||||
|
||||
- **Pre-creation phases:** Research gathering and formatting
|
||||
- **Post-creation phases:** Content review and validation
|
||||
- **Quality gates:** Compliance checking, runtime testing, integration validation
|
||||
|
||||
**Delegation to existing tools:**
|
||||
|
||||
- **skill-creator skill** → Core creation workflow (Understand → Plan → Initialize → Edit → Package)
|
||||
- **quick_validate.py** → Compliance validation (frontmatter, naming, structure)
|
||||
- **claude-skill-auditor agent** → Comprehensive audit
|
||||
|
||||
This separation maintains the stability of skill-creator while adding research-backed, validated skill creation
|
||||
with quality gates.
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
This skill provides:
|
||||
|
||||
1. **Quick Start** - Fast path for common use cases
|
||||
2. **Workflow Architecture** - Understanding the orchestration model
|
||||
3. **Detailed Phase Documentation** - Deep dive into each phase
|
||||
4. **Error Handling** - Comprehensive fix strategies
|
||||
5. **Examples** - Real-world scenarios
|
||||
|
||||
Load sections as needed for your use case.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common issues: research phase failures (check FIRECRAWL_API_KEY), content review loops (Tier 3 issues need
|
||||
redesign), compliance validation (run quick_validate.py manually), integration conflicts (check duplicate names).
|
||||
|
||||
**Details:** See [references/troubleshooting.md](references/troubleshooting.md)
|
||||
|
||||
## Success Metrics
|
||||
|
||||
You know skill-factory succeeds when:
|
||||
|
||||
1. **Time to create skill:** Reduced from hours to minutes
|
||||
2. **Skill quality:** 100% compliance with official specs on first validation
|
||||
3. **User satisfaction:** Beginners create high-quality skills without deep knowledge
|
||||
4. **Maintainability:** Primitives are independently testable and reusable
|
||||
5. **Workflow clarity:** Users understand current phase and next steps at all times
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **skill-creator skill** - Core skill creation workflow (delegated by skill-factory)
|
||||
- **multi-agent-composition skill** - Architectural patterns and composition rules
|
||||
- **Primitive commands** - Individual slash commands under `/skill-*` namespace
|
||||
- **quick_validate.py** - Compliance validation script
|
||||
- **claude-skill-auditor agent** - Comprehensive skill audit agent
|
||||
31
skills/skill-factory/references/design-principles.md
Normal file
31
skills/skill-factory/references/design-principles.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Design Principles
|
||||
|
||||
## 1. Primitives First
|
||||
|
||||
Slash commands are the foundation. The skill orchestrates them using the SlashCommand tool. This follows the
|
||||
multi-agent-composition principle: "Always start with prompts."
|
||||
|
||||
### 2. KISS State Management
|
||||
|
||||
TodoWrite provides visibility without complexity. No external state files, no databases, no complex checkpointing.
|
||||
Simple, effective progress tracking.
|
||||
|
||||
### 3. Fail Fast
|
||||
|
||||
No complex recovery mechanisms. When something can't be auto-fixed or user declines a fix, exit immediately with
|
||||
clear guidance. Preserves artifacts, provides next steps.
|
||||
|
||||
### 4. Context-Aware Entry
|
||||
|
||||
Detects workflow path from user's prompt. Explicit research location → Path 1. Ambiguous → Ask user. Natural
|
||||
language interface.
|
||||
|
||||
### 5. Composable & Testable
|
||||
|
||||
Every primitive works standalone (power users) or orchestrated (guided users). Each command is independently
|
||||
testable and verifiable.
|
||||
|
||||
### 6. Quality Gates
|
||||
|
||||
Sequential dependencies ensure quality: content before compliance, runtime before integration. Tiered validation
|
||||
with non-blocking audit for comprehensive feedback.
|
||||
181
skills/skill-factory/references/error-handling.md
Normal file
181
skills/skill-factory/references/error-handling.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Error Handling & Fix Strategy
|
||||
|
||||
## Core Principle: Fail Fast
|
||||
|
||||
When a phase fails without auto-fix capability, the workflow **stops immediately**. No complex recovery, no
|
||||
checkpointing, no resume commands—only clean exit with clear error reporting and preserved artifacts.
|
||||
|
||||
## Rule-Based Fix Tiers
|
||||
|
||||
Issues are categorized into three tiers based on complexity:
|
||||
|
||||
### Tier 1: Simple (Auto-Fix)
|
||||
|
||||
**Issue Types:**
|
||||
|
||||
- Formatting issues (whitespace, indentation)
|
||||
- Missing frontmatter fields (can be inferred)
|
||||
- Markdown syntax errors (quote escaping, link formatting)
|
||||
- File structure issues (missing directories)
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Automatically apply fix
|
||||
2. Auto re-run the failed command ONCE
|
||||
3. Continue if passes, fail fast if still broken
|
||||
|
||||
**Example:**
|
||||
|
||||
```text
|
||||
/meta-claude:skill:review-compliance fails: "Missing frontmatter description field"
|
||||
↓
|
||||
Tier: Simple → AUTO-FIX
|
||||
↓
|
||||
Fix: Add description field inferred from skill name
|
||||
↓
|
||||
Auto re-run: /meta-claude:skill:review-compliance <skill-path>
|
||||
↓
|
||||
Result: Pass → Mark todo completed, continue to /meta-claude:skill:validate-runtime
|
||||
```
|
||||
|
||||
### Tier 2: Medium (Guided Fix with Approval)
|
||||
|
||||
**Issue Types:**
|
||||
|
||||
- Content clarity suggestions
|
||||
- Example improvements
|
||||
- Instruction rewording
|
||||
- Structure optimization
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Present issue and suggested fix
|
||||
2. Ask user: "Apply this fix? [Yes/No/Edit]"
|
||||
3. If Yes → Apply fix, re-run command once
|
||||
4. If No → Fail fast
|
||||
5. If Edit → Show fix, let user modify, apply, re-run
|
||||
|
||||
**Example:**
|
||||
|
||||
```text
|
||||
/meta-claude:skill:review-content fails: "Examples section unclear, lacks practical context"
|
||||
↓
|
||||
Tier: Medium → GUIDED FIX
|
||||
↓
|
||||
Suggested fix: [Shows proposed rewrite with clearer examples]
|
||||
↓
|
||||
Ask: "Apply this fix? [Yes/No/Edit]"
|
||||
↓
|
||||
User: Yes
|
||||
↓
|
||||
Apply fix
|
||||
↓
|
||||
Re-run: /meta-claude:skill:review-content <skill-path>
|
||||
↓
|
||||
Result: Pass → Mark todo completed, continue to /meta-claude:skill:review-compliance
|
||||
```
|
||||
|
||||
### Tier 3: Complex (Stop and Report)
|
||||
|
||||
**Issue Types:**
|
||||
|
||||
- Architectural problems (skill design flaws)
|
||||
- Insufficient research (missing critical information)
|
||||
- Unsupported use cases (doesn't fit Claude Code model)
|
||||
- Schema violations (fundamental structure issues)
|
||||
- Composition rule violations (e.g., attempting to nest sub-agents)
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Report the issue with detailed explanation
|
||||
2. Provide recommendations for manual fixes
|
||||
3. **Fail fast** - exit workflow immediately
|
||||
4. User must fix manually and restart workflow
|
||||
|
||||
**Example:**
|
||||
|
||||
```text
|
||||
/meta-claude:skill:review-content fails: "Skill attempts to nest sub-agents, violates composition rules"
|
||||
↓
|
||||
Tier: Complex → STOP AND REPORT
|
||||
↓
|
||||
Report:
|
||||
❌ Skill creation failed at: Review Content Quality
|
||||
|
||||
Issue found:
|
||||
- [Tier 3: Complex] Skill attempts to nest sub-agents, which violates composition rules
|
||||
|
||||
Recommendation:
|
||||
- Restructure skill to invoke sub-agents via SlashCommand tool instead
|
||||
- See: plugins/meta/meta-claude/skills/multi-agent-composition/
|
||||
|
||||
Workflow stopped. Please fix manually and restart.
|
||||
|
||||
Artifacts preserved at:
|
||||
Research: docs/research/skills/coderabbit/
|
||||
Partial skill: plugins/meta/meta-claude/skills/coderabbit/
|
||||
|
||||
↓
|
||||
WORKFLOW EXITS (fail fast)
|
||||
```
|
||||
|
||||
## One-Shot Fix Policy
|
||||
|
||||
To prevent infinite loops:
|
||||
|
||||
```text
|
||||
Phase fails
|
||||
↓
|
||||
Apply fix (auto or guided)
|
||||
↓
|
||||
Re-run command ONCE
|
||||
↓
|
||||
Result:
|
||||
- Pass → Continue to next phase
|
||||
- Fail → FAIL FAST (no second fix attempt)
|
||||
```
|
||||
|
||||
**Rationale:** If the first fix fails, the issue exceeds initial assessment. Stop and let the user investigate rather
|
||||
than looping infinitely.
|
||||
|
||||
## Issue Categorization Response Format
|
||||
|
||||
Each primitive command returns errors with tier metadata:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"status": "fail",
|
||||
"issues": [
|
||||
{
|
||||
"tier": "simple",
|
||||
"category": "frontmatter",
|
||||
"description": "Missing description field",
|
||||
"fix": "Add description: 'Guide for CodeRabbit code review'",
|
||||
"auto_fixable": true
|
||||
},
|
||||
{
|
||||
"tier": "medium",
|
||||
"category": "content-clarity",
|
||||
"description": "Examples section unclear, lacks practical context",
|
||||
"suggestion": "[Proposed rewrite with clearer examples]",
|
||||
"auto_fixable": false
|
||||
},
|
||||
{
|
||||
"tier": "complex",
|
||||
"category": "architectural",
|
||||
"description": "Skill violates composition rules by nesting sub-agents",
|
||||
"recommendation": "Restructure to use SlashCommand tool for sub-agent invocation",
|
||||
"auto_fixable": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Parsing Command Responses
|
||||
|
||||
When a command completes, analyze its output to determine status:
|
||||
|
||||
- Look for "Success", "PASS", or exit code 0 → Continue
|
||||
- Look for "Error", "FAIL", or exit code 1 → Apply fix strategy
|
||||
- Parse issue tier metadata (if provided) to select fix approach
|
||||
- If no tier metadata, infer tier from issue description
|
||||
45
skills/skill-factory/references/troubleshooting.md
Normal file
45
skills/skill-factory/references/troubleshooting.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Research Phase Fails
|
||||
|
||||
**Symptom:** `/meta-claude:skill:research` command fails with API errors
|
||||
|
||||
**Solutions:**
|
||||
|
||||
- Verify FIRECRAWL_API_KEY is set: `echo $FIRECRAWL_API_KEY`
|
||||
- Check network connectivity
|
||||
- Verify research script permissions: `chmod +x scripts/firecrawl_*.py`
|
||||
- Try manual research and use Path 1 (skip research phase)
|
||||
|
||||
### Content Review Fails Repeatedly
|
||||
|
||||
**Symptom:** `/meta-claude:skill:review-content` fails even after applying fixes
|
||||
|
||||
**Solutions:**
|
||||
|
||||
- Review the specific issues in the quality report
|
||||
- Check if issues are Tier 3 (complex) - these require manual redesign
|
||||
- Consider if the skill design matches Claude Code's composition model
|
||||
- Consult multi-agent-composition skill for architectural guidance
|
||||
|
||||
### Compliance Validation Fails
|
||||
|
||||
**Symptom:** `/meta-claude:skill:review-compliance` reports frontmatter or naming violations
|
||||
|
||||
**Solutions:**
|
||||
|
||||
- Run quick_validate.py manually: `scripts/quick_validate.py <skill-path>`
|
||||
- Check frontmatter YAML syntax (valid YAML, required fields)
|
||||
- Verify skill name follows hyphen-case convention
|
||||
- Ensure description is clear and within 1024 characters
|
||||
|
||||
### Integration Validation Fails
|
||||
|
||||
**Symptom:** `/meta-claude:skill:validate-integration` reports conflicts
|
||||
|
||||
**Solutions:**
|
||||
|
||||
- Check for duplicate skill names in the plugin
|
||||
- Review skill description for overlap with existing skills
|
||||
- Consider renaming or refining scope to avoid conflicts
|
||||
- Ensure skill complements rather than duplicates existing functionality
|
||||
67
skills/skill-factory/references/workflow-architecture.md
Normal file
67
skills/skill-factory/references/workflow-architecture.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# Workflow Architecture
|
||||
|
||||
## Entry Point Detection
|
||||
|
||||
The skill analyzes your prompt to determine the workflow path:
|
||||
|
||||
**Explicit Research Path (Path 1):**
|
||||
|
||||
```text
|
||||
User: "Create coderabbit skill, research in docs/research/skills/coderabbit/"
|
||||
→ Detects research location, uses Path 1 (skip research phase)
|
||||
```
|
||||
|
||||
**Ambiguous Path:**
|
||||
|
||||
```text
|
||||
User: "Create coderabbit skill"
|
||||
→ Asks: "Have you already gathered research?"
|
||||
→ User response determines path
|
||||
```
|
||||
|
||||
**Research Needed (Path 2):**
|
||||
|
||||
```text
|
||||
User selects "No - Help me gather research"
|
||||
→ Uses Path 2 (full workflow including research)
|
||||
```
|
||||
|
||||
## Workflow Paths
|
||||
|
||||
### Path 1: Research Exists
|
||||
|
||||
```text
|
||||
format → create → review-content → review-compliance →
|
||||
validate-runtime → validate-integration → validate-audit → complete
|
||||
```
|
||||
|
||||
### Path 2: Research Needed
|
||||
|
||||
```text
|
||||
research → format → create → review-content → review-compliance →
|
||||
validate-runtime → validate-integration → validate-audit → complete
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
Progress tracking uses TodoWrite for real-time visibility:
|
||||
|
||||
**Path 2 Example (Full Workflow):**
|
||||
|
||||
```javascript
|
||||
[
|
||||
{"content": "Research skill domain", "status": "in_progress", "activeForm": "Researching skill domain"},
|
||||
{"content": "Format research materials", "status": "pending", "activeForm": "Formatting research materials"},
|
||||
{"content": "Create skill structure", "status": "pending", "activeForm": "Creating skill structure"},
|
||||
{"content": "Review content quality", "status": "pending", "activeForm": "Reviewing content quality"},
|
||||
{"content": "Review technical compliance", "status": "pending", "activeForm": "Reviewing technical compliance"},
|
||||
{"content": "Validate runtime loading", "status": "pending", "activeForm": "Validating runtime loading"},
|
||||
{"content": "Validate integration", "status": "pending", "activeForm": "Validating integration"},
|
||||
{"content": "Audit skill (non-blocking)", "status": "pending", "activeForm": "Auditing skill"},
|
||||
{"content": "Complete workflow", "status": "pending", "activeForm": "Completing workflow"}
|
||||
]
|
||||
```
|
||||
|
||||
**Path 1 Example (Research Exists):**
|
||||
|
||||
Omit first "Research skill domain" task from TodoWrite list.
|
||||
266
skills/skill-factory/references/workflow-examples.md
Normal file
266
skills/skill-factory/references/workflow-examples.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# Workflow Examples
|
||||
|
||||
## Example 1: Creating Infrastructure Skill (Path 2)
|
||||
|
||||
```text
|
||||
User: "Create terraform-best-practices skill"
|
||||
|
||||
skill-factory:
|
||||
"Have you already gathered research for this skill?
|
||||
[Yes - I have research at <path>]
|
||||
[No - Help me gather research]
|
||||
[Skip - I'll create from knowledge only]"
|
||||
|
||||
User: "No - Help me gather research"
|
||||
|
||||
skill-factory initializes TodoWrite with 9 tasks, starts workflow:
|
||||
|
||||
[Phase 1: Research]
|
||||
Invokes: /meta-claude:skill:research terraform-best-practices
|
||||
Mini brainstorm about scope and categories
|
||||
Executes firecrawl research script
|
||||
Research saved to docs/research/skills/terraform-best-practices/
|
||||
✓ Research completed
|
||||
|
||||
[Phase 2: Format]
|
||||
Invokes: /meta-claude:skill:format docs/research/skills/terraform-best-practices
|
||||
Cleans UI artifacts and navigation elements
|
||||
✓ Formatting completed
|
||||
|
||||
[Phase 3: Create]
|
||||
Invokes: /meta-claude:skill:create terraform-best-practices docs/research/skills/terraform-best-practices
|
||||
Delegates to skill-creator skill
|
||||
Follows Understand → Plan → Initialize → Edit → Package workflow
|
||||
✓ Skill created at plugins/infrastructure/terraform-skills/skills/terraform-best-practices/
|
||||
|
||||
[Phase 4: Review Content]
|
||||
Invokes: /meta-claude:skill:review-content plugins/infrastructure/terraform-skills/skills/terraform-best-practices
|
||||
Analyzes clarity, completeness, examples, actionability, usefulness
|
||||
✓ Content review passed (5/5 quality dimensions)
|
||||
|
||||
[Phase 5: Review Compliance]
|
||||
Invokes: /meta-claude:skill:review-compliance plugins/infrastructure/terraform-skills/skills/terraform-best-practices
|
||||
Runs quick_validate.py
|
||||
✓ Compliance check passed
|
||||
|
||||
[Phase 6: Validate Runtime]
|
||||
Invokes: /meta-claude:skill:validate-runtime plugins/infrastructure/terraform-skills/skills/terraform-best-practices
|
||||
Tests skill loading in Claude Code context
|
||||
✓ Runtime validation passed
|
||||
|
||||
[Phase 7: Validate Integration]
|
||||
Invokes: /meta-claude:skill:validate-integration plugins/infrastructure/terraform-skills/skills/terraform-best-practices
|
||||
Checks for conflicts with existing skills
|
||||
✓ Integration validation passed
|
||||
|
||||
[Phase 8: Audit]
|
||||
Invokes: /meta-claude:skill:validate-audit plugins/infrastructure/terraform-skills/skills/terraform-best-practices
|
||||
Runs claude-skill-auditor agent
|
||||
ℹ Audit completed with recommendations (non-blocking)
|
||||
|
||||
[Phase 9: Complete]
|
||||
✅ Skill created and validated successfully!
|
||||
|
||||
Location: plugins/infrastructure/terraform-skills/skills/terraform-best-practices/
|
||||
|
||||
Research materials: docs/research/skills/terraform-best-practices/
|
||||
Keep research materials? [Keep/Remove] (default: Keep)
|
||||
|
||||
User: Keep
|
||||
|
||||
Next steps - choose an option:
|
||||
[1] Test the skill now
|
||||
[2] Create PR
|
||||
[3] Add to plugin.json
|
||||
[4] Done
|
||||
|
||||
User: [2] Create PR
|
||||
|
||||
skill-factory creates branch, commits skill, pushes, opens PR
|
||||
Workflow complete!
|
||||
```
|
||||
|
||||
## Example 2: Creating Skill with Existing Research (Path 1)
|
||||
|
||||
```text
|
||||
User: "Create coderabbit skill, research in docs/research/skills/coderabbit/"
|
||||
|
||||
skill-factory detects explicit research path, uses Path 1
|
||||
|
||||
Initializes TodoWrite with 8 tasks (skips research), starts workflow:
|
||||
|
||||
[Phase 1: Format]
|
||||
Invokes: /meta-claude:skill:format docs/research/skills/coderabbit
|
||||
✓ Formatting completed
|
||||
|
||||
[Phase 2: Create]
|
||||
Invokes: /meta-claude:skill:create coderabbit docs/research/skills/coderabbit
|
||||
✓ Skill created
|
||||
|
||||
[Continues through remaining phases...]
|
||||
✓ Workflow complete
|
||||
```
|
||||
|
||||
## Example 3: Workflow Failure with Guided Fix
|
||||
|
||||
```text
|
||||
[Phase 4: Review Content]
|
||||
Invokes: /meta-claude:skill:review-content plugins/meta/meta-claude/skills/docker-compose
|
||||
|
||||
Command response:
|
||||
{
|
||||
"status": "fail",
|
||||
"issues": [
|
||||
{
|
||||
"tier": "medium",
|
||||
"category": "examples",
|
||||
"description": "Examples section missing practical docker-compose.yml configurations",
|
||||
"suggestion": "[Shows proposed examples with common patterns]",
|
||||
"auto_fixable": false
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
skill-factory detects Tier 2 (guided fix):
|
||||
|
||||
"Content review found issues that can be fixed:
|
||||
|
||||
Issue: Examples section missing practical docker-compose.yml configurations
|
||||
|
||||
Suggested fix:
|
||||
[Shows proposed docker-compose.yml examples]
|
||||
|
||||
Apply this fix? [Yes/No/Edit]"
|
||||
|
||||
User: Yes
|
||||
|
||||
skill-factory applies fix, re-runs command:
|
||||
|
||||
Invokes: /meta-claude:skill:review-content plugins/meta/meta-claude/skills/docker-compose
|
||||
✓ Content review passed
|
||||
|
||||
Continues to next phase...
|
||||
```
|
||||
|
||||
## Example 4: Workflow Failure with Complex Issue
|
||||
|
||||
```text
|
||||
[Phase 4: Review Content]
|
||||
Invokes: /meta-claude:skill:review-content plugins/meta/meta-claude/skills/advanced-orchestration
|
||||
|
||||
Command response:
|
||||
{
|
||||
"status": "fail",
|
||||
"issues": [
|
||||
{
|
||||
"tier": "complex",
|
||||
"category": "architectural",
|
||||
"description": "Skill attempts to nest sub-agents within sub-agents, which violates Claude Code composition rules",
|
||||
"recommendation": "Restructure skill to use SlashCommand tool for sub-agent invocation. See multi-agent-composition skill for patterns.",
|
||||
"auto_fixable": false
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
skill-factory detects Tier 3 (complex), fails fast:
|
||||
|
||||
❌ Skill creation failed at: Review Content Quality
|
||||
|
||||
Issue found:
|
||||
- [Tier 3: Complex] Skill attempts to nest sub-agents within sub-agents, which violates Claude Code composition rules
|
||||
|
||||
Recommendation:
|
||||
- Restructure skill to use SlashCommand tool for sub-agent invocation
|
||||
- See: plugins/meta/meta-claude/skills/multi-agent-composition/patterns/orchestrator-pattern.md
|
||||
|
||||
Workflow stopped. Please fix manually and restart with:
|
||||
skill-factory advanced-orchestration docs/research/skills/advanced-orchestration/
|
||||
|
||||
Artifacts preserved at:
|
||||
Research: docs/research/skills/advanced-orchestration/
|
||||
Partial skill: plugins/meta/meta-claude/skills/advanced-orchestration/
|
||||
|
||||
WORKFLOW EXITS
|
||||
```
|
||||
|
||||
## Command Output Reference
|
||||
|
||||
### Successful Command Outputs
|
||||
|
||||
**Research:**
|
||||
|
||||
```bash
|
||||
✓ Research completed for terraform-best-practices
|
||||
Saved to: docs/research/skills/terraform-best-practices/
|
||||
Files: 5 documents (github: 3, research: 2)
|
||||
```
|
||||
|
||||
**Format:**
|
||||
|
||||
```text
|
||||
✓ Formatting completed
|
||||
Cleaned: 5 files, removed 247 UI artifacts
|
||||
Output: docs/research/skills/terraform-best-practices/
|
||||
```
|
||||
|
||||
**Validation (Pass):**
|
||||
|
||||
```text
|
||||
✓ Content review passed (5/5 quality dimensions)
|
||||
✓ Compliance check passed
|
||||
✓ Runtime validation passed
|
||||
✓ Integration validation passed
|
||||
```
|
||||
|
||||
### Failed Command Outputs
|
||||
|
||||
**Tier 1 (Auto-fix):**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "fail",
|
||||
"issues": [
|
||||
{
|
||||
"tier": "simple",
|
||||
"category": "frontmatter",
|
||||
"description": "Missing description field",
|
||||
"fix": "Add description: 'Terraform infrastructure best practices'",
|
||||
"auto_fixable": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Tier 2 (Guided fix):**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "fail",
|
||||
"issues": [
|
||||
{
|
||||
"tier": "medium",
|
||||
"category": "examples",
|
||||
"description": "Examples section lacks practical configurations",
|
||||
"suggestion": "[Proposed examples with common patterns]",
|
||||
"auto_fixable": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Tier 3 (Complex):**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "fail",
|
||||
"issues": [
|
||||
{
|
||||
"tier": "complex",
|
||||
"category": "architectural",
|
||||
"description": "Violates composition rules",
|
||||
"recommendation": "Restructure to use SlashCommand tool",
|
||||
"auto_fixable": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
80
skills/skill-factory/references/workflow-execution.md
Normal file
80
skills/skill-factory/references/workflow-execution.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Workflow Execution
|
||||
|
||||
## Phase Invocation Pattern
|
||||
|
||||
For each phase in the workflow:
|
||||
|
||||
1. **Mark phase as in_progress** (update TodoWrite)
|
||||
2. **Check dependencies** (verify prior phases completed)
|
||||
3. **Invoke command** using SlashCommand tool:
|
||||
|
||||
```text
|
||||
/meta-claude:skill:research <skill-name> [sources]
|
||||
/meta-claude:skill:format <research-dir>
|
||||
/meta-claude:skill:create <skill-name> <research-dir>
|
||||
/meta-claude:skill:review-content <skill-path>
|
||||
/meta-claude:skill:review-compliance <skill-path>
|
||||
/meta-claude:skill:validate-runtime <skill-path>
|
||||
/meta-claude:skill:validate-integration <skill-path>
|
||||
/meta-claude:skill:validate-audit <skill-path>
|
||||
```
|
||||
|
||||
4. **Check result** (success or failure with tier metadata)
|
||||
5. **Apply fix strategy** (if needed - see Error Handling section)
|
||||
6. **Mark phase completed** (update TodoWrite)
|
||||
7. **Continue to next phase** (or exit if fail-fast triggered)
|
||||
|
||||
### Dependency Enforcement
|
||||
|
||||
Before running each command, verify dependencies:
|
||||
|
||||
**Review Phase (Sequential):**
|
||||
|
||||
```text
|
||||
/meta-claude:skill:review-content (no dependency)
|
||||
↓ (must pass)
|
||||
/meta-claude:skill:review-compliance (depends on content passing)
|
||||
```
|
||||
|
||||
**Validation Phase (Tiered):**
|
||||
|
||||
```text
|
||||
/meta-claude:skill:validate-runtime (depends on compliance passing)
|
||||
↓ (must pass)
|
||||
/meta-claude:skill:validate-integration (depends on runtime passing)
|
||||
↓ (runs regardless)
|
||||
/meta-claude:skill:validate-audit (non-blocking, informational)
|
||||
```
|
||||
|
||||
**Dependency Check Pattern:**
|
||||
|
||||
```text
|
||||
Before running /meta-claude:skill:review-compliance:
|
||||
Check: Is "Review content quality" completed?
|
||||
- Yes → Invoke /meta-claude:skill:review-compliance
|
||||
- No → Skip (workflow failed earlier, stop here)
|
||||
```
|
||||
|
||||
### Command Invocation with SlashCommand Tool
|
||||
|
||||
Use the SlashCommand tool to invoke each primitive command:
|
||||
|
||||
```javascript
|
||||
// Example: Invoking research phase
|
||||
SlashCommand({
|
||||
command: "/meta-claude:skill:research ansible-vault-security"
|
||||
})
|
||||
|
||||
// Example: Invoking format phase
|
||||
SlashCommand({
|
||||
command: "/meta-claude:skill:format docs/research/skills/ansible-vault-security"
|
||||
})
|
||||
|
||||
// Example: Invoking create phase
|
||||
SlashCommand({
|
||||
command: "/meta-claude:skill:create ansible-vault-security docs/research/skills/ansible-vault-security"
|
||||
})
|
||||
```
|
||||
|
||||
**IMPORTANT:** Wait for each command to complete before proceeding to the next phase. Check the response status
|
||||
before continuing.
|
||||
368
skills/skill-factory/workflows/visual-guide.md
Normal file
368
skills/skill-factory/workflows/visual-guide.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# Skill-Factory Visual Guide
|
||||
|
||||
Visual decision trees and workflow diagrams for the skill-factory orchestrator.
|
||||
|
||||
---
|
||||
|
||||
## How to Use This Guide
|
||||
|
||||
- **New to skill-factory?** Start with "Decision Tree: Full Workflow vs Individual Commands"
|
||||
- **Understanding the workflow?** Study the "Workflow State Diagram"
|
||||
- **Quick reference?** Check the "Command Decision Matrix"
|
||||
- **Troubleshooting?** Use the "Error Handling Flow"
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree: Full Workflow vs Individual Commands
|
||||
|
||||
This decision tree helps you choose between using the orchestrated workflow or individual slash commands.
|
||||
|
||||
```graphviz
|
||||
digraph skill_factory_decision {
|
||||
rankdir=TB;
|
||||
node [shape=box, style=rounded];
|
||||
|
||||
start [label="What are you trying to do?", shape=diamond, style="filled", fillcolor=lightblue];
|
||||
|
||||
new_skill [label="Creating a\nnew skill?", shape=diamond];
|
||||
have_research [label="Research\nalready gathered?", shape=diamond];
|
||||
specific_issue [label="Fixing a\nspecific issue?", shape=diamond];
|
||||
which_phase [label="Which phase\nhas the issue?", shape=diamond];
|
||||
|
||||
full_workflow_research [label="Use Full Workflow\n(Path 2)\n\nskill-factory <name>\n\n✓ Includes research\n✓ 8-phase validation\n✓ Progress tracking", shape=rect, style="filled", fillcolor=lightgreen];
|
||||
|
||||
full_workflow_skip [label="Use Full Workflow\n(Path 1)\n\nskill-factory <name> <research-path>\n\n✓ Skips research phase\n✓ Full 7-phase validation\n✓ TodoWrite progress tracking", shape=rect, style="filled", fillcolor=lightgreen];
|
||||
|
||||
research_cmd [label="/meta-claude:skill:research\n\nAutomate firecrawl scraping\nfor skill domain knowledge", shape=rect, style="filled", fillcolor=lightyellow];
|
||||
|
||||
format_cmd [label="/meta-claude:skill:format\n\nClean and structure\nraw research materials", shape=rect, style="filled", fillcolor=lightyellow];
|
||||
|
||||
create_cmd [label="/meta-claude:skill:create\n\nGenerate SKILL.md with\nYAML frontmatter", shape=rect, style="filled", fillcolor=lightyellow];
|
||||
|
||||
review_content_cmd [label="/meta-claude:skill:review-content\n\nValidate content quality\nand clarity", shape=rect, style="filled", fillcolor=lightyellow];
|
||||
|
||||
review_compliance_cmd [label="/meta-claude:skill:review-compliance\n\nRun quick_validate.py on\nSKILL.md", shape=rect, style="filled", fillcolor=lightyellow];
|
||||
|
||||
validate_runtime_cmd [label="/meta-claude:skill:validate-runtime\n\nTest skill loading\nin Claude context", shape=rect, style="filled", fillcolor=lightyellow];
|
||||
|
||||
validate_integration_cmd [label="/meta-claude:skill:validate-integration\n\nCheck for conflicts with\nexisting skills", shape=rect, style="filled", fillcolor=lightyellow];
|
||||
|
||||
validate_audit_cmd [label="/meta-claude:skill:validate-audit\n\nInvoke claude-skill-auditor\nfor comprehensive audit", shape=rect, style="filled", fillcolor=lightyellow];
|
||||
|
||||
start -> new_skill;
|
||||
|
||||
new_skill -> have_research [label="Yes"];
|
||||
new_skill -> specific_issue [label="No"];
|
||||
|
||||
have_research -> full_workflow_skip [label="Yes\nHave research at\nspecific path"];
|
||||
have_research -> full_workflow_research [label="No\nNeed to gather\nresearch"];
|
||||
|
||||
specific_issue -> which_phase [label="Yes"];
|
||||
specific_issue -> full_workflow_research [label="No\nUse full workflow"];
|
||||
|
||||
which_phase -> research_cmd [label="Research gathering"];
|
||||
which_phase -> format_cmd [label="Research formatting"];
|
||||
which_phase -> create_cmd [label="Skill generation"];
|
||||
which_phase -> review_content_cmd [label="Content quality"];
|
||||
which_phase -> review_compliance_cmd [label="YAML/compliance"];
|
||||
which_phase -> validate_runtime_cmd [label="Skill won't load"];
|
||||
which_phase -> validate_integration_cmd [label="Name conflicts"];
|
||||
which_phase -> validate_audit_cmd [label="Anthropic spec audit"];
|
||||
}
|
||||
```
|
||||
|
||||
### Decision Tree Key Points
|
||||
|
||||
**Critical Rule**: For new skills, use the **full workflow** (orchestrated). For specific fixes,
|
||||
use **individual commands**.
|
||||
|
||||
**Decision Flow**:
|
||||
|
||||
1. **Creating new skill?**
|
||||
- Yes → Check if research exists
|
||||
- Research exists → Full Workflow (Path 1)
|
||||
- Research needed → Full Workflow (Path 2)
|
||||
- No → Check if fixing specific issue
|
||||
2. **Fixing specific issue?**
|
||||
- Yes → Use individual command for that phase
|
||||
- No → Use full workflow
|
||||
|
||||
**Remember**: Individual commands are power user tools. Most users should use the full orchestrated workflow.
|
||||
|
||||
---
|
||||
|
||||
## Workflow State Diagram
|
||||
|
||||
Shows the phases and state transitions during skill creation.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> EntryPoint
|
||||
|
||||
EntryPoint --> PathDecision: Analyze prompt
|
||||
|
||||
PathDecision --> Path1: Research exists
|
||||
PathDecision --> Path2: Research needed
|
||||
|
||||
Path2 --> Research: Phase 1
|
||||
Research --> Format: Success
|
||||
Research --> FailFast: Tier 3 Error
|
||||
|
||||
Path1 --> Format: Skip research
|
||||
|
||||
Format --> Create: Success
|
||||
Format --> AutoFix: Tier 1 Error
|
||||
Format --> GuidedFix: Tier 2 Error
|
||||
Format --> FailFast: Tier 3 Error
|
||||
|
||||
AutoFix --> Format: Retry once
|
||||
GuidedFix --> Format: User approves
|
||||
GuidedFix --> FailFast: User declines
|
||||
|
||||
Create --> ReviewContent: Success
|
||||
Create --> AutoFix2: Tier 1 Error
|
||||
Create --> GuidedFix2: Tier 2 Error
|
||||
Create --> FailFast: Tier 3 Error
|
||||
|
||||
AutoFix2 --> Create: Retry once
|
||||
GuidedFix2 --> Create: User approves
|
||||
GuidedFix2 --> FailFast: User declines
|
||||
|
||||
ReviewContent --> ReviewCompliance: Pass
|
||||
ReviewContent --> FailFast: Fail
|
||||
|
||||
ReviewCompliance --> ValidateRuntime: Pass
|
||||
ReviewCompliance --> FailFast: Fail
|
||||
|
||||
ValidateRuntime --> ValidateIntegration: Pass
|
||||
ValidateRuntime --> FailFast: Fail
|
||||
|
||||
ValidateIntegration --> ValidateAudit: Pass
|
||||
ValidateIntegration --> FailFast: Fail
|
||||
|
||||
ValidateAudit --> Complete: Always runs
|
||||
|
||||
Complete --> NextSteps: Present options
|
||||
|
||||
NextSteps --> Test: User choice
|
||||
NextSteps --> CreatePR: User choice
|
||||
NextSteps --> UpdatePlugin: User choice
|
||||
NextSteps --> [*]: Done
|
||||
|
||||
FailFast --> [*]: Exit with guidance
|
||||
|
||||
note right of PathDecision
|
||||
Uses AskUserQuestion
|
||||
if path ambiguous
|
||||
end note
|
||||
|
||||
note right of AutoFix
|
||||
One-shot policy:
|
||||
Apply fix once,
|
||||
retry once,
|
||||
then fail fast
|
||||
end note
|
||||
|
||||
note right of ValidateAudit
|
||||
Non-blocking:
|
||||
Runs regardless of
|
||||
prior failures
|
||||
end note
|
||||
```
|
||||
|
||||
### State Diagram Key Points
|
||||
|
||||
**Entry Point Detection**:
|
||||
|
||||
- Analyzes user prompt
|
||||
- Uses AskUserQuestion if ambiguous
|
||||
- Routes to Path 1 (skip research) or Path 2 (include research)
|
||||
|
||||
**Error Handling States**:
|
||||
|
||||
- **AutoFix**: Tier 1 errors (formatting, syntax) - automated fix
|
||||
- **GuidedFix**: Tier 2 errors (content clarity) - user approval required
|
||||
- **FailFast**: Tier 3 errors (architectural) - exit immediately
|
||||
|
||||
**Quality Gates**:
|
||||
|
||||
- ReviewContent must pass before ReviewCompliance
|
||||
- ReviewCompliance must pass before ValidateRuntime
|
||||
- ValidateRuntime must pass before ValidateIntegration
|
||||
- ValidateAudit always runs (non-blocking feedback)
|
||||
|
||||
---
|
||||
|
||||
## Command Decision Matrix
|
||||
|
||||
Quick reference for choosing the right command.
|
||||
|
||||
| Scenario | Command | Why | Phase |
|
||||
|----------|---------|-----|-------|
|
||||
| **Need web research** | `/meta-claude:skill:research` | Automated firecrawl scraping | 1 |
|
||||
| **Have messy research** | `/meta-claude:skill:format` | Clean markdown formatting | 2 |
|
||||
| **Ready to generate SKILL.md** | `/meta-claude:skill:create` | Creates structure with YAML | 3 |
|
||||
| **Content unclear** | `/meta-claude:skill:review-content` | Quality gate before compliance | 4 |
|
||||
| **Check frontmatter** | `/meta-claude:skill:review-compliance` | Runs quick_validate.py | 5 |
|
||||
| **Skill won't load** | `/meta-claude:skill:validate-runtime` | Tests actual loading | 6 |
|
||||
| **Worried about conflicts** | `/meta-claude:skill:validate-integration` | Checks existing skills | 7 |
|
||||
| **Want Anthropic audit** | `/meta-claude:skill:validate-audit` | Runs claude-skill-auditor | 8 |
|
||||
|
||||
**Phase numbers** show the sequential order in the full workflow.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
Visual representation of the three-tier fix strategy.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([Command Executes]) --> Check{Check Result}
|
||||
|
||||
Check -->|Success| MarkComplete[Mark Phase Completed]
|
||||
Check -->|Failure| ClassifyError{Classify Error Tier}
|
||||
|
||||
ClassifyError -->|Tier 1<br/>Formatting, Syntax| AutoFix[Auto-Fix]
|
||||
ClassifyError -->|Tier 2<br/>Content Clarity| GuidedFix[Guided Fix]
|
||||
ClassifyError -->|Tier 3<br/>Architecture| FailFast[Fail Fast]
|
||||
|
||||
AutoFix --> ApplyFix1[Apply Fix Automatically]
|
||||
ApplyFix1 --> Retry1[Retry Command Once]
|
||||
Retry1 --> Check2{Check Result}
|
||||
|
||||
Check2 -->|Success| MarkComplete
|
||||
Check2 -->|Still Failed| EscalateTier2[Escalate to Tier 2]
|
||||
EscalateTier2 --> GuidedFix
|
||||
|
||||
GuidedFix --> Present[Present Fix to User]
|
||||
Present --> AskApproval{User Approves?}
|
||||
|
||||
AskApproval -->|Yes| ApplyFix2[Apply Fix]
|
||||
AskApproval -->|No| FailFast
|
||||
|
||||
ApplyFix2 --> Retry2[Retry Command Once]
|
||||
Retry2 --> Check3{Check Result}
|
||||
|
||||
Check3 -->|Success| MarkComplete
|
||||
Check3 -->|Still Failed| FailFast
|
||||
|
||||
FailFast --> Report[Report Issue with Detail]
|
||||
Report --> Guidance[Provide Fix Guidance]
|
||||
Guidance --> Exit([Exit Workflow])
|
||||
|
||||
MarkComplete --> Continue[Continue to Next Phase]
|
||||
|
||||
style AutoFix fill:#90EE90
|
||||
style GuidedFix fill:#FFE4B5
|
||||
style FailFast fill:#FFB6C1
|
||||
style MarkComplete fill:#ADD8E6
|
||||
```
|
||||
|
||||
### Error Handling Key Points
|
||||
|
||||
**Tier 1 (Auto-Fix)**: Formatting errors, YAML syntax, markdown issues
|
||||
|
||||
- **Action**: Apply fix automatically
|
||||
- **Retry**: Once
|
||||
- **Escalation**: If still fails → Tier 2
|
||||
|
||||
**Tier 2 (Guided-Fix)**: Content clarity, instruction rewording
|
||||
|
||||
- **Action**: Present suggested fix to user
|
||||
- **User Choice**: Approve or decline
|
||||
- **Retry**: Once if approved
|
||||
- **Escalation**: If still fails or user declines → Tier 3
|
||||
|
||||
**Tier 3 (Fail-Fast)**: Architectural problems, schema violations
|
||||
|
||||
- **Action**: Report issue with detailed explanation
|
||||
- **Recovery**: Exit immediately with guidance
|
||||
- **Manual**: User must fix manually
|
||||
|
||||
**One-Shot Policy**: Each tier gets one fix attempt, one retry, then escalates or fails. Prevents infinite loops.
|
||||
|
||||
---
|
||||
|
||||
## TodoWrite Progress Visualization
|
||||
|
||||
Shows how TodoWrite tracks progress through the workflow.
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title Skill-Factory Progress Tracking (Path 2 - Full Workflow)
|
||||
dateFormat X
|
||||
axisFormat %s
|
||||
|
||||
section Research
|
||||
Research skill domain :done, phase1, 0, 1
|
||||
|
||||
section Format
|
||||
Format research materials :active, phase2, 1, 2
|
||||
|
||||
section Create
|
||||
Create skill structure :phase3, 2, 3
|
||||
|
||||
section Review
|
||||
Review content quality :phase4, 3, 4
|
||||
Review technical compliance :phase5, 4, 5
|
||||
|
||||
section Validate
|
||||
Validate runtime loading :phase6, 5, 6
|
||||
Validate integration :phase7, 6, 7
|
||||
|
||||
section Audit
|
||||
Run comprehensive audit :phase8, 7, 8
|
||||
|
||||
section Complete
|
||||
Complete workflow :phase9, 8, 9
|
||||
```
|
||||
|
||||
**Status Indicators**:
|
||||
|
||||
- **Green** (done): Phase completed successfully
|
||||
- **Blue** (active): Phase currently in progress
|
||||
- **Gray** (pending): Phase not yet started
|
||||
|
||||
**TodoWrite Example** (Phase 2 in progress):
|
||||
|
||||
```javascript
|
||||
[
|
||||
{"content": "Research skill domain", "status": "completed", "activeForm": "Researching skill domain"},
|
||||
{"content": "Format research materials", "status": "in_progress", "activeForm": "Formatting research materials"},
|
||||
{"content": "Create skill structure", "status": "pending", "activeForm": "Creating skill structure"},
|
||||
{"content": "Review content quality", "status": "pending", "activeForm": "Reviewing content quality"},
|
||||
{"content": "Review technical compliance", "status": "pending", "activeForm": "Reviewing technical compliance"},
|
||||
{"content": "Validate runtime loading", "status": "pending", "activeForm": "Validating runtime loading"},
|
||||
{"content": "Validate integration", "status": "pending", "activeForm": "Validating integration"},
|
||||
{"content": "Run comprehensive audit", "status": "pending", "activeForm": "Running comprehensive audit"},
|
||||
{"content": "Complete workflow", "status": "pending", "activeForm": "Completing workflow"}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When to Use Visual Guides
|
||||
|
||||
- **New users**: Start with Decision Tree to understand full workflow vs individual commands
|
||||
- **Debugging**: Use Error Handling Flow to understand fix strategies
|
||||
- **Learning**: Study Workflow State Diagram to understand phase transitions
|
||||
- **Quick reference**: Use Command Decision Matrix for fast lookup
|
||||
|
||||
### Composition Pattern
|
||||
|
||||
This visual guide follows the same pattern as **multi-agent-composition/workflows/decision-tree.md**:
|
||||
|
||||
- Multiple visual formats (Graphviz, Mermaid, Tables)
|
||||
- Decision trees with diamond decision nodes
|
||||
- State diagrams showing transitions
|
||||
- Quick reference matrices
|
||||
- Best practices sections
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete Visual Guide
|
||||
**Pattern Source:** multi-agent-composition/workflows/decision-tree.md
|
||||
**Last Updated:** 2025-11-17
|
||||
Reference in New Issue
Block a user