specweave 0.23.16 → 0.24.0

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

@@ -0,0 +1,751 @@
+---
+name: specweave-tooling:skill-package
+description: Package Claude Code skill for distribution via npm, GitHub, or direct sharing. Creates distributable archives with installation instructions and validation.
+---
+
+# Package Skill for Distribution
+
+**Distribution-Ready Packaging**: Create shareable skill packages with installation scripts and documentation.
+
+You are helping the user package a Claude Code skill for distribution to others.
+
+## Distribution Methods
+
+### 1. NPM Package
+- Professional distribution
+- Versioning and updates
+- `npm install` workflow
+- Best for public skills
+
+### 2. GitHub Repository
+- Source control integration
+- Easy cloning and updates
+- Issue tracking
+- Best for collaborative skills
+
+### 3. Direct Archive (.tar.gz)
+- Self-contained package
+- No dependencies
+- Manual installation
+- Best for private/internal sharing
+
+### 4. Plugin Bundle
+- Multiple skills in one package
+- Shared dependencies
+- Professional presentation
+- Best for skill collections
+
+## Steps
+
+### Step 1: Validate Skill
+
+**Before packaging, ensure skill is valid**:
+
+```bash
+validate_before_package() {
+  local skill_path="$1"
+
+  echo "Validating skill before packaging..."
+
+  # Run validation (from skill-validate command)
+  if ! validate_skill "$skill_path"; then
+    echo "❌ Skill validation failed"
+    echo "   Fix errors before packaging"
+    return 1
+  fi
+
+  echo "✅ Skill validation passed"
+  return 0
+}
+```
+
+### Step 2: Gather Package Metadata
+
+**Collect information for package**:
+
+1. **Package Name**: npm-compatible name (e.g., `claude-skill-python-data-science`)
+2. **Version**: Semantic versioning (e.g., `1.0.0`)
+3. **Description**: Brief summary for package managers
+4. **Author**: Name and email
+5. **License**: MIT, Apache-2.0, etc.
+6. **Repository**: GitHub URL (optional)
+7. **Keywords**: For discoverability
+
+**Example**:
+```json
+{
+  "name": "claude-skill-python-data-science",
+  "version": "1.0.0",
+  "description": "Python data science expert skill for Claude Code",
+  "author": "Your Name <email@example.com>",
+  "license": "MIT",
+  "repository": "https://github.com/username/claude-skill-python-data-science",
+  "keywords": ["claude", "skill", "python", "data-science", "pandas", "numpy"]
+}
+```
+
+### Step 3: Create Package Structure
+
+**Standard package structure**:
+
+```
+package-name/
+├── README.md                    # Installation and usage
+├── LICENSE                      # License file
+├── package.json                 # NPM metadata (if NPM)
+├── install.sh                   # Installation script
+├── uninstall.sh                 # Uninstall script
+├── skill/                       # Skill files
+│   └── SKILL.md                 # The actual skill
+└── examples/                    # Usage examples (optional)
+    └── example-conversation.md
+```
+
+**Create structure**:
+
+```bash
+create_package_structure() {
+  local skill_path="$1"
+  local package_name="$2"
+  local package_dir="$3"
+
+  # Create directories
+  mkdir -p "$package_dir/skill"
+  mkdir -p "$package_dir/examples"
+
+  # Copy skill
+  cp "$skill_path" "$package_dir/skill/SKILL.md"
+
+  echo "✅ Package structure created"
+}
+```
+
+### Step 4: Generate README.md
+
+**Comprehensive README template**:
+
+```markdown
+# [Skill Name]
+
+[Brief description of what the skill does]
+
+## Installation
+
+### Personal Skills (Recommended)
+
+```bash
+# Clone or download this repository
+git clone [repository-url]
+
+# Run installation script
+cd [package-name]
+bash install.sh
+```
+
+Or manually:
+
+```bash
+# Copy skill to personal skills directory
+mkdir -p ~/.claude/skills/[skill-name]
+cp skill/SKILL.md ~/.claude/skills/[skill-name]/SKILL.md
+```
+
+### Project Skills
+
+```bash
+# Copy skill to project skills directory
+mkdir -p .claude/skills/[skill-name]
+cp skill/SKILL.md .claude/skills/[skill-name]/SKILL.md
+```
+
+### NPM (if published)
+
+```bash
+npm install -g [package-name]
+```
+
+## Activation
+
+This skill activates automatically when you mention:
+- [Trigger keyword 1]
+- [Trigger keyword 2]
+- [Trigger phrase 1]
+
+## Examples
+
+### Example 1: [Use Case]
+
+**You ask:**
+> [Example question]
+
+**Skill provides:**
+[Description of response]
+
+### Example 2: [Use Case]
+
+**You ask:**
+> [Example question]
+
+**Skill provides:**
+[Description of response]
+
+## Features
+
+- ✅ [Feature 1]
+- ✅ [Feature 2]
+- ✅ [Feature 3]
+
+## What This Skill Knows
+
+[Bullet list of expertise areas]
+
+## Uninstallation
+
+```bash
+bash uninstall.sh
+```
+
+Or manually:
+
+```bash
+rm -rf ~/.claude/skills/[skill-name]
+```
+
+## License
+
+[License name] - See LICENSE file for details
+
+## Author
+
+[Author name and contact]
+
+## Contributing
+
+[Contribution guidelines if applicable]
+
+## Version History
+
+### 1.0.0 (YYYY-MM-DD)
+- Initial release
+- [Feature 1]
+- [Feature 2]
+```
+
+**Generate README**:
+
+```bash
+generate_readme() {
+  local package_dir="$1"
+  local skill_name="$2"
+  local description="$3"
+  local author="$4"
+  local license="$5"
+
+  cat > "$package_dir/README.md" <<EOF
+# $skill_name
+
+$description
+
+## Installation
+
+### Personal Skills (Recommended)
+
+\`\`\`bash
+# Clone or download this repository
+git clone [repository-url]
+
+# Run installation script
+cd [package-name]
+bash install.sh
+\`\`\`
+
+Or manually:
+
+\`\`\`bash
+# Copy skill to personal skills directory
+mkdir -p ~/.claude/skills/$skill_name
+cp skill/SKILL.md ~/.claude/skills/$skill_name/SKILL.md
+\`\`\`
+
+## Activation
+
+This skill activates automatically when needed.
+
+## License
+
+$license
+
+## Author
+
+$author
+EOF
+
+  echo "✅ README.md generated"
+}
+```
+
+### Step 5: Create Installation Script
+
+**Universal installation script** (`install.sh`):
+
+```bash
+#!/bin/bash
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Skill configuration
+SKILL_NAME="[skill-name]"
+SKILL_DISPLAY_NAME="[Skill Display Name]"
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "INSTALLING: $SKILL_DISPLAY_NAME"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Check if skill already installed
+if [ -d "$HOME/.claude/skills/$SKILL_NAME" ]; then
+  echo -e "${YELLOW}⚠️  Skill already installed at: ~/.claude/skills/$SKILL_NAME${NC}"
+  echo ""
+  read -p "Overwrite existing installation? (y/N) " -n 1 -r
+  echo ""
+  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    echo "Installation cancelled."
+    exit 0
+  fi
+  rm -rf "$HOME/.claude/skills/$SKILL_NAME"
+fi
+
+# Create skills directory if needed
+mkdir -p "$HOME/.claude/skills"
+
+# Copy skill
+echo "📦 Installing skill..."
+mkdir -p "$HOME/.claude/skills/$SKILL_NAME"
+cp skill/SKILL.md "$HOME/.claude/skills/$SKILL_NAME/SKILL.md"
+
+# Validate installation
+if [ -f "$HOME/.claude/skills/$SKILL_NAME/SKILL.md" ]; then
+  echo -e "${GREEN}✅ Installation successful!${NC}"
+  echo ""
+  echo "📁 Installed to: ~/.claude/skills/$SKILL_NAME/"
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "NEXT STEPS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "1. 🔄 Restart Claude Code to load the skill"
+  echo "2. 🧪 Test the skill by asking a relevant question"
+  echo "3. 📚 See README.md for usage examples"
+  echo ""
+  echo "To uninstall: bash uninstall.sh"
+  echo ""
+else
+  echo -e "${RED}❌ Installation failed${NC}"
+  exit 1
+fi
+```
+
+**Generate install.sh**:
+
+```bash
+generate_install_script() {
+  local package_dir="$1"
+  local skill_name="$2"
+  local skill_display_name="$3"
+
+  cat > "$package_dir/install.sh" <<'INSTALL_SCRIPT'
+#!/bin/bash
+set -e
+
+# [Installation script content from above]
+INSTALL_SCRIPT
+
+  # Make executable
+  chmod +x "$package_dir/install.sh"
+
+  echo "✅ install.sh generated"
+}
+```
+
+### Step 6: Create Uninstallation Script
+
+**Uninstallation script** (`uninstall.sh`):
+
+```bash
+#!/bin/bash
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Skill configuration
+SKILL_NAME="[skill-name]"
+SKILL_DISPLAY_NAME="[Skill Display Name]"
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "UNINSTALLING: $SKILL_DISPLAY_NAME"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Check if skill is installed
+if [ ! -d "$HOME/.claude/skills/$SKILL_NAME" ]; then
+  echo -e "${YELLOW}⚠️  Skill not found at: ~/.claude/skills/$SKILL_NAME${NC}"
+  echo ""
+  echo "Nothing to uninstall."
+  exit 0
+fi
+
+# Confirm uninstallation
+echo "This will remove: ~/.claude/skills/$SKILL_NAME/"
+echo ""
+read -p "Continue with uninstallation? (y/N) " -n 1 -r
+echo ""
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+  echo "Uninstallation cancelled."
+  exit 0
+fi
+
+# Remove skill
+rm -rf "$HOME/.claude/skills/$SKILL_NAME"
+
+# Verify removal
+if [ ! -d "$HOME/.claude/skills/$SKILL_NAME" ]; then
+  echo -e "${GREEN}✅ Uninstallation successful!${NC}"
+  echo ""
+  echo "Skill removed from: ~/.claude/skills/$SKILL_NAME/"
+  echo ""
+  echo "🔄 Restart Claude Code to complete uninstallation"
+else
+  echo -e "${RED}❌ Uninstallation failed${NC}"
+  exit 1
+fi
+```
+
+### Step 7: Add License File
+
+**Common licenses**:
+
+**MIT License** (most permissive):
+```
+MIT License
+
+Copyright (c) [year] [author]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+### Step 8: Create package.json (NPM Only)
+
+**NPM package.json**:
+
+```json
+{
+  "name": "claude-skill-[skill-name]",
+  "version": "1.0.0",
+  "description": "[Skill description]",
+  "main": "index.js",
+  "scripts": {
+    "postinstall": "bash install.sh",
+    "preuninstall": "bash uninstall.sh"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skill",
+    "[domain]"
+  ],
+  "author": "[Author Name] <[email]>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/[username]/[repo].git"
+  },
+  "bugs": {
+    "url": "https://github.com/[username]/[repo]/issues"
+  },
+  "homepage": "https://github.com/[username]/[repo]#readme",
+  "files": [
+    "skill/",
+    "install.sh",
+    "uninstall.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}
+```
+
+### Step 9: Create Archive
+
+**For direct distribution**:
+
+```bash
+create_archive() {
+  local package_dir="$1"
+  local package_name="$2"
+  local version="$3"
+
+  # Archive filename
+  archive_name="${package_name}-${version}.tar.gz"
+
+  # Create archive
+  tar -czf "$archive_name" -C "$(dirname "$package_dir")" "$(basename "$package_dir")"
+
+  # Verify archive
+  if [ -f "$archive_name" ]; then
+    echo "✅ Archive created: $archive_name"
+    echo ""
+    echo "Archive contents:"
+    tar -tzf "$archive_name" | head -20
+    echo ""
+    echo "Distribution ready!"
+  else
+    echo "❌ Failed to create archive"
+    return 1
+  fi
+}
+```
+
+### Step 10: Generate Distribution Instructions
+
+**Include installation guide**:
+
+```markdown
+# Distribution Instructions
+
+## For NPM
+
+1. Publish to npm:
+   ```bash
+   npm publish
+   ```
+
+2. Users install with:
+   ```bash
+   npm install -g [package-name]
+   ```
+
+## For GitHub
+
+1. Push to GitHub:
+   ```bash
+   git init
+   git add .
+   git commit -m "Initial commit"
+   git remote add origin [repository-url]
+   git push -u origin main
+   ```
+
+2. Create release:
+   - Go to GitHub → Releases → New Release
+   - Tag: v1.0.0
+   - Upload .tar.gz archive
+   - Add release notes
+
+3. Users install with:
+   ```bash
+   git clone [repository-url]
+   cd [package-name]
+   bash install.sh
+   ```
+
+## For Direct Sharing
+
+1. Share the .tar.gz archive
+
+2. Users install with:
+   ```bash
+   tar -xzf [package-name]-1.0.0.tar.gz
+   cd [package-name]
+   bash install.sh
+   ```
+
+## Verification
+
+After installation, users should:
+1. Restart Claude Code
+2. Test skill activation
+3. Report issues
+```
+
+## Packaging Examples
+
+### Example 1: NPM Package
+
+**Input**:
+- Skill: `python-data-science`
+- Distribution: NPM
+- Version: 1.0.0
+- License: MIT
+
+**Output structure**:
+```
+claude-skill-python-data-science/
+├── README.md
+├── LICENSE
+├── package.json
+├── install.sh
+├── uninstall.sh
+├── skill/
+│   └── SKILL.md
+└── examples/
+    └── example-conversation.md
+```
+
+**package.json**:
+```json
+{
+  "name": "claude-skill-python-data-science",
+  "version": "1.0.0",
+  "description": "Python data science expert skill for Claude Code",
+  "author": "Your Name <email@example.com>",
+  "license": "MIT",
+  "keywords": ["claude", "skill", "python", "data-science"]
+}
+```
+
+**Publishing**:
+```bash
+npm publish
+```
+
+### Example 2: GitHub Repository
+
+**Input**:
+- Skill: `kubernetes-expert`
+- Distribution: GitHub
+- Repository: `github.com/username/claude-skill-k8s`
+
+**Setup**:
+```bash
+# Initialize repo
+git init
+git add .
+git commit -m "Initial commit: Kubernetes expert skill"
+
+# Push to GitHub
+git remote add origin https://github.com/username/claude-skill-k8s.git
+git push -u origin main
+
+# Create release
+gh release create v1.0.0 --title "v1.0.0" --notes "Initial release"
+```
+
+**Users install**:
+```bash
+git clone https://github.com/username/claude-skill-k8s.git
+cd claude-skill-k8s
+bash install.sh
+```
+
+### Example 3: Direct Archive
+
+**Input**:
+- Skill: `project-docs-helper`
+- Distribution: Internal sharing
+- Archive: `project-docs-helper-1.0.0.tar.gz`
+
+**Create archive**:
+```bash
+# Package structure already created
+tar -czf project-docs-helper-1.0.0.tar.gz project-docs-helper/
+
+# Share archive via email, shared drive, etc.
+```
+
+**Users install**:
+```bash
+tar -xzf project-docs-helper-1.0.0.tar.gz
+cd project-docs-helper
+bash install.sh
+```
+
+## Quality Checklist
+
+**Before distributing, verify**:
+
+- [ ] ✅ Skill validated successfully
+- [ ] ✅ README.md includes installation instructions
+- [ ] ✅ LICENSE file present
+- [ ] ✅ install.sh script works correctly
+- [ ] ✅ uninstall.sh script works correctly
+- [ ] ✅ Examples included
+- [ ] ✅ Version number set
+- [ ] ✅ Author information complete
+- [ ] ✅ Repository URL (if applicable)
+- [ ] ✅ Keywords for discoverability
+- [ ] ✅ Archive created (if direct distribution)
+- [ ] ✅ Tested installation on clean system
+
+## Publishing to NPM
+
+**Step-by-step**:
+
+```bash
+# 1. Login to npm
+npm login
+
+# 2. Validate package.json
+npm pack --dry-run
+
+# 3. Publish
+npm publish
+
+# 4. Verify
+npm view [package-name]
+```
+
+**Scope packages (recommended)**:
+```json
+{
+  "name": "@your-username/claude-skill-python-data-science",
+  ...
+}
+```
+
+## Summary
+
+**Package includes**:
+1. ✅ Skill file (SKILL.md)
+2. ✅ README with installation instructions
+3. ✅ LICENSE file
+4. ✅ install.sh script
+5. ✅ uninstall.sh script
+6. ✅ package.json (NPM only)
+7. ✅ Examples (optional)
+8. ✅ Archive file (direct distribution)
+
+**Distribution methods**:
+1. ✅ NPM (`npm install -g`)
+2. ✅ GitHub (clone + install.sh)
+3. ✅ Direct archive (.tar.gz)
+
+**Remember**: Test installation on clean system before distributing!