specweave 0.23.16 → 0.24.0

package/plugins/specweave-tooling/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "specweave-tooling",
+  "description": "Plugin development toolkit for SpecWeave. Provides skill creation, validation, packaging, and plugin scaffolding tools. Expert guidance for YAML frontmatter, skill routing, activation patterns, and best practices. Essential for SpecWeave plugin developers.",
+  "version": "0.24.0",
+  "author": {
+    "name": "SpecWeave Team",
+    "url": "https://spec-weave.com"
+  },
+  "homepage": "https://spec-weave.com",
+  "repository": "https://github.com/anton-abyzov/specweave",
+  "license": "MIT",
+  "keywords": [
+    "specweave",
+    "tooling",
+    "skill-creation",
+    "plugin-development",
+    "yaml-frontmatter",
+    "skill-routing",
+    "plugin-scaffolding",
+    "developer-tools"
+  ]
+}

package/plugins/specweave-tooling/commands/specweave-tooling-skill-create.md

@@ -0,0 +1,691 @@
+---
+name: specweave-tooling:skill-create
+description: Create new Claude Code skill with proper YAML frontmatter, directory structure, and activation triggers. Interactive wizard for skill creation with validation and best practices.
+---
+
+# Create New Skill
+
+**Interactive Wizard**: From concept to production-ready skill with proper structure and validation.
+
+You are helping the user create a new Claude Code skill following best practices and the required structure.
+
+## Critical Structure Rules (Get This Right First!)
+
+### 1. Directory Structure
+
+**MANDATORY format**:
+```
+~/.claude/skills/           ← Personal skills
+└── your-skill-name/        ← MUST be in subdirectory!
+    └── SKILL.md            ← Must be named exactly SKILL.md
+
+.claude/skills/             ← Project skills (in project root)
+└── your-skill-name/        ← MUST be in subdirectory!
+    └── SKILL.md            ← Must be named exactly SKILL.md
+```
+
+**Common mistake**: Putting `SKILL.md` directly in `~/.claude/skills/` ❌
+
+### 2. SKILL.md Format (Mandatory YAML Frontmatter)
+
+```yaml
+---
+name: your-skill-name
+description: What it does AND when to use it. Include trigger keywords users might say.
+---
+
+# Your Skill Title
+
+Rest of your markdown content here...
+```
+
+**Critical rules**:
+- Opening `---` MUST be on line 1
+- `name` field: lowercase, hyphens only, max 64 chars
+- `description` field: max 1024 chars, MUST include activation triggers
+- Closing `---` before any markdown content
+- No YAML frontmatter = skill won't work!
+
+## Steps
+
+### Step 1: Gather Skill Information
+
+Ask the user for the following information (use AskUserQuestion if appropriate):
+
+1. **Skill Name**:
+   - Lowercase, hyphens only
+   - Max 64 characters
+   - Example: `python-data-science`, `kubernetes-expert`, `react-hooks`
+
+2. **Skill Purpose**:
+   - What expertise does this skill provide?
+   - What questions should it answer?
+   - Example: "Python data science best practices"
+
+3. **Activation Triggers**:
+   - Keywords users might say
+   - Commands or patterns to detect
+   - Example: "pandas, numpy, matplotlib, jupyter notebooks, Python data analysis"
+
+4. **Skill Location**:
+   - Personal skill: `~/.claude/skills/`
+   - Project skill: `.claude/skills/` (in project root)
+
+5. **Optional Tool Restrictions**:
+   - Should this skill be read-only?
+   - Allowed tools: Read, Grep, Glob, WebSearch, etc.
+   - Leave empty for no restrictions
+
+### Step 2: Validate Skill Name
+
+**Validation rules**:
+```bash
+# Check format (lowercase, hyphens only)
+if [[ ! "$skill_name" =~ ^[a-z0-9-]+$ ]]; then
+  echo "❌ Invalid name: must be lowercase with hyphens only"
+  exit 1
+fi
+
+# Check length (max 64 chars)
+if [ ${#skill_name} -gt 64 ]; then
+  echo "❌ Invalid name: must be 64 characters or less"
+  exit 1
+fi
+
+# Check no consecutive hyphens
+if [[ "$skill_name" =~ -- ]]; then
+  echo "❌ Invalid name: no consecutive hyphens allowed"
+  exit 1
+fi
+
+# Check doesn't start/end with hyphen
+if [[ "$skill_name" =~ ^- ]] || [[ "$skill_name" =~ -$ ]]; then
+  echo "❌ Invalid name: cannot start or end with hyphen"
+  exit 1
+fi
+```
+
+### Step 3: Generate Skill Description
+
+**Requirements**:
+- Max 1024 characters
+- Must include activation triggers
+- Must explain when to use the skill
+- Include keyword variations (e.g., "k8s, kubernetes, kubectl")
+
+**Template**:
+```
+[What the skill does]. [When to use it]. Activates for: [keyword1], [keyword2], [keyword3], [phrase1], [phrase2].
+```
+
+**Examples**:
+
+```yaml
+# Command-based skill
+description: Kubernetes expert. Explains kubectl commands, pod management, deployments. Activates for: kubectl, k8s, kubernetes, pods, deployments, services, namespaces.
+
+# Framework skill
+description: React expert for hooks, components, state management. Activates for: React, useState, useEffect, components, JSX, props, virtual DOM, React hooks.
+
+# Project-specific skill
+description: MyCompany API documentation. Explains endpoints, authentication, rate limits. Activates for: MyCompany API, /api/v1, authentication token, rate limit, API key.
+```
+
+### Step 4: Create Skill Content Structure
+
+**Recommended sections**:
+
+```markdown
+---
+name: your-skill-name
+description: [Generated description with triggers]
+---
+
+# [Skill Title]
+
+## What I Know
+
+[Bullet list of expertise areas]
+- Topic 1
+- Topic 2
+- Topic 3
+
+## When to Use This Skill
+
+Ask me about:
+- "How do I [use case 1]..."
+- "What's the best way to [use case 2]..."
+- "[Topic] tips and best practices"
+
+## Key Concepts
+
+### [Concept 1]
+
+[Explanation]
+
+### [Concept 2]
+
+[Explanation]
+
+## Examples
+
+### [Example 1: Common Task]
+
+```[language]
+[code example]
+```
+
+**Explanation**: [Why this works]
+
+### [Example 2: Advanced Usage]
+
+```[language]
+[code example]
+```
+
+**Explanation**: [When to use this pattern]
+
+## Best Practices
+
+1. ✅ **[Practice 1]**: [Explanation]
+2. ✅ **[Practice 2]**: [Explanation]
+3. ⚠️ **[Anti-pattern to avoid]**: [Why to avoid]
+
+## Common Patterns
+
+### [Pattern 1]
+[Implementation details]
+
+### [Pattern 2]
+[Implementation details]
+
+## Resources
+
+- [Documentation link]
+- [Tutorial link]
+- [Reference link]
+```
+
+### Step 5: Handle Optional Tool Restrictions
+
+**If user wants read-only skill**:
+
+```yaml
+---
+name: documentation-helper
+description: Documentation expert for project docs
+allowed-tools: Read, Grep, Glob, WebSearch
+---
+```
+
+**Available tools**:
+- `Read` - Read files
+- `Write` - Create/overwrite files
+- `Edit` - Edit existing files
+- `Grep` - Search file contents
+- `Glob` - Find files by pattern
+- `Bash` - Execute bash commands
+- `WebSearch` - Search the web
+- `WebFetch` - Fetch web content
+- `TodoWrite` - Manage todos
+- `AskUserQuestion` - Ask user questions
+
+**Tool restriction patterns**:
+
+```yaml
+# Read-only (no modifications)
+allowed-tools: Read, Grep, Glob, WebSearch
+
+# Documentation expert (can create docs)
+allowed-tools: Read, Grep, Glob, Write, Edit
+
+# Analysis expert (no file modifications)
+allowed-tools: Read, Grep, Glob, Bash
+
+# Full access (no restrictions)
+# (omit allowed-tools field)
+```
+
+### Step 6: Create Skill Directory and File
+
+**Implementation**:
+
+```bash
+# Determine full path
+if [ "$location" = "personal" ]; then
+  skill_dir="$HOME/.claude/skills/$skill_name"
+else
+  skill_dir="$PWD/.claude/skills/$skill_name"
+fi
+
+# Create directory
+mkdir -p "$skill_dir"
+
+# Create SKILL.md
+cat > "$skill_dir/SKILL.md" <<'EOF'
+---
+name: $skill_name
+description: $description
+$allowed_tools_line
+---
+
+# $skill_title
+
+$skill_content
+EOF
+
+echo "✅ Skill created at: $skill_dir/SKILL.md"
+```
+
+### Step 7: Validate Skill Structure
+
+**Validation checklist**:
+
+```bash
+# 1. Check SKILL.md exists
+if [ ! -f "$skill_dir/SKILL.md" ]; then
+  echo "❌ SKILL.md not found"
+  exit 1
+fi
+
+# 2. Check YAML frontmatter
+if ! head -1 "$skill_dir/SKILL.md" | grep -q '^---$'; then
+  echo "❌ SKILL.md must start with '---'"
+  exit 1
+fi
+
+# 3. Check required fields
+if ! grep -q '^name:' "$skill_dir/SKILL.md"; then
+  echo "❌ Missing 'name' field in YAML frontmatter"
+  exit 1
+fi
+
+if ! grep -q '^description:' "$skill_dir/SKILL.md"; then
+  echo "❌ Missing 'description' field in YAML frontmatter"
+  exit 1
+fi
+
+# 4. Check closing ---
+if ! sed -n '2,10p' "$skill_dir/SKILL.md" | grep -q '^---$'; then
+  echo "❌ Missing closing '---' in YAML frontmatter"
+  exit 1
+fi
+
+# 5. Check description length
+desc_length=$(grep '^description:' "$skill_dir/SKILL.md" | sed 's/^description: *//' | wc -c)
+if [ "$desc_length" -gt 1024 ]; then
+  echo "⚠️ Warning: Description is ${desc_length} characters (max 1024)"
+fi
+
+echo "✅ Skill structure validated successfully"
+```
+
+### Step 8: Provide Next Steps
+
+**User instructions**:
+
+```
+✅ Skill created successfully!
+
+📁 Location: $skill_dir/SKILL.md
+
+📝 Next steps:
+
+1. Review the skill content and customize as needed
+2. Test the skill by asking a trigger question
+3. Restart Claude Code to load the skill
+4. Verify activation with a test question
+
+🔄 To restart Claude Code:
+   - Close and reopen the application
+   - OR use /restart command (if available)
+
+🧪 Test your skill:
+   Ask: "[example trigger question based on description]"
+
+📚 Documentation:
+   - Skill format: ~/CLAUDE.md (your quick reference)
+   - Activation patterns: Description keywords determine when skill loads
+   - Tool restrictions: Optional 'allowed-tools' field limits capabilities
+
+⚠️ Common issues:
+   - Skill doesn't activate → Check description has clear triggers
+   - YAML errors → Verify frontmatter format (opening/closing ---)
+   - File not found → Ensure SKILL.md is in subdirectory
+```
+
+## Examples
+
+### Example 1: Python Data Science Skill
+
+**Input**:
+- Name: `python-data-science`
+- Purpose: "Python best practices for data science projects"
+- Triggers: "pandas, numpy, matplotlib, jupyter notebooks, Python data analysis"
+- Location: Personal
+- Tool restrictions: None
+
+**Output** (`~/.claude/skills/python-data-science/SKILL.md`):
+
+```yaml
+---
+name: python-data-science
+description: Python best practices for data science projects. Explains pandas DataFrame operations, NumPy arrays, matplotlib visualizations, and Jupyter notebook workflows. Activates for: pandas, numpy, matplotlib, jupyter notebooks, Python data analysis, data science, scientific computing.
+---
+
+# Python Data Science Skill
+
+## What I Know
+
+- Pandas DataFrame operations and transformations
+- NumPy array manipulation and vectorization
+- Matplotlib and Seaborn visualizations
+- Jupyter notebook best practices
+- Data cleaning and preprocessing
+- Statistical analysis and modeling
+
+## When to Use This Skill
+
+Ask me about:
+- "How do I use pandas to..."
+- "What's the best way to visualize..."
+- "Python data analysis tips"
+- "NumPy array operations"
+- "Jupyter notebook shortcuts"
+
+## Key Concepts
+
+### Pandas DataFrames
+
+DataFrames are the core data structure for tabular data in Python:
+- Rows and columns with labels
+- Rich indexing and selection capabilities
+- Built-in aggregation and transformation methods
+
+### NumPy Arrays
+
+Efficient numerical computing with multi-dimensional arrays:
+- Vectorized operations (avoid loops!)
+- Broadcasting for element-wise operations
+- Linear algebra and statistical functions
+
+## Examples
+
+### Example 1: Loading and Exploring Data
+
+```python
+import pandas as pd
+
+# Load CSV file
+df = pd.read_csv('data.csv')
+
+# Quick exploration
+print(df.head())        # First 5 rows
+print(df.info())        # Column types and nulls
+print(df.describe())    # Statistical summary
+```
+
+**Explanation**: Always start with exploration to understand your data structure, types, and missing values.
+
+### Example 2: Data Cleaning
+
+```python
+# Handle missing values
+df_clean = df.dropna()              # Drop rows with any nulls
+df_filled = df.fillna(0)            # Fill nulls with 0
+df_ffill = df.fillna(method='ffill')  # Forward fill
+
+# Remove duplicates
+df_unique = df.drop_duplicates()
+```
+
+**Explanation**: Choose the right strategy based on your data and analysis goals.
+
+## Best Practices
+
+1. ✅ **Use vectorized operations**: Avoid Python loops, use pandas/numpy methods
+2. ✅ **Chain operations**: `df.groupby('col').agg('mean').sort_values()`
+3. ✅ **Copy data explicitly**: Use `.copy()` to avoid SettingWithCopyWarning
+4. ⚠️ **Avoid iterrows()**: Extremely slow, use `.apply()` or vectorization instead
+
+## Common Patterns
+
+### Groupby-Aggregation
+```python
+df.groupby('category').agg({
+    'sales': 'sum',
+    'quantity': 'mean',
+    'price': ['min', 'max']
+})
+```
+
+### Time Series Resampling
+```python
+df.set_index('date').resample('M').mean()
+```
+
+## Resources
+
+- [Pandas Documentation](https://pandas.pydata.org/docs/)
+- [NumPy User Guide](https://numpy.org/doc/stable/user/)
+- [Matplotlib Gallery](https://matplotlib.org/stable/gallery/index.html)
+```
+
+### Example 2: Read-Only Documentation Skill
+
+**Input**:
+- Name: `project-docs-helper`
+- Purpose: "Project documentation expert"
+- Triggers: "documentation, docs, readme, API reference"
+- Location: Project (`.claude/skills/`)
+- Tool restrictions: Read, Grep, Glob, WebSearch
+
+**Output** (`.claude/skills/project-docs-helper/SKILL.md`):
+
+```yaml
+---
+name: project-docs-helper
+description: Project documentation expert. Helps find and explain documentation, API references, and README files. Read-only access for safe documentation browsing. Activates for: documentation, docs, readme, API reference, how to use, user guide.
+allowed-tools: Read, Grep, Glob, WebSearch
+---
+
+# Project Documentation Helper
+
+## What I Know
+
+- Location of all project documentation
+- API reference structure
+- README and getting started guides
+- Architecture documentation
+- Contributing guidelines
+
+## When to Use This Skill
+
+Ask me about:
+- "Where is the documentation for..."
+- "How do I use [feature]..."
+- "What APIs are available..."
+- "Getting started with this project"
+
+## Documentation Structure
+
+This project follows standard documentation patterns:
+- `/docs/` - Main documentation folder
+- `README.md` - Getting started guide
+- `API.md` - API reference
+- `CONTRIBUTING.md` - Contribution guidelines
+- `ARCHITECTURE.md` - System design
+
+## How to Find Information
+
+### Search by Topic
+I can search through all documentation files to find information about specific topics.
+
+### Navigate by Structure
+I understand the documentation hierarchy and can guide you to the right files.
+
+### Explain Concepts
+I can read and explain complex documentation sections in simpler terms.
+
+## Best Practices
+
+1. ✅ **Check README first**: Start with README.md for project overview
+2. ✅ **Use search**: Ask me to search docs instead of browsing manually
+3. ✅ **Verify versions**: Documentation may be version-specific
+4. ⚠️ **Read-only**: This skill cannot modify documentation
+```
+
+## Validation and Testing
+
+### Post-Creation Validation
+
+**Run these checks after creation**:
+
+```bash
+# 1. File exists in correct location
+ls "$skill_dir/SKILL.md"
+
+# 2. YAML frontmatter is valid
+head -10 "$skill_dir/SKILL.md"
+
+# Should see:
+# ---
+# name: your-skill-name
+# description: ...
+# ---
+
+# 3. No syntax errors
+node -e "
+const fs = require('fs');
+const yaml = require('js-yaml');
+const content = fs.readFileSync('$skill_dir/SKILL.md', 'utf-8');
+const match = content.match(/^---\\n([\\s\\S]*?)\\n---/);
+if (!match) {
+  console.error('❌ No YAML frontmatter found');
+  process.exit(1);
+}
+try {
+  const data = yaml.load(match[1]);
+  console.log('✅ Valid YAML:', JSON.stringify(data, null, 2));
+} catch (e) {
+  console.error('❌ YAML parsing error:', e.message);
+  process.exit(1);
+}
+"
+```
+
+### Testing Activation
+
+**Steps**:
+1. Create skill
+2. Restart Claude Code
+3. Ask a question with trigger keywords
+4. Verify skill activates (should see skill content in context)
+
+**Test questions based on examples**:
+- Python Data Science: "How do I use pandas to read a CSV file?"
+- Documentation Helper: "Where is the API documentation?"
+- Kubernetes Expert: "How do I list all pods in a namespace?"
+
+## Troubleshooting
+
+### Skill Doesn't Activate
+
+**Possible causes**:
+
+1. **Claude Code not restarted**: Skills only load on startup
+   - **Fix**: Restart Claude Code
+
+2. **Missing trigger keywords**: Description doesn't match user's question
+   - **Fix**: Add more keyword variations to description
+
+3. **YAML syntax errors**: Frontmatter is invalid
+   - **Fix**: Validate YAML format (use checker above)
+
+4. **Wrong file location**: SKILL.md not in subdirectory
+   - **Fix**: Move to `skills/skill-name/SKILL.md`
+
+5. **Name mismatch**: YAML name doesn't match directory name
+   - **Fix**: Ensure consistency (can be different, but confusing)
+
+### YAML Parsing Errors
+
+**Common mistakes**:
+
+```yaml
+# ❌ WRONG: Missing closing ---
+---
+name: my-skill
+description: My skill description
+
+# ✅ CORRECT: Closing --- present
+---
+name: my-skill
+description: My skill description
+---
+
+# ❌ WRONG: Invalid characters in name
+---
+name: My Skill Name
+---
+
+# ✅ CORRECT: Lowercase with hyphens
+---
+name: my-skill-name
+---
+
+# ❌ WRONG: Description too long (>1024 chars)
+---
+name: skill
+description: [2000 character description]
+---
+
+# ✅ CORRECT: Concise description (<1024 chars)
+---
+name: skill
+description: Focused description with key triggers
+---
+```
+
+## Best Practices
+
+### Naming Conventions
+
+1. **Be specific**: `react-hooks` not `react`
+2. **Use domain language**: `kubernetes-expert` not `k8s-helper`
+3. **Avoid redundancy**: `python-data-science` not `python-data-science-skill`
+4. **Max 3 words**: Keep names concise
+
+### Description Writing
+
+1. **Front-load purpose**: Start with what the skill does
+2. **List all variations**: Include abbreviations (k8s, kubernetes)
+3. **Use action words**: "Explains", "Helps with", "Provides guidance"
+4. **Include examples**: "React hooks (useState, useEffect, useContext)"
+
+### Content Structure
+
+1. **Start simple**: Basic examples before advanced patterns
+2. **Use headings**: Clear section organization
+3. **Include code**: Concrete examples over abstract explanations
+4. **Anti-patterns**: Show what NOT to do (⚠️ warnings)
+
+### Tool Restrictions
+
+1. **Read-only by default**: Start restrictive, expand if needed
+2. **Justify access**: Only grant Write/Edit if skill creates files
+3. **Document reasons**: Explain why tools are needed
+
+## Summary
+
+**Key steps**:
+1. ✅ Validate skill name (lowercase, hyphens, max 64 chars)
+2. ✅ Create description with triggers (max 1024 chars)
+3. ✅ Choose skill location (personal vs project)
+4. ✅ Add tool restrictions if read-only
+5. ✅ Generate SKILL.md with YAML frontmatter
+6. ✅ Validate structure (frontmatter, fields, format)
+7. ✅ Restart Claude Code
+8. ✅ Test with trigger question
+
+**Remember**: Restart Claude Code after creating or modifying skills!