From 0b1f4556bc6393f0fa068d6d662e4d4316b0455d Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:20:15 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 16 + README.md | 3 + commands/demo-skills.md | 283 +++++++++++++++ plugin.lock.json | 173 +++++++++ skills/marketplace-manager/SKILL.md | 303 ++++++++++++++++ skills/marketplace-manager/assets/README.md | 26 ++ .../marketplace-manager/references/README.md | 26 ++ skills/marketplace-manager/scripts/README.md | 24 ++ skills/plugin-auditor/SKILL.md | 342 ++++++++++++++++++ skills/plugin-auditor/assets/README.md | 26 ++ skills/plugin-auditor/references/README.md | 26 ++ skills/plugin-auditor/scripts/README.md | 24 ++ skills/plugin-creator/SKILL.md | 207 +++++++++++ skills/plugin-creator/assets/README.md | 26 ++ skills/plugin-creator/references/README.md | 26 ++ skills/plugin-creator/scripts/README.md | 24 ++ skills/plugin-validator/SKILL.md | 249 +++++++++++++ skills/plugin-validator/assets/README.md | 26 ++ skills/plugin-validator/references/README.md | 26 ++ skills/plugin-validator/scripts/README.md | 24 ++ skills/skill-adapter/assets/README.md | 8 + .../skill-adapter/assets/config-template.json | 32 ++ .../assets/marketplace_schema.json | 153 ++++++++ skills/skill-adapter/assets/skill-schema.json | 28 ++ skills/skill-adapter/assets/test-data.json | 27 ++ .../assets/validation_rules.json | 113 ++++++ skills/skill-adapter/references/README.md | 9 + .../references/best-practices.md | 69 ++++ skills/skill-adapter/references/examples.md | 70 ++++ skills/skill-adapter/scripts/README.md | 9 + .../skill-adapter/scripts/helper-template.sh | 42 +++ skills/skill-adapter/scripts/validation.sh | 32 ++ skills/version-bumper/SKILL.md | 340 +++++++++++++++++ skills/version-bumper/assets/README.md | 26 ++ skills/version-bumper/references/README.md | 26 ++ skills/version-bumper/scripts/README.md | 24 ++ 36 files changed, 2888 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/demo-skills.md create mode 100644 plugin.lock.json create mode 100644 skills/marketplace-manager/SKILL.md create mode 100644 skills/marketplace-manager/assets/README.md create mode 100644 skills/marketplace-manager/references/README.md create mode 100644 skills/marketplace-manager/scripts/README.md create mode 100644 skills/plugin-auditor/SKILL.md create mode 100644 skills/plugin-auditor/assets/README.md create mode 100644 skills/plugin-auditor/references/README.md create mode 100644 skills/plugin-auditor/scripts/README.md create mode 100644 skills/plugin-creator/SKILL.md create mode 100644 skills/plugin-creator/assets/README.md create mode 100644 skills/plugin-creator/references/README.md create mode 100644 skills/plugin-creator/scripts/README.md create mode 100644 skills/plugin-validator/SKILL.md create mode 100644 skills/plugin-validator/assets/README.md create mode 100644 skills/plugin-validator/references/README.md create mode 100644 skills/plugin-validator/scripts/README.md create mode 100644 skills/skill-adapter/assets/README.md create mode 100644 skills/skill-adapter/assets/config-template.json create mode 100644 skills/skill-adapter/assets/marketplace_schema.json create mode 100644 skills/skill-adapter/assets/skill-schema.json create mode 100644 skills/skill-adapter/assets/test-data.json create mode 100644 skills/skill-adapter/assets/validation_rules.json create mode 100644 skills/skill-adapter/references/README.md create mode 100644 skills/skill-adapter/references/best-practices.md create mode 100644 skills/skill-adapter/references/examples.md create mode 100644 skills/skill-adapter/scripts/README.md create mode 100755 skills/skill-adapter/scripts/helper-template.sh create mode 100755 skills/skill-adapter/scripts/validation.sh create mode 100644 skills/version-bumper/SKILL.md create mode 100644 skills/version-bumper/assets/README.md create mode 100644 skills/version-bumper/references/README.md create mode 100644 skills/version-bumper/scripts/README.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..e40967c --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,16 @@ +{ + "name": "skills-powerkit", + "description": "Ultimate plugin management toolkit with 5 auto-invoked Skills for creating, validating, auditing, and managing plugins in the claude-code-plugins marketplace", + "version": "1.0.0", + "author": { + "name": "Claude Code Plugins", + "email": "plugins@claudecodeplugins.io", + "url": "https://claudecodeplugins.io" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..0a3d50c --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# skills-powerkit + +Ultimate plugin management toolkit with 5 auto-invoked Skills for creating, validating, auditing, and managing plugins in the claude-code-plugins marketplace diff --git a/commands/demo-skills.md b/commands/demo-skills.md new file mode 100644 index 0000000..09ae34a --- /dev/null +++ b/commands/demo-skills.md @@ -0,0 +1,283 @@ +--- +name: demo-skills +description: Demonstrates the 5 plugin management Skills for creating, validating, auditing, and managing plugins in claude-code-plugins repository +model: sonnet +--- + +# Skills Powerkit Demo - Plugin Management Skills + +This command demonstrates the 5 Agent Skills designed specifically for managing plugins in the **claude-code-plugins** repository. + +## What Is Skills Powerkit? + +**Skills Powerkit is a "meta-plugin"** - it helps you BUILD, VALIDATE, AUDIT, and MANAGE other plugins. + +Unlike general development skills, these are **repository-specific** - they understand: +- Two-catalog system (marketplace.extended.json → marketplace.json) +- Repository structure and standards +- CLAUDE.md compliance requirements +- Validation and security requirements + +--- + +## 5 Plugin Management Skills + +### 1. 🛠️ Plugin Creator +**Auto-invokes when you mention:** +- "create plugin", "new plugin" +- "scaffold plugin" +- "add plugin to marketplace" + +**Example request:** "Create a security plugin called 'owasp-scanner' with commands" + +**What it automatically does:** +1. Creates directory structure: `plugins/security/owasp-scanner/` +2. Generates plugin.json with proper schema +3. Creates README.md, LICENSE +4. Adds commands/ directory with example +5. Updates marketplace.extended.json +6. Runs `npm run sync-marketplace` +7. Validates everything +8. Reports: "✅ Plugin created and ready!" + +**Saves you:** 15-30 minutes of manual setup + +--- + +### 2. ✅ Plugin Validator +**Auto-invokes when you mention:** +- "validate plugin", "check plugin" +- "is plugin ready to commit" +- "plugin errors" + +**Example request:** "Validate the skills-powerkit plugin" + +**What it automatically does:** +1. Checks required files exist +2. Validates plugin.json schema +3. Checks markdown frontmatter format +4. Verifies script permissions +5. Validates marketplace entry +6. Runs security scans +7. Generates validation report + +**Saves you:** 5-10 minutes of manual checking + +--- + +### 3. 📦 Marketplace Manager +**Auto-invokes when you mention:** +- "update marketplace", "sync marketplace" +- "add to marketplace" +- "marketplace catalog" + +**Example request:** "Add the new security-scanner to marketplace" + +**What it automatically does:** +1. Reads plugin.json for metadata +2. Adds entry to marketplace.extended.json +3. Runs `npm run sync-marketplace` +4. Validates both catalog files +5. Checks for duplicates +6. Reports success + +**Saves you:** 3-5 minutes of manual catalog editing + +--- + +### 4. 🔍 Plugin Auditor +**Auto-invokes when you mention:** +- "audit plugin", "security review" +- "best practices check" +- "plugin quality" + +**Example request:** "Security audit on the password-manager plugin" + +**What it automatically does:** +1. Scans for hardcoded secrets (passwords, API keys) +2. Checks for dangerous commands (rm -rf, eval) +3. Validates security patterns +4. Checks best practices compliance +5. Verifies CLAUDE.md standards +6. Generates quality score +7. Provides recommendations + +**Saves you:** 10-15 minutes of manual security review + +--- + +### 5. 🔢 Version Bumper +**Auto-invokes when you mention:** +- "bump version", "update version" +- "release", "new version" +- "major/minor/patch" + +**Example request:** "Bump docker-optimizer to minor version" + +**What it automatically does:** +1. Reads current version from plugin.json +2. Calculates new version (1.0.0 → 1.1.0) +3. Updates plugin.json +4. Updates marketplace.extended.json +5. Runs `npm run sync-marketplace` +6. Updates CHANGELOG.md (if exists) +7. Can create git tags +8. Reports success + +**Saves you:** 5 minutes of manual version updates + +--- + +## How Skills Work + +**Skills are MODEL-INVOKED** - Claude automatically decides when to use them. + +**Example conversation:** + +**You:** "I need a new DevOps plugin for Docker optimization with commands" + +**Claude automatically:** +1. Recognizes "new plugin" → Invokes Plugin Creator +2. Recognizes "DevOps" → Sets category +3. Recognizes "with commands" → Creates commands/ directory +4. Creates plugins/devops/docker-optimizer/ +5. Generates all files +6. Updates marketplace +7. Validates +8. Reports: "✅ Created docker-optimizer plugin!" + +**You didn't run any commands** - Claude understood context and did everything! + +--- + +## Skills vs Commands Comparison + +| Feature | Skills (This Plugin) | Slash Commands | +|---------|---------------------|----------------| +| **Invocation** | Auto (Claude decides) | Manual (/command) | +| **Trigger** | Keywords in conversation | Explicit command | +| **Context** | Understands repository | Single purpose | +| **Workflow** | Chains multiple tasks | Single task | +| **Example** | "create and validate plugin" | /create then /validate | + +**Skills feel natural** - like talking to a teammate who knows the repo! + +--- + +## Real Workflow Examples + +### Workflow 1: Create + Validate + Audit +**You:** "Create a security plugin called 'owasp-scanner', validate it, and run security audit" + +**Skills automatically chain:** +1. Plugin Creator → Creates plugin +2. Plugin Validator → Validates structure +3. Plugin Auditor → Security audit +4. Reports all results + +### Workflow 2: Update + Sync +**You:** "Bump version to 1.2.0 and update marketplace" + +**Skills automatically chain:** +1. Version Bumper → Updates to 1.2.0 +2. Marketplace Manager → Syncs catalog +3. Reports success + +### Workflow 3: Pre-Commit Check +**You:** "Is everything ready to commit?" + +**Skills automatically:** +1. Plugin Validator → Full validation +2. Plugin Auditor → Security check +3. Reports: "✅ PASSED - Ready to commit!" + +--- + +## Repository-Specific Knowledge + +Skills Powerkit knows about claude-code-plugins: + +**Two-Catalog System:** +- marketplace.extended.json (source - edit this) +- marketplace.json (generated - never edit) +- Auto-runs `npm run sync-marketplace` + +**Directory Structure:** +- plugins/[category]/[plugin-name]/ +- 14 valid categories +- Required files + +**Validation Standards:** +- ./scripts/validate-all.sh +- python3 scripts/check-frontmatter.py +- jq for JSON validation + +**CLAUDE.md Compliance:** +- Follows repository conventions +- Uses correct marketplace slug +- Validates against standards + +--- + +## Try It Out! + +Test each skill by saying: + +1. **"Create a new testing plugin called 'jest-generator'"** + → Plugin Creator activates + +2. **"Validate the jest-generator plugin"** + → Plugin Validator activates + +3. **"Add jest-generator to marketplace"** + → Marketplace Manager activates + +4. **"Security audit on jest-generator"** + → Plugin Auditor activates + +5. **"Bump jest-generator to version 1.1.0"** + → Version Bumper activates + +Claude will automatically use the right skill! + +--- + +## Installation + +```bash +/plugin install skills-powerkit@claude-code-plugins-plus +``` + +Once installed, all 5 skills are active and auto-invoke when relevant. + +--- + +## Time Savings + +**Per plugin lifecycle:** +- Create: 15-30 min → 30 seconds +- Validate: 5-10 min → 10 seconds +- Marketplace: 3-5 min → 5 seconds +- Audit: 10-15 min → 15 seconds +- Version: 5 min → 10 seconds + +**Total saved: 40-60 minutes per plugin!** + +--- + +## Requirements + +- Claude Code CLI with Skills support (Oct 2025+) +- Working in claude-code-plugins repository +- Node.js for marketplace sync +- Python 3 for frontmatter validation +- jq for JSON validation + +--- + +**Need help?** Just ask: +- "What skills do I have available?" +- "How do I create a plugin?" +- "Validate my current plugin" + +Skills will respond automatically! 🚀 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..42d3949 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,173 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/examples/skills-powerkit", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "8107a1b19223d8b7bbed803eaa44fa78ad5bd771", + "treeHash": "65aba16b4face033f0fb1ec50b6bdcd63190e18e21951ceb61cd3edece193bfc", + "generatedAt": "2025-11-28T10:18:45.660124Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "skills-powerkit", + "description": "Ultimate plugin management toolkit with 5 auto-invoked Skills for creating, validating, auditing, and managing plugins in the claude-code-plugins marketplace", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "02ae5f9f7babfb7b35907ae7b01473b669492c3d993621a5289a512663a8269b" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "570c46d23cf3c58ef15b7b274927151f1e5fc2043a30fdfbe1e895d5f01a1cc4" + }, + { + "path": "commands/demo-skills.md", + "sha256": "0c982cbe77b2c5093c4d9588d928e16a0bcb1ea68a32de2dc348790b99632b85" + }, + { + "path": "skills/marketplace-manager/SKILL.md", + "sha256": "8695a29062c96821f81e4932c832a9bb3d7e5ce0318552018d812cc64472ed21" + }, + { + "path": "skills/marketplace-manager/references/README.md", + "sha256": "db9680278e03728fef93321fc76c435387bc0c8fe1dcc9870bdf2fa236ea8ac3" + }, + { + "path": "skills/marketplace-manager/scripts/README.md", + "sha256": "f042646ad5b685556c044080a6b73202a490fb8288be8219328faefc12d5a30e" + }, + { + "path": "skills/marketplace-manager/assets/README.md", + "sha256": "33bfb083485b48c78a1738368c52cd9f202724a414bce507db181d8291b83aec" + }, + { + "path": "skills/plugin-auditor/SKILL.md", + "sha256": "a49368208da3ed1f4210bcb76a886414144fdd22e53d8d853cc02fbd1ab2ac23" + }, + { + "path": "skills/plugin-auditor/references/README.md", + "sha256": "db9680278e03728fef93321fc76c435387bc0c8fe1dcc9870bdf2fa236ea8ac3" + }, + { + "path": "skills/plugin-auditor/scripts/README.md", + "sha256": "f042646ad5b685556c044080a6b73202a490fb8288be8219328faefc12d5a30e" + }, + { + "path": "skills/plugin-auditor/assets/README.md", + "sha256": "33bfb083485b48c78a1738368c52cd9f202724a414bce507db181d8291b83aec" + }, + { + "path": "skills/plugin-creator/SKILL.md", + "sha256": "0c9cc96db0302e8266e3069817199d481d12b54e7a277aa8e1807e1743814425" + }, + { + "path": "skills/plugin-creator/references/README.md", + "sha256": "db9680278e03728fef93321fc76c435387bc0c8fe1dcc9870bdf2fa236ea8ac3" + }, + { + "path": "skills/plugin-creator/scripts/README.md", + "sha256": "f042646ad5b685556c044080a6b73202a490fb8288be8219328faefc12d5a30e" + }, + { + "path": "skills/plugin-creator/assets/README.md", + "sha256": "33bfb083485b48c78a1738368c52cd9f202724a414bce507db181d8291b83aec" + }, + { + "path": "skills/version-bumper/SKILL.md", + "sha256": "12a3281ad124d5d3413bfc9757b57d41edf25e2942dfd78250623deb4dad758d" + }, + { + "path": "skills/version-bumper/references/README.md", + "sha256": "db9680278e03728fef93321fc76c435387bc0c8fe1dcc9870bdf2fa236ea8ac3" + }, + { + "path": "skills/version-bumper/scripts/README.md", + "sha256": "f042646ad5b685556c044080a6b73202a490fb8288be8219328faefc12d5a30e" + }, + { + "path": "skills/version-bumper/assets/README.md", + "sha256": "33bfb083485b48c78a1738368c52cd9f202724a414bce507db181d8291b83aec" + }, + { + "path": "skills/plugin-validator/SKILL.md", + "sha256": "ea1ed314741ed81ba73de8b12118848cdea4696e8ba4449bee87c9f569388526" + }, + { + "path": "skills/plugin-validator/references/README.md", + "sha256": "db9680278e03728fef93321fc76c435387bc0c8fe1dcc9870bdf2fa236ea8ac3" + }, + { + "path": "skills/plugin-validator/scripts/README.md", + "sha256": "f042646ad5b685556c044080a6b73202a490fb8288be8219328faefc12d5a30e" + }, + { + "path": "skills/plugin-validator/assets/README.md", + "sha256": "33bfb083485b48c78a1738368c52cd9f202724a414bce507db181d8291b83aec" + }, + { + "path": "skills/skill-adapter/references/examples.md", + "sha256": "922bbc3c4ebf38b76f515b5c1998ebde6bf902233e00e2c5a0e9176f975a7572" + }, + { + "path": "skills/skill-adapter/references/best-practices.md", + "sha256": "c8f32b3566252f50daacd346d7045a1060c718ef5cfb07c55a0f2dec5f1fb39e" + }, + { + "path": "skills/skill-adapter/references/README.md", + "sha256": "aacf5c8f66a0c5a8d868d45c890dd0d142e98a10d480a0983fa697a70e575f9e" + }, + { + "path": "skills/skill-adapter/scripts/helper-template.sh", + "sha256": "0881d5660a8a7045550d09ae0acc15642c24b70de6f08808120f47f86ccdf077" + }, + { + "path": "skills/skill-adapter/scripts/validation.sh", + "sha256": "92551a29a7f512d2036e4f1fb46c2a3dc6bff0f7dde4a9f699533e446db48502" + }, + { + "path": "skills/skill-adapter/scripts/README.md", + "sha256": "d23601ac4a2de0b34020dc9c4595ffd451280515795aff4353bb7557540bd4da" + }, + { + "path": "skills/skill-adapter/assets/test-data.json", + "sha256": "ac17dca3d6e253a5f39f2a2f1b388e5146043756b05d9ce7ac53a0042eee139d" + }, + { + "path": "skills/skill-adapter/assets/marketplace_schema.json", + "sha256": "3e3c5d0476b9dcd34e05cd8c50f2f03088aafcaa4567ee52fead92a8e97e7bae" + }, + { + "path": "skills/skill-adapter/assets/validation_rules.json", + "sha256": "2bcfee4ee9660d2a8fa24991305a49493f6b6f53724905c798602fbc6a2e9204" + }, + { + "path": "skills/skill-adapter/assets/README.md", + "sha256": "c69dc1ff9387b99d7952dec35758fb4fbfd81048d2d7f482f29fd0733c5f6d33" + }, + { + "path": "skills/skill-adapter/assets/skill-schema.json", + "sha256": "f5639ba823a24c9ac4fb21444c0717b7aefde1a4993682897f5bf544f863c2cd" + }, + { + "path": "skills/skill-adapter/assets/config-template.json", + "sha256": "0c2ba33d2d3c5ccb266c0848fc43caa68a2aa6a80ff315d4b378352711f83e1c" + } + ], + "dirSha256": "65aba16b4face033f0fb1ec50b6bdcd63190e18e21951ceb61cd3edece193bfc" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/marketplace-manager/SKILL.md b/skills/marketplace-manager/SKILL.md new file mode 100644 index 0000000..ef66b5c --- /dev/null +++ b/skills/marketplace-manager/SKILL.md @@ -0,0 +1,303 @@ +--- +name: marketplace-manager +description: | + Automatically manages marketplace catalog updates, syncs marketplace.json, and handles plugin distribution when user mentions marketplace update, sync catalog, or add to marketplace. Specific to claude-code-plugins two-catalog system. +allowed-tools: Read, Write, Edit, Grep, Bash +version: 1.0.0 +--- + +# Marketplace Manager + +## Purpose +Automatically manages the claude-code-plugins marketplace catalog system, handling updates to marketplace.extended.json, syncing to marketplace.json, and ensuring catalog integrity. + +## Trigger Keywords +- "update marketplace" +- "sync marketplace" or "sync catalog" +- "add to marketplace" +- "marketplace catalog" +- "update catalog" +- "regenerate marketplace" + +## Two-Catalog System + +**Critical Understanding:** +``` +marketplace.extended.json (SOURCE OF TRUTH) +├── Full metadata +├── Extended fields (featured, mcpTools, etc.) +└── Edit THIS file manually + +↓ npm run sync-marketplace + +marketplace.json (GENERATED) +├── CLI-compatible subset +├── Sanitized fields +└── NEVER edit directly +``` + +## Marketplace Management Tasks + +### 1. Add Plugin to Catalog + +When adding new plugin: + +```json +// Add to marketplace.extended.json +{ + "name": "plugin-name", + "source": "./plugins/category/plugin-name", + "description": "Clear one-line description", + "version": "1.0.0", + "category": "productivity", + "keywords": ["keyword1", "keyword2"], + "author": { + "name": "Author Name", + "email": "[email protected]" + }, + "repository": "https://github.com/user/repo", + "featured": false // true for featured plugins +} +``` + +Then: +```bash +npm run sync-marketplace +``` + +### 2. Update Plugin Version + +When bumping version: + +1. Update `plugins/category/plugin-name/.claude-plugin/plugin.json` +2. Update marketplace.extended.json entry +3. Run `npm run sync-marketplace` +4. Validate sync worked: `git diff .claude-plugin/marketplace.json` + +### 3. Sync Validation + +After sync, verify: +```bash +# Check marketplace.json was regenerated +git status .claude-plugin/marketplace.json + +# Validate JSON syntax +jq empty .claude-plugin/marketplace.extended.json +jq empty .claude-plugin/marketplace.json + +# Check specific plugin entry +jq '.plugins[] | select(.name == "plugin-name")' .claude-plugin/marketplace.json +``` + +### 4. Featured Plugin Management + +Mark plugin as featured: +```json +{ + "name": "plugin-name", + "featured": true, // Add this field + // ... rest of fields +} +``` + +Featured plugins appear first in marketplace. + +### 5. Catalog Integrity Checks + +I automatically verify: +- ✅ No duplicate plugin names +- ✅ All source paths exist +- ✅ All plugins have required fields +- ✅ Versions are semantic (x.y.z) +- ✅ Categories are valid +- ✅ JSON is valid +- ✅ Sync is current (no uncommitted changes to marketplace.json) + +## Valid Categories + +``` +productivity, security, testing, deployment, documentation, +analysis, integration, ai, devops, debugging, code-quality, +design, example, api-development, database, crypto, +performance, ai-ml, other +``` + +## Sync Process + +When I sync marketplace: + +1. **Backup Current State** + ```bash + cp .claude-plugin/marketplace.json .claude-plugin/marketplace.json.backup + ``` + +2. **Run Sync Script** + ```bash + npm run sync-marketplace + # or: node scripts/sync-marketplace.cjs + ``` + +3. **Validate Output** + ```bash + # Check sync success + jq empty .claude-plugin/marketplace.json + + # Verify plugins count + jq '.plugins | length' .claude-plugin/marketplace.json + ``` + +4. **Check Diff** + ```bash + git diff .claude-plugin/marketplace.json + ``` + +5. **Commit if Valid** + ```bash + git add .claude-plugin/marketplace.extended.json .claude-plugin/marketplace.json + git commit -m "chore: Update marketplace catalog" + ``` + +## Sanitized Fields + +These fields are REMOVED from marketplace.json (CLI): +- `featured` - Extended metadata +- `mcpTools` - Extended metadata +- `pluginCount` - Extended metadata +- `pricing` - Extended metadata +- `components` - Extended metadata + +**Only add these to marketplace.extended.json** + +## Marketplace Schema + +**Required fields for every plugin:** +```json +{ + "name": "string (kebab-case)", + "source": "string (relative path from repo root)", + "description": "string (clear, concise)", + "version": "string (semver: x.y.z)", + "category": "string (from valid list)", + "keywords": "array (at least 2)", + "author": { + "name": "string", + "email": "string (valid email)" + } +} +``` + +**Optional fields:** +```json +{ + "repository": "string (GitHub URL)", + "homepage": "string (docs URL)", + "license": "string (MIT, Apache-2.0, etc.)", + "featured": "boolean (extended only)", + "mcpTools": "number (extended only)" +} +``` + +## Common Issues & Fixes + +### Issue: Sync fails with schema error +```bash +# Check marketplace.extended.json syntax +jq empty .claude-plugin/marketplace.extended.json + +# Common errors: +# - Missing comma +# - Invalid field type +# - Duplicate plugin name +``` + +### Issue: marketplace.json out of sync +```bash +# Regenerate from source +npm run sync-marketplace + +# If still fails, check git status +git status .claude-plugin/ +``` + +### Issue: Plugin not appearing +```bash +# Verify entry exists +jq '.plugins[] | select(.name == "plugin-name")' .claude-plugin/marketplace.extended.json + +# Check source path +ls -la ./plugins/category/plugin-name +``` + +## Automation + +I can automatically: +1. Add plugin entries with all required fields +2. Update version across plugin + catalog +3. Sync marketplace.json +4. Validate catalog integrity +5. Check for duplicates +6. Fix common issues + +## Output Format + +``` +📦 MARKETPLACE UPDATE REPORT + +Action: Add plugin "new-plugin" +Location: plugins/productivity/new-plugin/ + +✅ COMPLETED STEPS: +1. Added entry to marketplace.extended.json +2. Ran npm run sync-marketplace +3. Validated marketplace.json +4. Checked for duplicates: NONE +5. Verified source path exists + +📊 MARKETPLACE STATS: +Total plugins: 227 (+1) +Categories: 14 +Featured: 3 +Latest sync: 2025-10-16 14:30 UTC + +✨ Ready to commit: +git add .claude-plugin/marketplace.extended.json .claude-plugin/marketplace.json +git commit -m "feat: Add new-plugin to marketplace" +``` + +## Repository-Specific Features + +**For claude-code-plugins repo:** +- Manages `claude-code-plugins-plus` marketplace +- Handles both extended and CLI catalogs +- Validates against repository structure +- Checks plugin count accuracy +- Ensures featured plugins are quality plugins + +## Examples + +**User says:** "Add the new security-scanner plugin to marketplace" + +**I automatically:** +1. Read plugin.json for metadata +2. Add entry to marketplace.extended.json +3. Run npm run sync-marketplace +4. Validate both catalogs +5. Check no duplicates +6. Report success + +**User says:** "Sync the marketplace catalog" + +**I automatically:** +1. Run npm run sync-marketplace +2. Validate marketplace.json generated +3. Check git diff +4. Report changes + +**User says:** "Update plugin version in marketplace" + +**I automatically:** +1. Find plugin entry +2. Update version in marketplace.extended.json +3. Sync marketplace.json +4. Validate versions match +5. Report success diff --git a/skills/marketplace-manager/assets/README.md b/skills/marketplace-manager/assets/README.md new file mode 100644 index 0000000..148d1c3 --- /dev/null +++ b/skills/marketplace-manager/assets/README.md @@ -0,0 +1,26 @@ +# Skill Assets + +This directory contains static assets used by this skill. + +## Purpose + +Assets can include: +- Configuration files (JSON, YAML) +- Data files +- Templates +- Schemas +- Test fixtures + +## Guidelines + +- Keep assets small and focused +- Document asset purpose and format +- Use standard file formats +- Include schema validation where applicable + +## Common Asset Types + +- **config.json** - Configuration templates +- **schema.json** - JSON schemas +- **template.yaml** - YAML templates +- **test-data.json** - Test fixtures diff --git a/skills/marketplace-manager/references/README.md b/skills/marketplace-manager/references/README.md new file mode 100644 index 0000000..bf97184 --- /dev/null +++ b/skills/marketplace-manager/references/README.md @@ -0,0 +1,26 @@ +# Skill References + +This directory contains reference materials that enhance this skill's capabilities. + +## Purpose + +References can include: +- Code examples +- Style guides +- Best practices documentation +- Template files +- Configuration examples + +## Guidelines + +- Keep references concise and actionable +- Use markdown for documentation +- Include clear examples +- Link to external resources when appropriate + +## Types of References + +- **examples.md** - Usage examples +- **style-guide.md** - Coding standards +- **templates/** - Reusable templates +- **patterns.md** - Design patterns diff --git a/skills/marketplace-manager/scripts/README.md b/skills/marketplace-manager/scripts/README.md new file mode 100644 index 0000000..9f9c7ad --- /dev/null +++ b/skills/marketplace-manager/scripts/README.md @@ -0,0 +1,24 @@ +# Skill Scripts + +This directory contains optional helper scripts that support this skill's functionality. + +## Purpose + +Scripts here can be: +- Referenced by the skill for automation +- Used as examples for users +- Executed during skill activation + +## Guidelines + +- All scripts should be well-documented +- Include usage examples in comments +- Make scripts executable (`chmod +x`) +- Use `#!/bin/bash` or `#!/usr/bin/env python3` shebangs + +## Adding Scripts + +1. Create script file (e.g., `analyze.sh`, `process.py`) +2. Add documentation header +3. Make executable: `chmod +x script-name.sh` +4. Test thoroughly before committing diff --git a/skills/plugin-auditor/SKILL.md b/skills/plugin-auditor/SKILL.md new file mode 100644 index 0000000..fbb9097 --- /dev/null +++ b/skills/plugin-auditor/SKILL.md @@ -0,0 +1,342 @@ +--- +name: plugin-auditor +description: | + Automatically audits Claude Code plugins for security vulnerabilities, best practices, CLAUDE.md compliance, and quality standards when user mentions audit plugin, security review, or best practices check. Specific to claude-code-plugins repository standards. +allowed-tools: Read, Grep, Bash +version: 1.0.0 +--- + +# Plugin Auditor + +## Purpose +Automatically audits Claude Code plugins for security vulnerabilities, best practice violations, CLAUDE.md compliance, and quality standards - optimized for claude-code-plugins repository requirements. + +## Trigger Keywords +- "audit plugin" +- "security review" or "security audit" +- "best practices check" +- "plugin quality" +- "compliance check" +- "plugin security" + +## Audit Categories + +### 1. Security Audit + +**Critical Checks:** +- ❌ No hardcoded secrets (passwords, API keys, tokens) +- ❌ No AWS keys (AKIA...) +- ❌ No private keys (BEGIN PRIVATE KEY) +- ❌ No dangerous commands (rm -rf /, eval(), exec()) +- ❌ No command injection vectors +- ❌ No suspicious URLs (IP addresses, non-HTTPS) +- ❌ No obfuscated code (base64 decode, hex encoding) + +**Security Patterns:** +```bash +# Check for hardcoded secrets +grep -r "password\s*=\s*['\"]" --exclude-dir=node_modules +grep -r "api_key\s*=\s*['\"]" --exclude-dir=node_modules +grep -r "secret\s*=\s*['\"]" --exclude-dir=node_modules + +# Check for AWS keys +grep -r "AKIA[0-9A-Z]{16}" --exclude=README.md + +# Check for private keys +grep -r "BEGIN.*PRIVATE KEY" --exclude=README.md + +# Check for dangerous patterns +grep -r "rm -rf /" | grep -v "/var/" | grep -v "/tmp/" +grep -r "eval\s*\(" --exclude=README.md +``` + +### 2. Best Practices Audit + +**Plugin Structure:** +- ✅ Proper directory hierarchy +- ✅ Required files present +- ✅ Semantic versioning (x.y.z) +- ✅ Clear, concise descriptions +- ✅ Proper LICENSE file (MIT/Apache-2.0) +- ✅ Comprehensive README +- ✅ At least 5 keywords + +**Code Quality:** +- ✅ No TODO/FIXME without issue links +- ✅ No console.log() in production code +- ✅ No hardcoded paths (/home/, /Users/) +- ✅ Uses `${CLAUDE_PLUGIN_ROOT}` in hooks +- ✅ Scripts have proper shebangs +- ✅ All scripts are executable + +**Documentation:** +- ✅ README has installation section +- ✅ README has usage examples +- ✅ README has clear description +- ✅ Commands have proper frontmatter +- ✅ Agents have model specified +- ✅ Skills have trigger keywords + +### 3. CLAUDE.md Compliance + +**Repository Standards:** +- ✅ Follows plugin structure from CLAUDE.md +- ✅ Uses correct marketplace slug +- ✅ Proper category assignment +- ✅ Valid plugin.json schema +- ✅ Marketplace catalog entry exists +- ✅ Version consistency + +**Skills Compliance (if applicable):** +- ✅ SKILL.md has proper frontmatter +- ✅ Description includes trigger keywords +- ✅ allowed-tools specified (if restricted) +- ✅ Clear purpose and instructions +- ✅ Examples provided + +### 4. Marketplace Compliance + +**Catalog Requirements:** +- ✅ Plugin listed in marketplace.extended.json +- ✅ Source path matches actual location +- ✅ Version matches plugin.json +- ✅ Category is valid +- ✅ No duplicate plugin names +- ✅ Author information complete + +### 5. Git Hygiene + +**Repository Practices:** +- ✅ No large binary files +- ✅ No node_modules/ committed +- ✅ No .env files +- ✅ Proper .gitignore +- ✅ No merge conflicts +- ✅ Clean commit history + +### 6. MCP Plugin Audit (if applicable) + +**MCP-Specific Checks:** +- ✅ Valid package.json with @modelcontextprotocol/sdk +- ✅ TypeScript configured correctly +- ✅ dist/ in .gitignore +- ✅ Proper mcp/*.json configuration +- ✅ Build scripts present +- ✅ No dependency vulnerabilities + +### 7. Performance Audit + +**Efficiency Checks:** +- ✅ No unnecessary file reads +- ✅ Efficient glob patterns +- ✅ No recursive loops +- ✅ Reasonable timeout values +- ✅ No memory leaks (event listeners) + +### 8. Accessibility & UX + +**User Experience:** +- ✅ Clear error messages +- ✅ Helpful command descriptions +- ✅ Proper usage examples +- ✅ Good README formatting +- ✅ Working demo commands + +## Audit Process + +When activated, I will: + +1. **Security Scan** + ```bash + # Run security checks + grep -r "password\|secret\|api_key" plugins/plugin-name/ + grep -r "AKIA[0-9A-Z]{16}" plugins/plugin-name/ + grep -r "BEGIN.*PRIVATE KEY" plugins/plugin-name/ + grep -r "rm -rf /" plugins/plugin-name/ + grep -r "eval\(" plugins/plugin-name/ + ``` + +2. **Structure Validation** + ```bash + # Check required files + test -f .claude-plugin/plugin.json + test -f README.md + test -f LICENSE + + # Check component directories + ls -d commands/ agents/ skills/ hooks/ mcp/ 2>/dev/null + ``` + +3. **Best Practices Check** + ```bash + # Check for TODO/FIXME + grep -r "TODO\|FIXME" --exclude=README.md + + # Check for console.log + grep -r "console\.log" --exclude=README.md + + # Check script permissions + find . -name "*.sh" ! -perm -u+x + ``` + +4. **Compliance Verification** + ```bash + # Check marketplace entry + jq '.plugins[] | select(.name == "plugin-name")' .claude-plugin/marketplace.extended.json + + # Verify version consistency + plugin_version=$(jq -r '.version' .claude-plugin/plugin.json) + market_version=$(jq -r '.plugins[] | select(.name == "plugin-name") | .version' .claude-plugin/marketplace.extended.json) + ``` + +5. **Generate Audit Report** + +## Audit Report Format + +``` +🔍 PLUGIN AUDIT REPORT +Plugin: plugin-name +Version: 1.0.0 +Category: security +Audit Date: 2025-10-16 + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🔒 SECURITY AUDIT +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +✅ PASSED (7/7) +- No hardcoded secrets +- No AWS keys +- No private keys +- No dangerous commands +- No command injection vectors +- HTTPS URLs only +- No obfuscated code + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📋 BEST PRACTICES +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +✅ PASSED (10/12) +- Proper directory structure +- Required files present +- Semantic versioning +- Clear descriptions +- Comprehensive README + +⚠️ WARNINGS (2) +- 3 scripts missing execute permission + Fix: chmod +x scripts/*.sh + +- 2 TODO items without issue links + Location: commands/scan.md:45, agents/analyzer.md:67 + Recommendation: Create GitHub issues or remove TODOs + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +✅ CLAUDE.MD COMPLIANCE +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +✅ PASSED (6/6) +- Follows plugin structure +- Uses correct marketplace slug +- Proper category assignment +- Valid plugin.json schema +- Marketplace entry exists +- Version consistency + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📊 QUALITY SCORE +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Security: 10/10 ✅ +Best Practices: 8/10 ⚠️ +Compliance: 10/10 ✅ +Documentation: 10/10 ✅ + +OVERALL SCORE: 9.5/10 (EXCELLENT) + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +🎯 RECOMMENDATIONS +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Priority: MEDIUM +1. Fix script permissions (2 min) +2. Resolve TODO items (10 min) + +Optional Improvements: +- Add more usage examples in README +- Include troubleshooting section +- Add GIF/video demo + +✅ AUDIT COMPLETE +Plugin is production-ready with minor improvements needed. +``` + +## Severity Levels + +**Critical (🔴):** +- Security vulnerabilities +- Hardcoded secrets +- Dangerous commands +- Missing required files + +**High (🟠):** +- Best practice violations +- Missing documentation +- Broken functionality +- Schema violations + +**Medium (🟡):** +- Code quality issues +- Missing optional features +- Performance concerns +- UX improvements + +**Low (🟢):** +- Style inconsistencies +- Minor documentation gaps +- Nice-to-have features + +## Auto-Fix Capabilities + +I can automatically fix: +- ✅ Script permissions +- ✅ JSON formatting +- ✅ Markdown formatting +- ✅ Version sync issues + +## Repository-Specific Checks + +**For claude-code-plugins repo:** +- Validates against CLAUDE.md standards +- Checks marketplace integration +- Verifies category structure +- Ensures quality for featured plugins +- Checks contributor guidelines compliance + +## Examples + +**User says:** "Audit the security-scanner plugin" + +**I automatically:** +1. Run full security scan +2. Check best practices +3. Verify CLAUDE.md compliance +4. Generate comprehensive report +5. Provide recommendations + +**User says:** "Is this plugin safe to publish?" + +**I automatically:** +1. Security audit (critical) +2. Marketplace compliance +3. Quality score calculation +4. Publish readiness assessment + +**User says:** "Quality review before featured status" + +**I automatically:** +1. Full audit (all categories) +2. Higher quality thresholds +3. Featured plugin requirements +4. Recommendation: approve/reject diff --git a/skills/plugin-auditor/assets/README.md b/skills/plugin-auditor/assets/README.md new file mode 100644 index 0000000..148d1c3 --- /dev/null +++ b/skills/plugin-auditor/assets/README.md @@ -0,0 +1,26 @@ +# Skill Assets + +This directory contains static assets used by this skill. + +## Purpose + +Assets can include: +- Configuration files (JSON, YAML) +- Data files +- Templates +- Schemas +- Test fixtures + +## Guidelines + +- Keep assets small and focused +- Document asset purpose and format +- Use standard file formats +- Include schema validation where applicable + +## Common Asset Types + +- **config.json** - Configuration templates +- **schema.json** - JSON schemas +- **template.yaml** - YAML templates +- **test-data.json** - Test fixtures diff --git a/skills/plugin-auditor/references/README.md b/skills/plugin-auditor/references/README.md new file mode 100644 index 0000000..bf97184 --- /dev/null +++ b/skills/plugin-auditor/references/README.md @@ -0,0 +1,26 @@ +# Skill References + +This directory contains reference materials that enhance this skill's capabilities. + +## Purpose + +References can include: +- Code examples +- Style guides +- Best practices documentation +- Template files +- Configuration examples + +## Guidelines + +- Keep references concise and actionable +- Use markdown for documentation +- Include clear examples +- Link to external resources when appropriate + +## Types of References + +- **examples.md** - Usage examples +- **style-guide.md** - Coding standards +- **templates/** - Reusable templates +- **patterns.md** - Design patterns diff --git a/skills/plugin-auditor/scripts/README.md b/skills/plugin-auditor/scripts/README.md new file mode 100644 index 0000000..9f9c7ad --- /dev/null +++ b/skills/plugin-auditor/scripts/README.md @@ -0,0 +1,24 @@ +# Skill Scripts + +This directory contains optional helper scripts that support this skill's functionality. + +## Purpose + +Scripts here can be: +- Referenced by the skill for automation +- Used as examples for users +- Executed during skill activation + +## Guidelines + +- All scripts should be well-documented +- Include usage examples in comments +- Make scripts executable (`chmod +x`) +- Use `#!/bin/bash` or `#!/usr/bin/env python3` shebangs + +## Adding Scripts + +1. Create script file (e.g., `analyze.sh`, `process.py`) +2. Add documentation header +3. Make executable: `chmod +x script-name.sh` +4. Test thoroughly before committing diff --git a/skills/plugin-creator/SKILL.md b/skills/plugin-creator/SKILL.md new file mode 100644 index 0000000..f8deda5 --- /dev/null +++ b/skills/plugin-creator/SKILL.md @@ -0,0 +1,207 @@ +--- +name: plugin-creator +description: | + Automatically creates new Claude Code plugins with proper structure, validation, and marketplace integration when user mentions creating a plugin, new plugin, or plugin from template. Specific to claude-code-plugins repository workflow. +allowed-tools: Write, Read, Grep, Bash +version: 1.0.0 +--- + +# Plugin Creator + +## Purpose +Automatically scaffolds new Claude Code plugins with complete directory structure, required files, proper formatting, and marketplace catalog integration - specifically optimized for the claude-code-plugins repository. + +## Trigger Keywords +- "create plugin" or "new plugin" +- "plugin from template" +- "scaffold plugin" +- "generate plugin" +- "add new plugin to marketplace" + +## Plugin Creation Process + +When activated, I will: + +1. **Gather Requirements** + - Plugin name (kebab-case) + - Category (productivity, security, devops, etc.) + - Type (commands, agents, skills, MCP, or combination) + - Description and keywords + - Author information + +2. **Create Directory Structure** + ``` + plugins/[category]/[plugin-name]/ + ├── .claude-plugin/ + │ └── plugin.json + ├── README.md + ├── LICENSE + └── [commands|agents|skills|hooks|mcp]/ + ``` + +3. **Generate Required Files** + - **plugin.json** with proper schema (name, version, description, author) + - **README.md** with comprehensive documentation + - **LICENSE** (MIT by default) + - Component files based on type + +4. **Add to Marketplace Catalog** + - Update `.claude-plugin/marketplace.extended.json` + - Run `npm run sync-marketplace` automatically + - Validate catalog schema + +5. **Validate Everything** + - Run `./scripts/validate-all.sh` on new plugin + - Check JSON syntax with `jq` + - Verify frontmatter in markdown files + - Ensure scripts are executable + +## Plugin Types Supported + +### Commands Plugin +- Creates `commands/` directory +- Generates example command with proper frontmatter +- Includes `/demo-command` example + +### Agents Plugin +- Creates `agents/` directory +- Generates example agent with capabilities +- Includes model specification + +### Skills Plugin +- Creates `skills/skill-name/` directory +- Generates SKILL.md with proper format +- Includes trigger keywords and allowed-tools + +### MCP Plugin +- Creates `src/`, `dist/`, `mcp/` directories +- Generates TypeScript boilerplate +- Includes package.json with MCP SDK +- Adds to pnpm workspace + +### Full Plugin +- Combines all types +- Creates complete example structure +- Ready for customization + +## File Templates + +### plugin.json Template +```json +{ + "name": "plugin-name", + "version": "1.0.0", + "description": "Clear description", + "author": { + "name": "Author Name", + "email": "[email protected]" + }, + "repository": "https://github.com/jeremylongshore/claude-code-plugins", + "license": "MIT", + "keywords": ["keyword1", "keyword2"] +} +``` + +### Command Template +```markdown +--- +name: command-name +description: What this command does +model: sonnet +--- + +# Command Title + +Instructions for Claude... +``` + +### Skill Template +```markdown +--- +name: Skill Name +description: What it does AND when to use it +allowed-tools: Read, Write, Grep +--- + +# Skill Name + +## Purpose +[What this skill does] + +## Trigger Keywords +- keyword1 +- keyword2 + +## Instructions +[Step-by-step for Claude] +``` + +## Marketplace Integration + +I automatically: +1. Add plugin entry to `marketplace.extended.json` +2. Run `npm run sync-marketplace` to update CLI catalog +3. Validate both catalogs with `jq` +4. Check for duplicate names +5. Verify source paths exist + +## Validation Steps + +After creation: +- ✅ All required files present +- ✅ Valid JSON (plugin.json, catalogs) +- ✅ Proper frontmatter in markdown +- ✅ Scripts executable (`chmod +x`) +- ✅ No duplicate plugin names +- ✅ Category is valid +- ✅ Keywords present + +## Repository-Specific Features + +**For claude-code-plugins repo:** +- Follows exact directory structure +- Uses correct marketplace slug (`claude-code-plugins-plus`) +- Includes proper LICENSE file +- Adds to correct category folder +- Validates against existing plugins +- Updates version in marketplace + +## Output + +I provide: +``` +✅ Created plugin: plugin-name +📁 Location: plugins/category/plugin-name/ +📝 Files created: 8 +🔍 Validation: PASSED +📦 Marketplace: UPDATED +✨ Ready to commit! + +Next steps: +1. Review files in plugins/category/plugin-name/ +2. Customize README.md and component files +3. Run: git add plugins/category/plugin-name/ +4. Run: git commit -m "feat: Add plugin-name plugin" +``` + +## Examples + +**User says:** "Create a new security plugin called 'owasp-scanner' with commands" + +**I automatically:** +1. Create directory: `plugins/security/owasp-scanner/` +2. Generate plugin.json, README, LICENSE +3. Create `commands/` with example +4. Add to marketplace.extended.json +5. Sync marketplace.json +6. Validate all files +7. Report success + +**User says:** "Scaffold a Skills plugin for code review" + +**I automatically:** +1. Create directory with `skills/` subdirectories +2. Generate SKILL.md templates +3. Add trigger keywords for code review +4. Add to marketplace +5. Validate and report diff --git a/skills/plugin-creator/assets/README.md b/skills/plugin-creator/assets/README.md new file mode 100644 index 0000000..148d1c3 --- /dev/null +++ b/skills/plugin-creator/assets/README.md @@ -0,0 +1,26 @@ +# Skill Assets + +This directory contains static assets used by this skill. + +## Purpose + +Assets can include: +- Configuration files (JSON, YAML) +- Data files +- Templates +- Schemas +- Test fixtures + +## Guidelines + +- Keep assets small and focused +- Document asset purpose and format +- Use standard file formats +- Include schema validation where applicable + +## Common Asset Types + +- **config.json** - Configuration templates +- **schema.json** - JSON schemas +- **template.yaml** - YAML templates +- **test-data.json** - Test fixtures diff --git a/skills/plugin-creator/references/README.md b/skills/plugin-creator/references/README.md new file mode 100644 index 0000000..bf97184 --- /dev/null +++ b/skills/plugin-creator/references/README.md @@ -0,0 +1,26 @@ +# Skill References + +This directory contains reference materials that enhance this skill's capabilities. + +## Purpose + +References can include: +- Code examples +- Style guides +- Best practices documentation +- Template files +- Configuration examples + +## Guidelines + +- Keep references concise and actionable +- Use markdown for documentation +- Include clear examples +- Link to external resources when appropriate + +## Types of References + +- **examples.md** - Usage examples +- **style-guide.md** - Coding standards +- **templates/** - Reusable templates +- **patterns.md** - Design patterns diff --git a/skills/plugin-creator/scripts/README.md b/skills/plugin-creator/scripts/README.md new file mode 100644 index 0000000..9f9c7ad --- /dev/null +++ b/skills/plugin-creator/scripts/README.md @@ -0,0 +1,24 @@ +# Skill Scripts + +This directory contains optional helper scripts that support this skill's functionality. + +## Purpose + +Scripts here can be: +- Referenced by the skill for automation +- Used as examples for users +- Executed during skill activation + +## Guidelines + +- All scripts should be well-documented +- Include usage examples in comments +- Make scripts executable (`chmod +x`) +- Use `#!/bin/bash` or `#!/usr/bin/env python3` shebangs + +## Adding Scripts + +1. Create script file (e.g., `analyze.sh`, `process.py`) +2. Add documentation header +3. Make executable: `chmod +x script-name.sh` +4. Test thoroughly before committing diff --git a/skills/plugin-validator/SKILL.md b/skills/plugin-validator/SKILL.md new file mode 100644 index 0000000..b722636 --- /dev/null +++ b/skills/plugin-validator/SKILL.md @@ -0,0 +1,249 @@ +--- +name: plugin-validator +description: | + Automatically validates Claude Code plugin structure, schemas, and compliance when user mentions validate plugin, check plugin, or plugin errors. Runs comprehensive validation specific to claude-code-plugins repository standards. +allowed-tools: Read, Grep, Bash +version: 1.0.0 +--- + +# Plugin Validator + +## Purpose +Automatically validates Claude Code plugins against repository standards, checking structure, JSON schemas, frontmatter, permissions, security, and marketplace compliance - optimized for claude-code-plugins repository. + +## Trigger Keywords +- "validate plugin" +- "check plugin" +- "plugin validation" +- "plugin errors" +- "lint plugin" +- "verify plugin" + +## Validation Checks + +### 1. Required Files +- ✅ `.claude-plugin/plugin.json` exists +- ✅ `README.md` exists and not empty +- ✅ `LICENSE` file exists +- ✅ At least one component directory (commands/, agents/, skills/, hooks/, mcp/) + +### 2. Plugin.json Schema +```bash +# Required fields: +- name (kebab-case, lowercase, hyphens only) +- version (semantic versioning x.y.z) +- description (clear, concise) +- author.name +- author.email +- license (MIT, Apache-2.0, etc.) +- keywords (array, at least 2) + +# Optional but recommended: +- repository (GitHub URL) +- homepage (docs URL) +``` + +### 3. Frontmatter Validation +**For Commands (commands/*.md):** +```yaml +--- +name: command-name +description: Brief description +model: sonnet|opus|haiku +--- +``` + +**For Agents (agents/*.md):** +```yaml +--- +name: agent-name +description: Agent purpose +model: sonnet|opus|haiku +--- +``` + +**For Skills (skills/*/SKILL.md):** +```yaml +--- +name: Skill Name +description: What it does AND when to use it +allowed-tools: Tool1, Tool2, Tool3 # optional +--- +``` + +### 4. Directory Structure +Validates proper hierarchy: +``` +plugin-name/ +├── .claude-plugin/ # Required +│ └── plugin.json # Required +├── README.md # Required +├── LICENSE # Required +├── commands/ # Optional +│ └── *.md +├── agents/ # Optional +│ └── *.md +├── skills/ # Optional +│ └── skill-name/ +│ └── SKILL.md +├── hooks/ # Optional +│ └── hooks.json +└── mcp/ # Optional + └── *.json +``` + +### 5. Script Permissions +```bash +# All .sh files must be executable +find . -name "*.sh" ! -perm -u+x +# Should return empty +``` + +### 6. JSON Validation +```bash +# All JSON must be valid +jq empty plugin.json +jq empty marketplace.extended.json +jq empty hooks/hooks.json +``` + +### 7. Security Scans +- ❌ No hardcoded secrets (API keys, tokens, passwords) +- ❌ No AWS keys (AKIA...) +- ❌ No private keys (BEGIN PRIVATE KEY) +- ❌ No dangerous commands (rm -rf /, eval()) +- ❌ No suspicious URLs (non-HTTPS, IP addresses) + +### 8. Marketplace Compliance +- ✅ Plugin listed in marketplace.extended.json +- ✅ Source path matches actual location +- ✅ Version matches between plugin.json and catalog +- ✅ Category is valid +- ✅ No duplicate plugin names + +### 9. README Requirements +- ✅ Has installation instructions +- ✅ Has usage examples +- ✅ Has description section +- ✅ Proper markdown formatting +- ✅ No broken links + +### 10. Path Variables +For hooks: +- ✅ Uses `${CLAUDE_PLUGIN_ROOT}` not absolute paths +- ✅ No hardcoded /home/ or /Users/ paths + +## Validation Process + +When activated, I will: + +1. **Identify Plugin** + - Detect plugin directory from context + - Or ask user which plugin to validate + +2. **Run Comprehensive Checks** + ```bash + # Structure validation + ./scripts/validate-all.sh plugins/category/plugin-name/ + + # JSON validation + jq empty .claude-plugin/plugin.json + + # Frontmatter check + python3 scripts/check-frontmatter.py + + # Permission check + find . -name "*.sh" ! -perm -u+x + + # Security scan + grep -r "password\|secret\|api_key" | grep -v placeholder + ``` + +3. **Generate Report** + - List all issues by severity (critical, high, medium, low) + - Provide fix commands for each issue + - Summary: PASSED or FAILED + +## Validation Report Format + +``` +🔍 PLUGIN VALIDATION REPORT +Plugin: plugin-name +Location: plugins/category/plugin-name/ + +✅ PASSED CHECKS (8/10) +- Required files present +- Valid plugin.json schema +- Proper frontmatter format +- Directory structure correct +- No security issues +- Marketplace compliance +- README complete +- JSON valid + +❌ FAILED CHECKS (2/10) +- Script permissions: 3 .sh files not executable + Fix: chmod +x scripts/*.sh + +- Marketplace version mismatch + plugin.json: v1.2.0 + marketplace.extended.json: v1.1.0 + Fix: Update marketplace.extended.json to v1.2.0 + +⚠️ WARNINGS (1) +- README missing usage examples + Recommendation: Add ## Usage section with examples + +OVERALL: FAILED (2 critical issues) +Fix issues above before committing. +``` + +## Auto-Fix Capabilities + +I can automatically fix: +- ✅ Script permissions (`chmod +x`) +- ✅ JSON formatting (`jq` reformat) +- ✅ Marketplace version sync +- ✅ Missing LICENSE (copy from root) + +## Repository-Specific Checks + +**For claude-code-plugins repo:** +- Validates against `.claude-plugin/marketplace.extended.json` +- Checks category folder matches catalog entry +- Ensures marketplace slug is `claude-code-plugins-plus` +- Validates against other plugins (no duplicates) +- Checks compliance with CLAUDE.md standards + +## Integration with CI + +Validation results match GitHub Actions: +- Same checks as `.github/workflows/validate-plugins.yml` +- Compatible with CI error format +- Can be run locally before pushing + +## Examples + +**User says:** "Validate the skills-powerkit plugin" + +**I automatically:** +1. Run all validation checks +2. Identify 2 issues (permissions, version mismatch) +3. Provide fix commands +4. Report overall status: FAILED + +**User says:** "Check if my plugin is ready to commit" + +**I automatically:** +1. Detect plugin from context +2. Run comprehensive validation +3. Check marketplace compliance +4. Report: PASSED or list issues + +**User says:** "Why is my plugin failing CI?" + +**I automatically:** +1. Run same checks as CI +2. Identify exact failure +3. Provide fix command +4. Validate fix works diff --git a/skills/plugin-validator/assets/README.md b/skills/plugin-validator/assets/README.md new file mode 100644 index 0000000..148d1c3 --- /dev/null +++ b/skills/plugin-validator/assets/README.md @@ -0,0 +1,26 @@ +# Skill Assets + +This directory contains static assets used by this skill. + +## Purpose + +Assets can include: +- Configuration files (JSON, YAML) +- Data files +- Templates +- Schemas +- Test fixtures + +## Guidelines + +- Keep assets small and focused +- Document asset purpose and format +- Use standard file formats +- Include schema validation where applicable + +## Common Asset Types + +- **config.json** - Configuration templates +- **schema.json** - JSON schemas +- **template.yaml** - YAML templates +- **test-data.json** - Test fixtures diff --git a/skills/plugin-validator/references/README.md b/skills/plugin-validator/references/README.md new file mode 100644 index 0000000..bf97184 --- /dev/null +++ b/skills/plugin-validator/references/README.md @@ -0,0 +1,26 @@ +# Skill References + +This directory contains reference materials that enhance this skill's capabilities. + +## Purpose + +References can include: +- Code examples +- Style guides +- Best practices documentation +- Template files +- Configuration examples + +## Guidelines + +- Keep references concise and actionable +- Use markdown for documentation +- Include clear examples +- Link to external resources when appropriate + +## Types of References + +- **examples.md** - Usage examples +- **style-guide.md** - Coding standards +- **templates/** - Reusable templates +- **patterns.md** - Design patterns diff --git a/skills/plugin-validator/scripts/README.md b/skills/plugin-validator/scripts/README.md new file mode 100644 index 0000000..9f9c7ad --- /dev/null +++ b/skills/plugin-validator/scripts/README.md @@ -0,0 +1,24 @@ +# Skill Scripts + +This directory contains optional helper scripts that support this skill's functionality. + +## Purpose + +Scripts here can be: +- Referenced by the skill for automation +- Used as examples for users +- Executed during skill activation + +## Guidelines + +- All scripts should be well-documented +- Include usage examples in comments +- Make scripts executable (`chmod +x`) +- Use `#!/bin/bash` or `#!/usr/bin/env python3` shebangs + +## Adding Scripts + +1. Create script file (e.g., `analyze.sh`, `process.py`) +2. Add documentation header +3. Make executable: `chmod +x script-name.sh` +4. Test thoroughly before committing diff --git a/skills/skill-adapter/assets/README.md b/skills/skill-adapter/assets/README.md new file mode 100644 index 0000000..3943e5e --- /dev/null +++ b/skills/skill-adapter/assets/README.md @@ -0,0 +1,8 @@ +# Assets + +Bundled resources for skills-powerkit skill + +- [ ] plugin_template/: Template files for creating new plugins. +- [ ] validation_rules.json: JSON file containing validation rules for plugins. +- [ ] example_plugin/: Example plugin with all the required files and directory structure. +- [ ] marketplace_schema.json: JSON schema for the marketplace catalog. diff --git a/skills/skill-adapter/assets/config-template.json b/skills/skill-adapter/assets/config-template.json new file mode 100644 index 0000000..16f1712 --- /dev/null +++ b/skills/skill-adapter/assets/config-template.json @@ -0,0 +1,32 @@ +{ + "skill": { + "name": "skill-name", + "version": "1.0.0", + "enabled": true, + "settings": { + "verbose": false, + "autoActivate": true, + "toolRestrictions": true + } + }, + "triggers": { + "keywords": [ + "example-trigger-1", + "example-trigger-2" + ], + "patterns": [] + }, + "tools": { + "allowed": [ + "Read", + "Grep", + "Bash" + ], + "restricted": [] + }, + "metadata": { + "author": "Plugin Author", + "category": "general", + "tags": [] + } +} diff --git a/skills/skill-adapter/assets/marketplace_schema.json b/skills/skill-adapter/assets/marketplace_schema.json new file mode 100644 index 0000000..c2dd629 --- /dev/null +++ b/skills/skill-adapter/assets/marketplace_schema.json @@ -0,0 +1,153 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Marketplace Plugin Schema", + "description": "JSON schema for plugins in the claude-code-plugins marketplace.", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the plugin (e.g., UUID).", + "example": "skills-powerkit-12345", + "_comment": "Consider using a UUID generator for this." + }, + "name": { + "type": "string", + "description": "Human-readable name of the plugin.", + "example": "Skills Powerkit" + }, + "version": { + "type": "string", + "description": "Semantic version of the plugin.", + "example": "1.0.0" + }, + "description": { + "type": "string", + "description": "A brief description of the plugin's functionality.", + "example": "The ultimate plugin management toolkit for the claude-code-plugins marketplace." + }, + "author": { + "type": "string", + "description": "Name of the plugin author or organization.", + "example": "Awesome Plugin Devs Inc." + }, + "author_url": { + "type": "string", + "format": "url", + "description": "URL to the author's website or profile.", + "example": "https://awesomeplugindevs.com" + }, + "repository_url": { + "type": "string", + "format": "url", + "description": "URL to the plugin's source code repository.", + "example": "https://github.com/awesomeplugindevs/skills-powerkit" + }, + "license": { + "type": "string", + "description": "License under which the plugin is distributed.", + "example": "MIT" + }, + "tags": { + "type": "array", + "description": "Keywords or tags to help users find the plugin.", + "items": { + "type": "string" + }, + "example": ["plugin management", "development", "validation", "marketplace", "meta-plugin"] + }, + "category": { + "type": "string", + "description": "Category the plugin belongs to.", + "example": "Development Tools" + }, + "skills": { + "type": "array", + "description": "List of skills provided by the plugin.", + "items": { + "type": "string" + }, + "example": [ + "create_plugin", + "validate_plugin", + "audit_plugin", + "manage_plugin", + "update_plugin" + ] + }, + "icon_url": { + "type": "string", + "format": "url", + "description": "URL to the plugin's icon.", + "example": "https://example.com/icons/skills-powerkit.png" + }, + "readme_url": { + "type": "string", + "format": "url", + "description": "URL to the plugin's README file.", + "example": "https://raw.githubusercontent.com/awesomeplugindevs/skills-powerkit/main/README.md" + }, + "plugin_url": { + "type": "string", + "format": "url", + "description": "URL to the main plugin manifest or entry point.", + "example": "https://raw.githubusercontent.com/awesomeplugindevs/skills-powerkit/main/plugin.yaml" + }, + "dependencies": { + "type": "array", + "description": "List of other plugins or libraries this plugin depends on.", + "items": { + "type": "string" + }, + "example": [] + }, + "type": { + "type": "string", + "description": "Type of plugin.", + "example": "meta-plugin" + }, + "pricing": { + "type": "object", + "description": "Pricing information for the plugin (if applicable).", + "properties": { + "type": { + "type": "string", + "enum": ["free", "paid", "subscription"], + "description": "Type of pricing model." + }, + "price": { + "type": "number", + "description": "Price of the plugin (if applicable).", + "example": 9.99 + }, + "currency": { + "type": "string", + "description": "Currency of the price (if applicable).", + "example": "USD" + }, + "interval": { + "type": "string", + "description": "Billing interval (if applicable).", + "enum": ["monthly", "yearly"], + "example": "monthly" + } + }, + "required": ["type"] + } + }, + "required": [ + "id", + "name", + "version", + "description", + "author", + "author_url", + "repository_url", + "license", + "tags", + "category", + "skills", + "icon_url", + "readme_url", + "plugin_url" + ] +} \ No newline at end of file diff --git a/skills/skill-adapter/assets/skill-schema.json b/skills/skill-adapter/assets/skill-schema.json new file mode 100644 index 0000000..8dc154c --- /dev/null +++ b/skills/skill-adapter/assets/skill-schema.json @@ -0,0 +1,28 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Claude Skill Configuration", + "type": "object", + "required": ["name", "description"], + "properties": { + "name": { + "type": "string", + "pattern": "^[a-z0-9-]+$", + "maxLength": 64, + "description": "Skill identifier (lowercase, hyphens only)" + }, + "description": { + "type": "string", + "maxLength": 1024, + "description": "What the skill does and when to use it" + }, + "allowed-tools": { + "type": "string", + "description": "Comma-separated list of allowed tools" + }, + "version": { + "type": "string", + "pattern": "^\\d+\\.\\d+\\.\\d+$", + "description": "Semantic version (x.y.z)" + } + } +} diff --git a/skills/skill-adapter/assets/test-data.json b/skills/skill-adapter/assets/test-data.json new file mode 100644 index 0000000..f0cd871 --- /dev/null +++ b/skills/skill-adapter/assets/test-data.json @@ -0,0 +1,27 @@ +{ + "testCases": [ + { + "name": "Basic activation test", + "input": "trigger phrase example", + "expected": { + "activated": true, + "toolsUsed": ["Read", "Grep"], + "success": true + } + }, + { + "name": "Complex workflow test", + "input": "multi-step trigger example", + "expected": { + "activated": true, + "steps": 3, + "toolsUsed": ["Read", "Write", "Bash"], + "success": true + } + } + ], + "fixtures": { + "sampleInput": "example data", + "expectedOutput": "processed result" + } +} diff --git a/skills/skill-adapter/assets/validation_rules.json b/skills/skill-adapter/assets/validation_rules.json new file mode 100644 index 0000000..79b3222 --- /dev/null +++ b/skills/skill-adapter/assets/validation_rules.json @@ -0,0 +1,113 @@ +{ + "_comment": "Validation rules for plugins in the claude-code-plugins marketplace. These rules are used by the 'validate_plugin' skill.", + "plugin_name": { + "type": "string", + "required": true, + "min_length": 3, + "max_length": 64, + "pattern": "^[a-z0-9-]+$", + "_comment": "Plugin name must be lowercase, alphanumeric, and can contain hyphens. No spaces allowed.", + "error_message": "Plugin name must be lowercase, alphanumeric, and contain only hyphens. Minimum 3 characters, maximum 64." + }, + "description": { + "type": "string", + "required": true, + "min_length": 20, + "max_length": 500, + "_comment": "A concise description of the plugin's functionality.", + "error_message": "Description must be between 20 and 500 characters." + }, + "version": { + "type": "string", + "required": true, + "pattern": "^\\d+\\.\\d+\\.\\d+$", + "_comment": "Semantic versioning (e.g., 1.0.0).", + "error_message": "Version must follow semantic versioning (e.g., 1.0.0)." + }, + "author": { + "type": "string", + "required": true, + "min_length": 3, + "max_length": 64, + "_comment": "Author's name or organization.", + "error_message": "Author must be between 3 and 64 characters." + }, + "skills": { + "type": "array", + "min_items": 1, + "_comment": "List of skills provided by the plugin.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "required": true, + "min_length": 3, + "max_length": 64, + "pattern": "^[a-zA-Z0-9_]+$", + "_comment": "Skill name must be alphanumeric and can contain underscores.", + "error_message": "Skill name must be alphanumeric and contain only underscores. Minimum 3 characters, maximum 64." + }, + "description": { + "type": "string", + "required": true, + "min_length": 20, + "max_length": 500, + "_comment": "A concise description of the skill's functionality.", + "error_message": "Skill description must be between 20 and 500 characters." + }, + "parameters": { + "type": "object", + "_comment": "Parameters accepted by the skill. Should correspond to the function signature.", + "additionalProperties": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["string", "number", "boolean", "array", "object"], + "required": true, + "_comment": "Data type of the parameter." + }, + "description": { + "type": "string", + "required": true, + "min_length": 10, + "max_length": 200, + "_comment": "Description of the parameter's purpose.", + "error_message": "Parameter description must be between 10 and 200 characters." + }, + "required": { + "type": "boolean", + "default": false, + "_comment": "Whether the parameter is required." + } + }, + "required": ["type", "description"] + } + } + }, + "required": ["name", "description"] + } + }, + "api_url": { + "type": "string", + "required": true, + "format": "uri", + "_comment": "Base URL for the plugin's API.", + "error_message": "API URL must be a valid URL." + }, + "license": { + "type": "string", + "required": true, + "enum": ["MIT", "Apache-2.0", "GPL-3.0", "BSD-3-Clause", "Other"], + "_comment": "License under which the plugin is distributed.", + "error_message": "Invalid license type." + }, + "privacy_policy_url": { + "type": "string", + "required": false, + "format": "uri", + "_comment": "URL for the plugin's privacy policy. Required if the plugin collects user data.", + "error_message": "Privacy policy URL must be a valid URL." + } +} \ No newline at end of file diff --git a/skills/skill-adapter/references/README.md b/skills/skill-adapter/references/README.md new file mode 100644 index 0000000..ca0bda8 --- /dev/null +++ b/skills/skill-adapter/references/README.md @@ -0,0 +1,9 @@ +# References + +Bundled resources for skills-powerkit skill + +- [ ] plugin_creation_guide.md: Detailed guide on creating plugins, including directory structure, file formats, and best practices. +- [ ] plugin_validation_rules.md: Comprehensive list of validation rules and checks for plugins. +- [ ] marketplace_api_docs.md: API documentation for interacting with the marketplace. +- [ ] security_best_practices.md: Security best practices for plugin development. +- [ ] plugin_update_guide.md: Guide on updating plugins and ensuring compatibility. diff --git a/skills/skill-adapter/references/best-practices.md b/skills/skill-adapter/references/best-practices.md new file mode 100644 index 0000000..3505048 --- /dev/null +++ b/skills/skill-adapter/references/best-practices.md @@ -0,0 +1,69 @@ +# Skill Best Practices + +Guidelines for optimal skill usage and development. + +## For Users + +### Activation Best Practices + +1. **Use Clear Trigger Phrases** + - Match phrases from skill description + - Be specific about intent + - Provide necessary context + +2. **Provide Sufficient Context** + - Include relevant file paths + - Specify scope of analysis + - Mention any constraints + +3. **Understand Tool Permissions** + - Check allowed-tools in frontmatter + - Know what the skill can/cannot do + - Request appropriate actions + +### Workflow Optimization + +- Start with simple requests +- Build up to complex workflows +- Verify each step before proceeding +- Use skill consistently for related tasks + +## For Developers + +### Skill Development Guidelines + +1. **Clear Descriptions** + - Include explicit trigger phrases + - Document all capabilities + - Specify limitations + +2. **Proper Tool Permissions** + - Use minimal necessary tools + - Document security implications + - Test with restricted tools + +3. **Comprehensive Documentation** + - Provide usage examples + - Document common pitfalls + - Include troubleshooting guide + +### Maintenance + +- Keep version updated +- Test after tool updates +- Monitor user feedback +- Iterate on descriptions + +## Performance Tips + +- Scope skills to specific domains +- Avoid overlapping trigger phrases +- Keep descriptions under 1024 chars +- Test activation reliability + +## Security Considerations + +- Never include secrets in skill files +- Validate all inputs +- Use read-only tools when possible +- Document security requirements diff --git a/skills/skill-adapter/references/examples.md b/skills/skill-adapter/references/examples.md new file mode 100644 index 0000000..b1d8bd2 --- /dev/null +++ b/skills/skill-adapter/references/examples.md @@ -0,0 +1,70 @@ +# Skill Usage Examples + +This document provides practical examples of how to use this skill effectively. + +## Basic Usage + +### Example 1: Simple Activation + +**User Request:** +``` +[Describe trigger phrase here] +``` + +**Skill Response:** +1. Analyzes the request +2. Performs the required action +3. Returns results + +### Example 2: Complex Workflow + +**User Request:** +``` +[Describe complex scenario] +``` + +**Workflow:** +1. Step 1: Initial analysis +2. Step 2: Data processing +3. Step 3: Result generation +4. Step 4: Validation + +## Advanced Patterns + +### Pattern 1: Chaining Operations + +Combine this skill with other tools: +``` +Step 1: Use this skill for [purpose] +Step 2: Chain with [other tool] +Step 3: Finalize with [action] +``` + +### Pattern 2: Error Handling + +If issues occur: +- Check trigger phrase matches +- Verify context is available +- Review allowed-tools permissions + +## Tips & Best Practices + +- ✅ Be specific with trigger phrases +- ✅ Provide necessary context +- ✅ Check tool permissions match needs +- ❌ Avoid vague requests +- ❌ Don't mix unrelated tasks + +## Common Issues + +**Issue:** Skill doesn't activate +**Solution:** Use exact trigger phrases from description + +**Issue:** Unexpected results +**Solution:** Check input format and context + +## See Also + +- Main SKILL.md for full documentation +- scripts/ for automation helpers +- assets/ for configuration examples diff --git a/skills/skill-adapter/scripts/README.md b/skills/skill-adapter/scripts/README.md new file mode 100644 index 0000000..03f888c --- /dev/null +++ b/skills/skill-adapter/scripts/README.md @@ -0,0 +1,9 @@ +# Scripts + +Bundled resources for skills-powerkit skill + +- [ ] plugin_creator.py: Automates the creation of plugin files and directory structure. +- [ ] plugin_validator.py: Validates the plugin.json schema, required files, and markdown frontmatter. +- [ ] marketplace_manager.py: Manages the marketplace catalog and syncing process. +- [ ] plugin_auditor.py: Audits the plugin for security vulnerabilities and best practices. +- [ ] plugin_updater.py: Updates the plugin to the latest version and checks for compatibility. diff --git a/skills/skill-adapter/scripts/helper-template.sh b/skills/skill-adapter/scripts/helper-template.sh new file mode 100755 index 0000000..c4aae90 --- /dev/null +++ b/skills/skill-adapter/scripts/helper-template.sh @@ -0,0 +1,42 @@ +#!/bin/bash +# Helper script template for skill automation +# Customize this for your skill's specific needs + +set -e + +function show_usage() { + echo "Usage: $0 [options]" + echo "" + echo "Options:" + echo " -h, --help Show this help message" + echo " -v, --verbose Enable verbose output" + echo "" +} + +# Parse arguments +VERBOSE=false + +while [[ $# -gt 0 ]]; do + case $1 in + -h|--help) + show_usage + exit 0 + ;; + -v|--verbose) + VERBOSE=true + shift + ;; + *) + echo "Unknown option: $1" + show_usage + exit 1 + ;; + esac +done + +# Your skill logic here +if [ "$VERBOSE" = true ]; then + echo "Running skill automation..." +fi + +echo "✅ Complete" diff --git a/skills/skill-adapter/scripts/validation.sh b/skills/skill-adapter/scripts/validation.sh new file mode 100755 index 0000000..590af58 --- /dev/null +++ b/skills/skill-adapter/scripts/validation.sh @@ -0,0 +1,32 @@ +#!/bin/bash +# Skill validation helper +# Validates skill activation and functionality + +set -e + +echo "🔍 Validating skill..." + +# Check if SKILL.md exists +if [ ! -f "../SKILL.md" ]; then + echo "❌ Error: SKILL.md not found" + exit 1 +fi + +# Validate frontmatter +if ! grep -q "^---$" "../SKILL.md"; then + echo "❌ Error: No frontmatter found" + exit 1 +fi + +# Check required fields +if ! grep -q "^name:" "../SKILL.md"; then + echo "❌ Error: Missing 'name' field" + exit 1 +fi + +if ! grep -q "^description:" "../SKILL.md"; then + echo "❌ Error: Missing 'description' field" + exit 1 +fi + +echo "✅ Skill validation passed" diff --git a/skills/version-bumper/SKILL.md b/skills/version-bumper/SKILL.md new file mode 100644 index 0000000..93b8f50 --- /dev/null +++ b/skills/version-bumper/SKILL.md @@ -0,0 +1,340 @@ +--- +name: version-bumper +description: | + Automatically handles semantic version updates across plugin.json and marketplace catalog when user mentions version bump, update version, or release. Ensures version consistency in claude-code-plugins repository. +allowed-tools: Read, Write, Edit, Grep, Bash +version: 1.0.0 +--- + +# Version Bumper + +## Purpose +Automatically manages semantic version updates for Claude Code plugins, ensuring consistency across plugin.json, marketplace catalog, and git tags - optimized for claude-code-plugins repository workflow. + +## Trigger Keywords +- "bump version" or "update version" +- "release" or "new release" +- "major version" or "minor version" or "patch version" +- "increment version" +- "version update" + +## Semantic Versioning + +**Format:** MAJOR.MINOR.PATCH (e.g., 2.1.3) + +**Rules:** +- **MAJOR (2.x.x)** - Breaking changes, incompatible API changes +- **MINOR (x.1.x)** - New features, backward compatible +- **PATCH (x.x.3)** - Bug fixes, backward compatible + +**Examples:** +- `1.0.0` → `1.0.1` (bug fix) +- `1.0.0` → `1.1.0` (new feature) +- `1.0.0` → `2.0.0` (breaking change) + +## Version Bump Process + +When activated, I will: + +1. **Identify Current Version** + ```bash + # Read plugin version + current=$(jq -r '.version' .claude-plugin/plugin.json) + echo "Current version: $current" + ``` + +2. **Determine Bump Type** + - From user request (major/minor/patch) + - Or suggest based on changes + - Or ask user which type + +3. **Calculate New Version** + ```bash + # Example for patch bump: 1.2.3 → 1.2.4 + IFS='.' read -r major minor patch <<< "$current" + new_version="$major.$minor.$((patch + 1))" + ``` + +4. **Update Files** + - Update `.claude-plugin/plugin.json` + - Update `.claude-plugin/marketplace.extended.json` + - Sync to `marketplace.json` + +5. **Validate Consistency** + - Verify all files have same version + - Check no other plugins use this version + - Validate semver format + +6. **Create Git Tag (Optional)** + ```bash + git tag -a "v$new_version" -m "Release v$new_version" + ``` + +## Update Locations + +### 1. Plugin JSON +```json +// .claude-plugin/plugin.json +{ + "name": "plugin-name", + "version": "1.2.4", // ← Update here + ... +} +``` + +### 2. Marketplace Extended +```json +// .claude-plugin/marketplace.extended.json +{ + "plugins": [ + { + "name": "plugin-name", + "version": "1.2.4", // ← Update here + ... + } + ] +} +``` + +### 3. Sync CLI Catalog +```bash +npm run sync-marketplace +# Regenerates marketplace.json with new version +``` + +## Bump Types + +### Patch Bump (Bug Fix) +**When to use:** +- Bug fixes +- Documentation updates +- Minor improvements +- No new features + +**Example:** 1.2.3 → 1.2.4 + +### Minor Bump (New Feature) +**When to use:** +- New features +- New commands/agents/skills +- Backward compatible changes +- Enhanced functionality + +**Example:** 1.2.3 → 1.3.0 + +### Major Bump (Breaking Change) +**When to use:** +- Breaking API changes +- Incompatible updates +- Major refactor +- Removed features + +**Example:** 1.2.3 → 2.0.0 + +## Validation Checks + +Before bumping: +- ✅ Current version is valid semver +- ✅ New version is higher than current +- ✅ No other plugin uses new version +- ✅ All files have same current version +- ✅ Git working directory is clean (optional) + +After bumping: +- ✅ plugin.json updated +- ✅ marketplace.extended.json updated +- ✅ marketplace.json synced +- ✅ All versions consistent +- ✅ CHANGELOG.md updated (if exists) + +## Changelog Management + +If CHANGELOG.md exists, I update it: + +```markdown +# Changelog + +## [1.2.4] - 2025-10-16 + +### Fixed +- Bug fix description +- Another fix + +## [1.2.3] - 2025-10-15 +... +``` + +## Git Integration + +### Option 1: Version Commit +```bash +# Update version files +git add .claude-plugin/plugin.json +git add .claude-plugin/marketplace.extended.json +git add .claude-plugin/marketplace.json +git add CHANGELOG.md # if exists + +# Commit version bump +git commit -m "chore: Bump plugin-name to v1.2.4" +``` + +### Option 2: Version Tag +```bash +# Create annotated tag +git tag -a "plugin-name-v1.2.4" -m "Release plugin-name v1.2.4" + +# Or for monorepo +git tag -a "v1.2.4" -m "Release v1.2.4" + +# Push tag +git push origin plugin-name-v1.2.4 +``` + +## Multi-Plugin Updates + +For repository-wide version bump: + +```bash +# Bump marketplace version +jq '.metadata.version = "1.0.40"' .claude-plugin/marketplace.extended.json + +# Update all plugins (if needed) +for plugin in plugins/*/; do + # Update plugin.json + # Update marketplace entry +done +``` + +## Version Consistency Check + +I verify: +```bash +# Plugin version +plugin_v=$(jq -r '.version' plugins/category/plugin-name/.claude-plugin/plugin.json) + +# Marketplace version +market_v=$(jq -r '.plugins[] | select(.name == "plugin-name") | .version' .claude-plugin/marketplace.extended.json) + +# Should match +if [ "$plugin_v" != "$market_v" ]; then + echo "❌ Version mismatch!" + echo "Plugin: $plugin_v" + echo "Marketplace: $market_v" +fi +``` + +## Release Workflow + +Complete release process: + +1. **Determine Bump Type** + - Review changes since last version + - Decide: patch/minor/major + +2. **Update Version** + - Bump plugin.json + - Update marketplace catalog + - Sync marketplace.json + +3. **Update Changelog** + - Add release notes + - List changes + - Include date + +4. **Commit Changes** + ```bash + git add . + git commit -m "chore: Release v1.2.4" + ``` + +5. **Create Tag** + ```bash + git tag -a "v1.2.4" -m "Release v1.2.4" + ``` + +6. **Push** + ```bash + git push origin main + git push origin v1.2.4 + ``` + +7. **Validate** + - Check GitHub release created + - Verify marketplace updated + - Test plugin installation + +## Output Format + +``` +🔢 VERSION BUMP REPORT + +Plugin: plugin-name +Old Version: 1.2.3 +New Version: 1.2.4 +Bump Type: PATCH + +✅ UPDATES COMPLETED: +1. Updated .claude-plugin/plugin.json → v1.2.4 +2. Updated marketplace.extended.json → v1.2.4 +3. Synced marketplace.json → v1.2.4 +4. Updated CHANGELOG.md + +📊 CONSISTENCY CHECK: +✅ All files have version 1.2.4 +✅ No version conflicts +✅ Semantic versioning valid + +📝 CHANGELOG ENTRY: +## [1.2.4] - 2025-10-16 +### Fixed +- Bug fix description + +🎯 NEXT STEPS: +1. Review changes: git diff +2. Commit: git add . && git commit -m "chore: Bump to v1.2.4" +3. Tag: git tag -a "v1.2.4" -m "Release v1.2.4" +4. Push: git push origin main && git push origin v1.2.4 + +✨ Ready to release! +``` + +## Repository-Specific Features + +**For claude-code-plugins repo:** +- Handles both plugin and marketplace versions +- Updates marketplace metadata version +- Manages plugin count in README +- Syncs both catalog files +- Creates proper release tags + +## Examples + +**User says:** "Bump the security-scanner plugin to patch version" + +**I automatically:** +1. Read current version: 1.2.3 +2. Calculate patch bump: 1.2.4 +3. Update plugin.json +4. Update marketplace.extended.json +5. Sync marketplace.json +6. Validate consistency +7. Report success + +**User says:** "Release version 2.0.0 of plugin-name" + +**I automatically:** +1. Recognize major version (breaking change) +2. Update all version files +3. Update CHANGELOG.md with major release notes +4. Create git commit +5. Create git tag v2.0.0 +6. Provide push commands + +**User says:** "Increment version for new feature" + +**I automatically:** +1. Detect this is a minor bump +2. Calculate new version (1.2.3 → 1.3.0) +3. Update all files +4. Add changelog entry +5. Report completion diff --git a/skills/version-bumper/assets/README.md b/skills/version-bumper/assets/README.md new file mode 100644 index 0000000..148d1c3 --- /dev/null +++ b/skills/version-bumper/assets/README.md @@ -0,0 +1,26 @@ +# Skill Assets + +This directory contains static assets used by this skill. + +## Purpose + +Assets can include: +- Configuration files (JSON, YAML) +- Data files +- Templates +- Schemas +- Test fixtures + +## Guidelines + +- Keep assets small and focused +- Document asset purpose and format +- Use standard file formats +- Include schema validation where applicable + +## Common Asset Types + +- **config.json** - Configuration templates +- **schema.json** - JSON schemas +- **template.yaml** - YAML templates +- **test-data.json** - Test fixtures diff --git a/skills/version-bumper/references/README.md b/skills/version-bumper/references/README.md new file mode 100644 index 0000000..bf97184 --- /dev/null +++ b/skills/version-bumper/references/README.md @@ -0,0 +1,26 @@ +# Skill References + +This directory contains reference materials that enhance this skill's capabilities. + +## Purpose + +References can include: +- Code examples +- Style guides +- Best practices documentation +- Template files +- Configuration examples + +## Guidelines + +- Keep references concise and actionable +- Use markdown for documentation +- Include clear examples +- Link to external resources when appropriate + +## Types of References + +- **examples.md** - Usage examples +- **style-guide.md** - Coding standards +- **templates/** - Reusable templates +- **patterns.md** - Design patterns diff --git a/skills/version-bumper/scripts/README.md b/skills/version-bumper/scripts/README.md new file mode 100644 index 0000000..9f9c7ad --- /dev/null +++ b/skills/version-bumper/scripts/README.md @@ -0,0 +1,24 @@ +# Skill Scripts + +This directory contains optional helper scripts that support this skill's functionality. + +## Purpose + +Scripts here can be: +- Referenced by the skill for automation +- Used as examples for users +- Executed during skill activation + +## Guidelines + +- All scripts should be well-documented +- Include usage examples in comments +- Make scripts executable (`chmod +x`) +- Use `#!/bin/bash` or `#!/usr/bin/env python3` shebangs + +## Adding Scripts + +1. Create script file (e.g., `analyze.sh`, `process.py`) +2. Add documentation header +3. Make executable: `chmod +x script-name.sh` +4. Test thoroughly before committing