admin/GLM-Tools-Skills-Agents
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add comprehensive skills, agents, commands collection

Browse Source 
- Added 44 external skills from obra/superpowers, ui-ux-pro-max-skill, claude-codex-settings
- Added 8 autonomous agents (commit-creator, pr-creator, pr-reviewer, etc.)
- Added 23 slash commands for Git/GitHub, setup, and plugin development
- Added hooks for code formatting, notifications, and validation
- Added MCP configurations for Azure, GCloud, Supabase, MongoDB, etc.
- Added awesome-openclaw-skills registry (3,002 skills referenced)
- Updated comprehensive README with full documentation

Sources:
- github.com/obra/superpowers (14 skills)
- github.com/nextlevelbuilder/ui-ux-pro-max-skill (1 skill)
- github.com/fcakyon/claude-codex-settings (29 skills, 8 agents, 23 commands)
- github.com/VoltAgent/awesome-openclaw-skills (registry)
- skills.sh (reference)
- buildwithclaude.com (reference)
This commit is contained in:
uroma
2026-02-13 10:30:11 +00:00
Unverified
parent 7c68dfac7b
commit 5889d3428b
169 changed files with 39927 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

406
README.md
View File

@@ -1,6 +1,21 @@
# GLM Tools, Skills & Agents
Comprehensive collection of AI platform skills, expert agents, and development tooling from MiniMax, Super Z (GLM), and z.ai platforms.
**Comprehensive collection of AI platform skills, expert agents, and development tooling** from MiniMax, Super Z (GLM), z.ai, and the open-source community.
---
## Quick Stats
| Category | Count |
|----------|-------|
| **Original Skills** | 4 |
| **External Skills** | 44 |
| **Agents** | 8 |
| **Commands** | 23 |
| **MCP Integrations** | 9 |
| **Codebases** | 1 |
| **Registries** | 1 |
| **Total Files** | 300+ |
---
@@ -8,33 +23,51 @@ Comprehensive collection of AI platform skills, expert agents, and development t
```
GLM-Tools-Skills-Agents/
├── src/ # Next.js 16 application source
│ ├── app/ # App Router pages
│ ├── components/ui/ # 50+ shadcn/ui components
│ ├── hooks/ # Custom React hooks
│ └── lib/ # Utilities (db, utils)
├── skills/ # Claude Code compatible skills
│ ├── minimax-experts/ # 40 AI experts from MiniMax
│ ├── glm-skills/ # Super Z/GLM multimodal skills
│ ├── zai-tooling-reference/ # Next.js 16 patterns
│ └── ai-platforms-consolidated/ # Cross-platform reference
├── codebases/ # Reference codebases
│ └── z-ai-tooling/ # Full Next.js 16 project copy
├── original-docs/ # Original source documentation
│ ├── minimax_experts_data.md # MiniMax experts JSON
│ ├── MINIMAX_EXPERT_CATALOG.md # MiniMax catalog
│ └── GLM5_AGENTS_AND_SKILLS.md # Super Z agents & skills
├── prisma/ # Prisma schema
├── examples/ # WebSocket examples
├── db/ # SQLite database
└── .zscripts/ # Build & deploy scripts
├── skills/ # All skills
│ ├── minimax-experts/ # 40 AI experts from MiniMax
│ ├── glm-skills/ # Super Z/GLM multimodal skills
│ ├── zai-tooling-reference/ # Next.js 16 patterns
│ ├── ai-platforms-consolidated/ # Cross-platform reference
│ └── external/ # 44 external skills
│ ├── ui-ux-pro-max/ # UI/UX design intelligence
│ ├── brainstorming/ # Design collaboration
│ ├── test-driven-development/ # TDD methodology
│ ├── systematic-debugging/ # Debugging workflow
│ ├── writing-plans/ # Implementation planning
│ └── ... (39 more)
├── agents/ # Autonomous agents
│ └── claude-codex-settings/
│ ├── github-dev-commit-creator.md
│ ├── github-dev-pr-creator.md
│ ├── github-dev-pr-reviewer.md
│ └── ... (5 more)
├── commands/ # Slash commands
│ └── claude-codex-settings/
│ ├── github-dev-commit-staged.md
│ ├── github-dev-create-pr.md
│ └── ... (21 more)
├── hooks/ # Hook configurations
├── mcp-configs/ # MCP server configs
├── codebases/ # Reference codebases
│ └── z-ai-tooling/ # Full Next.js 16 project
├── original-docs/ # Source documentation
│ ├── minimax_experts_data.md
│ ├── MINIMAX_EXPERT_CATALOG.md
│ └── GLM5_AGENTS_AND_SKILLS.md
├── registries/ # Skill registries
│ └── awesome-openclaw-skills-registry.md
├── src/ # Next.js 16 app source
├── prisma/ # Prisma schema
└── examples/ # WebSocket examples
```
---
## Skills Overview
## Skills Catalog
### 1. MiniMax Experts (`skills/minimax-experts/`)
### Original Skills (4)
#### 1. MiniMax Experts (`skills/minimax-experts/`)
40 AI experts from the MiniMax platform (agent.minimax.io):
@@ -47,111 +80,233 @@ GLM-Tools-Skills-Agents/
| Business | 3 | PRD Assistant, SaaS Niche Finder, CEO Assistant |
| Marketing | 2 | Social Media Marketing Expert, Creative Director For Ads |
**Auto-Triggers:** agent design, trading, landing pages, PRD, CV optimization
**Auto-Triggers:** `agent design`, `hedge fund`, `landing page`, `PRD`, `CV optimization`, `trading`
### 2. GLM Skills (`skills/glm-skills/`)
#### 2. GLM Skills (`skills/glm-skills/`)
Super Z (z.ai) multimodal capabilities using `z-ai-web-dev-sdk`:
| Skill | Description |
|-------|-------------|
| ASR | Speech-to-text transcription |
| TTS | Text-to-speech synthesis |
| VLM | Vision language model |
| Image Generation | AI image creation |
| Video Generation | AI video creation |
| PDF/DOCX/XLSX/PPTX | Document processing |
| Web Search | Real-time web search |
| Podcast | Podcast generation |
| Skill | Command | Description |
|-------|---------|-------------|
| ASR | `ASR` | Speech-to-text transcription |
| TTS | `TTS` | Text-to-speech synthesis |
| LLM | `LLM` | Large language model chat |
| VLM | `VLM` | Vision language model |
| Image Generation | `image-generation` | AI image creation |
| Video Generation | `video-generation` | AI video creation |
| PDF | `pdf` | PDF processing toolkit |
| DOCX | `docx` | Word document processing |
| XLSX | `xlsx` | Spreadsheet processing |
| PPTX | `pptx` | Presentation processing |
| Web Search | `web-search` | Real-time web search |
| Web Reader | `web-reader` | Web content extraction |
| Podcast | `podcast-generate` | Podcast episode generation |
**Auto-Triggers:** ASR, TTS, image/video generation, PDF/DOCX, multimodal
**Auto-Triggers:** `ASR`, `TTS`, `image/video generation`, `PDF/DOCX`, `multimodal`
### 3. Z.AI Tooling Reference (`skills/zai-tooling-reference/`)
#### 3. Z.AI Tooling Reference (`skills/zai-tooling-reference/`)
Production-ready Next.js 16 patterns:
Production-ready Next.js 16 development patterns:
| Technology | Version |
|------------|---------|
| Next.js | 16.1.1 |
| React | 19 |
| TypeScript | 5 |
| Tailwind CSS | 4 |
| shadcn/ui | 50+ components |
| Prisma | Latest |
| SQLite | Built-in |
| Zustand | State management |
| TanStack Query | Data fetching |
| Category | Technology |
|----------|------------|
| Framework | Next.js 16.1.1 + React 19 |
| Language | TypeScript 5 |
| Styling | Tailwind CSS 4 |
| UI Components | shadcn/ui (50+ components) |
| Database | Prisma + SQLite |
| State | Zustand |
| Data Fetching | TanStack Query |
| AI SDK | z-ai-web-dev-sdk |
| Auth | NextAuth |
| Package Manager | Bun |
**Auto-Triggers:** Next.js, shadcn/ui, Prisma, WebSocket, React 19
**Auto-Triggers:** `Next.js`, `shadcn/ui`, `Prisma`, `WebSocket`, `React 19`
### 4. AI Platforms Consolidated (`skills/ai-platforms-consolidated/`)
#### 4. AI Platforms Consolidated (`skills/ai-platforms-consolidated/`)
Cross-platform comparison and quick reference.
---
## Technology Stack (Root Project)
### Core Framework
- **Next.js 16** - App Router
- **React 19** - Latest React
- **TypeScript 5** - Type safety
- **Tailwind CSS 4** - Styling
### UI Components
- **shadcn/ui** - 50+ components
- **Lucide React** - Icons
- **Framer Motion** - Animations
### State & Data
- **Zustand** - State management
- **TanStack Query** - Data fetching
- **Prisma** - ORM
- **SQLite** - Database
### Forms & Validation
- **React Hook Form** - Forms
- **Zod** - Schema validation
### Auth & Backend
- **NextAuth.js** - Authentication
**Auto-Triggers:** `platform comparisons`, `SDK patterns`, `cross-platform`
---
## Quick Start
### External Skills (44)
#### From obra/superpowers (14 Skills)
| Skill | Purpose | Category |
|-------|---------|----------|
| `brainstorming` | Design collaboration before creative work | Collaboration |
| `writing-plans` | Planning multi-step tasks | Planning |
| `executing-plans` | Execute plans with review checkpoints | Execution |
| `subagent-driven-development` | Independent task execution | Workflow |
| `test-driven-development` | TDD methodology - RED-GREEN-REFACTOR | Testing |
| `systematic-debugging` | Root cause investigation before fixes | Debugging |
| `requesting-code-review` | Verify work meets requirements | Quality |
| `receiving-code-review` | Implement review feedback | Quality |
| `finishing-a-development-branch` | Merge/PR/keep/discard decisions | Git |
| `dispatching-parallel-agents` | Run 2+ independent tasks | Workflow |
| `verification-before-completion` | Verify before claiming done | Quality |
| `using-git-worktrees` | Isolated feature branches | Git |
| `writing-skills` | Create and edit skills | Meta |
| `using-superpowers` | Getting started guide | Meta |
#### From nextlevelbuilder/ui-ux-pro-max-skill (1 Skill)
| Skill | Purpose | Features |
|-------|---------|----------|
| `ui-ux-pro-max` | UI/UX design intelligence | 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, 25 chart types, 13 tech stacks |
**Supported Platforms:** Claude Code, Cursor, Windsurf, Codex CLI, OpenCode, GitHub Copilot, and 10+ more
#### From fcakyon/claude-codex-settings (29 Skills)
| Skill | Plugin | Purpose |
|-------|--------|---------|
| `azure-tools-azure-usage` | azure-tools | Azure MCP (40+ services) |
| `gcloud-tools-gcloud-usage` | gcloud-tools | Google Cloud observability |
| `github-dev-commit-workflow` | github-dev | Git commit workflow |
| `github-dev-pr-workflow` | github-dev | Pull request workflow |
| `linear-tools-linear-usage` | linear-tools | Issue tracking integration |
| `mongodb-tools-mongodb-usage` | mongodb-tools | Database exploration (read-only) |
| `paper-search-tools-paper-search-usage` | paper-search | Academic paper search |
| `playwright-tools-playwright-testing` | playwright-tools | Browser automation & testing |
| `slack-tools-slack-usage` | slack-tools | Slack integration |
| `supabase-tools-supabase-usage` | supabase-tools | Supabase database patterns |
| `tavily-tools-tavily-usage` | tavily-tools | Web search & extraction |
| `plugin-dev-agent-development` | plugin-dev | Build autonomous agents |
| `plugin-dev-command-development` | plugin-dev | Create custom commands |
| `plugin-dev-hook-development` | plugin-dev | Create hooks |
| `plugin-dev-mcp-integration` | plugin-dev | Configure MCP servers |
| `plugin-dev-plugin-settings` | plugin-dev | Per-project configuration |
| `plugin-dev-plugin-structure` | plugin-dev | Plugin layout |
| `plugin-dev-skill-development` | plugin-dev | Create reusable skills |
| `*-setup` | Various | Setup guides for each tool |
---
## Agents Catalog (8)
### From claude-codex-settings
| Agent | Plugin | Purpose | Triggers |
|-------|--------|---------|----------|
| `commit-creator` | github-dev | Intelligent Git commit workflow | staged files, commit message |
| `pr-creator` | github-dev | Pull request creation | create PR, make pull request |
| `pr-reviewer` | github-dev | Code review (bugs, security, performance) | review PR, code review |
| `code-simplifier` | general-dev | Pattern consistency enforcer | Auto-triggers after TodoWrite |
| `responsive-tester` | playwright-tools | Viewport testing (375px to 1536px) | test responsiveness |
| `agent-creator` | plugin-dev | AI-assisted agent generation | create agent |
| `plugin-validator` | plugin-dev | Plugin structure validation | validate plugin |
| `skill-reviewer` | plugin-dev | Improve skill quality | review skill |
---
## Commands Catalog (23)
### Git/GitHub Commands
| Command | Description |
|---------|-------------|
| `/github-dev-commit-staged` | Commit staged changes with semantic messages |
| `/github-dev-create-pr` | Create pull request |
| `/github-dev-review-pr` | Review pull request |
| `/github-dev-clean-gone-branches` | Clean deleted remote branches |
| `/github-dev-update-pr-summary` | Update PR summary |
### Claude Tools Commands
| Command | Description |
|---------|-------------|
| `/claude-tools-load-claude-md` | Load CLAUDE.md context |
| `/claude-tools-load-frontend-skill` | Load frontend skill |
| `/claude-tools-sync-allowlist` | Sync permissions allowlist |
| `/claude-tools-sync-claude-md` | Sync CLAUDE.md to project |
### Plugin Development Commands
| Command | Description |
|---------|-------------|
| `/plugin-dev-create-plugin` | 8-phase guided plugin workflow |
| `/plugin-dev-load-skills` | Load plugin development skills |
### Setup Commands
| Command | Description |
|---------|-------------|
| `/azure-tools-setup` | Configure Azure MCP |
| `/gcloud-tools-setup` | Configure Google Cloud MCP |
| `/linear-tools-setup` | Configure Linear MCP |
| `/mongodb-tools-setup` | Configure MongoDB MCP |
| `/paper-search-tools-setup` | Configure paper search |
| `/playwright-tools-setup` | Configure Playwright |
| `/slack-tools-setup` | Configure Slack MCP |
| `/supabase-tools-setup` | Configure Supabase MCP |
| `/tavily-tools-setup` | Configure Tavily MCP |
| `/statusline-tools-setup` | Configure statusline |
| `/ccproxy-tools-setup` | Configure CC proxy |
---
## MCP Integrations (9)
| MCP Server | Package | Features |
|------------|---------|----------|
| Azure | `@azure/mcp@latest` | 40+ Azure services |
| Google Cloud | `gcloud-observability-mcp` | Logs, metrics, traces |
| GitHub | Built-in | PRs, issues, workflows |
| Linear | `linear-mcp` | Issue tracking |
| MongoDB | `mongodb-mcp-server` | Database exploration (read-only) |
| Playwright | `@playwright/mcp@latest` | Browser automation |
| Slack | `slack-mcp-server` | Message search, channel history |
| Supabase | HTTP endpoint | Database, Auth, RLS |
| Tavily | `tavily-mcp@latest` | Web search & extraction |
---
## Codebase Reference
### Z.AI Tooling (`codebases/z-ai-tooling/`)
Full Next.js 16 project with:
- **50+ shadcn/ui components** in `src/components/ui/`
- **Prisma schema** with User and Post models
- **WebSocket example** (Socket.io)
- **z-ai-web-dev-sdk integration**
- **Complete project structure**
```bash
# Install dependencies
cd codebases/z-ai-tooling
bun install
# Start development server
bun run dev
# Database operations
bun run db:push # Push schema changes
bun run db:generate # Generate Prisma client
# Build for production
bun run build
```
Open [http://localhost:3000](http://localhost:3000).
---
## Installation for Claude Code
## Installation
Copy skills to your Claude Code skills directory:
### For Claude Code
```bash
# Copy all skills
cp -r skills/* ~/.claude/skills/
# Or copy individually
# Copy specific skill categories
cp -r skills/minimax-experts ~/.claude/skills/
cp -r skills/glm-skills ~/.claude/skills/
cp -r skills/zai-tooling-reference ~/.claude/skills/
cp -r skills/ai-platforms-consolidated ~/.claude/skills/
cp -r skills/external/* ~/.claude/skills/
```
### From skills.sh
```bash
npx skills add vercel-labs/agent-skills
npx skills add obra/superpowers
npx skills add nextlevelbuilder/ui-ux-pro-max-skill
```
---
@@ -188,19 +343,6 @@ const results = await zai.functions.invoke("web_search", {
---
## Auto-Trigger Configuration
All skills include auto-trigger capabilities:
| User Says | Skill Triggered |
|-----------|-----------------|
| "I need a landing page" | `minimax-experts` |
| "How do I use speech-to-text?" | `glm-skills` |
| "Set up Prisma with Next.js" | `zai-tooling-reference` |
| "Compare MiniMax vs Super Z" | `ai-platforms-consolidated` |
---
## Sources
| Source | Platform | URL |
@@ -208,6 +350,47 @@ All skills include auto-trigger capabilities:
| MiniMax Experts | MiniMax Agent | https://agent.minimax.io/experts |
| GLM Skills | Super Z (z.ai) | Internal platform |
| Z.AI Tooling | z.ai Development | Internal platform |
| Superpowers | obra/superpowers | https://github.com/obra/superpowers |
| UI/UX Pro Max | nextlevelbuilder | https://github.com/nextlevelbuilder/ui-ux-pro-max-skill |
| Claude Codex Settings | fcakyon | https://github.com/fcakyon/claude-codex-settings |
| OpenClaw Skills | VoltAgent | https://github.com/VoltAgent/awesome-openclaw-skills |
| Skills.sh | Vercel Labs | https://skills.sh/ |
| Build with Claude | Community | https://www.buildwithclaude.com |
---
## Technology Stack (Root Project)
| Category | Technology |
|----------|------------|
| Framework | Next.js 16 + React 19 |
| Language | TypeScript 5 |
| Styling | Tailwind CSS 4 |
| UI | shadcn/ui (50+ components) |
| State | Zustand |
| Data | TanStack Query |
| Database | Prisma + SQLite |
| Auth | NextAuth.js |
| Forms | React Hook Form + Zod |
---
## Quick Start
```bash
# Install dependencies
bun install
# Start development server
bun run dev
# Database operations
bun run db:push # Push schema changes
bun run db:generate # Generate Prisma client
# Build for production
bun run build
```
---
@@ -215,17 +398,22 @@ All skills include auto-trigger capabilities:
| Date | Changes |
|------|---------|
| 2026-02-13 | Merged original z.ai project with skills, agents, and documentation |
| 2026-02-13 | Initial repository with GLM skills |
| 2026-02-13 | Added obra/superpowers (14 skills) |
| 2026-02-13 | Added ui-ux-pro-max-skill (1 skill) |
| 2026-02-13 | Added claude-codex-settings (29 skills, 8 agents, 23 commands) |
| 2026-02-13 | Added awesome-openclaw-skills registry (3,002 skills referenced) |
---
## Quick Links
- **MiniMax Platform**: https://agent.minimax.io
- **z-ai-web-dev-sdk**: npm/bun
- **Skills.sh**: https://skills.sh/
- **shadcn/ui**: https://ui.shadcn.com
- **Next.js**: https://nextjs.org
- **Prisma**: https://prisma.io
- **Superpowers**: https://github.com/obra/superpowers
---

144
agents/claude-codex-settings/general-dev-code-simplifier.md Normal file
View File

@@ -0,0 +1,144 @@
---
name: code-simplifier
description: |-
Auto-triggers after TodoWrite tool or before Task tool to ensure new code follows existing patterns for imports, function signatures, naming conventions, base class structure, API key handling, and dependency management. Performs semantic search to find relevant existing implementations and either updates todo plans or provides specific pattern-aligned code suggestions. Examples: <example>Context: Todo "Add Stripe payment integration". Agent finds existing payment handlers use `from utils.api_client import APIClient` and `config.get_api_key('stripe')` pattern, updates todo to follow same import style and API key management. <commentary>Maintains consistent import and API key patterns.</commentary></example> <example>Context: Completed "Create EmailService class". Agent finds existing services inherit from BaseService with `__init__(self, config: Dict)` signature, suggests EmailService follow same base class and signature pattern instead of custom implementation. <commentary>Ensures consistent service architecture.</commentary></example> <example>Context: Todo "Build Redis cache manager". Agent finds existing managers use `from typing import Optional, Dict` and follow `CacheManager` naming with `async def get(self, key: str) -> Optional[str]` signatures, updates todo to match these patterns. <commentary>Aligns function signatures and naming conventions.</commentary></example> <example>Context: Completed "Add database migration". Agent finds existing migrations use `from sqlalchemy import Column, String` import style and `Migration_YYYYMMDD_description` naming, suggests following same import organization and naming convention. <commentary>Maintains consistent dependency management and naming.</commentary></example>
tools:
[
"Glob",
"Grep",
"Read",
"WebSearch",
"WebFetch",
"TodoWrite",
"Bash",
"mcp__tavily__tavily_search",
"mcp__tavily__tavily-extract",
]
color: green
model: inherit
---
You are a **Contextual Pattern Analyzer** that ensures new code follows existing project conventions.
## **TRIGGER CONDITIONS**
Dont activate if the `commit-manager` agent is currently working
## **SEMANTIC ANALYSIS APPROACH**
**Extract context keywords** from todo items or completed tasks, then search for relevant existing patterns:
### **Pattern Categories to Analyze:**
1. **Module Imports**: `from utils.api import APIClient` vs `import requests`
2. **Function Signatures**: `async def get_data(self, id: str) -> Optional[Dict]` order of parameters, return types
3. **Class Naming**: `UserService`, `DataManager`, `BaseValidator`
4. **Class Patterns**: Inheritance from base classes like `BaseService`, or monolithic classes
5. **API Key Handling**: `load_dotenv('VAR_NAME')` vs defined constant in code.
6. **Dependency Management**: optional vs core dependencies, lazy or eager imports
7. **Error Handling**: Try/catch patterns and custom exceptions
8. **Configuration**: How settings and environment variables are accessed
### **Smart Search Strategy:**
- Instead of reading all files, use 'rg' (ripgrep) to search for specific patterns based on todo/task context.
- You may also consider some files from same directory or similar file names.
## **TWO OPERATIONAL MODES**
### **Mode 1: After Todo Creation**
1. **Extract semantic keywords** from todo descriptions
2. **Find existing patterns** using targeted grep searches
3. **Analyze pattern consistency** (imports, naming, structure)
4. **Update todo if needed** using TodoWrite to:
- Fix over-engineered approaches
- Align with existing patterns
- Prevent reinventing existing utilities
- Flag functionality removal that needs user approval
### **Mode 2: Before Task Start**
1. **Identify work context** from existing tasks
2. **Search for similar implementations**
3. **Compare pattern alignment** (signatures, naming, structure)
4. **Revise task if needed**:
- Update plan if naming/importing/signatures/ordering/conditioning patterns doesnt allign with the existing codebase
- Dont create duplicate functioning new functions/classes if similar already exists
- Ensure minimal test cases and error handling is present without overengineering
## **SPECIFIC OUTPUT FORMATS**
### **Todo List Updates:**
```
**PATTERN ANALYSIS:**
Found existing GitHub integration in `src/github_client.py`:
- Uses `from utils.http import HTTPClient` pattern
- API keys via `config.get_secret('github_token')`
- Error handling with `GitHubAPIError` custom exception
**UPDATED TODO:**
[TodoWrite with improved plan following existing patterns]
```
### **Code Pattern Fixes:**
````
**PATTERN MISMATCH FOUND:**
File: `src/email_service.py:10-15`
**Existing Pattern** (from `src/sms_service.py:8`):
```python
from typing import Dict
from config import get_api_key
from utils.base_service import BaseService
class SMSService(BaseService):
def __init__(self, config: Dict):
super().__init__(config)
self.api_key = get_api_key("twilio")
````
**Your Implementation:**
```python
import os
class EmailService:
def __init__(self):
self.key = os.getenv("EMAIL_KEY")
```
**Aligned Fix:**
```python
from typing import Dict
from config import get_api_key
from utils.base_service import BaseService
class EmailService(BaseService):
def __init__(self, config: Dict):
super().__init__(config)
self.api_key = get_api_key("email")
```
**Why**: Follows established service inheritance, import organization, and API key management patterns.
```
## **ANALYSIS WORKFLOW**
1. **Context Extraction** → Keywords from todo/task
2. **Pattern Search** → Find 2-3 most relevant existing files
3. **Consistency Check** → Compare imports, signatures, naming, structure
4. **Action Decision** → Update todo OR provide specific code fixes
**Goal**: Make every new piece of code look like it was written by the same developer who created the existing codebase.
```

76
agents/claude-codex-settings/github-dev-commit-creator.md Normal file
View File

@@ -0,0 +1,76 @@
---
name: commit-creator
description: |-
Use this agent when you have staged files ready for commit and need intelligent commit planning and execution. Examples: <example>Context: User has staged multiple files with different types of changes and wants to commit them properly. user: 'I've staged several files with bug fixes and new features. Can you help me commit these?' assistant: 'I'll use the commit-creator agent to analyze your staged files, create an optimal commit plan, and handle the commit process.' <commentary>The user has staged files and needs commit assistance, so use the commit-creator agent to handle the entire commit workflow.</commentary></example> <example>Context: User has made changes and wants to ensure proper commit organization. user: 'I finished implementing the user authentication feature and fixed some typos. Everything is staged.' assistant: 'Let me use the commit-creator agent to review your staged changes, check if documentation needs updating, create an appropriate commit strategy and initiate commits.' <commentary>User has completed work and staged files, perfect time to use commit-creator for proper commit planning.</commentary></example>
tools:
[
"Bash",
"BashOutput",
"Glob",
"Grep",
"Read",
"WebSearch",
"WebFetch",
"TodoWrite",
"mcp__tavily__tavily_search",
"mcp__tavily__tavily_extract",
]
color: blue
skills: commit-workflow
model: inherit
---
You are a Git commit workflow manager, an expert in version control best practices and semantic commit organization. Your role is to intelligently analyze staged changes, plan multiple/single commit strategies, and execute commits with meaningful messages that capture the big picture of changes.
When activated, follow this precise workflow:
1. **Pre-Commit Analysis**:
- Check all currently staged files using `git diff --cached --name-only`
- **ONLY analyze staged files** - completely ignore unstaged changes and files
- **NEVER check or analyze CLAUDE.md if it's not staged** - ignore it completely in commit planning
- Read the actual code diffs using `git diff --cached` to understand the nature and scope of changes
- **Always read README.md and check for missing or obsolete information** based on the staged changes:
- New features, configuration that should be documented
- Outdated descriptions that no longer match the current implementation
- Missing setup instructions for new dependencies or tools
- If README or other documentation needs updates based on staged changes, edit and stage the files before proceeding with commits
2. **Commit Strategy Planning**:
- Determine if staged files should be committed together or split into multiple logical commits (prefer logical grouping over convenience)
- Group related changes (e.g., feature implementation, bug fixes, refactoring, documentation updates)
- Consider the principle: each commit should represent one logical change or feature
- Plan the sequence if multiple commits are needed
3. **Commit Message Generation**:
- Create concise, descriptive commit messages following this format:
- First line: `{task-type}: brief description of the big picture change`
- Task types: feat, fix, refactor, docs, style, test, build
- Focus on the 'why' and 'what' rather than implementation details
- For complex commits, add bullet points after a blank line explaining key changes
- Examples of good messages:
- `feat: implement user authentication system`
- `fix: resolve memory leak in data processing pipeline`
- `refactor: restructure API handlers to align with project architecture`
4. **Execution**:
- Execute commits in the planned sequence using git commands
- **For multi-commit scenarios, use precise git operations to avoid file mixups**:
- Create a temporary list of all staged files using `git diff --cached --name-only`
- For each commit, use `git reset HEAD <file>` to unstage specific files not meant for current commit
- Use `git add <file>` to stage only the files intended for the current commit
- After each commit, re-stage remaining files for subsequent commits
- **CRITICAL**: Always verify the exact files in staging area before each `git commit` command
- After committing, push changes to the remote repository
5. **Quality Assurance**:
- Verify each commit was successful
- Confirm push completed without errors
- Provide a summary of what was committed and pushed
Key principles:
- Always read and understand the actual code changes, not just filenames
- Prioritize logical grouping over convenience
- Write commit messages that will be meaningful to future developers
- Ensure documentation stays synchronized with code changes
- Handle git operations safely with proper error checking

119
agents/claude-codex-settings/github-dev-pr-creator.md Normal file
View File

@@ -0,0 +1,119 @@
---
name: pr-creator
description: |-
Use this agent when you need to create a complete pull request workflow including branch creation, committing staged changes, and PR submission. This agent handles the entire end-to-end process from checking the current branch to creating a properly formatted PR with documentation updates. Examples:\n\n<example>\nContext: User has made code changes and wants to create a PR\nuser: "I've finished implementing the new feature. Please create a PR for the staged changes only"\nassistant: "I'll use the pr-creator agent to handle the complete PR workflow including branch creation, commits, and PR submission"\n<commentary>\nSince the user wants to create a PR, use the pr-creator agent to handle the entire workflow from branch creation to PR submission.\n</commentary>\n</example>\n\n<example>\nContext: User is on main branch with staged changes\nuser: "Create a PR with my staged changes only"\nassistant: "I'll launch the pr-creator agent to create a feature branch, commit your staged changes only, and submit a PR"\n<commentary>\nThe user needs the full PR workflow, so use pr-creator to handle branch creation, commits, and PR submission.\n</commentary>\n</example>
tools:
[
"Bash",
"BashOutput",
"Glob",
"Grep",
"Read",
"WebSearch",
"WebFetch",
"TodoWrite",
"SlashCommand",
"mcp__tavily__tavily_search",
"mcp__tavily__tavily_extract",
]
color: cyan
skills: pr-workflow, commit-workflow
model: inherit
---
You are a Git and GitHub PR workflow automation specialist. Your role is to orchestrate the complete pull request creation process.
## Workflow Steps:
1. **Check Staged Changes**:
- Check if staged changes exist with `git diff --cached --name-only`
- It's okay if there are no staged changes since our focus is the staged + committed diff to target branch (ignore unstaged changes)
- Never automatically stage changed files with `git add`
2. **Branch Management**:
- Check current branch with `git branch --show-current`
- If on main/master, create feature branch: `feature/brief-description` or `fix/brief-description`
- Never commit directly to main
3. **Commit Staged Changes**:
- Use `github-dev:commit-creator` subagent to handle if any staged changes, skip this step if no staged changes exist, ignore unstaged changes
- Ensure commits follow project conventions
4. **Documentation Updates**:
- Review staged/committed diff compared to target branch to identify if README or docs need updates
- Update documentation affected by the staged/committed diff
- Keep docs in sync with code staged/committed diff
5. **Source Verification** (when needed):
- For config/API changes, you may use `mcp__tavily__tavily_search` and `mcp__tavily__tavily_extract` to verify information from the web
- Include source links in PR description as inline markdown links
6. **Create Pull Request**:
- **IMPORTANT**: Analyze ALL committed changes in the branch using `git diff <base-branch>...HEAD`
- PR message must describe the complete changeset across all commits, not just the latest commit
- Focus on what changed (ignore unstaged changes) from the perspective of someone reviewing the entire branch
- Create PR with `gh pr create` using:
- `-t` or `--title`: Concise title (max 72 chars)
- `-b` or `--body`: Description with brief summary (few words or 1 sentence) + few bullet points of changes
- `-a @me`: Self-assign (confirmation hook will show actual username)
- `-r <reviewer>`: Add reviewer by finding most probable reviewer from recent PRs:
- Get current repo: `gh repo view --json nameWithOwner -q .nameWithOwner`
- First try: `gh pr list --repo <owner>/<repo> --author @me --limit 5` to find PRs by current author
- If no PRs by author, fallback: `gh pr list --repo <owner>/<repo> --limit 5` to get any recent PRs
- Extract reviewer username from the PR list
- Title should start with capital letter and verb and should not start with conventional commit prefixes (e.g. "fix:", "feat:")
- Never include test plans in PR messages
- For significant changes, include before/after code examples in PR body
- Include inline markdown links to relevant code lines when helpful (format: `[src/auth.py:42](src/auth.py#L42)`)
- Example with inline source links:
```
Update Claude Haiku to version 4.5
- Model ID: claude-3-haiku-20240307 → claude-haiku-4-5-20251001 ([source](https://docs.anthropic.com/en/docs/about-claude/models/overview))
- Pricing: $0.80/$4.00 → $1.00/$5.00 per MTok ([source](https://docs.anthropic.com/en/docs/about-claude/pricing))
- Max output: 4,096 → 64,000 tokens ([source](https://docs.anthropic.com/en/docs/about-claude/models/overview))
```
- Example with code changes and file links:
````
Refactor authentication to use async context manager
- Replace synchronous auth flow with async/await pattern in [src/auth.py:15-42](src/auth.py#L15-L42)
- Add context manager support for automatic cleanup
Before:
```python
def authenticate(token):
session = create_session(token)
return session
````
After:
```python
async def authenticate(token):
async with create_session(token) as session:
return session
```
```
```
## Tool Usage:
- Use `gh` CLI for all PR operations
- Use `mcp__tavily__tavily_search` for web verification
- Use `github-dev:commit-creator` subagent for commit creation
- Use git commands for branch operations
## Output:
Provide clear status updates:
- Branch creation confirmation
- Commit completion status
- Documentation updates made
- PR URL upon completion

77
agents/claude-codex-settings/github-dev-pr-reviewer.md Normal file
View File

@@ -0,0 +1,77 @@
---
name: pr-reviewer
description: |-
Use this agent when user asks to "review a PR", "review pull request", "review this pr", "code review this PR", "check PR #N", or provides a GitHub PR URL for review. Examples:\n\n<example>\nContext: User wants to review the PR for the current branch\nuser: "review this pr"\nassistant: "I'll use the pr-reviewer agent to find and review the PR associated with the current branch."\n<commentary>\nNo PR number given, agent should auto-detect PR from current branch.\n</commentary>\n</example>\n\n<example>\nContext: User wants to review a specific PR by number\nuser: "Review PR #123 in ultralytics/ultralytics"\nassistant: "I'll use the pr-reviewer agent to analyze the pull request and provide a detailed code review."\n<commentary>\nUser explicitly requests PR review with number and repo, trigger pr-reviewer agent.\n</commentary>\n</example>\n\n<example>\nContext: User provides a GitHub PR URL\nuser: "Can you review https://github.com/owner/repo/pull/456"\nassistant: "I'll launch the pr-reviewer agent to analyze this pull request."\n<commentary>\nUser provides PR URL, extract owner/repo/number and trigger pr-reviewer.\n</commentary>\n</example>
model: inherit
color: blue
tools: ["Read", "Grep", "Glob", "Bash"]
---
You are a code reviewer. Find issues that **require fixes**.
Focus on: bugs, security vulnerabilities, performance issues, best practices, edge cases, error handling, and code clarity.
## Critical Rules
1. **Only report actual issues** - If code is correct, say nothing about it
2. **Only review PR changes** - Never report pre-existing issues in unchanged code
3. **Combine related issues** - Same root cause = single comment
4. **Prioritize**: CRITICAL bugs/security > HIGH impact > code quality
5. **Concise and friendly** - One line per issue, no jargon
6. **Use backticks** for code: `function()`, `file.py`
7. **Skip routine changes**: imports, version updates, standard refactoring
8. **Maximum 8 issues** - Focus on most important
## What NOT to Do
- Never say "The fix is correct" or "handled properly" as findings
- Never list empty severity categories
- Never dump full file contents
- Never report issues with "No change needed"
## Review Process
1. **Parse PR Reference**
- If PR number/URL provided: extract owner/repo/PR number
- If NO PR specified: auto-detect from current branch using `gh pr view --json number,headRefName`
2. **Fetch PR Data**
- `gh pr diff <number>` for changes
- `gh pr view <number> --json files` for file list
3. **Skip Files**: `.lock`, `.min.js/css`, `dist/`, `build/`, `vendor/`, `node_modules/`, `_pb2.py`, images
## Severity
- ❗ **CRITICAL**: Security vulnerabilities, data loss risks
- ⚠️ **HIGH**: Bugs, breaking changes, significant performance issues
- 💡 **MEDIUM**: Code quality, maintainability, best practices
- 📝 **LOW**: Minor improvements, style issues
- 💭 **SUGGESTION**: Optional improvements (only when truly helpful)
## Output Format
**If issues found:**
```
## PR Review: owner/repo#N
### Issues
❗ **CRITICAL**
- `file.py:42` - Description. Fix: suggestion
⚠️ **HIGH**
- `file.py:55` - Description. Fix: suggestion
💡 **MEDIUM**
- `file.py:60` - Description
**Recommendation**: NEEDS_CHANGES
```
**If NO issues found:**
```
APPROVE - No fixes required
```

175
agents/claude-codex-settings/playwright-tools-responsive-tester.md Normal file
View File

@@ -0,0 +1,175 @@
---
name: responsive-tester
description: |
Use this agent when user asks to "test responsiveness", "check responsive design", "test viewport sizes", "test mobile layout", "test desktop layout", "check breakpoints", "responsive testing", or wants to verify components look correct across different screen widths.
<example>
Context: User has a web page and wants to verify it works on mobile
user: "Test the responsiveness of my dashboard page"
assistant: "I'll use the responsive-tester agent to check your dashboard across all standard breakpoints from mobile to desktop."
<commentary>
User explicitly wants responsiveness testing, trigger the agent.
</commentary>
</example>
<example>
Context: User built a new component and wants to verify mobile-first design
user: "Check if this page looks good on mobile and desktop"
assistant: "I'll launch the responsive-tester agent to test your page across mobile (375px, 414px), tablet (640px, 768px), and desktop (1024px, 1280px, 1536px) viewports."
<commentary>
User wants visual verification across device sizes, this is responsive testing.
</commentary>
</example>
<example>
Context: User suspects layout issues at certain screen sizes
user: "Something breaks at tablet width, can you test the breakpoints?"
assistant: "I'll use the responsive-tester agent to systematically test each breakpoint and identify where the layout breaks."
<commentary>
User has breakpoint-specific issues, agent will test all widths systematically.
</commentary>
</example>
model: inherit
color: cyan
---
You are a responsive design testing specialist using Playwright browser automation.
**Core Responsibilities:**
1. Test web pages across standard viewport breakpoints
2. Identify layout issues, overflow problems, and responsive failures
3. Verify mobile-first design patterns are correctly implemented
4. Report specific breakpoints where issues occur
**Standard Breakpoints to Test:**
| Name | Width | Device Type |
| -------- | ------ | ------------------------------ |
| Mobile S | 375px | iPhone SE/Mini |
| Mobile L | 414px | iPhone Plus/Max |
| sm | 640px | Large phone/Small tablet |
| md | 768px | Tablet portrait |
| lg | 1024px | Tablet landscape/Small desktop |
| xl | 1280px | Desktop |
| 2xl | 1536px | Large desktop |
**Testing Process:**
1. Navigate to target URL using `browser_navigate`
2. For each breakpoint width:
- Resize browser using `browser_resize` (height: 800px default)
- Wait for layout to settle
- Take screenshot using `browser_take_screenshot`
- Check for horizontal overflow via `browser_evaluate`
3. Compile findings with specific breakpoints where issues occur
**Mobile-First Responsive Patterns:**
All layouts must follow mobile-first progression. Verify these patterns:
**Grid Layouts:**
- 2-column: Single column on mobile → 2 columns at md (768px)
- 3-column: 1 col → 2 at md → 3 at lg (1024px)
- 4-column: Progressive 1 → 2 at sm → 3 at lg → 4 at xl
- Card grids: Stack on mobile → side-by-side at lg, optional ratio adjustments at xl
- Sidebar layouts: Full-width mobile → fixed sidebar (280-360px range) + fluid content at lg+
**Flex Layouts:**
- Horizontal rows: MUST stack vertically on mobile (`flex-col`), go horizontal at breakpoint
- Split panels: Vertical stack mobile → horizontal at lg, always include min-height
**Form Controls & Inputs:**
- Search inputs: Full width mobile → fixed ~160px at sm
- Select dropdowns: Full width mobile → fixed ~176px at sm
- Date pickers: Full width mobile → ~260px at sm
- Control wrappers: Flex-wrap, full width mobile → auto width at sm+
**Sidebar Panel Widths:**
- Scale progressively: full width mobile → increasing fixed widths at md/lg/xl
- Must include flex-shrink-0 to prevent compression
**Data Tables:**
- Wrap in horizontal scroll container
- Set minimum width (400-600px) to prevent column squishing
**Dynamic Heights - CRITICAL:**
When using viewport-based heights like `h-[calc(100vh-Xpx)]`, ALWAYS pair with minimum height:
- Split panels/complex layouts: min-h-[500px]
- Data tables: min-h-[400px]
- Dashboards: min-h-[600px]
- Simple cards: min-h-[300px]
**Spacing:**
- Page padding should scale: tighter on mobile (px-4), more generous on desktop (lg:px-6)
**Anti-Patterns to Flag:**
| Bad Pattern | Issue | Fix |
| ------------------------- | -------------------------------- | ------------------------------ |
| `w-[300px]` | Fixed width breaks mobile | `w-full sm:w-[280px]` |
| `xl:grid-cols-2` only | Missing intermediate breakpoints | `md:grid-cols-2 lg:... xl:...` |
| `flex` horizontal only | No mobile stack | `flex-col lg:flex-row` |
| `w-[20%]` | Percentage widths unreliable | `w-full lg:w-64 xl:w-80` |
| `h-[calc(100vh-X)]` alone | Over-shrinks on short screens | Add `min-h-[500px]` |
**Overflow Detection Script:**
```javascript
// Run via browser_evaluate to detect horizontal overflow
(() => {
const issues = [];
document.querySelectorAll("*").forEach((el) => {
if (el.scrollWidth > el.clientWidth) {
issues.push({
element:
el.tagName + (el.className ? "." + el.className.split(" ")[0] : ""),
overflow: el.scrollWidth - el.clientWidth,
});
}
});
return issues.length ? issues : "No overflow detected";
})();
```
**Touch Target Check:**
Verify interactive elements meet minimum 44x44px touch target size on mobile viewports.
**Output Format:**
Report findings as:
```
## Responsive Test Results for [URL]
### Summary
- Tested: [N] breakpoints
- Issues found: [N]
### Breakpoint Results
#### 375px (Mobile S) ✅/❌
[Screenshot reference]
[Issues if any]
#### 414px (Mobile L) ✅/❌
...
### Issues Found
1. [Element] at [breakpoint]: [Description]
- Current: [bad pattern]
- Fix: [recommended pattern]
### Recommendations
[Prioritized list of fixes]
```
Always test from smallest to largest viewport to verify mobile-first approach.

154
agents/claude-codex-settings/plugin-dev-agent-creator.md Normal file
View File

@@ -0,0 +1,154 @@
---
name: agent-creator
description: |-
Use this agent when the user asks to "create an agent", "generate an agent", "build a new agent", "make me an agent that...", or describes agent functionality they need. Trigger when user wants to create autonomous agents for plugins. Examples:\n\n<example>\nContext: User wants to create a code review agent\nuser: "Create an agent that reviews code for quality issues"\nassistant: "I'll use the agent-creator agent to generate the agent configuration."\n<commentary>\nUser requesting new agent creation, trigger agent-creator to generate it.\n</commentary>\n</example>\n\n<example>\nContext: User describes needed functionality\nuser: "I need an agent that generates unit tests for my code"\nassistant: "I'll use the agent-creator agent to create a test generation agent."\n<commentary>\nUser describes agent need, trigger agent-creator to build it.\n</commentary>\n</example>\n\n<example>\nContext: User wants to add agent to plugin\nuser: "Add an agent to my plugin that validates configurations"\nassistant: "I'll use the agent-creator agent to generate a configuration validator agent."\n<commentary>\nPlugin development with agent addition, trigger agent-creator.\n</commentary>\n</example>
model: inherit
color: magenta
tools: ["Write", "Read"]
skills: agent-development, plugin-structure
---
You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.
**Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.
When a user describes what they want an agent to do, you will:
1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.
2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.
3. **Architect Comprehensive Instructions**: Develop a system prompt that:
- Establishes clear behavioral boundaries and operational parameters
- Provides specific methodologies and best practices for task execution
- Anticipates edge cases and provides guidance for handling them
- Incorporates any specific requirements or preferences mentioned by the user
- Defines output format expectations when relevant
- Aligns with project-specific coding standards and patterns from CLAUDE.md
4. **Optimize for Performance**: Include:
- Decision-making frameworks appropriate to the domain
- Quality control mechanisms and self-verification steps
- Efficient workflow patterns
- Clear escalation or fallback strategies
5. **Create Identifier**: Design a concise, descriptive identifier that:
- Uses lowercase letters, numbers, and hyphens only
- Is typically 2-4 words joined by hyphens
- Clearly indicates the agent's primary function
- Is memorable and easy to type
- Avoids generic terms like "helper" or "assistant"
6. **Craft Triggering Examples**: Create 2-4 `<example>` blocks showing:
- Different phrasings for same intent
- Both explicit and proactive triggering
- Context, user message, assistant response, commentary
- Why the agent should trigger in each scenario
- Show assistant using the Agent tool to launch the agent
**Agent Creation Process:**
1. **Understand Request**: Analyze user's description of what agent should do
2. **Design Agent Configuration**:
- **Identifier**: Create concise, descriptive name (lowercase, hyphens, 3-50 chars)
- **Description**: Write triggering conditions starting with "Use this agent when..."
- **Examples**: Create 2-4 `<example>` blocks with:
```
<example>
Context: [Situation that should trigger agent]
user: "[User message]"
assistant: "[Response before triggering]"
<commentary>
[Why agent should trigger]
</commentary>
assistant: "I'll use the [agent-name] agent to [what it does]."
</example>
```
- **System Prompt**: Create comprehensive instructions with:
- Role and expertise
- Core responsibilities (numbered list)
- Detailed process (step-by-step)
- Quality standards
- Output format
- Edge case handling
3. **Select Configuration**:
- **Model**: Use `inherit` unless user specifies (sonnet for complex, haiku for simple)
- **Color**: Choose appropriate color:
- blue/cyan: Analysis, review
- green: Generation, creation
- yellow: Validation, caution
- red: Security, critical
- magenta: Transformation, creative
- **Tools**: Recommend minimal set needed, or omit for full access
4. **Generate Agent File**: Use Write tool to create `agents/[identifier].md`:
```markdown
---
name: [identifier]
description: [Use this agent when... Examples: <example>...</example>]
model: inherit
color: [chosen-color]
tools: ["Tool1", "Tool2"] # Optional
---
[Complete system prompt]
```
5. **Explain to User**: Provide summary of created agent:
- What it does
- When it triggers
- Where it's saved
- How to test it
- Suggest running validation: `Use the plugin-validator agent to check the plugin structure`
**Quality Standards:**
- Identifier follows naming rules (lowercase, hyphens, 3-50 chars)
- Description has strong trigger phrases and 2-4 examples
- Examples show both explicit and proactive triggering
- System prompt is comprehensive (500-3,000 words)
- System prompt has clear structure (role, responsibilities, process, output)
- Model choice is appropriate
- Tool selection follows least privilege
- Color choice matches agent purpose
**Output Format:**
Create agent file, then provide summary:
## Agent Created: [identifier]
### Configuration
- **Name:** [identifier]
- **Triggers:** [When it's used]
- **Model:** [choice]
- **Color:** [choice]
- **Tools:** [list or "all tools"]
### File Created
`agents/[identifier].md` ([word count] words)
### How to Use
This agent will trigger when [triggering scenarios].
Test it by: [suggest test scenario]
Validate with: `scripts/validate-agent.sh agents/[identifier].md`
### Next Steps
[Recommendations for testing, integration, or improvements]
**Edge Cases:**
- Vague user request: Ask clarifying questions before generating
- Conflicts with existing agents: Note conflict, suggest different scope/name
- Very complex requirements: Break into multiple specialized agents
- User wants specific tool access: Honor the request in agent configuration
- User specifies model: Use specified model instead of inherit
- First agent in plugin: Create agents/ directory first

165
agents/claude-codex-settings/plugin-dev-plugin-validator.md Normal file
View File

@@ -0,0 +1,165 @@
---
name: plugin-validator
description: |-
Use this agent when the user asks to "validate my plugin", "check plugin structure", "verify plugin is correct", "validate plugin.json", "check plugin files", or mentions plugin validation. Also trigger proactively after user creates or modifies plugin components. Examples:\n\n<example>\nContext: User finished creating a new plugin\nuser: "I've created my first plugin with commands and hooks"\nassistant: "Great! Let me validate the plugin structure."\n<commentary>\nPlugin created, proactively validate to catch issues early.\n</commentary>\nassistant: "I'll use the plugin-validator agent to check the plugin."\n</example>\n\n<example>\nContext: User explicitly requests validation\nuser: "Validate my plugin before I publish it"\nassistant: "I'll use the plugin-validator agent to perform comprehensive validation."\n<commentary>\nExplicit validation request triggers the agent.\n</commentary>\n</example>\n\n<example>\nContext: User modified plugin.json\nuser: "I've updated the plugin manifest"\nassistant: "Let me validate the changes."\n<commentary>\nManifest modified, validate to ensure correctness.\n</commentary>\nassistant: "I'll use the plugin-validator agent to check the manifest."\n</example>
model: inherit
color: yellow
tools: ["Read", "Grep", "Glob", "Bash"]
skills: plugin-structure, command-development, agent-development, skill-development, hook-development, mcp-integration
---
You are an expert plugin validator specializing in comprehensive validation of Claude Code plugin structure, configuration, and components.
**Your Core Responsibilities:**
1. Validate plugin structure and organization
2. Check plugin.json manifest for correctness
3. Validate all component files (commands, agents, skills, hooks)
4. Verify naming conventions and file organization
5. Check for common issues and anti-patterns
6. Provide specific, actionable recommendations
**Validation Process:**
1. **Locate Plugin Root**:
- Check for `.claude-plugin/plugin.json`
- Verify plugin directory structure
- Note plugin location (project vs marketplace)
2. **Validate Manifest** (`.claude-plugin/plugin.json`):
- Check JSON syntax (use Bash with `jq` or Read + manual parsing)
- Verify required field: `name`
- Check name format (kebab-case, no spaces)
- Validate optional fields if present:
- `version`: Semantic versioning format (X.Y.Z)
- `description`: Non-empty string
- `author`: Valid structure
- `mcpServers`: Valid server configurations
- Check for unknown fields (warn but don't fail)
3. **Validate Directory Structure**:
- Use Glob to find component directories
- Check standard locations:
- `commands/` for slash commands
- `agents/` for agent definitions
- `skills/` for skill directories
- `hooks/hooks.json` for hooks
- Verify auto-discovery works
4. **Validate Commands** (if `commands/` exists):
- Use Glob to find `commands/**/*.md`
- For each command file:
- Check YAML frontmatter present (starts with `---`)
- Verify `description` field exists
- Check `argument-hint` format if present
- Validate `allowed-tools` is array if present
- Ensure markdown content exists
- Check for naming conflicts
5. **Validate Agents** (if `agents/` exists):
- Use Glob to find `agents/**/*.md`
- For each agent file:
- Use the validate-agent.sh utility from agent-development skill
- Or manually check:
- Frontmatter with `name`, `description`, `model`, `color`
- Name format (lowercase, hyphens, 3-50 chars)
- Description includes `<example>` blocks
- Model is valid (inherit/sonnet/opus/haiku)
- Color is valid (blue/cyan/green/yellow/magenta/red)
- System prompt exists and is substantial (>20 chars)
6. **Validate Skills** (if `skills/` exists):
- Use Glob to find `skills/*/SKILL.md`
- For each skill directory:
- Verify `SKILL.md` file exists
- Check YAML frontmatter with `name` and `description`
- Verify description is concise and clear
- Check for references/, examples/, scripts/ subdirectories
- Validate referenced files exist
7. **Validate Hooks** (if `hooks/hooks.json` exists):
- Use the validate-hook-schema.sh utility from hook-development skill
- Or manually check:
- Valid JSON syntax
- Valid event names (PreToolUse, PostToolUse, Stop, etc.)
- Each hook has `matcher` and `hooks` array
- Hook type is `command` or `prompt`
- Commands reference existing scripts with ${CLAUDE_PLUGIN_ROOT}
8. **Validate MCP Configuration** (if `.mcp.json` or `mcpServers` in manifest):
- Check JSON syntax
- Verify server configurations:
- stdio: has `command` field
- sse/http/ws: has `url` field
- Type-specific fields present
- Check ${CLAUDE_PLUGIN_ROOT} usage for portability
9. **Check File Organization**:
- README.md exists and is comprehensive
- No unnecessary files (node_modules, .DS_Store, etc.)
- .gitignore present if needed
- LICENSE file present
10. **Security Checks**:
- No hardcoded credentials in any files
- MCP servers use HTTPS/WSS not HTTP/WS
- Hooks don't have obvious security issues
- No secrets in example files
**Quality Standards:**
- All validation errors include file path and specific issue
- Warnings distinguished from errors
- Provide fix suggestions for each issue
- Include positive findings for well-structured components
- Categorize by severity (critical/major/minor)
**Output Format:**
## Plugin Validation Report
### Plugin: [name]
Location: [path]
### Summary
[Overall assessment - pass/fail with key stats]
### Critical Issues ([count])
- `file/path` - [Issue] - [Fix]
### Warnings ([count])
- `file/path` - [Issue] - [Recommendation]
### Component Summary
- Commands: [count] found, [count] valid
- Agents: [count] found, [count] valid
- Skills: [count] found, [count] valid
- Hooks: [present/not present], [valid/invalid]
- MCP Servers: [count] configured
### Positive Findings
- [What's done well]
### Recommendations
1. [Priority recommendation]
2. [Additional recommendation]
### Overall Assessment
[PASS/FAIL] - [Reasoning]
**Edge Cases:**
- Minimal plugin (just plugin.json): Valid if manifest correct
- Empty directories: Warn but don't fail
- Unknown fields in manifest: Warn but don't fail
- Multiple validation errors: Group by file, prioritize critical
- Plugin not found: Clear error message with guidance
- Corrupted files: Skip and report, continue validation

172
agents/claude-codex-settings/plugin-dev-skill-reviewer.md Normal file
View File

@@ -0,0 +1,172 @@
---
name: skill-reviewer
description: |-
Use this agent when the user has created or modified a skill and needs quality review, asks to "review my skill", "check skill quality", "improve skill description", or wants to ensure skill follows best practices. Trigger proactively after skill creation. Examples:\n\n<example>\nContext: User just created a new skill\nuser: "I've created a PDF processing skill"\nassistant: "Great! Let me review the skill quality."\n<commentary>\nSkill created, proactively trigger skill-reviewer to ensure it follows best practices.\n</commentary>\nassistant: "I'll use the skill-reviewer agent to review the skill."\n</example>\n\n<example>\nContext: User requests skill review\nuser: "Review my skill and tell me how to improve it"\nassistant: "I'll use the skill-reviewer agent to analyze the skill quality."\n<commentary>\nExplicit skill review request triggers the agent.\n</commentary>\n</example>\n\n<example>\nContext: User modified skill description\nuser: "I updated the skill description, does it look good?"\nassistant: "I'll use the skill-reviewer agent to review the changes."\n<commentary>\nSkill description modified, review for triggering effectiveness.\n</commentary>\n</example>
model: inherit
color: cyan
tools: ["Read", "Grep", "Glob"]
skills: skill-development, plugin-structure
---
You are an expert skill architect specializing in reviewing and improving Claude Code skills for maximum effectiveness and reliability.
**Your Core Responsibilities:**
1. Review skill structure and organization
2. Evaluate description quality and triggering effectiveness
3. Assess progressive disclosure implementation
4. Check adherence to skill-creator best practices
5. Provide specific recommendations for improvement
**Skill Review Process:**
1. **Locate and Read Skill**:
- Find SKILL.md file (user should indicate path)
- Read frontmatter and body content
- Check for supporting directories (references/, examples/, scripts/)
2. **Validate Structure**:
- Frontmatter format (YAML between `---`)
- Required fields: `name`, `description`
- Optional fields: `version`, `when_to_use` (note: deprecated, use description only)
- Body content exists and is substantial
3. **Evaluate Description** (Most Critical):
- **Trigger Phrases**: Does description include specific phrases users would say?
- **Third Person**: Uses "This skill should be used when..." not "Load this skill when..."
- **Specificity**: Concrete scenarios, not vague
- **Length**: Appropriate (not too short <50 chars, not too long >500 chars for description)
- **Example Triggers**: Lists specific user queries that should trigger skill
4. **Assess Content Quality**:
- **Word Count**: SKILL.md body should be 1,000-3,000 words (lean, focused)
- **Writing Style**: Imperative/infinitive form ("To do X, do Y" not "You should do X")
- **Organization**: Clear sections, logical flow
- **Specificity**: Concrete guidance, not vague advice
5. **Check Progressive Disclosure**:
- **Core SKILL.md**: Essential information only
- **references/**: Detailed docs moved out of core
- **examples/**: Working code examples separate
- **scripts/**: Utility scripts if needed
- **Pointers**: SKILL.md references these resources clearly
6. **Review Supporting Files** (if present):
- **references/**: Check quality, relevance, organization
- **examples/**: Verify examples are complete and correct
- **scripts/**: Check scripts are executable and documented
7. **Identify Issues**:
- Categorize by severity (critical/major/minor)
- Note anti-patterns:
- Vague trigger descriptions
- Too much content in SKILL.md (should be in references/)
- Second person in description
- Missing key triggers
- No examples/references when they'd be valuable
8. **Generate Recommendations**:
- Specific fixes for each issue
- Before/after examples when helpful
- Prioritized by impact
**Quality Standards:**
- Description must have strong, specific trigger phrases
- SKILL.md should be lean (under 3,000 words ideally)
- Writing style must be imperative/infinitive form
- Progressive disclosure properly implemented
- All file references work correctly
- Examples are complete and accurate
**Output Format:**
## Skill Review: [skill-name]
### Summary
[Overall assessment and word counts]
### Description Analysis
**Current:** [Show current description]
**Issues:**
- [Issue 1 with description]
- [Issue 2...]
**Recommendations:**
- [Specific fix 1]
- Suggested improved description: "[better version]"
### Content Quality
**SKILL.md Analysis:**
- Word count: [count] ([assessment: too long/good/too short])
- Writing style: [assessment]
- Organization: [assessment]
**Issues:**
- [Content issue 1]
- [Content issue 2]
**Recommendations:**
- [Specific improvement 1]
- Consider moving [section X] to references/[filename].md
### Progressive Disclosure
**Current Structure:**
- SKILL.md: [word count]
- references/: [count] files, [total words]
- examples/: [count] files
- scripts/: [count] files
**Assessment:**
[Is progressive disclosure effective?]
**Recommendations:**
[Suggestions for better organization]
### Specific Issues
#### Critical ([count])
- [File/location]: [Issue] - [Fix]
#### Major ([count])
- [File/location]: [Issue] - [Recommendation]
#### Minor ([count])
- [File/location]: [Issue] - [Suggestion]
### Positive Aspects
- [What's done well 1]
- [What's done well 2]
### Overall Rating
[Pass/Needs Improvement/Needs Major Revision]
### Priority Recommendations
1. [Highest priority fix]
2. [Second priority]
3. [Third priority]
**Edge Cases:**
- Skill with no description issues: Focus on content and organization
- Very long skill (>5,000 words): Strongly recommend splitting into references
- New skill (minimal content): Provide constructive building guidance
- Perfect skill: Acknowledge quality and suggest minor enhancements only
- Missing referenced files: Report errors clearly with paths

92
commands/claude-codex-settings/azure-tools-setup.md Normal file
View File

@@ -0,0 +1,92 @@
---
description: Configure Azure MCP server with Azure CLI authentication
---
# Azure Tools Setup
Configure the Azure MCP server with Azure CLI authentication.
## Step 1: Check Prerequisites
Check if Azure CLI is installed:
```bash
az --version
```
Check if Node.js is installed:
```bash
node --version
```
Report status based on results.
## Step 2: Show Installation Guide
If Azure CLI is missing, tell the user:
```
Azure CLI is required for Azure MCP authentication.
Install Azure CLI:
- macOS: brew install azure-cli
- Linux: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
- Windows: winget install Microsoft.AzureCLI
After installing, restart your terminal and run this setup again.
```
If Node.js is missing, tell the user:
```
Node.js 20 LTS or later is required for Azure MCP.
Install Node.js:
- macOS: brew install node@20
- Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs
- Windows: winget install OpenJS.NodeJS.LTS
After installing, restart your terminal and run this setup again.
```
## Step 3: Check Authentication
If prerequisites are installed, check Azure login status:
```bash
az account show
```
If not logged in, tell the user:
```
You need to authenticate to Azure.
Run: az login
This opens a browser for authentication. After signing in, you can close the browser.
```
## Step 4: Verify Configuration
After authentication, verify:
1. Read `${CLAUDE_PLUGIN_ROOT}/.mcp.json` to confirm Azure MCP is configured
2. Tell the user the current configuration
## Step 5: Confirm Success
Tell the user:
```
Azure MCP is configured!
IMPORTANT: Restart Claude Code for changes to take effect.
- Exit Claude Code
- Run `claude` again
To verify after restart, run /mcp and check that 'azure' server is connected.
Reference: https://github.com/microsoft/mcp/tree/main/servers/Azure.Mcp.Server
```

379
commands/claude-codex-settings/ccproxy-tools-setup.md Normal file
View File

@@ -0,0 +1,379 @@
---
description: Configure ccproxy/LiteLLM to use Claude Code with any LLM provider
---
# ccproxy-tools Setup
Configure Claude Code to use ccproxy/LiteLLM with Claude Pro/Max subscription, GitHub Copilot, or other LLM providers.
## Step 1: Check Prerequisites
Check if `uv` is installed:
```bash
which uv
```
If not installed, install it:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Then reload shell or run `source ~/.bashrc` (or `~/.zshrc`).
## Step 2: Ask Provider Choice
Use AskUserQuestion:
- question: "Which LLM provider do you want to use with Claude Code?"
- header: "Provider"
- options:
- label: "Claude Pro/Max (ccproxy)"
description: "Use your Claude subscription via OAuth - no API keys needed"
- label: "GitHub Copilot (LiteLLM)"
description: "Use GitHub Copilot subscription via LiteLLM proxy"
- label: "OpenAI API (LiteLLM)"
description: "Use OpenAI models via LiteLLM proxy"
- label: "Gemini API (LiteLLM)"
description: "Use Google Gemini models via LiteLLM proxy"
## Step 3: Install Proxy Tool
### If Claude Pro/Max (ccproxy)
Install and initialize ccproxy:
```bash
uv tool install ccproxy
ccproxy init
```
### If GitHub Copilot, OpenAI, or Gemini (LiteLLM)
Install LiteLLM:
```bash
uv tool install 'litellm[proxy]'
```
## Step 4: Configure LiteLLM (if applicable)
### For GitHub Copilot
Auto-detect VS Code and Copilot versions:
```bash
# Get VS Code version
VSCODE_VERSION=$(code --version 2> /dev/null | head -1 || echo "1.96.0")
# Find Copilot Chat extension version
COPILOT_VERSION=$(ls ~/.vscode/extensions/ 2> /dev/null | grep "github.copilot-chat-" | sed 's/github.copilot-chat-//' | sort -V | tail -1 || echo "0.26.7")
```
Create `~/.litellm/config.yaml` with detected versions:
```yaml
general_settings:
master_key: sk-dummy
litellm_settings:
drop_params: true
model_list:
- model_name: "*"
litellm_params:
model: "github_copilot/*"
extra_headers:
editor-version: "vscode/${VSCODE_VERSION}"
editor-plugin-version: "copilot-chat/${COPILOT_VERSION}"
Copilot-Integration-Id: "vscode-chat"
user-agent: "GitHubCopilotChat/${COPILOT_VERSION}"
```
### For OpenAI API
Ask for OpenAI API key using AskUserQuestion:
- question: "Enter your OpenAI API key (starts with sk-):"
- header: "OpenAI Key"
- options:
- label: "I have it ready"
description: "I'll paste my OpenAI API key"
- label: "Skip for now"
description: "I'll configure it later"
Create `~/.litellm/config.yaml`:
```yaml
general_settings:
master_key: sk-dummy
litellm_settings:
drop_params: true
model_list:
- model_name: "*"
litellm_params:
model: openai/gpt-4o
api_key: ${OPENAI_API_KEY}
```
### For Gemini API
Ask for Gemini API key using AskUserQuestion:
- question: "Enter your Gemini API key:"
- header: "Gemini Key"
- options:
- label: "I have it ready"
description: "I'll paste my Gemini API key"
- label: "Skip for now"
description: "I'll configure it later"
Create `~/.litellm/config.yaml`:
```yaml
general_settings:
master_key: sk-dummy
litellm_settings:
drop_params: true
model_list:
- model_name: "*"
litellm_params:
model: gemini/gemini-2.5-flash
api_key: ${GEMINI_API_KEY}
```
## Step 5: Setup Auto-Start Service
Detect platform and create appropriate service:
### macOS (launchd)
For ccproxy, create `~/Library/LaunchAgents/com.ccproxy.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.ccproxy</string>
<key>ProgramArguments</key>
<array>
<string>${HOME}/.local/bin/ccproxy</string>
<string>start</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>${HOME}/.local/share/ccproxy/stdout.log</string>
<key>StandardErrorPath</key>
<string>${HOME}/.local/share/ccproxy/stderr.log</string>
</dict>
</plist>
```
For LiteLLM, create `~/Library/LaunchAgents/com.litellm.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.litellm</string>
<key>ProgramArguments</key>
<array>
<string>${HOME}/.local/bin/litellm</string>
<string>--config</string>
<string>${HOME}/.litellm/config.yaml</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>${HOME}/.local/share/litellm/stdout.log</string>
<key>StandardErrorPath</key>
<string>${HOME}/.local/share/litellm/stderr.log</string>
</dict>
</plist>
```
Load and start the service:
```bash
launchctl load ~/Library/LaunchAgents/com.ccproxy.plist # or com.litellm.plist
```
### Linux (systemd user service)
For ccproxy, create `~/.config/systemd/user/ccproxy.service`:
```ini
[Unit]
Description=ccproxy LLM Proxy
[Service]
ExecStart=%h/.local/bin/ccproxy start
Restart=always
RestartSec=5
[Install]
WantedBy=default.target
```
For LiteLLM, create `~/.config/systemd/user/litellm.service`:
```ini
[Unit]
Description=LiteLLM Proxy
[Service]
ExecStart=%h/.local/bin/litellm --config %h/.litellm/config.yaml
Restart=always
RestartSec=5
[Install]
WantedBy=default.target
```
Enable and start the service:
```bash
systemctl --user daemon-reload
systemctl --user enable --now ccproxy # or litellm
```
## Step 6: Authenticate (ccproxy only)
For ccproxy, tell the user:
```
The proxy is starting. A browser window will open for authentication.
1. Sign in with your Claude Pro/Max account
2. Authorize the connection
3. Return here after successful authentication
```
Wait for authentication to complete.
## Step 7: Verify Proxy is Running
Check if proxy is healthy:
```bash
curl -s http://localhost:4000/health
```
Retry up to 5 times with 3-second delays if not responding.
If proxy is not healthy after retries:
- Show error and troubleshooting steps
- Do NOT proceed to update settings
- Exit
## Step 8: Confirm Before Updating Settings
Use AskUserQuestion:
- question: "Proxy is running. Ready to configure Claude Code to use it?"
- header: "Configure"
- options:
- label: "Yes, configure now"
description: "Update settings to use the proxy (requires restart)"
- label: "No, not yet"
description: "Keep current settings, I'll configure later"
If user selects "No, not yet":
- Tell them they can run `/ccproxy-tools:setup` again when ready
- Exit without changing settings
## Step 9: Update Settings
1. Read current `~/.claude/settings.json`
2. Create backup at `~/.claude/settings.json.backup`
3. Add to env section based on provider:
For ccproxy:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:4000"
}
}
```
For LiteLLM:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:4000",
"ANTHROPIC_AUTH_TOKEN": "sk-dummy"
}
}
```
4. Write updated settings
## Step 10: Confirm Success
Tell the user:
```
Configuration complete!
IMPORTANT: Restart Claude Code for changes to take effect.
- Exit Claude Code
- Run `claude` again
The proxy will start automatically on system boot.
To verify after restart:
- Claude Code should connect to the proxy at localhost:4000
- Check proxy logs: ~/Library/LaunchAgents/*.log (macOS) or journalctl --user -u ccproxy (Linux)
```
## Recovery Instructions
Always show these recovery instructions:
```
If Claude Code stops working after setup:
1. Check proxy status:
curl http://localhost:4000/health
2. Restart proxy:
macOS: launchctl kickstart -k gui/$(id -u)/com.ccproxy
Linux: systemctl --user restart ccproxy
3. Check proxy logs:
macOS: cat ~/.local/share/ccproxy/stderr.log
Linux: journalctl --user -u ccproxy
4. Restore original settings (removes proxy):
cp ~/.claude/settings.json.backup ~/.claude/settings.json
Or manually edit ~/.claude/settings.json and remove:
- ANTHROPIC_BASE_URL
- ANTHROPIC_AUTH_TOKEN (if present)
```
## Troubleshooting
If proxy setup fails:
```
Common fixes:
1. Port in use - Check if another process uses port 4000: lsof -i :4000
2. Service not starting - Check logs in ~/.local/share/ccproxy/ or ~/.local/share/litellm/
3. Authentication failed - Re-run setup to re-authenticate
4. Permission denied - Ensure ~/.local/bin is in PATH
5. Config invalid - Verify ~/.litellm/config.yaml syntax
```

12
commands/claude-codex-settings/claude-tools-load-claude-md.md Normal file
View File

@@ -0,0 +1,12 @@
---
allowed-tools: Read
description: Refresh context with CLAUDE.md instructions
---
# Load CLAUDE.md
Read and inject CLAUDE.md content into the current context. Useful for refreshing instructions in long conversations.
1. Read `~/.claude/CLAUDE.md` (global instructions)
2. Read `CLAUDE.md` or `AGENTS.md` from the current project directory (whichever exists)
3. Acknowledge that context has been refreshed with these instructions

13
commands/claude-codex-settings/claude-tools-load-frontend-skill.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: Load frontend design skill from Anthropic
allowed-tools: WebFetch
---
# Load Frontend Design Skill
Load the frontend-design skill from Anthropic's official Claude Code plugins to guide creation of distinctive, production-grade frontend interfaces.
Fetch from:
https://raw.githubusercontent.com/anthropics/claude-code/main/plugins/frontend-design/skills/frontend-design/SKILL.md
Use this guidance when building web components, pages, or applications that require high design quality and avoid generic AI aesthetics.

17
commands/claude-codex-settings/claude-tools-sync-allowlist.md Normal file
View File

@@ -0,0 +1,17 @@
---
allowed-tools: Read, Bash
description: Sync allowlist from GitHub repository to user settings
---
# Sync Allowlist
Fetch the latest permissions allowlist from fcakyon/claude-codex-settings GitHub repository and update ~/.claude/settings.json.
Steps:
1. Use `gh api repos/fcakyon/claude-settings/contents/.claude/settings.json --jq '.content' | base64 -d` to fetch settings
2. Parse the JSON and extract the `permissions.allow` array
3. Read the user's `~/.claude/settings.json`
4. Update only the `permissions.allow` field (preserve all other user settings)
5. Write back to `~/.claude/settings.json`
6. Confirm with a message showing count of allowlist entries synced

10
commands/claude-codex-settings/claude-tools-sync-claude-md.md Normal file
View File

@@ -0,0 +1,10 @@
---
allowed-tools: Read, Bash
description: Sync CLAUDE.md from GitHub repository
---
# Sync CLAUDE.md
Fetch the latest CLAUDE.md from fcakyon/claude-codex-settings GitHub repository and update ~/.claude/CLAUDE.md.
Use `gh api repos/fcakyon/claude-codex-settings/contents/CLAUDE.md --jq '.content' | base64 -d` to fetch the file content, then write to ~/.claude/CLAUDE.md. Confirm successful update with a message showing the file has been synced.

104
commands/claude-codex-settings/gcloud-tools-setup.md Normal file
View File

@@ -0,0 +1,104 @@
---
description: Configure GCloud CLI authentication
---
# GCloud Tools Setup
**Source:** [googleapis/gcloud-mcp](https://github.com/googleapis/gcloud-mcp)
Check GCloud MCP status and configure CLI authentication if needed.
## Step 1: Check gcloud CLI
Run: `gcloud --version`
If not installed: Continue to Step 2.
If installed: Skip to Step 3.
## Step 2: Install gcloud CLI
Tell the user:
```
Install Google Cloud SDK:
macOS (Homebrew):
brew install google-cloud-sdk
macOS/Linux (Manual):
curl https://sdk.cloud.google.com | bash
exec -l $SHELL
Windows:
Download from: https://cloud.google.com/sdk/docs/install
After install, restart your terminal.
```
## Step 3: Authenticate
Run these commands:
```bash
# Login with your Google account
gcloud auth login
# Set up Application Default Credentials (required for MCP)
gcloud auth application-default login
```
Both commands will open a browser for authentication.
## Step 4: Set Default Project
```bash
# List available projects
gcloud projects list
# Set default project
gcloud config set project YOUR_PROJECT_ID
```
## Step 5: Verify Setup
Run: `gcloud auth list`
Should show your authenticated account with asterisk (\*).
## Step 6: Restart Claude Code
Tell the user:
```
After authentication:
1. Exit Claude Code
2. Run `claude` again
The MCP will use your gcloud credentials.
```
## Troubleshooting
If GCloud MCP fails:
```
Common fixes:
1. ADC not found - Run gcloud auth application-default login
2. Project not set - Run gcloud config set project PROJECT_ID
3. Permission denied - Check IAM roles in Cloud Console
4. Quota exceeded - Check quotas in Cloud Console
5. Token expired - Run gcloud auth application-default login again
```
## Alternative: Disable Plugin
If user doesn't need GCloud integration:
```
To disable this plugin:
1. Run /mcp command
2. Find the gcloud-observability server
3. Disable it
This prevents errors from missing authentication.
```

44
commands/claude-codex-settings/github-dev-clean-gone-branches.md Normal file
View File

@@ -0,0 +1,44 @@
---
description: Clean up local branches deleted from remote
---
# Clean Gone Branches
Remove local git branches that have been deleted from remote (marked as [gone]).
## Instructions
Run the following commands in sequence:
1. **Update remote references:**
```bash
git fetch --prune
```
2. **View branches marked as [gone]:**
```bash
git branch -vv
```
3. **List worktrees (if any):**
```bash
git worktree list
```
4. **Remove worktrees for gone branches (if any):**
```bash
git branch -vv | grep '\[gone\]' | awk '{print $1}' | sed 's/^[*+]*//' | while read -r branch; do
worktree=$(git worktree list | grep "\[$branch\]" | awk '{print $1}')
if [ -n "$worktree" ]; then
echo "Removing worktree: $worktree"
git worktree remove --force "$worktree"
fi
done
```
5. **Delete gone branches:**
```bash
git branch -vv | grep '\[gone\]' | awk '{print $1}' | sed 's/^[*+]*//' | xargs -I {} git branch -D {}
```
Report the results: list of removed worktrees and deleted branches, or notify if no [gone] branches exist.

19
commands/claude-codex-settings/github-dev-commit-staged.md Normal file
View File

@@ -0,0 +1,19 @@
---
allowed-tools: Task, Read, Grep, SlashCommand
argument-hint: [context]
description: Commit staged changes with optional context
---
# Commit Staged Changes
Use the commit-creator agent to analyze and commit staged changes with intelligent organization and optimal commit strategy.
## Additional Context
$ARGUMENTS
Task(
description: "Analyze and commit staged changes",
prompt: "Analyze the staged changes and create appropriate commits. Additional context: $ARGUMENTS",
subagent_type: "github-dev:commit-creator"
)

19
commands/claude-codex-settings/github-dev-create-pr.md Normal file
View File

@@ -0,0 +1,19 @@
---
allowed-tools: Task, Read, Grep, SlashCommand, Bash(git checkout:*), Bash(git -C:* checkout:*)
argument-hint: [context]
description: Create pull request with optional context
---
# Create Pull Request
Use the pr-creator agent to handle the complete PR workflow including branch creation, commits, and PR submission.
## Additional Context
$ARGUMENTS
Task(
description: "Create pull request",
prompt: "Handle the complete PR workflow including branch creation, commits, and PR submission. Additional context: $ARGUMENTS",
subagent_type: "github-dev:pr-creator"
)

19
commands/claude-codex-settings/github-dev-review-pr.md Normal file
View File

@@ -0,0 +1,19 @@
---
allowed-tools: Task, Read, Grep, Glob
argument-hint: <PR number or URL>
description: Review a pull request for code quality and issues
---
# Review Pull Request
Use the pr-reviewer agent to analyze the pull request and provide a detailed code review.
## PR Reference
$ARGUMENTS
Task(
description: "Review pull request",
prompt: "Review the pull request and provide detailed feedback on code quality, potential bugs, and suggestions. PR reference: $ARGUMENTS",
subagent_type: "github-dev:pr-reviewer"
)

53
commands/claude-codex-settings/github-dev-setup.md Normal file
View File

@@ -0,0 +1,53 @@
---
description: Configure GitHub CLI authentication
---
# GitHub CLI Setup
**Source:** [github/github-mcp-server](https://github.com/github/github-mcp-server)
Configure `gh` CLI for GitHub access.
## Step 1: Check Current Status
Run `gh auth status` to check authentication state.
Report status:
- "GitHub CLI is not authenticated - needs login"
- OR "GitHub CLI is authenticated as <username>"
## Step 2: If Not Authenticated
Guide the user:
```
To authenticate with GitHub CLI:
gh auth login
This will open a browser for GitHub OAuth login.
Select: GitHub.com → HTTPS → Login with browser
```
## Step 3: Verify Setup
After login, verify with:
```bash
gh auth status
gh api user --jq '.login'
```
## Troubleshooting
If `gh` commands fail:
```
Common fixes:
1. Check authentication - gh auth status
2. Re-login - gh auth login
3. Missing scopes - re-auth with required permissions
4. Update gh CLI - brew upgrade gh (or equivalent)
5. Token expired - gh auth refresh
```

118
commands/claude-codex-settings/github-dev-update-pr-summary.md Normal file
View File

@@ -0,0 +1,118 @@
# Claude Command: Update PR Summary
Update PR description with automatically generated summary based on complete changeset.
## Usage
```bash
/update-pr-summary <pr_number> # Update PR description
/update-pr-summary 131 # Example: update PR #131
```
## Workflow Steps
1. **Fetch PR Information**:
- Get PR details using `gh pr view <pr_number> --json title,body,baseRefName,headRefName`
- Identify base branch and head branch from PR metadata
2. **Analyze Complete Changeset**:
- **IMPORTANT**: Analyze ALL committed changes in the branch using `git diff <base-branch>...HEAD`
- PR description must describe the complete changeset across all commits, not just the latest commit
- Focus on what changed from the perspective of someone reviewing the entire branch
- Ignore unstaged changes
3. **Generate PR Description**:
- Create brief summary (1 sentence or few words)
- Add few bullet points of key changes
- For significant changes, include before/after code examples in PR body
- Include inline markdown links to relevant code lines when helpful (format: `[src/auth.py:42](src/auth.py#L42)`)
- For config/API changes, use `mcp__tavily__tavily_search` to verify information and include source links inline
- Never include test plans in PR descriptions
4. **Update PR Title** (if needed):
- Title should start with capital letter and verb
- Should NOT start with conventional commit prefixes (e.g. "fix:", "feat:")
5. **Update PR**:
- Use `gh pr edit <pr_number>` with `--body` (and optionally `--title`) to update the PR
- Use HEREDOC for proper formatting:
```bash
gh pr edit "$(
cat << 'EOF'
[PR description here]
EOF
)" < pr_number > --body
```
## PR Description Format
```markdown
[Brief summary in 1 sentence or few words]
- [Key change 1 with inline code reference if helpful]
- [Key change 2 with source link if config/API change]
- [Key change 3]
[Optional: Before/after code examples for significant changes]
```
## Examples
### Example 1: Config/API Change with Source Links
```markdown
Update Claude Haiku to version 4.5
- Model ID: claude-3-haiku-20240307 → claude-haiku-4-5-20251001 ([source](https://docs.anthropic.com/en/docs/about-claude/models/overview))
- Pricing: $0.80/$4.00 → $1.00/$5.00 per MTok ([source](https://docs.anthropic.com/en/docs/about-claude/pricing))
- Max output: 4,096 → 64,000 tokens ([source](https://docs.anthropic.com/en/docs/about-claude/models/overview))
```
### Example 2: Code Changes with File Links
````markdown
Refactor authentication to use async context manager
- Replace synchronous auth flow with async/await pattern in [src/auth.py:15-42](src/auth.py#L15-L42)
- Add context manager support for automatic cleanup
Before:
```python
def authenticate(token):
session = create_session(token)
return session
```
After:
```python
async def authenticate(token):
async with create_session(token) as session:
return session
```
````
### Example 3: Simple Feature Addition
```markdown
Add user profile export functionality
- Export user data to JSON format in [src/export.py:45-78](src/export.py#L45-L78)
- Add CLI command `/export-profile` in [src/cli.py:123](src/cli.py#L123)
- Include email, preferences, and activity history in export
```
## Error Handling
**Pre-Analysis Verification**:
- Verify PR exists and is accessible
- Check tool availability (`gh auth status`)
- Confirm authentication status
**Common Issues**:
- Invalid PR number → List available PRs
- Missing tools → Provide setup instructions
- Auth issues → Guide through authentication

74
commands/claude-codex-settings/linear-tools-setup.md Normal file
View File

@@ -0,0 +1,74 @@
---
description: Configure Linear OAuth authentication
---
# Linear Tools Setup
**Source:** [Linear MCP Docs](https://linear.app/docs/mcp)
Check Linear MCP status and configure OAuth if needed.
## Step 1: Test Current Setup
Try listing teams using `mcp__linear__list_teams`.
If successful: Tell user Linear is configured and working.
If fails with authentication error: Continue to Step 2.
## Step 2: OAuth Authentication
Linear uses OAuth - no API keys needed. Tell the user:
```
Linear MCP uses OAuth authentication.
To authenticate:
1. Run the /mcp command in Claude Code
2. Find the "linear" server in the list
3. Click "Authenticate" or similar option
4. A browser window will open
5. Sign in to Linear and authorize access
```
## Step 3: Complete OAuth Flow
After user clicks authenticate:
- Browser opens to Linear authorization page
- User signs in with their Linear account
- User approves the permission request
- Browser shows success message
- Claude Code receives the token automatically
## Step 4: Verify Setup
Try listing teams again using `mcp__linear__list_teams`.
If successful: Linear is now configured.
## Troubleshooting
If OAuth fails:
```
Common fixes:
1. Clear browser cookies for linear.app
2. Try a different browser
3. Disable browser extensions
4. Re-run /mcp and authenticate again
5. Restart Claude Code and try again
```
## Alternative: Disable Plugin
If user doesn't need Linear integration:
```
To disable this plugin:
1. Run /mcp command
2. Find the linear server
3. Disable it
This prevents errors from missing authentication.
```

112
commands/claude-codex-settings/mongodb-tools-setup.md Normal file
View File

@@ -0,0 +1,112 @@
---
description: Configure MongoDB MCP connection
---
# MongoDB Tools Setup
**Source:** [mongodb-js/mongodb-mcp-server](https://github.com/mongodb-js/mongodb-mcp-server)
Configure the MongoDB MCP server with your connection string.
## Step 1: Check Current Status
Read the MCP configuration from `${CLAUDE_PLUGIN_ROOT}/.mcp.json`.
Check if MongoDB is configured:
- If `mongodb.env.MDB_MCP_CONNECTION_STRING` contains `REPLACE_WITH_CONNECTION_STRING`, it needs configuration
- If it contains a value starting with `mongodb://` or `mongodb+srv://`, already configured
Report status:
- "MongoDB MCP is not configured - needs a connection string"
- OR "MongoDB MCP is already configured"
## Step 2: Show Setup Guide
Tell the user:
```
To configure MongoDB MCP, you need a connection string.
Formats:
- Atlas: mongodb+srv://username:password@cluster.mongodb.net/database
- Local: mongodb://localhost:27017/database
Get Atlas connection string:
1. Go to cloud.mongodb.com
2. Navigate to your cluster
3. Click "Connect" → "Drivers"
4. Copy connection string
Note: MCP runs in READ-ONLY mode.
Don't need MongoDB MCP? Disable it via /mcp command.
```
## Step 3: Ask for Connection String
Use AskUserQuestion:
- question: "Do you have your MongoDB connection string ready?"
- header: "MongoDB"
- options:
- label: "Yes, I have it"
description: "I have my MongoDB connection string ready to paste"
- label: "No, skip for now"
description: "I'll configure it later"
If user selects "No, skip for now":
- Tell them they can run `/mongodb-tools:setup` again when ready
- Remind them they can disable MongoDB MCP via `/mcp` if not needed
- Exit
If user selects "Yes" or provides connection string via "Other":
- If they provided connection string in "Other" response, use that
- Otherwise, ask them to paste the connection string
## Step 4: Validate Connection String
Validate the provided connection string:
- Must start with `mongodb://` or `mongodb+srv://`
If invalid:
- Show error: "Invalid connection string format. Must start with 'mongodb://' or 'mongodb+srv://'"
- Ask if they want to try again or skip
## Step 5: Update Configuration
1. Read current `${CLAUDE_PLUGIN_ROOT}/.mcp.json`
2. Create backup at `${CLAUDE_PLUGIN_ROOT}/.mcp.json.backup`
3. Update `mongodb.env.MDB_MCP_CONNECTION_STRING` value to the actual connection string
4. Write updated configuration back to `${CLAUDE_PLUGIN_ROOT}/.mcp.json`
## Step 6: Confirm Success
Tell the user:
```
MongoDB MCP configured successfully!
IMPORTANT: Restart Claude Code for changes to take effect.
- Exit Claude Code
- Run `claude` again
To verify after restart, run /mcp and check that 'mongodb' server is connected.
```
## Troubleshooting
If MongoDB MCP fails after configuration:
```
Common fixes:
1. Authentication failed - Add ?authSource=admin to connection string
2. Network timeout - Whitelist IP in Atlas Network Access settings
3. Wrong credentials - Verify username/password, special chars need URL encoding
4. SSL/TLS errors - For Atlas, ensure mongodb+srv:// is used
```

62
commands/claude-codex-settings/paper-search-tools-setup.md Normal file
View File

@@ -0,0 +1,62 @@
---
description: Configure Paper Search MCP (requires Docker)
---
# Paper Search Tools Setup
**Source:** [mcp/paper-search](https://hub.docker.com/r/mcp/paper-search)
Configure the Paper Search MCP server. Requires Docker.
## Step 1: Check Docker Installation
Run `docker --version` to check if Docker is installed.
If Docker is not installed, show:
```
Docker is required for Paper Search MCP.
Install Docker:
macOS: brew install --cask docker
Linux: curl -fsSL https://get.docker.com | sh
Windows: winget install Docker.DockerDesktop
After installation, start Docker Desktop and wait for it to fully launch.
```
## Step 2: Verify Docker is Running
Run `docker info` to verify Docker daemon is running.
If not running, tell user:
```
Docker is installed but not running.
Start Docker Desktop and wait for it to fully launch before continuing.
```
## Step 3: Pull the Image
Run `docker pull mcp/paper-search` to download the MCP image.
Report progress:
- "Pulling paper-search image..."
- "Image ready!"
## Step 4: Confirm Success
Tell the user:
```
Paper Search MCP configured successfully!
IMPORTANT: Restart Claude Code for changes to take effect.
- Exit Claude Code
- Run `claude` again
To verify after restart, run /mcp and check that 'paper-search' server is connected.
```

104
commands/claude-codex-settings/playwright-tools-setup.md Normal file
View File

@@ -0,0 +1,104 @@
---
description: Configure Playwright MCP
---
# Playwright Tools Setup
**Source:** [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp)
Check Playwright MCP status and configure browser dependencies if needed.
## Step 1: Test Current Setup
Run `/mcp` command to check if playwright server is listed and connected.
If playwright server shows as connected: Tell user Playwright is configured and working.
If playwright server is missing or shows connection error: Continue to Step 2.
## Step 2: Browser Installation
Tell the user:
```
Playwright MCP requires browser binaries. Install them with:
npx playwright install
This installs Chromium, Firefox, and WebKit browsers.
For a specific browser only:
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit
```
## Step 3: Browser Options
The MCP server supports these browsers via the `--browser` flag in `.mcp.json`:
- `chrome` (default)
- `firefox`
- `webkit`
- `msedge`
Example `.mcp.json` for Firefox:
```json
{
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--browser", "firefox"]
}
}
```
## Step 4: Headless Mode
For headless operation (no visible browser), add `--headless`:
```json
{
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"]
}
}
```
## Step 5: Restart
Tell the user:
```
After making changes:
1. Exit Claude Code
2. Run `claude` again
Changes take effect after restart.
```
## Troubleshooting
If Playwright MCP fails:
```
Common fixes:
1. Browser not found - Run `npx playwright install`
2. Permission denied - Check file permissions on browser binaries
3. Display issues - Use `--headless` flag for headless mode
4. Timeout errors - Increase timeout with `--timeout-navigation 120000`
```
## Alternative: Disable Plugin
If user doesn't need browser automation:
```
To disable this plugin:
1. Run /mcp command
2. Find the playwright server
3. Disable it
This prevents errors from missing browser binaries.
```

415
commands/claude-codex-settings/plugin-dev-create-plugin.md Normal file
View File

@@ -0,0 +1,415 @@
---
description: Guided end-to-end plugin creation workflow with component design, implementation, and validation
argument-hint: Optional plugin description
allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash", "TodoWrite", "AskUserQuestion", "Skill", "Task"]
---
# Plugin Creation Workflow
Guide the user through creating a complete, high-quality Claude Code plugin from initial concept to tested implementation. Follow a systematic approach: understand requirements, design components, clarify details, implement following best practices, validate, and test.
## Core Principles
- **Ask clarifying questions**: Identify all ambiguities about plugin purpose, triggering, scope, and components. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding with implementation.
- **Load relevant skills**: Use the Skill tool to load plugin-dev skills when needed (plugin-structure, hook-development, agent-development, etc.)
- **Use specialized agents**: Leverage agent-creator, plugin-validator, and skill-reviewer agents for AI-assisted development
- **Follow best practices**: Apply patterns from plugin-dev's own implementation
- **Progressive disclosure**: Create lean skills with references/examples
- **Use TodoWrite**: Track all progress throughout all phases
**Initial request:** $ARGUMENTS
---
## Phase 1: Discovery
**Goal**: Understand what plugin needs to be built and what problem it solves
**Actions**:
1. Create todo list with all 7 phases
2. If plugin purpose is clear from arguments:
- Summarize understanding
- Identify plugin type (integration, workflow, analysis, toolkit, etc.)
3. If plugin purpose is unclear, ask user:
- What problem does this plugin solve?
- Who will use it and when?
- What should it do?
- Any similar plugins to reference?
4. Summarize understanding and confirm with user before proceeding
**Output**: Clear statement of plugin purpose and target users
---
## Phase 2: Component Planning
**Goal**: Determine what plugin components are needed
**MUST load plugin-structure skill** using Skill tool before this phase.
**Actions**:
1. Load plugin-structure skill to understand component types
2. Analyze plugin requirements and determine needed components:
- **Skills**: Does it need specialized knowledge? (hooks API, MCP patterns, etc.)
- **Commands**: User-initiated actions? (deploy, configure, analyze)
- **Agents**: Autonomous tasks? (validation, generation, analysis)
- **Hooks**: Event-driven automation? (validation, notifications)
- **MCP**: External service integration? (databases, APIs)
- **Settings**: User configuration? (.local.md files)
3. For each component type needed, identify:
- How many of each type
- What each one does
- Rough triggering/usage patterns
4. Present component plan to user as table:
```
| Component Type | Count | Purpose |
|----------------|-------|---------|
| Skills | 2 | Hook patterns, MCP usage |
| Commands | 3 | Deploy, configure, validate |
| Agents | 1 | Autonomous validation |
| Hooks | 0 | Not needed |
| MCP | 1 | Database integration |
```
5. Get user confirmation or adjustments
**Output**: Confirmed list of components to create
---
## Phase 3: Detailed Design & Clarifying Questions
**Goal**: Specify each component in detail and resolve all ambiguities
**CRITICAL**: This is one of the most important phases. DO NOT SKIP.
**Actions**:
1. For each component in the plan, identify underspecified aspects:
- **Skills**: What triggers them? What knowledge do they provide? How detailed?
- **Commands**: What arguments? What tools? Interactive or automated?
- **Agents**: When to trigger (proactive/reactive)? What tools? Output format?
- **Hooks**: Which events? Prompt or command based? Validation criteria?
- **MCP**: What server type? Authentication? Which tools?
- **Settings**: What fields? Required vs optional? Defaults?
2. **Present all questions to user in organized sections** (one section per component type)
3. **Wait for answers before proceeding to implementation**
4. If user says "whatever you think is best", provide specific recommendations and get explicit confirmation
**Example questions for a skill**:
- What specific user queries should trigger this skill?
- Should it include utility scripts? What functionality?
- How detailed should the core SKILL.md be vs references/?
- Any real-world examples to include?
**Example questions for an agent**:
- Should this agent trigger proactively after certain actions, or only when explicitly requested?
- What tools does it need (Read, Write, Bash, etc.)?
- What should the output format be?
- Any specific quality standards to enforce?
**Output**: Detailed specification for each component
---
## Phase 4: Plugin Structure Creation
**Goal**: Create plugin directory structure and manifest
**Actions**:
1. Determine plugin name (kebab-case, descriptive)
2. Choose plugin location:
- Ask user: "Where should I create the plugin?"
- Offer options: current directory, ../new-plugin-name, custom path
3. Create directory structure using bash:
```bash
mkdir -p plugin-name/.claude-plugin
mkdir -p plugin-name/skills # if needed
mkdir -p plugin-name/commands # if needed
mkdir -p plugin-name/agents # if needed
mkdir -p plugin-name/hooks # if needed
```
4. Create plugin.json manifest using Write tool:
```json
{
"name": "plugin-name",
"version": "0.1.0",
"description": "[brief description]",
"author": {
"name": "[author from user or default]",
"email": "[email or default]"
}
}
```
5. Create README.md template
6. Create .gitignore if needed (for .claude/*.local.md, etc.)
7. Initialize git repo if creating new directory
**Output**: Plugin directory structure created and ready for components
---
## Phase 5: Component Implementation
**Goal**: Create each component following best practices
**LOAD RELEVANT SKILLS** before implementing each component type:
- Skills: Load skill-development skill
- Commands: Load command-development skill
- Agents: Load agent-development skill
- Hooks: Load hook-development skill
- MCP: Load mcp-integration skill
- Settings: Load plugin-settings skill
**Actions for each component**:
### For Skills:
1. Load skill-development skill using Skill tool
2. For each skill:
- Ask user for concrete usage examples (or use from Phase 3)
- Plan resources (scripts/, references/, examples/)
- Create skill directory structure
- Write SKILL.md with:
- Third-person description with specific trigger phrases
- Lean body (1,500-2,000 words) in imperative form
- References to supporting files
- Create reference files for detailed content
- Create example files for working code
- Create utility scripts if needed
3. Use skill-reviewer agent to validate each skill
### For Commands:
1. Load command-development skill using Skill tool
2. For each command:
- Write command markdown with frontmatter
- Include clear description and argument-hint
- Specify allowed-tools (minimal necessary)
- Write instructions FOR Claude (not TO user)
- Provide usage examples and tips
- Reference relevant skills if applicable
### For Agents:
1. Load agent-development skill using Skill tool
2. For each agent, use agent-creator agent:
- Provide description of what agent should do
- Agent-creator generates: identifier, whenToUse with examples, systemPrompt
- Create agent markdown file with frontmatter and system prompt
- Add appropriate model, color, and tools
- Validate with validate-agent.sh script
### For Hooks:
1. Load hook-development skill using Skill tool
2. For each hook:
- Create hooks/hooks.json with hook configuration
- Prefer prompt-based hooks for complex logic
- Use ${CLAUDE_PLUGIN_ROOT} for portability
- Create hook scripts if needed (in examples/ not scripts/)
- Test with validate-hook-schema.sh and test-hook.sh utilities
### For MCP:
1. Load mcp-integration skill using Skill tool
2. Create .mcp.json configuration with:
- Server type (stdio for local, SSE for hosted)
- Command and args (with ${CLAUDE_PLUGIN_ROOT})
- extensionToLanguage mapping if LSP
- Environment variables as needed
3. Document required env vars in README
4. Provide setup instructions
### For Settings:
1. Load plugin-settings skill using Skill tool
2. Create settings template in README
3. Create example .claude/plugin-name.local.md file (as documentation)
4. Implement settings reading in hooks/commands as needed
5. Add to .gitignore: `.claude/*.local.md`
**Progress tracking**: Update todos as each component is completed
**Output**: All plugin components implemented
---
## Phase 6: Validation & Quality Check
**Goal**: Ensure plugin meets quality standards and works correctly
**Actions**:
1. **Run plugin-validator agent**:
- Use plugin-validator agent to comprehensively validate plugin
- Check: manifest, structure, naming, components, security
- Review validation report
2. **Fix critical issues**:
- Address any critical errors from validation
- Fix any warnings that indicate real problems
3. **Review with skill-reviewer** (if plugin has skills):
- For each skill, use skill-reviewer agent
- Check description quality, progressive disclosure, writing style
- Apply recommendations
4. **Test agent triggering** (if plugin has agents):
- For each agent, verify <example> blocks are clear
- Check triggering conditions are specific
- Run validate-agent.sh on agent files
5. **Test hook configuration** (if plugin has hooks):
- Run validate-hook-schema.sh on hooks/hooks.json
- Test hook scripts with test-hook.sh
- Verify ${CLAUDE_PLUGIN_ROOT} usage
6. **Present findings**:
- Summary of validation results
- Any remaining issues
- Overall quality assessment
7. **Ask user**: "Validation complete. Issues found: [count critical], [count warnings]. Would you like me to fix them now, or proceed to testing?"
**Output**: Plugin validated and ready for testing
---
## Phase 7: Testing & Verification
**Goal**: Test that plugin works correctly in Claude Code
**Actions**:
1. **Installation instructions**:
- Show user how to test locally:
```bash
cc --plugin-dir /path/to/plugin-name
```
- Or copy to `.claude-plugin/` for project testing
2. **Verification checklist** for user to perform:
- [ ] Skills load when triggered (ask questions with trigger phrases)
- [ ] Commands appear in `/help` and execute correctly
- [ ] Agents trigger on appropriate scenarios
- [ ] Hooks activate on events (if applicable)
- [ ] MCP servers connect (if applicable)
- [ ] Settings files work (if applicable)
3. **Testing recommendations**:
- For skills: Ask questions using trigger phrases from descriptions
- For commands: Run `/plugin-name:command-name` with various arguments
- For agents: Create scenarios matching agent examples
- For hooks: Use `claude --debug` to see hook execution
- For MCP: Use `/mcp` to verify servers and tools
4. **Ask user**: "I've prepared the plugin for testing. Would you like me to guide you through testing each component, or do you want to test it yourself?"
5. **If user wants guidance**, walk through testing each component with specific test cases
**Output**: Plugin tested and verified working
---
## Phase 8: Documentation & Next Steps
**Goal**: Ensure plugin is well-documented and ready for distribution
**Actions**:
1. **Verify README completeness**:
- Check README has: overview, features, installation, prerequisites, usage
- For MCP plugins: Document required environment variables
- For hook plugins: Explain hook activation
- For settings: Provide configuration templates
2. **Add marketplace entry** (if publishing):
- Show user how to add to marketplace.json
- Help draft marketplace description
- Suggest category and tags
3. **Create summary**:
- Mark all todos complete
- List what was created:
- Plugin name and purpose
- Components created (X skills, Y commands, Z agents, etc.)
- Key files and their purposes
- Total file count and structure
- Next steps:
- Testing recommendations
- Publishing to marketplace (if desired)
- Iteration based on usage
4. **Suggest improvements** (optional):
- Additional components that could enhance plugin
- Integration opportunities
- Testing strategies
**Output**: Complete, documented plugin ready for use or publication
---
## Important Notes
### Throughout All Phases
- **Use TodoWrite** to track progress at every phase
- **Load skills with Skill tool** when working on specific component types
- **Use specialized agents** (agent-creator, plugin-validator, skill-reviewer)
- **Ask for user confirmation** at key decision points
- **Follow plugin-dev's own patterns** as reference examples
- **Apply best practices**:
- Third-person descriptions for skills
- Imperative form in skill bodies
- Commands written FOR Claude
- Strong trigger phrases
- ${CLAUDE_PLUGIN_ROOT} for portability
- Progressive disclosure
- Security-first (HTTPS, no hardcoded credentials)
### Key Decision Points (Wait for User)
1. After Phase 1: Confirm plugin purpose
2. After Phase 2: Approve component plan
3. After Phase 3: Proceed to implementation
4. After Phase 6: Fix issues or proceed
5. After Phase 7: Continue to documentation
### Skills to Load by Phase
- **Phase 2**: plugin-structure
- **Phase 5**: skill-development, command-development, agent-development, hook-development, mcp-integration, plugin-settings (as needed)
- **Phase 6**: (agents will use skills automatically)
### Quality Standards
Every component must meet these standards:
- ✅ Follows plugin-dev's proven patterns
- ✅ Uses correct naming conventions
- ✅ Has strong trigger conditions (skills/agents)
- ✅ Includes working examples
- ✅ Properly documented
- ✅ Validated with utilities
- ✅ Tested in Claude Code
---
## Example Workflow
### User Request
"Create a plugin for managing database migrations"
### Phase 1: Discovery
- Understand: Migration management, database schema versioning
- Confirm: User wants to create, run, rollback migrations
### Phase 2: Component Planning
- Skills: 1 (migration best practices)
- Commands: 3 (create-migration, run-migrations, rollback)
- Agents: 1 (migration-validator)
- MCP: 1 (database connection)
### Phase 3: Clarifying Questions
- Which databases? (PostgreSQL, MySQL, etc.)
- Migration file format? (SQL, code-based?)
- Should agent validate before applying?
- What MCP tools needed? (query, execute, schema)
### Phase 4-8: Implementation, Validation, Testing, Documentation
---
**Begin with Phase 1: Discovery**

18
commands/claude-codex-settings/plugin-dev-load-skills.md Normal file
View File

@@ -0,0 +1,18 @@
---
description: Load all plugin development skills
allowed-tools: Read
---
# Load Plugin Development Skills
Read all plugin development SKILL.md files to provide guidance. The files are located at:
- @${CLAUDE_PLUGIN_ROOT}/skills/plugin-structure/SKILL.md
- @${CLAUDE_PLUGIN_ROOT}/skills/agent-development/SKILL.md
- @${CLAUDE_PLUGIN_ROOT}/skills/command-development/SKILL.md
- @${CLAUDE_PLUGIN_ROOT}/skills/skill-development/SKILL.md
- @${CLAUDE_PLUGIN_ROOT}/skills/hook-development/SKILL.md
- @${CLAUDE_PLUGIN_ROOT}/skills/mcp-integration/SKILL.md
- @${CLAUDE_PLUGIN_ROOT}/skills/plugin-settings/SKILL.md
Use this guidance to help with plugin development tasks.

162
commands/claude-codex-settings/slack-tools-setup.md Normal file
View File

@@ -0,0 +1,162 @@
---
description: Configure Slack MCP tokens
---
# Slack Tools Setup
**Source:** [ubie-oss/slack-mcp-server](https://github.com/ubie-oss/slack-mcp-server)
Configure the Slack MCP server with your tokens.
## Step 1: Check Current Status
Read the MCP configuration from `${CLAUDE_PLUGIN_ROOT}/.mcp.json`.
Check if Slack is configured:
- If any of these contain placeholder values, it needs configuration:
- `slack.env.GITHUB_TOKEN` contains `REPLACE_WITH_GITHUB_PAT`
- `slack.env.SLACK_BOT_TOKEN` contains `REPLACE_WITH_BOT_TOKEN`
- `slack.env.SLACK_USER_TOKEN` contains `REPLACE_WITH_USER_TOKEN`
- If all contain actual tokens (ghp\_, xoxb-, xoxp-), already configured
Report status:
- "Slack MCP is not configured - needs tokens"
- OR "Slack MCP is already configured"
## Step 2: Show Setup Guide
Tell the user:
```
To configure Slack MCP, you need 3 tokens:
1. GitHub PAT (ghp_...) - For npm package access
Get it at: https://github.com/settings/tokens
Required scope: read:packages
2. Bot Token (xoxb-...) - From your Slack app
3. User Token (xoxp-...) - From your Slack app
Get both at: https://api.slack.com/apps
Required scopes: channels:history, channels:read, chat:write, users:read
Don't need Slack MCP? Disable it via /mcp command.
```
## Step 3: Ask for GitHub PAT
Use AskUserQuestion:
- question: "Do you have your GitHub PAT ready?"
- header: "GitHub PAT"
- options:
- label: "Yes, I have it"
description: "I have my GitHub PAT ready to paste (starts with ghp\_)"
- label: "No, skip for now"
description: "I'll configure it later"
If user selects "No, skip for now":
- Tell them they can run `/slack-tools:setup` again when ready
- Remind them they can disable Slack MCP via `/mcp` if not needed
- Exit
If user selects "Yes" or provides token via "Other":
- If they provided token in "Other" response, use that
- Otherwise, ask them to paste the token
## Step 4: Ask for Bot Token
Use AskUserQuestion:
- question: "Do you have your Slack Bot Token ready?"
- header: "Bot Token"
- options:
- label: "Yes, I have it"
description: "I have my Slack bot token ready (starts with xoxb-)"
- label: "No, skip for now"
description: "I'll configure it later"
If user selects "No, skip for now":
- Tell them they can run `/slack-tools:setup` again when ready
- Exit
If user selects "Yes" or provides token via "Other":
- If they provided token in "Other" response, use that
- Otherwise, ask them to paste the token
## Step 5: Ask for User Token
Use AskUserQuestion:
- question: "Do you have your Slack User Token ready?"
- header: "User Token"
- options:
- label: "Yes, I have it"
description: "I have my Slack user token ready (starts with xoxp-)"
- label: "No, skip for now"
description: "I'll configure it later"
If user selects "No, skip for now":
- Tell them they can run `/slack-tools:setup` again when ready
- Exit
If user selects "Yes" or provides token via "Other":
- If they provided token in "Other" response, use that
- Otherwise, ask them to paste the token
## Step 6: Validate Tokens
Validate the provided tokens:
- GitHub PAT must start with `ghp_`
- Bot Token must start with `xoxb-`
- User Token must start with `xoxp-`
If any invalid:
- Show error with specific token that failed validation
- Ask if they want to try again or skip
## Step 7: Update Configuration
1. Read current `${CLAUDE_PLUGIN_ROOT}/.mcp.json`
2. Create backup at `${CLAUDE_PLUGIN_ROOT}/.mcp.json.backup`
3. Update these values:
- `slack.env.GITHUB_TOKEN` to the GitHub PAT
- `slack.env.SLACK_BOT_TOKEN` to the bot token
- `slack.env.SLACK_USER_TOKEN` to the user token
4. Write updated configuration back to `${CLAUDE_PLUGIN_ROOT}/.mcp.json`
## Step 8: Confirm Success
Tell the user:
```
Slack MCP configured successfully!
IMPORTANT: Restart Claude Code for changes to take effect.
- Exit Claude Code
- Run `claude` again
To verify after restart, run /mcp and check that 'slack' server is connected.
```
## Troubleshooting
If Slack MCP fails after configuration:
```
Common fixes:
1. invalid_auth - Token expired or invalid, regenerate from api.slack.com
2. missing_scope - Re-install app with required OAuth scopes
3. Token format - Bot tokens start with xoxb-, user tokens with xoxp-
4. Channel not found - Ensure bot is invited to the channel
5. Rate limited - Wait and retry, reduce request frequency
```

165
commands/claude-codex-settings/statusline-tools-setup.md Normal file
View File

@@ -0,0 +1,165 @@
---
description: Configure Claude Code statusline
---
# Statusline Setup
Configure the Claude Code statusline to display session context, cost, and account-wide usage.
## Step 1: Check Current Status
Read `~/.claude/settings.json` and `.claude/settings.local.json` to check if `statusLine` is configured.
Report:
- "Statusline configured in user settings: [command]" if found in ~/.claude/settings.json
- "Statusline configured in project settings: [command]" if found in .claude/settings.local.json
- "Statusline is not configured" if neither exists
## Step 2: Show Options
Tell the user:
```
Statusline Options:
1. Native (recommended for Claude subscription/API)
- Shows: [Session] context% $cost | [5H] usage% time-until-reset
- Account-wide 5H usage tracking with time until reset
- Color-coded: green <50%, yellow 50-80%, red >80%
- Requires: Claude subscription (Max/Pro) or Claude API key
- Does NOT work with: z.ai, third-party endpoints
2. ccusage (for external endpoints)
- Shows: context%, session/daily cost
- Works with: Anthropic, z.ai, third-party endpoints
- Limitation: No account-wide 5H block usage info
3. Disable - Remove statusline
```
## Step 3: Ask for Choice
Use AskUserQuestion:
- question: "Which statusline do you want?"
- header: "Statusline"
- options:
- label: "Native (Claude subscription/API)"
description: "Session + account-wide 5H usage with reset time"
- label: "ccusage (external endpoints)"
description: "Works with z.ai - no 5H block info"
- label: "Disable"
description: "Remove statusline"
## Step 4: If Native Selected
### Ask where to install
Use AskUserQuestion:
- question: "Where should the statusline be configured?"
- header: "Location"
- options:
- label: "User settings (global)"
description: "~/.claude/settings.json - applies to all projects"
- label: "Project local"
description: ".claude/settings.local.json - this project only"
### Check for existing config
If statusLine already exists in chosen location, use AskUserQuestion:
- question: "Statusline already configured. Replace it?"
- header: "Override"
- options:
- label: "Yes, replace"
description: "Override existing statusline config"
- label: "No, cancel"
description: "Keep current config"
If user chooses "No, cancel", stop and say "Setup cancelled."
### Install Native
1. Read `${CLAUDE_PLUGIN_ROOT}/scripts/statusline.sh`
2. Write to `~/.claude/statusline.sh`
3. Run `chmod +x ~/.claude/statusline.sh`
4. Read current settings file (user or project based on choice)
5. Create backup with `.backup` suffix
6. Add/update `statusLine`:
```json
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 0
}
```
7. Write back to settings file
## Step 5: If ccusage Selected
### Ask where to install
Use AskUserQuestion:
- question: "Where should the statusline be configured?"
- header: "Location"
- options:
- label: "User settings (global)"
description: "~/.claude/settings.json - applies to all projects"
- label: "Project local"
description: ".claude/settings.local.json - this project only"
### Check for existing config and confirm override (same as Native)
### Install ccusage
1. Read current settings file
2. Create backup with `.backup` suffix
3. Add/update `statusLine`:
```json
"statusLine": {
"type": "command",
"command": "npx -y ccusage@latest statusline --cost-source cc",
"padding": 0
}
```
4. Write back to settings file
## Step 6: If Disable Selected
1. Read `~/.claude/settings.json`
2. Create backup
3. Remove `statusLine` key if exists
4. Write back
Also check `.claude/settings.local.json` and remove `statusLine` if present.
## Step 7: Confirm Success
Tell the user:
```
Statusline configured successfully!
IMPORTANT: Restart Claude Code for changes to take effect.
- Exit Claude Code (Ctrl+C or /exit)
- Run `claude` again
Backup saved to [settings-file].backup
```
## Requirements
Native statusline requires `jq`. Check with `which jq`.
If jq not installed:
- macOS: `brew install jq`
- Ubuntu/Debian: `sudo apt install jq`
- Other: https://jqlang.org/download/

96
commands/claude-codex-settings/supabase-tools-setup.md Normal file
View File

@@ -0,0 +1,96 @@
---
description: Configure Supabase MCP with OAuth authentication
---
# Supabase Tools Setup
**Source:** [supabase-community/supabase-mcp](https://github.com/supabase-community/supabase-mcp)
Configure the official Supabase MCP server with OAuth.
## Step 1: Check Current Status
Read the MCP configuration from `${CLAUDE_PLUGIN_ROOT}/.mcp.json`.
Check if Supabase is configured:
- If `supabase.url` contains `REPLACE_WITH_PROJECT_REF`, it needs configuration
- If it contains an actual project reference, already configured
Report status:
- "Supabase MCP is not configured - needs project reference"
- OR "Supabase MCP is configured with project: PROJECT_REF"
## Step 2: Show Setup Guide
Tell the user:
```
To configure Supabase MCP, you need your Supabase project reference.
Quick steps:
1. Go to supabase.com/dashboard
2. Select your project
3. Go to Project Settings > General
4. Copy the "Reference ID" (looks like: abcdefghijklmnop)
The MCP uses OAuth - you'll authenticate via browser when first connecting.
```
## Step 3: Ask for Project Reference
Use AskUserQuestion:
- question: "Do you have your Supabase project reference ready?"
- header: "Project Ref"
- options:
- label: "Yes, I have it"
description: "I have my Supabase project reference ready"
- label: "No, skip for now"
description: "I'll configure it later"
If user selects "No, skip for now":
- Tell them they can run `/supabase-tools:setup` again when ready
- Remind them they can disable Supabase MCP via `/mcp` if not needed
- Exit
If user selects "Yes" or provides reference via "Other":
- If they provided reference in "Other" response, use that
- Otherwise, ask them to paste the project reference
## Step 4: Validate Reference
Validate the provided reference:
- Must be alphanumeric
- Should be 16-24 characters
If invalid:
- Show error: "Invalid project reference format"
- Ask if they want to try again or skip
## Step 5: Update Configuration
1. Read current `${CLAUDE_PLUGIN_ROOT}/.mcp.json`
2. Create backup at `${CLAUDE_PLUGIN_ROOT}/.mcp.json.backup`
3. Replace `REPLACE_WITH_PROJECT_REF` with the actual project reference in the URL
4. Write updated configuration back to `${CLAUDE_PLUGIN_ROOT}/.mcp.json`
## Step 6: Confirm Success
Tell the user:
```
Supabase MCP configured successfully!
IMPORTANT: Restart Claude Code for changes to take effect.
- Exit Claude Code
- Run `claude` again
On first use, you'll be prompted to authenticate via browser (OAuth).
To verify after restart, run /mcp and check that 'supabase' server is connected.
```

97
commands/claude-codex-settings/tavily-tools-setup.md Normal file
View File

@@ -0,0 +1,97 @@
---
description: Configure Tavily MCP server credentials
---
# Tavily Tools Setup
**Source:** [tavily-ai/tavily-mcp](https://github.com/tavily-ai/tavily-mcp)
Configure the Tavily MCP server with your API key.
## Step 1: Check Current Status
Read the MCP configuration from `${CLAUDE_PLUGIN_ROOT}/.mcp.json`.
Check if Tavily is configured:
- If `tavily.env.TAVILY_API_KEY` contains `REPLACE_WITH_TAVILY_API_KEY`, it needs configuration
- If it contains a value starting with `tvly-`, already configured
Report status:
- "Tavily MCP is not configured - needs an API key"
- OR "Tavily MCP is already configured"
## Step 2: Show Setup Guide
Tell the user:
```
To configure Tavily MCP, you need a Tavily API key.
Quick steps:
1. Go to app.tavily.com and sign in
2. Navigate to API Keys
3. Create a new API key
4. Copy the key (starts with tvly-)
Free tier: 1,000 searches/month
Don't need Tavily MCP? Disable it via /mcp command.
```
## Step 3: Ask for Key
Use AskUserQuestion:
- question: "Do you have your Tavily API key ready?"
- header: "Tavily Key"
- options:
- label: "Yes, I have it"
description: "I have my Tavily API key ready to paste"
- label: "No, skip for now"
description: "I'll configure it later"
If user selects "No, skip for now":
- Tell them they can run `/tavily-tools:setup` again when ready
- Remind them they can disable Tavily MCP via `/mcp` if not needed
- Exit
If user selects "Yes" or provides key via "Other":
- If they provided key in "Other" response, use that
- Otherwise, ask them to paste the key
## Step 4: Validate Key
Validate the provided key:
- Must start with `tvly-`
- Must be at least 20 characters
If invalid:
- Show error: "Invalid key format. Tavily keys start with 'tvly-'"
- Ask if they want to try again or skip
## Step 5: Update Configuration
1. Read current `${CLAUDE_PLUGIN_ROOT}/.mcp.json`
2. Create backup at `${CLAUDE_PLUGIN_ROOT}/.mcp.json.backup`
3. Update `tavily.env.TAVILY_API_KEY` value to the actual key
4. Write updated configuration back to `${CLAUDE_PLUGIN_ROOT}/.mcp.json`
## Step 6: Confirm Success
Tell the user:
```
Tavily MCP configured successfully!
IMPORTANT: Restart Claude Code for changes to take effect.
- Exit Claude Code
- Run `claude` again
To verify after restart, run /mcp and check that 'tavily' server is connected.
```

16
hooks/claude-codex-settings/hooks.json Normal file
View File

@@ -0,0 +1,16 @@
{
"description": "General development hooks for code quality",
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/enforce_rg_over_grep.py"
}
]
}
]
}
}

58
hooks/claude-codex-settings/scripts/bash_formatting.py Executable file
View File

@@ -0,0 +1,58 @@
#!/usr/bin/env python3
"""
PostToolUse hook: Auto-format Bash/Shell scripts with prettier-plugin-sh
"""
import json
import shutil
import subprocess
import sys
from pathlib import Path
def check_prettier_version() -> bool:
"""Check if prettier is installed and warn if version differs from 3.6.2."""
if not shutil.which('npx'):
return False
try:
result = subprocess.run(['npx', 'prettier', '--version'],
capture_output=True, text=True, check=False, timeout=5)
if result.returncode == 0:
version = result.stdout.strip()
if '3.6.2' not in version:
print(f"⚠️ Prettier version mismatch: expected 3.6.2, found {version}")
return True
except Exception:
pass
return False
def main():
try:
data = json.load(sys.stdin)
file_path = data.get("tool_input", {}).get("file_path", "")
if not file_path.endswith(('.sh', '.bash')):
sys.exit(0)
sh_file = Path(file_path)
if not sh_file.exists() or any(p in sh_file.parts for p in ['.git', '.venv', 'venv', 'env', '.env', '__pycache__', '.mypy_cache', '.pytest_cache', '.tox', '.nox', '.eggs', 'eggs', '.idea', '.vscode', 'node_modules', 'site-packages', 'build', 'dist', '.claude']):
sys.exit(0)
# Check if prettier is available
if not check_prettier_version():
sys.exit(0)
# Try prettier with prettier-plugin-sh, handle any failure gracefully
try:
cmd = f'npx prettier --write --list-different --print-width 120 --plugin=$(npm root -g)/prettier-plugin-sh/lib/index.cjs "{sh_file}"'
subprocess.run(cmd, shell=True, capture_output=True, check=False, cwd=sh_file.parent, timeout=10)
except Exception:
pass # Silently handle any failure (missing plugin, timeout, etc.)
except Exception:
pass
sys.exit(0)
if __name__ == "__main__":
main()

47
hooks/claude-codex-settings/scripts/enforce_rg_over_grep.py Executable file
View File

@@ -0,0 +1,47 @@
#!/usr/bin/env python3
import json
import re
import sys
# Define validation rules as a list of (regex pattern, message) tuples
VALIDATION_RULES = [
(
r"\bgrep\b(?!.*\|)",
"Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
),
(
r"\bfind\s+\S+\s+-name\b",
"Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
),
]
def validate_command(command: str) -> list[str]:
issues = []
for pattern, message in VALIDATION_RULES:
if re.search(pattern, command):
issues.append(message)
return issues
try:
input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
sys.exit(1)
tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")
if tool_name != "Bash" or not command:
sys.exit(0)
# Validate the command
issues = validate_command(command)
if issues:
for message in issues:
print(f"• {message}", file=sys.stderr)
# Exit code 2 blocks tool call and shows stderr to Claude
sys.exit(2)

547
hooks/claude-codex-settings/scripts/format_python_docstrings.py Executable file
View File

@@ -0,0 +1,547 @@
#!/usr/bin/env python3
"""Format Python docstrings in Google style without external dependencies."""
from __future__ import annotations
import ast
import json
import re
import sys
from pathlib import Path
URLS = {"https", "http", "ftp"}
SECTIONS = (
"Args",
"Attributes",
"Methods",
"Returns",
"Yields",
"Raises",
"Example",
"Examples",
"Notes",
"References",
)
SECTION_ALIASES = {
"Arguments": "Args",
"Usage": "Examples",
"Usage Example": "Examples",
"Usage Examples": "Examples",
"Example Usage": "Examples",
"Example": "Examples",
"Return": "Returns",
"Yield": "Yields",
"Raise": "Raises",
"Note": "Notes",
"Reference": "References",
}
LIST_RX = re.compile(r"""^(\s*)(?:[-*•]\s+|(?:\d+|[A-Za-z]+)[\.\)]\s+)""")
TABLE_RX = re.compile(r"^\s*\|.*\|\s*$")
TABLE_RULE_RX = re.compile(r"^\s*[:\-\|\s]{3,}$")
TREE_CHARS = ("└", "├", "│", "─")
# Antipatterns for non-Google docstring styles
RST_FIELD_RX = re.compile(r"^\s*:(param|type|return|rtype|raises)\b", re.M)
EPYDOC_RX = re.compile(r"^\s*@(?:param|type|return|rtype|raise)\b", re.M)
NUMPY_UNDERLINE_SECTION_RX = re.compile(r"^\s*(Parameters|Returns|Yields|Raises|Notes|Examples)\n[-]{3,}\s*$", re.M)
GOOGLE_SECTION_RX = re.compile(
r"^\s*(Args|Attributes|Methods|Returns|Yields|Raises|Example|Examples|Notes|References):\s*$", re.M
)
NON_GOOGLE = {"numpy", "rest", "epydoc"}
def wrap_words(words: list[str], width: int, indent: int, min_words_per_line: int = 1) -> list[str]:
"""Wrap words to width with indent; optionally avoid very short orphan lines."""
pad = " " * indent
if not words:
return []
lines: list[list[str]] = []
cur: list[str] = []
cur_len = indent
for w in words:
need = len(w) + (1 if cur else 0)
if cur and cur_len + need > width:
lines.append(cur)
cur, cur_len = [w], indent + len(w)
else:
cur.append(w)
cur_len += need
if cur:
lines.append(cur)
if min_words_per_line > 1:
i = 1
while i < len(lines):
if len(lines[i]) < min_words_per_line and len(lines[i - 1]) > 1:
donor = lines[i - 1][-1]
this_len = len(pad) + sum(len(x) for x in lines[i]) + (len(lines[i]) - 1)
if this_len + (1 if lines[i] else 0) + len(donor) <= width:
lines[i - 1].pop()
lines[i].insert(0, donor)
if i > 1 and len(lines[i - 1]) == 1:
i -= 1
continue
i += 1
return [pad + " ".join(line) for line in lines]
def wrap_para(text: str, width: int, indent: int, min_words_per_line: int = 1) -> list[str]:
"""Wrap a paragraph string; orphan control via min_words_per_line."""
if text := text.strip():
return wrap_words(text.split(), width, indent, min_words_per_line)
else:
return []
def wrap_hanging(head: str, desc: str, width: int, cont_indent: int) -> list[str]:
"""Wrap 'head + desc' with hanging indent; ensure first continuation has >=2 words."""
room = width - len(head)
words = desc.split()
if not words:
return [head.rstrip()]
take, used = [], 0
for w in words:
need = len(w) + (1 if take else 0)
if used + need <= room:
take.append(w)
used += need
else:
break
out: list[str] = []
if take:
out.append(head + " ".join(take))
rest = words[len(take) :]
else:
out.append(head.rstrip())
rest = words
out.extend(wrap_words(rest, width, cont_indent, min_words_per_line=2))
return out
def is_list_item(s: str) -> bool:
"""Return True if s looks like a bullet/numbered list item."""
return bool(LIST_RX.match(s.lstrip()))
def is_fence_line(s: str) -> bool:
"""Return True if s is a Markdown code-fence line."""
t = s.lstrip()
return t.startswith("```")
def is_table_like(s: str) -> bool:
"""Return True if s resembles a simple Markdown table or rule line."""
return bool(TABLE_RX.match(s)) or bool(TABLE_RULE_RX.match(s))
def is_tree_like(s: str) -> bool:
"""Return True if s contains common ASCII tree characters."""
return any(ch in s for ch in TREE_CHARS)
def is_indented_block_line(s: str) -> bool:
"""Return True if s looks like a deeply-indented preformatted block."""
return bool(s.startswith(" ")) or s.startswith("\t")
def header_name(line: str) -> str | None:
"""Return canonical section header or None."""
s = line.strip()
if not s.endswith(":") or len(s) <= 1:
return None
name = s[:-1].strip()
name = SECTION_ALIASES.get(name, name)
return name if name in SECTIONS else None
def add_header(lines: list[str], indent: int, title: str) -> None:
"""Append a section header with a blank line before it."""
while lines and lines[-1] == "":
lines.pop()
if lines:
lines.append("")
lines.append(" " * indent + f"{title}:")
def emit_paragraphs(
src: list[str], width: int, indent: int, list_indent: int | None = None, orphan_min: int = 1
) -> list[str]:
"""Wrap text while preserving lists, fenced code, tables, trees, and deeply-indented blocks."""
out: list[str] = []
buf: list[str] = []
in_fence = False
def flush():
"""Flush buffered paragraph with wrapping."""
nonlocal buf
if buf:
out.extend(wrap_para(" ".join(x.strip() for x in buf), width, indent, min_words_per_line=orphan_min))
buf = []
for raw in src:
s = raw.rstrip("\n")
stripped = s.strip()
if not stripped:
flush()
out.append("")
continue
if is_fence_line(s):
flush()
out.append(s.rstrip())
in_fence = not in_fence
continue
if in_fence or is_table_like(s) or is_tree_like(s) or is_indented_block_line(s):
flush()
out.append(s.rstrip())
continue
if is_list_item(s):
flush()
out.append((" " * list_indent + stripped) if list_indent is not None else s.rstrip())
continue
buf.append(s)
flush()
while out and out[-1] == "":
out.pop()
return out
def parse_sections(text: str) -> dict[str, list[str]]:
"""Parse Google-style docstring into sections."""
parts = {k: [] for k in ("summary", "description", *SECTIONS)}
cur = "summary"
for raw in text.splitlines():
line = raw.rstrip("\n")
if h := header_name(line):
cur = h
continue
if not line.strip():
if cur == "summary" and parts["summary"]:
cur = "description"
if parts[cur]:
parts[cur].append("")
continue
parts[cur].append(line)
return parts
def looks_like_param(s: str) -> bool:
"""Heuristic: True if line looks like a 'name: desc' param without being a list item."""
if is_list_item(s) or ":" not in s:
return False
head = s.split(":", 1)[0].strip()
return False if head in URLS else bool(head)
def iter_items(lines: list[str]) -> list[list[str]]:
"""Group lines into logical items separated by next param-like line."""
items, i, n = [], 0, len(lines)
while i < n:
while i < n and not lines[i].strip():
i += 1
if i >= n:
break
item = [lines[i]]
i += 1
while i < n:
st = lines[i].strip()
if st and looks_like_param(st):
break
item.append(lines[i])
i += 1
items.append(item)
return items
def format_structured_block(lines: list[str], width: int, base: int) -> list[str]:
"""Format Args/Returns/etc.; continuation at base+4, lists at base+8."""
out: list[str] = []
cont, lst = base + 4, base + 8
for item in iter_items(lines):
first = item[0].strip()
name, desc = ([*first.split(":", 1), ""])[:2]
name, desc = name.strip(), desc.strip()
had_colon = ":" in first
if not name or (" " in name and "(" not in name and ")" not in name):
out.extend(emit_paragraphs(item, width, cont, lst, orphan_min=2))
continue
# Join continuation lines that aren't new paragraphs into desc
parts = [desc] if desc else []
tail, i = [], 1
while i < len(item):
line = item[i].strip()
if not line or is_list_item(item[i]) or is_fence_line(item[i]) or is_table_like(item[i]):
tail = item[i:]
break
parts.append(line)
i += 1
else:
tail = []
desc = " ".join(parts)
head = " " * cont + (f"{name}: " if (desc or had_colon) else name)
out.extend(wrap_hanging(head, desc, width, cont + 4))
if tail:
if body := emit_paragraphs(tail, width, cont + 4, lst, orphan_min=2):
out.extend(body)
return out
def detect_opener(original_literal: str) -> tuple[str, str, bool]:
"""Return (prefix, quotes, inline_hint) from the original string token safely."""
s = original_literal.lstrip()
i = 0
while i < len(s) and s[i] in "rRuUbBfF":
i += 1
quotes = '"""'
if i + 3 <= len(s) and s[i : i + 3] in ('"""', "'''"):
quotes = s[i : i + 3]
keep = "".join(ch for ch in s[:i] if ch in "rRuU")
j = i + len(quotes)
inline_hint = j < len(s) and s[j : j + 1] not in {"", "\n", "\r"}
return keep, quotes, inline_hint
def format_google(text: str, indent: int, width: int, quotes: str, prefix: str, start_newline: bool) -> str:
"""Format multi-line Google-style docstring with start_newline controlling summary placement."""
p = parse_sections(text)
opener = prefix + quotes
out: list[str] = []
if p["summary"]:
summary_text = " ".join(x.strip() for x in p["summary"]).strip()
if summary_text and summary_text[-1] not in ".!?":
summary_text += "."
if start_newline:
out.append(opener)
out.extend(emit_paragraphs([summary_text], width, indent, list_indent=indent, orphan_min=1))
else:
eff_width = max(1, width - indent)
out.extend(wrap_hanging(opener, summary_text, eff_width, indent))
else:
out.append(opener)
if any(x.strip() for x in p["description"]):
out.append("")
out.extend(emit_paragraphs(p["description"], width, indent, list_indent=indent, orphan_min=1))
has_content = bool(p["summary"]) or any(x.strip() for x in p["description"])
for sec in ("Args", "Attributes", "Methods", "Returns", "Yields", "Raises"):
if any(x.strip() for x in p[sec]):
if has_content:
add_header(out, indent, sec)
else:
out.append(" " * indent + f"{sec}:")
has_content = True
out.extend(format_structured_block(p[sec], width, indent))
for sec in ("Examples", "Notes", "References"):
if any(x.strip() for x in p[sec]):
add_header(out, indent, sec)
out.extend(x.rstrip() for x in p[sec])
while out and out[-1] == "":
out.pop()
out.append(" " * indent + quotes)
return "\n".join(out)
def likely_docstring_style(text: str) -> str:
"""Return 'google' | 'numpy' | 'rest' | 'epydoc' | 'unknown' for docstring text."""
t = "\n".join(line.rstrip() for line in text.strip().splitlines())
if RST_FIELD_RX.search(t):
return "rest"
if EPYDOC_RX.search(t):
return "epydoc"
if NUMPY_UNDERLINE_SECTION_RX.search(t):
return "numpy"
return "google" if GOOGLE_SECTION_RX.search(t) else "unknown"
def format_docstring(
content: str, indent: int, width: int, quotes: str, prefix: str, start_newline: bool = False
) -> str:
"""Single-line if short/sectionless/no-lists; else Google-style; preserve quotes/prefix."""
if not content or not content.strip():
return f"{prefix}{quotes}{quotes}"
style = likely_docstring_style(content)
if style in NON_GOOGLE:
body = "\n".join(line.rstrip() for line in content.rstrip("\n").splitlines())
return f"{prefix}{quotes}{body}{quotes}"
text = content.strip()
has_section = any(f"{s}:" in text for s in SECTIONS)
has_list = any(is_list_item(line) for line in text.splitlines())
single_ok = (
("\n" not in text)
and not has_section
and not has_list
and (indent + len(prefix) + len(quotes) * 2 + len(text) <= width)
)
if single_ok:
words = text.split()
if words and not words[0].startswith(("http://", "https://")) and not words[0][0].isupper():
words[0] = words[0][0].upper() + words[0][1:]
out = " ".join(words)
if out and out[-1] not in ".!?":
out += "."
return f"{prefix}{quotes}{out}{quotes}"
return format_google(text, indent, width, quotes, prefix, start_newline)
class Visitor(ast.NodeVisitor):
"""Collect docstring replacements for classes and functions."""
def __init__(self, src: list[str], width: int = 120, start_newline: bool = False):
"""Init with source lines, target width, and start_newline flag."""
self.src, self.width, self.repl, self.start_newline = src, width, [], start_newline
def visit_Module(self, node):
"""Skip module docstring; visit children."""
self.generic_visit(node)
def visit_ClassDef(self, node):
"""Visit class definition and handle its docstring."""
self._handle(node)
self.generic_visit(node)
def visit_FunctionDef(self, node):
"""Visit function definition and handle its docstring."""
self._handle(node)
self.generic_visit(node)
def visit_AsyncFunctionDef(self, node):
"""Visit async function definition and handle its docstring."""
self._handle(node)
self.generic_visit(node)
def _handle(self, node):
"""If first stmt is a string expr, schedule replacement."""
try:
doc = ast.get_docstring(node, clean=False)
if not doc or not node.body or not isinstance(node.body[0], ast.Expr):
return
s = node.body[0].value
if not (isinstance(s, ast.Constant) and isinstance(s.value, str)):
return
if likely_docstring_style(doc) in NON_GOOGLE:
return
sl, el = node.body[0].lineno - 1, node.body[0].end_lineno - 1
sc, ec = node.body[0].col_offset, node.body[0].end_col_offset
if sl < 0 or el >= len(self.src):
return
original = (
self.src[sl][sc:ec]
if sl == el
else "\n".join([self.src[sl][sc:], *self.src[sl + 1 : el], self.src[el][:ec]])
)
prefix, quotes, _ = detect_opener(original)
formatted = format_docstring(doc, sc, self.width, quotes, prefix, self.start_newline)
if formatted.strip() != original.strip():
self.repl.append((sl, el, sc, ec, formatted))
except Exception:
return
def format_python_file(text: str, width: int = 120, start_newline: bool = False) -> str:
"""Return source with reformatted docstrings; on failure, return original."""
s = text
if not s.strip():
return s
if ('"""' not in s and "'''" not in s) or ("def " not in s and "class " not in s and "async def " not in s):
return s
try:
tree = ast.parse(s)
except SyntaxError:
return s
src = s.splitlines()
v = Visitor(src, width, start_newline=start_newline)
try:
v.visit(tree)
except Exception:
return s
if not v.repl:
return s
for sl, el, sc, ec, rep in reversed(v.repl):
try:
if sl == el:
src[sl] = src[sl][:sc] + rep + src[sl][ec:]
else:
nl = rep.splitlines()
nl[0] = src[sl][:sc] + nl[0]
nl[-1] += src[el][ec:]
src[sl : el + 1] = nl
except Exception:
continue
return "\n".join(src)
def preserve_trailing_newlines(original: str, formatted: str) -> str:
"""Preserve the original trailing newline count."""
o = len(original) - len(original.rstrip("\n"))
f = len(formatted) - len(formatted.rstrip("\n"))
return formatted if o == f else formatted.rstrip("\n") + ("\n" * o)
def read_python_path() -> Path | None:
"""Read the Python path from stdin payload.
Returns:
(Path | None): Python file path when present and valid.
"""
try:
data = json.load(sys.stdin)
except Exception:
return None
file_path = data.get("tool_input", {}).get("file_path", "")
path = Path(file_path) if file_path else None
if not path or path.suffix != ".py" or not path.exists():
return None
if any(
p in path.parts
for p in [
".git",
".venv",
"venv",
"env",
".env",
"__pycache__",
".mypy_cache",
".pytest_cache",
".tox",
".nox",
".eggs",
"eggs",
".idea",
".vscode",
"node_modules",
"site-packages",
"build",
"dist",
".claude",
]
):
return None
return path
def main() -> None:
"""Format Python docstrings in files."""
python_file = read_python_path()
if python_file:
try:
content = python_file.read_text()
formatted = preserve_trailing_newlines(content, format_python_file(content))
if formatted != content:
python_file.write_text(formatted)
print(f"Formatted: {python_file}")
except Exception as e:
output = {
"hookSpecificOutput": {
"hookEventName": "PostToolUse",
"additionalContext": f"Docstring formatting failed for {python_file.name}: {e}",
}
}
print(json.dumps(output))
sys.exit(0)
if __name__ == "__main__":
main()

135
hooks/claude-codex-settings/scripts/gh_pr_create_confirm.py Executable file
View File

@@ -0,0 +1,135 @@
#!/usr/bin/env python3
"""PreToolUse hook: show confirmation modal before creating GitHub PR via gh CLI."""
import json
import re
import subprocess
import sys
def parse_gh_pr_create(command: str) -> dict[str, str]:
"""Parse gh pr create command to extract PR parameters.
Args:
command (str): The gh pr create command string
Returns:
(dict): Dictionary with title, body, assignee, reviewer keys
"""
params = {"title": "", "body": "", "assignee": "", "reviewer": ""}
# Extract title (-t or --title)
title_match = re.search(r'(?:-t|--title)\s+["\']([^"\']+)["\']', command)
if title_match:
params["title"] = title_match.group(1)
# Extract body (-b or --body) - handle HEREDOC syntax first, then simple quotes
heredoc_match = re.search(
r'(?:-b|--body)\s+"?\$\(cat\s+<<["\']?(\w+)["\']?\s+(.*?)\s+\1\s*\)"?',
command,
re.DOTALL,
)
if heredoc_match:
params["body"] = heredoc_match.group(2).strip()
else:
body_match = re.search(r'(?:-b|--body)\s+"([^"]+)"', command)
if body_match:
params["body"] = body_match.group(1)
# Extract assignee (-a or --assignee)
assignee_match = re.search(r'(?:-a|--assignee)\s+([^\s]+)', command)
if assignee_match:
params["assignee"] = assignee_match.group(1)
# Extract reviewer (-r or --reviewer)
reviewer_match = re.search(r'(?:-r|--reviewer)\s+([^\s]+)', command)
if reviewer_match:
params["reviewer"] = reviewer_match.group(1)
return params
def resolve_username(assignee: str) -> str:
"""Resolve @me to actual GitHub username.
Args:
assignee (str): Assignee value from command (may be @me)
Returns:
(str): Resolved username or original value
"""
if assignee == "@me":
try:
result = subprocess.run(
["gh", "api", "user", "--jq", ".login"],
capture_output=True,
text=True,
timeout=5,
)
if result.returncode == 0:
return result.stdout.strip()
except (subprocess.TimeoutExpired, FileNotFoundError):
pass
return assignee
def format_confirmation_message(params: dict[str, str]) -> str:
"""Format PR parameters into readable confirmation message.
Args:
params (dict): Dictionary with title, body, assignee, reviewer
Returns:
(str): Formatted confirmation message
"""
# Truncate body if too long
body = params["body"]
if len(body) > 500:
body = body[:500] + "..."
# Resolve assignee
assignee = resolve_username(params["assignee"]) if params["assignee"] else "None"
lines = ["📝 Create Pull Request?", "", f"Title: {params['title']}", ""]
if body:
lines.extend(["Body:", body, ""])
lines.append(f"Assignee: {assignee}")
if params["reviewer"]:
lines.append(f"Reviewer: {params['reviewer']}")
return "\n".join(lines)
try:
input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
sys.exit(1)
tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")
# Only handle gh pr create commands
if tool_name != "Bash" or not command.strip().startswith("gh pr create"):
sys.exit(0)
# Parse PR parameters
params = parse_gh_pr_create(command)
# Format confirmation message
message = format_confirmation_message(params)
# Return JSON with ask decision
output = {
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "ask",
"permissionDecisionReason": message,
}
}
print(json.dumps(output))
sys.exit(0)

162
hooks/claude-codex-settings/scripts/git_commit_confirm.py Executable file
View File

@@ -0,0 +1,162 @@
#!/usr/bin/env python3
"""PreToolUse hook: show confirmation modal before creating git commit."""
import json
import re
import subprocess
import sys
def parse_git_commit_message(command: str) -> dict[str, str]:
"""Parse git commit command to extract commit message.
Args:
command (str): The git commit command string
Returns:
(dict): Dictionary with message and is_amend keys
"""
params = {"message": "", "is_amend": False}
# Check for --amend flag
params["is_amend"] = "--amend" in command
# Try to extract heredoc format: git commit -m "$(cat <<'EOF' ... EOF)"
heredoc_match = re.search(r"<<'EOF'\s*\n(.*?)\nEOF", command, re.DOTALL)
if heredoc_match:
params["message"] = heredoc_match.group(1).strip()
return params
# Try to extract simple -m "message" format
simple_matches = re.findall(r'(?:-m|--message)\s+["\']([^"\']+)["\']', command)
if simple_matches:
# Join multiple -m flags with double newlines
params["message"] = "\n\n".join(simple_matches)
return params
return params
def get_staged_files() -> tuple[list[str], str]:
"""Get list of staged files and diff stats.
Returns:
(tuple): (list of file paths, diff stats string)
"""
try:
# Get list of staged files
files_result = subprocess.run(
["git", "diff", "--cached", "--name-only"],
capture_output=True,
text=True,
timeout=5,
)
# Get diff stats
stats_result = subprocess.run(
["git", "diff", "--cached", "--stat"],
capture_output=True,
text=True,
timeout=5,
)
files = []
if files_result.returncode == 0:
files = [f for f in files_result.stdout.strip().split("\n") if f]
stats = ""
if stats_result.returncode == 0:
# Get last line which contains the summary
stats_lines = stats_result.stdout.strip().split("\n")
if stats_lines:
stats = stats_lines[-1]
return files, stats
except (subprocess.TimeoutExpired, FileNotFoundError):
return [], ""
def format_confirmation_message(message: str, is_amend: bool, files: list[str], stats: str) -> str:
"""Format commit parameters into readable confirmation message.
Args:
message (str): Commit message
is_amend (bool): Whether this is an amend commit
files (list): List of staged file paths
stats (str): Diff statistics string
Returns:
(str): Formatted confirmation message
"""
lines = []
# Header
if is_amend:
lines.append("💾 Amend Previous Commit?")
else:
lines.append("💾 Create Commit?")
lines.append("")
# Commit message
if message:
lines.append("Message:")
lines.append(message)
lines.append("")
# Files
if files:
lines.append(f"Files to be committed ({len(files)}):")
# Show first 15 files, truncate if more
display_files = files[:15]
for f in display_files:
lines.append(f"- {f}")
if len(files) > 15:
lines.append(f"... and {len(files) - 15} more files")
lines.append("")
# Stats
if stats:
lines.append("Stats:")
lines.append(stats)
# Warning if no files staged
if not files:
lines.append("⚠️ No files staged for commit")
return "\n".join(lines)
try:
input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
sys.exit(1)
tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")
# Only handle git commit commands
if tool_name != "Bash" or not command.strip().startswith("git commit"):
sys.exit(0)
# Parse commit message
params = parse_git_commit_message(command)
# Get staged files and stats
files, stats = get_staged_files()
# Format confirmation message
message = format_confirmation_message(params["message"], params["is_amend"], files, stats)
# Return JSON with ask decision
output = {
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "ask",
"permissionDecisionReason": message,
}
}
print(json.dumps(output))
sys.exit(0)

311
hooks/claude-codex-settings/scripts/markdown_formatting.py Executable file
View File

@@ -0,0 +1,311 @@
#!/usr/bin/env python3
"""
PostToolUse hook: Format Markdown files and embedded code blocks.
Inspired by https://github.com/ultralytics/actions/blob/main/actions/update_markdown_code_blocks.py
"""
from __future__ import annotations
import hashlib
import json
import re
import shutil
import subprocess
import sys
from pathlib import Path
from tempfile import TemporaryDirectory
PYTHON_BLOCK_PATTERN = r"^( *)```(?:python|py|\{[ ]*\.py[ ]*\.annotate[ ]*\})\n(.*?)\n\1```"
BASH_BLOCK_PATTERN = r"^( *)```(?:bash|sh|shell)\n(.*?)\n\1```"
LANGUAGE_TAGS = {"python": ["python", "py", "{ .py .annotate }"], "bash": ["bash", "sh", "shell"]}
def check_prettier_version() -> bool:
"""Check if prettier is installed and warn if version differs from 3.6.2."""
if not shutil.which("npx"):
return False
try:
result = subprocess.run(["npx", "prettier", "--version"],
capture_output=True, text=True, check=False, timeout=5)
if result.returncode == 0:
version = result.stdout.strip()
if "3.6.2" not in version:
print(f"⚠️ Prettier version mismatch: expected 3.6.2, found {version}")
return True
except Exception:
pass
return False
def extract_code_blocks(markdown_content: str) -> dict[str, list[tuple[str, str]]]:
"""Extract code blocks from markdown content.
Args:
markdown_content (str): Markdown text to inspect.
Returns:
(dict): Mapping of language names to lists of (indentation, block) pairs.
"""
python_blocks = re.compile(PYTHON_BLOCK_PATTERN, re.DOTALL | re.MULTILINE).findall(markdown_content)
bash_blocks = re.compile(BASH_BLOCK_PATTERN, re.DOTALL | re.MULTILINE).findall(markdown_content)
return {"python": python_blocks, "bash": bash_blocks}
def remove_indentation(code_block: str, num_spaces: int) -> str:
"""Remove indentation from a block of code.
Args:
code_block (str): Code snippet to adjust.
num_spaces (int): Leading space count to strip.
Returns:
(str): Code with indentation removed.
"""
lines = code_block.split("\n")
stripped_lines = [line[num_spaces:] if len(line) >= num_spaces else line for line in lines]
return "\n".join(stripped_lines)
def add_indentation(code_block: str, num_spaces: int) -> str:
"""Add indentation back to non-empty lines in a code block.
Args:
code_block (str): Code snippet to indent.
num_spaces (int): Space count to prefix.
Returns:
(str): Code with indentation restored.
"""
indent = " " * num_spaces
lines = code_block.split("\n")
return "\n".join([indent + line if line.strip() else line for line in lines])
def format_code_with_ruff(temp_dir: Path) -> None:
"""Format Python files in a temporary directory with Ruff and docstring formatter.
Args:
temp_dir (Path): Directory containing extracted Python blocks.
"""
try:
subprocess.run(["ruff", "format", "--line-length=120", str(temp_dir)], check=True)
print("Completed ruff format ✅")
except Exception as exc:
print(f"ERROR running ruff format ❌ {exc}")
try:
subprocess.run(
[
"ruff",
"check",
"--fix",
"--extend-select=F,I,D,UP,RUF",
"--target-version=py39",
"--ignore=D100,D101,D103,D104,D203,D205,D212,D213,D401,D406,D407,D413,F821,F841,RUF001,RUF002,RUF012",
str(temp_dir),
],
check=True,
)
print("Completed ruff check ✅")
except Exception as exc:
print(f"ERROR running ruff check ❌ {exc}")
# Format docstrings in extracted Python blocks (matches actions pipeline)
try:
from format_python_docstrings import format_python_file
for py_file in Path(temp_dir).glob("*.py"):
content = py_file.read_text()
formatted = format_python_file(content)
if formatted != content:
py_file.write_text(formatted)
print("Completed docstring formatting ✅")
except Exception as exc:
print(f"ERROR running docstring formatter ❌ {exc}")
def format_bash_with_prettier(temp_dir: Path) -> None:
"""Format Bash files in a temporary directory with prettier-plugin-sh.
Args:
temp_dir (Path): Directory containing extracted Bash blocks.
"""
try:
result = subprocess.run(
"npx prettier --write --print-width 120 --plugin=$(npm root -g)/prettier-plugin-sh/lib/index.cjs ./**/*.sh",
shell=True,
capture_output=True,
text=True,
cwd=temp_dir,
)
if result.returncode != 0:
print(f"ERROR running prettier-plugin-sh ❌ {result.stderr}")
else:
print("Completed bash formatting ✅")
except Exception as exc:
print(f"ERROR running prettier-plugin-sh ❌ {exc}")
def generate_temp_filename(file_path: Path, index: int, code_type: str) -> str:
"""Generate a deterministic filename for a temporary code block.
Args:
file_path (Path): Source markdown path.
index (int): Block index for uniqueness.
code_type (str): Language identifier.
Returns:
(str): Safe filename for the temporary code file.
"""
stem = file_path.stem
code_letter = code_type[0]
path_part = str(file_path.parent).replace("/", "_").replace("\\", "_").replace(" ", "-")
hash_val = hashlib.md5(f"{file_path}_{index}".encode(), usedforsecurity=False).hexdigest()[:6]
ext = ".py" if code_type == "python" else ".sh"
filename = f"{stem}_{path_part}_{code_letter}{index}_{hash_val}{ext}"
return re.sub(r"[^\w\-.]", "_", filename)
def process_markdown_file(
file_path: Path,
temp_dir: Path,
process_python: bool = True,
process_bash: bool = True,
) -> tuple[str, list[tuple[int, str, Path, str]]]:
"""Extract code blocks from a markdown file and store them as temporary files.
Args:
file_path (Path): Markdown path to process.
temp_dir (Path): Directory to store temporary files.
process_python (bool, optional): Enable Python block extraction.
process_bash (bool, optional): Enable Bash block extraction.
Returns:
markdown_content (str): Original markdown content.
temp_files (list): Extracted block metadata.
"""
try:
markdown_content = file_path.read_text()
except Exception as exc:
print(f"Error reading file {file_path}: {exc}")
return "", []
code_blocks_by_type = extract_code_blocks(markdown_content)
temp_files: list[tuple[int, str, Path, str]] = []
code_types: list[tuple[str, int]] = []
if process_python:
code_types.append(("python", 0))
if process_bash:
code_types.append(("bash", 1000))
for code_type, offset in code_types:
for i, (indentation, code_block) in enumerate(code_blocks_by_type[code_type]):
num_spaces = len(indentation)
code_without_indentation = remove_indentation(code_block, num_spaces)
temp_file_path = temp_dir / generate_temp_filename(file_path, i + offset, code_type)
try:
temp_file_path.write_text(code_without_indentation)
except Exception as exc:
print(f"Error writing temp file {temp_file_path}: {exc}")
continue
temp_files.append((num_spaces, code_block, temp_file_path, code_type))
return markdown_content, temp_files
def update_markdown_file(file_path: Path, markdown_content: str, temp_files: list[tuple[int, str, Path, str]]) -> None:
"""Replace markdown code blocks with formatted versions.
Args:
file_path (Path): Markdown file to update.
markdown_content (str): Original content.
temp_files (list): Metadata for formatted code blocks.
"""
for num_spaces, original_code_block, temp_file_path, code_type in temp_files:
try:
formatted_code = temp_file_path.read_text().rstrip("\n")
except Exception as exc:
print(f"Error reading temp file {temp_file_path}: {exc}")
continue
formatted_code_with_indentation = add_indentation(formatted_code, num_spaces)
for lang in LANGUAGE_TAGS[code_type]:
markdown_content = markdown_content.replace(
f"{' ' * num_spaces}```{lang}\n{original_code_block}\n{' ' * num_spaces}```",
f"{' ' * num_spaces}```{lang}\n{formatted_code_with_indentation}\n{' ' * num_spaces}```",
)
try:
file_path.write_text(markdown_content)
except Exception as exc:
print(f"Error writing file {file_path}: {exc}")
def run_prettier(markdown_file: Path) -> None:
"""Format a markdown file with Prettier when available.
Args:
markdown_file (Path): Markdown file to format.
"""
if not check_prettier_version():
return
is_docs = "docs" in markdown_file.parts and "reference" not in markdown_file.parts
command = ["npx", "prettier", "--write", "--list-different", "--print-width", "120", str(markdown_file)]
if is_docs:
command = ["npx", "prettier", "--tab-width", "4", "--print-width", "120", "--write", "--list-different", str(markdown_file)]
subprocess.run(command, capture_output=True, check=False, cwd=markdown_file.parent)
def format_markdown_file(markdown_file: Path) -> None:
"""Format markdown-embedded code and run Prettier on the file.
Args:
markdown_file (Path): Markdown file to process.
"""
with TemporaryDirectory() as tmp_dir_name:
temp_dir = Path(tmp_dir_name)
markdown_content, temp_files = process_markdown_file(markdown_file, temp_dir)
if not temp_files:
run_prettier(markdown_file)
return
has_python = any(code_type == "python" for *_, code_type in temp_files)
has_bash = any(code_type == "bash" for *_, code_type in temp_files)
if has_python:
format_code_with_ruff(temp_dir)
if has_bash:
format_bash_with_prettier(temp_dir)
update_markdown_file(markdown_file, markdown_content, temp_files)
run_prettier(markdown_file)
def read_markdown_path() -> Path | None:
"""Read the markdown path from stdin payload.
Returns:
markdown_path (Path | None): Markdown path when present and valid.
"""
try:
data = json.load(sys.stdin)
except Exception:
return None
file_path = data.get("tool_input", {}).get("file_path", "")
path = Path(file_path) if file_path else None
if not path or path.suffix.lower() != ".md" or not path.exists():
return None
if any(p in path.parts for p in ['.git', '.venv', 'venv', 'env', '.env', '__pycache__', '.mypy_cache', '.pytest_cache', '.tox', '.nox', '.eggs', 'eggs', '.idea', '.vscode', 'node_modules', 'site-packages', 'build', 'dist', '.claude']):
return None
return path
def main() -> None:
"""Run markdown formatting hook."""
markdown_file = read_markdown_path()
if markdown_file:
format_markdown_file(markdown_file)
sys.exit(0)
if __name__ == "__main__":
main()

18
hooks/claude-codex-settings/scripts/notify.sh Executable file
View File

@@ -0,0 +1,18 @@
#!/usr/bin/env bash
# Read JSON input from Claude Code hook
input=$(cat)
# Extract message from JSON (basic parsing)
message=$(echo "$input" | grep -o '"message":"[^"]*"' | cut -d'"' -f4)
title="Claude Code"
# Terminal bell - triggers VSCode visual bell icon
printf '\a'
# Send OS notification
if [[ "$OSTYPE" == "darwin"* ]]; then
osascript -e "display notification \"${message}\" with title \"${title}\" sound name \"Glass\""
elif command -v notify-send &> /dev/null; then
notify-send "${title}" "${message}" -u normal -i terminal
fi

66
hooks/claude-codex-settings/scripts/prettier_formatting.py Executable file
View File

@@ -0,0 +1,66 @@
#!/usr/bin/env python3
"""
PostToolUse hook: Auto-format JS/TS/CSS/JSON/YAML/HTML/Vue/Svelte files with prettier
"""
import json
import re
import shutil
import subprocess
import sys
from pathlib import Path
# File extensions that prettier handles
PRETTIER_EXTENSIONS = {'.js', '.jsx', '.ts', '.tsx', '.css', '.less', '.scss',
'.json', '.yml', '.yaml', '.html', '.vue', '.svelte'}
LOCK_FILE_PATTERN = re.compile(r'.*lock\.(json|yaml|yml)$|.*\.lock$')
def check_prettier_version() -> bool:
"""Check if prettier is installed and warn if version differs from 3.6.2."""
if not shutil.which('npx'):
return False
try:
result = subprocess.run(['npx', 'prettier', '--version'],
capture_output=True, text=True, check=False, timeout=5)
if result.returncode == 0:
version = result.stdout.strip()
if '3.6.2' not in version:
print(f"⚠️ Prettier version mismatch: expected 3.6.2, found {version}")
return True
except Exception:
pass
return False
def main():
try:
data = json.load(sys.stdin)
file_path = data.get("tool_input", {}).get("file_path", "")
if not file_path:
sys.exit(0)
py_file = Path(file_path)
if not py_file.exists() or py_file.suffix not in PRETTIER_EXTENSIONS:
sys.exit(0)
# Skip virtual env, cache, .claude directories, lock files, model.json, and minified assets
if any(p in py_file.parts for p in ['.git', '.venv', 'venv', 'env', '.env', '__pycache__', '.mypy_cache', '.pytest_cache', '.tox', '.nox', '.eggs', 'eggs', '.idea', '.vscode', 'node_modules', 'site-packages', 'build', 'dist', '.claude']) or LOCK_FILE_PATTERN.match(py_file.name) or py_file.name == 'model.json' or py_file.name.endswith(('.min.js', '.min.css')):
sys.exit(0)
# Check if prettier is available
if not check_prettier_version():
sys.exit(0)
# Run prettier
subprocess.run([
'npx', 'prettier', '--write', '--list-different', '--print-width', '120', str(py_file)
], capture_output=True, check=False, cwd=py_file.parent)
except Exception:
pass
sys.exit(0)
if __name__ == "__main__":
main()

67
hooks/claude-codex-settings/scripts/python_code_quality.py Executable file
View File

@@ -0,0 +1,67 @@
#!/usr/bin/env python3
"""PostToolUse hook: Auto-format Python files with ruff, provide feedback on errors."""
import json
import shutil
import subprocess
import sys
from pathlib import Path
EXCLUDED_DIRS = {'.git', '.venv', 'venv', 'env', '.env', '__pycache__', '.mypy_cache', '.pytest_cache',
'.tox', '.nox', '.eggs', 'eggs', '.idea', '.vscode', 'node_modules', 'site-packages',
'build', 'dist', '.claude'}
def main():
try:
data = json.load(sys.stdin)
except Exception:
sys.exit(0)
file_path = data.get("tool_input", {}).get("file_path", "")
if not file_path.endswith('.py'):
sys.exit(0)
py_file = Path(file_path)
if not py_file.exists() or any(p in py_file.parts for p in EXCLUDED_DIRS):
sys.exit(0)
if not shutil.which('ruff'):
sys.exit(0)
work_dir = py_file.parent
issues = []
# Run ruff check with fixes
check_result = subprocess.run([
'ruff', 'check', '--fix',
'--extend-select', 'F,I,D,UP,RUF,FA',
'--target-version', 'py39',
'--ignore', 'D100,D104,D203,D205,D212,D213,D401,D406,D407,D413,RUF001,RUF002,RUF012',
str(py_file)
], capture_output=True, text=True, cwd=work_dir)
if check_result.returncode != 0:
error_output = check_result.stdout.strip() or check_result.stderr.strip()
issues.append(f'Ruff check found unfixable errors in {py_file.name}:\n{error_output}')
# Run ruff format regardless of check result
format_result = subprocess.run([
'ruff', 'format', '--line-length', '120', str(py_file)
], capture_output=True, text=True, cwd=work_dir)
if format_result.returncode != 0:
error_output = format_result.stderr.strip()
issues.append(f'Ruff format failed for {py_file.name}:\n{error_output}')
# Output single JSON with all collected feedback
if issues:
output = {"hookSpecificOutput": {"hookEventName": "PostToolUse",
"additionalContext": "\n\n".join(issues)}}
print(json.dumps(output))
sys.exit(0)
if __name__ == '__main__':
main()

83
hooks/claude-codex-settings/scripts/sync_marketplace_to_plugins.py Executable file
View File

@@ -0,0 +1,83 @@
#!/usr/bin/env python3
"""Sync marketplace.json plugin entries to individual plugin.json files."""
import json
import sys
from pathlib import Path
def get_edited_file_path():
"""Extract file path from hook input."""
try:
input_data = json.load(sys.stdin)
return input_data.get("tool_input", {}).get("file_path", "")
except (json.JSONDecodeError, KeyError):
return ""
def sync_marketplace_to_plugins():
"""Sync marketplace.json entries to individual plugin.json files."""
edited_path = get_edited_file_path()
# Only trigger for marketplace.json edits
if not edited_path.endswith("marketplace.json"):
return 0
marketplace_path = Path(edited_path)
if not marketplace_path.exists():
return 0
try:
marketplace = json.loads(marketplace_path.read_text())
except (json.JSONDecodeError, OSError) as e:
print(f"❌ Failed to read marketplace.json: {e}", file=sys.stderr)
return 2
plugins = marketplace.get("plugins", [])
if not plugins:
return 0
marketplace_dir = marketplace_path.parent.parent # Go up from .claude-plugin/
synced = []
for plugin in plugins:
source = plugin.get("source")
if not source:
continue
# Resolve plugin directory relative to marketplace root
plugin_dir = (marketplace_dir / source).resolve()
plugin_json_dir = plugin_dir / ".claude-plugin"
plugin_json_path = plugin_json_dir / "plugin.json"
# Build plugin.json content from marketplace entry
plugin_data = {"name": plugin.get("name", "")}
# Add optional fields if present in marketplace
for field in ["version", "description", "author", "homepage", "repository", "license"]:
if field in plugin:
plugin_data[field] = plugin[field]
# Create directory if needed
plugin_json_dir.mkdir(parents=True, exist_ok=True)
# Check if update needed
current_data = {}
if plugin_json_path.exists():
try:
current_data = json.loads(plugin_json_path.read_text())
except json.JSONDecodeError:
pass
if current_data != plugin_data:
plugin_json_path.write_text(json.dumps(plugin_data, indent=2) + "\n")
synced.append(plugin.get("name", source))
if synced:
print(f"✓ Synced {len(synced)} plugin manifest(s): {', '.join(synced)}")
return 0
if __name__ == "__main__":
sys.exit(sync_marketplace_to_plugins())

53
hooks/claude-codex-settings/scripts/tavily_extract_to_advanced.py Executable file
View File

@@ -0,0 +1,53 @@
#!/usr/bin/env python3
"""Intercept mcp__tavily__tavily-extract to upgrade extract_depth and suggest gh CLI for GitHub URLs."""
import json
import sys
try:
data = json.load(sys.stdin)
tool_input = data["tool_input"]
urls = tool_input.get("urls", [])
# Always ensure extract_depth="advanced"
tool_input["extract_depth"] = "advanced"
# Check for GitHub URLs and add soft suggestion
github_domains = ("github.com", "raw.githubusercontent.com", "gist.github.com")
github_urls = [url for url in urls if any(domain in url for domain in github_domains)]
if github_urls:
# Allow but suggest GitHub MCP/gh CLI for next time
print(
json.dumps(
{
"systemMessage": "Tip: For GitHub URLs, use gh CLI: `gh api repos/{owner}/{repo}/contents/{path} --jq '.content' | base64 -d` for files, `gh pr view` for PRs, `gh issue view` for issues.",
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "allow",
"updatedInput": tool_input,
},
},
separators=(",", ":"),
)
)
sys.exit(0)
# Allow the call to proceed
print(
json.dumps(
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "allow",
"updatedInput": tool_input,
}
},
separators=(",", ":"),
)
)
sys.exit(0)
except (KeyError, json.JSONDecodeError) as err:
print(f"hook-error: {err}", file=sys.stderr)
sys.exit(1)

23
hooks/claude-codex-settings/scripts/webfetch_to_tavily_extract.py Executable file
View File

@@ -0,0 +1,23 @@
#!/usr/bin/env python3
"""
PreToolUse hook: intercept WebFetch → suggest using tavily-extract instead
"""
import json
import sys
try:
data = json.load(sys.stdin)
url = data["tool_input"]["url"]
except (KeyError, json.JSONDecodeError) as err:
print(f"hook-error: {err}", file=sys.stderr)
sys.exit(1)
print(json.dumps({
"systemMessage": "WebFetch detected. AI is directed to use Tavily extract instead.",
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": f"Please use mcp__tavily__tavily-extract with urls: ['{url}'] and extract_depth: 'advanced'"
}
}, separators=(',', ':')))
sys.exit(0)

24
hooks/claude-codex-settings/scripts/websearch_to_tavily_search.py Executable file
View File

@@ -0,0 +1,24 @@
#!/usr/bin/env python3
"""
PreToolUse hook: intercept WebSearch → suggest using Tavily search instead
"""
import json
import sys
try:
data = json.load(sys.stdin)
tool_input = data["tool_input"]
query = tool_input["query"]
except (KeyError, json.JSONDecodeError) as err:
print(f"hook-error: {err}", file=sys.stderr)
sys.exit(1)
print(json.dumps({
"systemMessage": "WebSearch detected. AI is directed to use Tavily search instead.",
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": f"Please use mcp__tavily__tavily_search with query: '{query}'"
}
}, separators=(',', ':')))
sys.exit(0)

119
mcp-configs/claude-codex-settings/settings.json Normal file
View File

@@ -0,0 +1,119 @@
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"env": {
"CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1",
"CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY": "1",
"DISABLE_BUG_COMMAND": "1",
"DISABLE_ERROR_REPORTING": "1",
"DISABLE_TELEMETRY": "1",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-opus-4-6",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-4-5-20250929",
"CLAUDE_CODE_SUBAGENT_MODEL": "claude-opus-4-6",
"MAX_MCP_OUTPUT_TOKENS": "40000"
},
"attribution": {
"commit": "",
"pr": ""
},
"permissions": {
"allow": [
"Bash(find:*)",
"Bash(rg:*)",
"Bash(echo:*)",
"Bash(grep:*)",
"Bash(ls:*)",
"Bash(cat:*)",
"Bash(sed:*)",
"Bash(tree:*)",
"Bash(tail:*)",
"Bash(pgrep:*)",
"Bash(ps:*)",
"Bash(sort:*)",
"Bash(dmesg:*)",
"Bash(done)",
"Bash(ruff:*)",
"Bash(nvidia-smi:*)",
"Bash(pdflatex:*)",
"Bash(biber:*)",
"Bash(tmux ls:*)",
"Bash(tmux capture-pane:*)",
"Bash(tmux list-sessions:*)",
"Bash(tmux list-windows:*)",
"Bash(gh pr list:*)",
"Bash(gh pr view:*)",
"Bash(gh pr diff:*)",
"Bash(gh api user:*)",
"Bash(gh repo view:*)",
"Bash(gh issue view:*)",
"Bash(git branch --show-current:*)",
"Bash(git diff:*)",
"Bash(git status:*)",
"Bash(git rev-parse:*)",
"Bash(git push:*)",
"Bash(git log:*)",
"Bash(git -C :* branch --show-current:*)",
"Bash(git -C :* diff:*)",
"Bash(git -C :* status:*)",
"Bash(git -C :* rev-parse:*)",
"Bash(git -C :* push:*)",
"Bash(git -C :* log:*)",
"Bash(git fetch --prune:*)",
"Bash(git worktree list:*)",
"Bash(uv run ruff:*)",
"Bash(python --version:*)",
"WebSearch",
"WebFetch(domain:docs.litellm.ai)",
"WebFetch(domain:openai.com)",
"WebFetch(domain:anthropic.com)",
"WebFetch(domain:docs.anthropic.com)",
"WebFetch(domain:github.com)",
"WebFetch(domain:gradio.app)",
"WebFetch(domain:arxiv.org)",
"WebFetch(domain:pypi.org)",
"WebFetch(domain:docs.ultralytics.com)",
"WebFetch(domain:sli.dev)",
"WebFetch(domain:docs.vllm.ai)",
"mcp__tavily__tavily_extract",
"mcp__tavily__tavily_search",
"mcp__context7__resolve-library-id",
"mcp__context7__get-library-docs",
"mcp__github__get_me",
"mcp__github__pull_request_read",
"mcp__github__get_file_contents",
"mcp__github__get_workflow_run",
"mcp__github__get_job_logs",
"mcp__github__get_pull_request_comments",
"mcp__github__get_pull_request_reviews",
"mcp__github__issue_read",
"mcp__github__list_pull_requests",
"mcp__github__list_commits",
"mcp__github__list_workflows",
"mcp__github__list_workflow_runs",
"mcp__github__list_workflow_jobs",
"mcp__github__search_pull_requests",
"mcp__github__search_issues",
"mcp__github__search_code",
"mcp__mongodb__list_databases",
"mcp__mongodb__list_collections",
"mcp__mongodb__get_collection_schema",
"mcp__mongodb__collection-indexes",
"mcp__mongodb__db-stats",
"mcp__mongodb__count",
"mcp__supabase__list_tables",
"mcp__gcloud-observability__list_log_entries"
]
},
"outputStyle": "Explanatory",
"model": "opus",
"extraKnownMarketplaces": {
"claude-settings": {
"source": {
"source": "github",
"repo": "fcakyon/claude-codex-settings"
}
}
},
"spinnerTipsEnabled": false,
"alwaysThinkingEnabled": true
}

3319
registries/awesome-openclaw-skills-registry.md Normal file
View File

File diff suppressed because it is too large Load Diff

277
skills/ai-platforms-consolidated/SKILL.md Normal file
View File

@@ -0,0 +1,277 @@
---
name: ai-platforms-consolidated
description: "Consolidated AI platforms reference. AUTO-TRIGGERS when: comparing AI platforms, cross-platform patterns, choosing between tools, MiniMax vs Super Z, multimodal capabilities overview, expert agents summary, document processing matrix, SDK patterns comparison."
priority: 90
autoTrigger: true
triggers:
- "compare platforms"
- "which platform"
- "AI platform"
- "MiniMax vs"
- "Super Z vs"
- "GLM vs"
- "cross-platform"
- "expert agent"
- "multimodal capabilities"
- "document processing"
- "image operations"
- "video operations"
- "audio operations"
- "SDK comparison"
- "tech stack comparison"
- "agent design patterns"
---
# AI Platforms Consolidated Reference
Quick reference guide combining expertise from MiniMax, Super Z (GLM), and z.ai tooling.
---
## Quick Navigation
| Need | Skill to Use | Source |
|------|-------------|--------|
| Agent design inspiration | `/minimax-experts` | MiniMax Platform |
| Multimodal AI patterns | `/glm-skills` | Super Z Platform |
| Next.js 15 development | `/zai-tooling-reference` | z.ai Tooling |
| Document processing | This file | All platforms |
---
## Platform Comparison
| Feature | MiniMax | Super Z (GLM) |
|---------|---------|---------------|
| Expert Agents | 40 | 6 subagents |
| Focus | Business/Creative | Technical/Development |
| SDK | Platform-specific | z-ai-web-dev-sdk |
| Image Generation | Built-in | SDK-based |
| Video Generation | Built-in | SDK-based |
| Document Processing | Doc Processor | PDF/DOCX/XLSX/PPTX |
| Audio | Limited | ASR + TTS |
---
## Expert Agent Categories
### Content Creation (Both Platforms)
| Expert | Platform | Best For |
|--------|----------|----------|
| Landing Page Builder | MiniMax | Marketing pages |
| Visual Lab | MiniMax | Presentations, infographics |
| Video Story Generator | MiniMax | Video from images/text |
| Icon Maker | MiniMax | App/web icons |
| image-generation | Super Z | Programmatic image creation |
| podcast-generate | Super Z | Audio content |
| story-video-generation | Super Z | Story to video |
### Finance & Trading (MiniMax)
| Expert | Specialization |
|--------|---------------|
| Hedge Fund Expert Team | 18-analyst team (Buffett, Munger perspectives) |
| AI Trading Consortium | Multi-strategy trading |
| Crypto Trading Agent | BTC/ETH/SOL with risk management |
| Quant Trading Strategist | Options, futures, backtesting |
### Development (Both Platforms)
| Expert | Platform | Specialization |
|--------|----------|---------------|
| Mini Coder Max | MiniMax | Parallel subagent coding |
| Peak Coder | MiniMax | Checklist-driven development |
| Prompt Development Studio | MiniMax | Prompt engineering |
| Remotion Video Assistant | MiniMax | React video development |
| full-stack-developer | Super Z | Next.js + Prisma |
| frontend-styling-expert | Super Z | CSS, responsive design |
### Career & Business
| Expert | Platform | Use Case |
|--------|----------|----------|
| Job Hunter Agent | MiniMax | Auto job application |
| CV Optimization Expert | MiniMax | ATS-optimized resumes |
| CEO Assistant | MiniMax | Executive support |
| PRD Assistant | MiniMax | Product requirements |
| SaaS Niche Finder | MiniMax | Business validation |
---
## Document Processing Matrix
| Format | MiniMax (Doc Processor) | Super Z Skill |
|--------|------------------------|---------------|
| PDF | Create, convert, edit | pdf skill |
| DOCX | Full lifecycle | docx skill |
| XLSX | Limited | xlsx skill (formulas, charts) |
| PPTX | Limited | pptx skill |
---
## Multimodal Capabilities
### Image Operations
| Task | MiniMax | Super Z SDK |
|------|---------|-------------|
| Generate | Icon Maker, Image Craft | `zai.images.generations.create()` |
| Edit | Image Craft Pro | `zai.images.edits.create()` |
| Understand | Limited | `image-understand` skill |
| Stickers | GIF Sticker Maker | Custom implementation |
### Video Operations
| Task | MiniMax | Super Z SDK |
|------|---------|-------------|
| Generate | Video Story Generator | `video-generation` skill |
| Understand | Limited | `video-understand` skill |
| Story to Video | Built-in | `story-video-generation` |
### Audio Operations
| Task | MiniMax | Super Z SDK |
|------|---------|-------------|
| Speech to Text | Limited | `ASR` skill |
| Text to Speech | Limited | `TTS` skill |
| Podcast | Limited | `podcast-generate` |
---
## Design Patterns Reference
### Multi-Agent Teams
```
Use when: Complex analysis requiring multiple perspectives
Pattern: Hedge Fund Expert (18 specialists)
Implementation: Spawn subagents with specific roles
```
### Safety-First Operations
```
Use when: Destructive operations, file management
Pattern: Tidy Folder (backup before, move not delete)
Implementation: Automatic backups, reversible actions
```
### One-to-Many Generation
```
Use when: Creative exploration, A/B testing
Pattern: GIF Sticker Maker (4 variations), 9 Cinematic Angles
Implementation: Single input → multiple output variations
```
### Perspective Simulation
```
Use when: Decision validation, bias checking
Pattern: AI Trading Consortium (Buffett, Lynch, Burry)
Implementation: Generate multiple expert opinions
```
### Binary Decision Systems
```
Use when: Risk management, clear action signals
Pattern: Crypto Trading Agent (EXECUTE/NO TRADE)
Implementation: Strict output constraints
```
### Multi-Format Output
```
Use when: Reaching different audiences
Pattern: Knowledge Digest (notes, quizzes, slides, audio)
Implementation: Transform single source to multiple formats
```
---
## SDK Quick Reference (z-ai-web-dev-sdk)
### Initialization
```javascript
import ZAI from 'z-ai-web-dev-sdk';
const zai = await ZAI.create();
```
### LLM Chat
```javascript
const completion = await zai.chat.completions.create({
messages: [
{ role: 'system', content: 'You are helpful.' },
{ role: 'user', content: 'Hello!' }
]
});
```
### Image Generation
```javascript
const image = await zai.images.generations.create({
prompt: 'A sunset over mountains',
size: '1024x1024'
});
// image.data[0].base64 contains the image
```
### Web Search
```javascript
const results = await zai.functions.invoke("web_search", {
query: "latest AI news",
num: 10
});
```
### Video Generation (Async)
```javascript
const task = await zai.videos.generations.create({ prompt });
const status = await zai.videos.generations.status(task.id);
const result = await zai.videos.generations.retrieve(task.id);
```
---
## Tech Stack Reference (z.ai Tooling)
| Layer | Technology |
|-------|------------|
| Framework | Next.js 16 + React 19 |
| Language | TypeScript 5 |
| Styling | Tailwind CSS 4 |
| UI | shadcn/ui (50+ components) |
| Database | Prisma + SQLite |
| State | Zustand |
| Data Fetching | TanStack Query |
| AI | z-ai-web-dev-sdk |
| Auth | NextAuth |
| Package Manager | Bun |
---
## When to Use This Reference
1. **Choosing the right tool**: Compare platforms side-by-side
2. **Cross-platform patterns**: Learn from multiple implementations
3. **SDK integration**: Quick code snippets
4. **Design decisions**: Pattern matching for your use case
5. **Skill discovery**: Find relevant capabilities
---
## Installed Skills Summary
| Skill | Location | Content |
|-------|----------|---------|
| minimax-experts | `~/.claude/skills/minimax-experts/` | 40 AI experts catalog |
| glm-skills | `~/.claude/skills/glm-skills/` | Super Z skills & SDK |
| zai-tooling-reference | `~/.claude/skills/zai-tooling-reference/` | Next.js 15 patterns |
| ai-platforms-consolidated | `~/.claude/skills/ai-platforms-consolidated/` | This file |
## Codebase Reference
| Location | Content |
|----------|---------|
| `~/reference-codebases/z-ai-tooling/` | Full Next.js 15 project |
---
*Generated from MiniMax Expert Catalog, GLM5 Agents & Skills, and z.ai Tooling documentation*
*Installation date: 2026-02-13*

57
skills/external/azure-tools-azure-usage/SKILL.md vendored Normal file
View File

@@ -0,0 +1,57 @@
---
name: azure-usage
description: This skill should be used when user asks to "query Azure resources", "list storage accounts", "manage Key Vault secrets", "work with Cosmos DB", "check AKS clusters", "use Azure MCP", or interact with any Azure service.
---
# Azure MCP Best Practices
## Tool Selection
| Task | Tool | Example |
| -------------------- | ---------------------- | ----------------------------------- |
| List resources | `mcp__azure__*_list` | Storage accounts, Key Vault secrets |
| Get resource details | `mcp__azure__*_get` | Container details, database info |
| Create resources | `mcp__azure__*_create` | New secrets, storage containers |
| Query data | `mcp__azure__*_query` | Log Analytics, Cosmos DB |
## Common Operations
### Storage
- `storage_accounts_list` - List storage accounts
- `storage_blobs_list` - List blobs in container
- `storage_blobs_upload` - Upload file to blob
### Key Vault
- `keyvault_secrets_list` - List secrets
- `keyvault_secrets_get` - Get secret value
- `keyvault_secrets_set` - Create/update secret
### Cosmos DB
- `cosmosdb_databases_list` - List databases
- `cosmosdb_containers_list` - List containers
- `cosmosdb_query` - Query documents
### AKS
- `aks_clusters_list` - List AKS clusters
- `aks_nodepools_list` - List node pools
### Monitor
- `monitor_logs_query` - Query Log Analytics
## Authentication
Azure MCP uses Azure Identity SDK. Authenticate via:
- `az login` (Azure CLI - recommended)
- VS Code Azure extension
- Environment variables (service principal)
## Reference
- [Azure MCP Server](https://github.com/microsoft/mcp/tree/main/servers/Azure.Mcp.Server)
- [Supported Services (40+)](https://learn.microsoft.com/azure/developer/azure-mcp-server/)

19
skills/external/azure-tools-setup/SKILL.md vendored Normal file
View File

@@ -0,0 +1,19 @@
---
name: setup
description: This skill should be used when user encounters "Azure MCP error", "Azure authentication failed", "az login required", "Azure CLI not found", or needs help configuring Azure MCP integration.
---
# Azure Tools Setup
Run `/azure-tools:setup` to configure Azure MCP.
## Quick Fixes
- **Authentication failed** - Run `az login` to authenticate
- **Azure CLI not found** - Install Azure CLI first
- **Permission denied** - Check Azure RBAC roles for your account
- **Node.js not found** - Install Node.js 20 LTS or later
## Don't Need Azure MCP?
Disable via `/mcp` command to prevent errors.

96
skills/external/brainstorming/SKILL.md vendored Normal file
View File

@@ -0,0 +1,96 @@
---
name: brainstorming
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
---
# Brainstorming Ideas Into Designs
## Overview
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>
## Anti-Pattern: "This Is Too Simple To Need A Design"
Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
## Checklist
You MUST create a task for each of these items and complete them in order:
1. **Explore project context** — check files, docs, recent commits
2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
3. **Propose 2-3 approaches** — with trade-offs and your recommendation
4. **Present design** — in sections scaled to their complexity, get user approval after each section
5. **Write design doc** — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit
6. **Transition to implementation** — invoke writing-plans skill to create implementation plan
## Process Flow
```dot
digraph brainstorming {
"Explore project context" [shape=box];
"Ask clarifying questions" [shape=box];
"Propose 2-3 approaches" [shape=box];
"Present design sections" [shape=box];
"User approves design?" [shape=diamond];
"Write design doc" [shape=box];
"Invoke writing-plans skill" [shape=doublecircle];
"Explore project context" -> "Ask clarifying questions";
"Ask clarifying questions" -> "Propose 2-3 approaches";
"Propose 2-3 approaches" -> "Present design sections";
"Present design sections" -> "User approves design?";
"User approves design?" -> "Present design sections" [label="no, revise"];
"User approves design?" -> "Write design doc" [label="yes"];
"Write design doc" -> "Invoke writing-plans skill";
}
```
**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
## The Process
**Understanding the idea:**
- Check out the current project state first (files, docs, recent commits)
- Ask questions one at a time to refine the idea
- Prefer multiple choice questions when possible, but open-ended is fine too
- Only one question per message - if a topic needs more exploration, break it into multiple questions
- Focus on understanding: purpose, constraints, success criteria
**Exploring approaches:**
- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why
**Presenting the design:**
- Once you believe you understand what you're building, present the design
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense
## After the Design
**Documentation:**
- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
- Use elements-of-style:writing-clearly-and-concisely skill if available
- Commit the design document to git
**Implementation:**
- Invoke the writing-plans skill to create a detailed implementation plan
- Do NOT invoke any other skill. writing-plans is the next step.
## Key Principles
- **One question at a time** - Don't overwhelm with multiple questions
- **Multiple choice preferred** - Easier to answer than open-ended when possible
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
- **Explore alternatives** - Always propose 2-3 approaches before settling
- **Incremental validation** - Present design, get approval before moving on
- **Be flexible** - Go back and clarify when something doesn't make sense

39
skills/external/ccproxy-tools-setup/SKILL.md vendored Normal file
View File

@@ -0,0 +1,39 @@
---
name: setup
description: This skill should be used when user encounters "ccproxy not found", "LiteLLM connection failed", "localhost:4000 refused", "OAuth failed", "proxy not running", or needs help configuring ccproxy/LiteLLM integration.
---
# ccproxy-tools Setup
Run `/ccproxy-tools:setup` to configure ccproxy/LiteLLM.
## Quick Fixes
- **ccproxy/litellm not found** - Install with `uv tool install 'litellm[proxy]' 'ccproxy'`
- **Connection refused localhost:4000** - Start proxy: `ccproxy start` or `litellm --config ~/.litellm/config.yaml`
- **OAuth failed** - Re-run `ccproxy init` and authenticate via browser
- **Invalid model name** - Check model names in `.claude/settings.json` match LiteLLM config
- **Changes not applied** - Restart Claude Code after updating settings
## Environment Variables
Key settings in `.claude/settings.json` → `env`:
| Variable | Purpose |
| -------------------------------- | -------------------------------------- |
| `ANTHROPIC_BASE_URL` | Proxy endpoint (http://localhost:4000) |
| `ANTHROPIC_AUTH_TOKEN` | Auth token for proxy |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Opus model name |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Sonnet model name |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Haiku model name |
## Check Proxy Health
```bash
curl http://localhost:4000/health
```
## Resources
- ccproxy: https://github.com/starbased-co/ccproxy
- LiteLLM: https://docs.litellm.ai

180
skills/external/dispatching-parallel-agents/SKILL.md vendored Normal file
View File

@@ -0,0 +1,180 @@
---
name: dispatching-parallel-agents
description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
---
# Dispatching Parallel Agents
## Overview
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
## When to Use
```dot
digraph when_to_use {
"Multiple failures?" [shape=diamond];
"Are they independent?" [shape=diamond];
"Single agent investigates all" [shape=box];
"One agent per problem domain" [shape=box];
"Can they work in parallel?" [shape=diamond];
"Sequential agents" [shape=box];
"Parallel dispatch" [shape=box];
"Multiple failures?" -> "Are they independent?" [label="yes"];
"Are they independent?" -> "Single agent investigates all" [label="no - related"];
"Are they independent?" -> "Can they work in parallel?" [label="yes"];
"Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
"Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}
```
**Use when:**
- 3+ test files failing with different root causes
- Multiple subsystems broken independently
- Each problem can be understood without context from others
- No shared state between investigations
**Don't use when:**
- Failures are related (fix one might fix others)
- Need to understand full system state
- Agents would interfere with each other
## The Pattern
### 1. Identify Independent Domains
Group failures by what's broken:
- File A tests: Tool approval flow
- File B tests: Batch completion behavior
- File C tests: Abort functionality
Each domain is independent - fixing tool approval doesn't affect abort tests.
### 2. Create Focused Agent Tasks
Each agent gets:
- **Specific scope:** One test file or subsystem
- **Clear goal:** Make these tests pass
- **Constraints:** Don't change other code
- **Expected output:** Summary of what you found and fixed
### 3. Dispatch in Parallel
```typescript
// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently
```
### 4. Review and Integrate
When agents return:
- Read each summary
- Verify fixes don't conflict
- Run full test suite
- Integrate all changes
## Agent Prompt Structure
Good agent prompts are:
1. **Focused** - One clear problem domain
2. **Self-contained** - All context needed to understand the problem
3. **Specific about output** - What should the agent return?
```markdown
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0
These are timing/race condition issues. Your task:
1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
- Replacing arbitrary timeouts with event-based waiting
- Fixing bugs in abort implementation if found
- Adjusting test expectations if testing changed behavior
Do NOT just increase timeouts - find the real issue.
Return: Summary of what you found and what you fixed.
```
## Common Mistakes
**❌ Too broad:** "Fix all the tests" - agent gets lost
**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
**❌ No context:** "Fix the race condition" - agent doesn't know where
**✅ Context:** Paste the error messages and test names
**❌ No constraints:** Agent might refactor everything
**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
**❌ Vague output:** "Fix it" - you don't know what changed
**✅ Specific:** "Return summary of root cause and changes"
## When NOT to Use
**Related failures:** Fixing one might fix others - investigate together first
**Need full context:** Understanding requires seeing entire system
**Exploratory debugging:** You don't know what's broken yet
**Shared state:** Agents would interfere (editing same files, using same resources)
## Real Example from Session
**Scenario:** 6 test failures across 3 files after major refactoring
**Failures:**
- agent-tool-abort.test.ts: 3 failures (timing issues)
- batch-completion-behavior.test.ts: 2 failures (tools not executing)
- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
**Dispatch:**
```
Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts
```
**Results:**
- Agent 1: Replaced timeouts with event-based waiting
- Agent 2: Fixed event structure bug (threadId in wrong place)
- Agent 3: Added wait for async tool execution to complete
**Integration:** All fixes independent, no conflicts, full suite green
**Time saved:** 3 problems solved in parallel vs sequentially
## Key Benefits
1. **Parallelization** - Multiple investigations happen simultaneously
2. **Focus** - Each agent has narrow scope, less context to track
3. **Independence** - Agents don't interfere with each other
4. **Speed** - 3 problems solved in time of 1
## Verification
After agents return:
1. **Review each summary** - Understand what changed
2. **Check for conflicts** - Did agents edit same code?
3. **Run full suite** - Verify all fixes work together
4. **Spot check** - Agents can make systematic errors
## Real-World Impact
From debugging session (2025-10-03):
- 6 failures across 3 files
- 3 agents dispatched in parallel
- All investigations completed concurrently
- All fixes integrated successfully
- Zero conflicts between agent changes

84
skills/external/executing-plans/SKILL.md vendored Normal file
View File

@@ -0,0 +1,84 @@
---
name: executing-plans
description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
---
# Executing Plans
## Overview
Load plan, review critically, execute tasks in batches, report for review between batches.
**Core principle:** Batch execution with checkpoints for architect review.
**Announce at start:** "I'm using the executing-plans skill to implement this plan."
## The Process
### Step 1: Load and Review Plan
1. Read plan file
2. Review critically - identify any questions or concerns about the plan
3. If concerns: Raise them with your human partner before starting
4. If no concerns: Create TodoWrite and proceed
### Step 2: Execute Batch
**Default: First 3 tasks**
For each task:
1. Mark as in_progress
2. Follow each step exactly (plan has bite-sized steps)
3. Run verifications as specified
4. Mark as completed
### Step 3: Report
When batch complete:
- Show what was implemented
- Show verification output
- Say: "Ready for feedback."
### Step 4: Continue
Based on feedback:
- Apply changes if needed
- Execute next batch
- Repeat until complete
### Step 5: Complete Development
After all tasks complete and verified:
- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
- Follow that skill to verify tests, present options, execute choice
## When to Stop and Ask for Help
**STOP executing immediately when:**
- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
- Plan has critical gaps preventing starting
- You don't understand an instruction
- Verification fails repeatedly
**Ask for clarification rather than guessing.**
## When to Revisit Earlier Steps
**Return to Review (Step 1) when:**
- Partner updates the plan based on your feedback
- Fundamental approach needs rethinking
**Don't force through blockers** - stop and ask.
## Remember
- Review plan critically first
- Follow plan steps exactly
- Don't skip verifications
- Reference skills when plan says to
- Between batches: just report and wait
- Stop when blocked, don't guess
- Never start implementation on main/master branch without explicit user consent
## Integration
**Required workflow skills:**
- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
- **superpowers:writing-plans** - Creates the plan this skill executes
- **superpowers:finishing-a-development-branch** - Complete development after all tasks

200
skills/external/finishing-a-development-branch/SKILL.md vendored Normal file
View File

@@ -0,0 +1,200 @@
---
name: finishing-a-development-branch
description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
---
# Finishing a Development Branch
## Overview
Guide completion of development work by presenting clear options and handling chosen workflow.
**Core principle:** Verify tests → Present options → Execute choice → Clean up.
**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
## The Process
### Step 1: Verify Tests
**Before presenting options, verify tests pass:**
```bash
# Run project's test suite
npm test / cargo test / pytest / go test ./...
```
**If tests fail:**
```
Tests failing (<N> failures). Must fix before completing:
[Show failures]
Cannot proceed with merge/PR until tests pass.
```
Stop. Don't proceed to Step 2.
**If tests pass:** Continue to Step 2.
### Step 2: Determine Base Branch
```bash
# Try common base branches
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
```
Or ask: "This branch split from main - is that correct?"
### Step 3: Present Options
Present exactly these 4 options:
```
Implementation complete. What would you like to do?
1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work
Which option?
```
**Don't add explanation** - keep options concise.
### Step 4: Execute Choice
#### Option 1: Merge Locally
```bash
# Switch to base branch
git checkout <base-branch>
# Pull latest
git pull
# Merge feature branch
git merge <feature-branch>
# Verify tests on merged result
<test command>
# If tests pass
git branch -d <feature-branch>
```
Then: Cleanup worktree (Step 5)
#### Option 2: Push and Create PR
```bash
# Push branch
git push -u origin <feature-branch>
# Create PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>
## Test Plan
- [ ] <verification steps>
EOF
)"
```
Then: Cleanup worktree (Step 5)
#### Option 3: Keep As-Is
Report: "Keeping branch <name>. Worktree preserved at <path>."
**Don't cleanup worktree.**
#### Option 4: Discard
**Confirm first:**
```
This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>
Type 'discard' to confirm.
```
Wait for exact confirmation.
If confirmed:
```bash
git checkout <base-branch>
git branch -D <feature-branch>
```
Then: Cleanup worktree (Step 5)
### Step 5: Cleanup Worktree
**For Options 1, 2, 4:**
Check if in worktree:
```bash
git worktree list | grep $(git branch --show-current)
```
If yes:
```bash
git worktree remove <worktree-path>
```
**For Option 3:** Keep worktree.
## Quick Reference
| Option | Merge | Push | Keep Worktree | Cleanup Branch |
|--------|-------|------|---------------|----------------|
| 1. Merge locally | ✓ | - | - | ✓ |
| 2. Create PR | - | ✓ | ✓ | - |
| 3. Keep as-is | - | - | ✓ | - |
| 4. Discard | - | - | - | ✓ (force) |
## Common Mistakes
**Skipping test verification**
- **Problem:** Merge broken code, create failing PR
- **Fix:** Always verify tests before offering options
**Open-ended questions**
- **Problem:** "What should I do next?" → ambiguous
- **Fix:** Present exactly 4 structured options
**Automatic worktree cleanup**
- **Problem:** Remove worktree when might need it (Option 2, 3)
- **Fix:** Only cleanup for Options 1 and 4
**No confirmation for discard**
- **Problem:** Accidentally delete work
- **Fix:** Require typed "discard" confirmation
## Red Flags
**Never:**
- Proceed with failing tests
- Merge without verifying tests on result
- Delete work without confirmation
- Force-push without explicit request
**Always:**
- Verify tests before offering options
- Present exactly 4 options
- Get typed confirmation for Option 4
- Clean up worktree for Options 1 & 4 only
## Integration
**Called by:**
- **subagent-driven-development** (Step 7) - After all tasks complete
- **executing-plans** (Step 5) - After all batches complete
**Pairs with:**
- **using-git-worktrees** - Cleans up worktree created by that skill

148
skills/external/gcloud-tools-gcloud-usage/SKILL.md vendored Normal file
View File

@@ -0,0 +1,148 @@
---
name: gcloud-usage
description: This skill should be used when user asks about "GCloud logs", "Cloud Logging queries", "Google Cloud metrics", "GCP observability", "trace analysis", or "debugging production issues on GCP".
---
# GCP Observability Best Practices
## Structured Logging
### JSON Log Format
Use structured JSON logging for better queryability:
```json
{
"severity": "ERROR",
"message": "Payment failed",
"httpRequest": { "requestMethod": "POST", "requestUrl": "/api/payment" },
"labels": { "user_id": "123", "transaction_id": "abc" },
"timestamp": "2025-01-15T10:30:00Z"
}
```
### Severity Levels
Use appropriate severity for filtering:
- **DEBUG:** Detailed diagnostic info
- **INFO:** Normal operations, milestones
- **NOTICE:** Normal but significant events
- **WARNING:** Potential issues, degraded performance
- **ERROR:** Failures that don't stop the service
- **CRITICAL:** Failures requiring immediate action
- **ALERT:** Person must take action immediately
- **EMERGENCY:** System is unusable
## Log Filtering Queries
### Common Filters
```
# By severity
severity >= WARNING
# By resource
resource.type="cloud_run_revision"
resource.labels.service_name="my-service"
# By time
timestamp >= "2025-01-15T00:00:00Z"
# By text content
textPayload =~ "error.*timeout"
# By JSON field
jsonPayload.user_id = "123"
# Combined
severity >= ERROR AND resource.labels.service_name="api"
```
### Advanced Queries
```
# Regex matching
textPayload =~ "status=[45][0-9]{2}"
# Substring search
textPayload : "connection refused"
# Multiple values
severity = (ERROR OR CRITICAL)
```
## Metrics vs Logs vs Traces
### When to Use Each
**Metrics:** Aggregated numeric data over time
- Request counts, latency percentiles
- Resource utilization (CPU, memory)
- Business KPIs (orders/minute)
**Logs:** Detailed event records
- Error details and stack traces
- Audit trails
- Debugging specific requests
**Traces:** Request flow across services
- Latency breakdown by service
- Identifying bottlenecks
- Distributed system debugging
## Alert Policy Design
### Alert Best Practices
- **Avoid alert fatigue:** Only alert on actionable issues
- **Use multi-condition alerts:** Reduce noise from transient spikes
- **Set appropriate windows:** 5-15 min for most metrics
- **Include runbook links:** Help responders act quickly
### Common Alert Patterns
**Error rate:**
- Condition: Error rate > 1% for 5 minutes
- Good for: Service health monitoring
**Latency:**
- Condition: P99 latency > 2s for 10 minutes
- Good for: Performance degradation detection
**Resource exhaustion:**
- Condition: Memory > 90% for 5 minutes
- Good for: Capacity planning triggers
## Cost Optimization
### Reducing Log Costs
- **Exclusion filters:** Drop verbose logs at ingestion
- **Sampling:** Log only percentage of high-volume events
- **Shorter retention:** Reduce default 30-day retention
- **Downgrade logs:** Route to cheaper storage buckets
### Exclusion Filter Examples
```
# Exclude health checks
resource.type="cloud_run_revision" AND httpRequest.requestUrl="/health"
# Exclude debug logs in production
severity = DEBUG
```
## Debugging Workflow
1. **Start with metrics:** Identify when issues started
2. **Correlate with logs:** Filter logs around problem time
3. **Use traces:** Follow specific requests across services
4. **Check resource logs:** Look for infrastructure issues
5. **Compare baselines:** Check against known-good periods

18
skills/external/gcloud-tools-setup/SKILL.md vendored Normal file
View File

@@ -0,0 +1,18 @@
---
name: setup
description: This skill should be used when user encounters "ADC not found", "gcloud auth error", "GCloud MCP error", "Application Default Credentials", "project not set", or needs help configuring GCloud integration.
---
# GCloud Tools Setup
Run `/gcloud-tools:setup` to configure GCloud MCP.
## Quick Fixes
- **ADC not found** - Run `gcloud auth application-default login`
- **Project not set** - Run `gcloud config set project PROJECT_ID`
- **Permission denied** - Check IAM roles in Cloud Console
## Don't Need GCloud?
Disable via `/mcp` command to prevent errors.

51
skills/external/github-dev-commit-workflow/SKILL.md vendored Normal file
View File

@@ -0,0 +1,51 @@
---
name: commit-workflow
description: This skill should be used when user asks to "commit these changes", "write commit message", "stage and commit", "create a commit", "commit staged files", or runs /commit-staged or /commit-creator commands.
---
# Commit Workflow
Complete workflow for creating commits following project standards.
## Process
1. **Use commit-creator agent**
- Run `/commit-staged [context]` for automated commit handling
- Or follow manual steps below
2. **Analyze staged files only**
- Check all staged files: `git diff --cached --name-only`
- Read diffs: `git diff --cached`
- Completely ignore unstaged changes
3. **Commit message format**
- First line: `{task-type}: brief description of the big picture change`
- Task types: `feat`, `fix`, `refactor`, `docs`, `style`, `test`, `build`
- Focus on 'why' and 'what', not implementation details
- For complex changes, add bullet points after blank line
4. **Message examples**
- `feat: implement user authentication system`
- `fix: resolve memory leak in data processing pipeline`
- `refactor: restructure API handlers to align with project architecture`
5. **Documentation update**
- Check README.md for:
- New features that should be documented
- Outdated descriptions no longer matching implementation
- Missing setup instructions for new dependencies
- Update as needed based on staged changes
6. **Execution**
- Commit uses HEREDOC syntax for proper formatting
- Verify commit message has correct format
- Don't add test plans to commit messages
## Best Practices
- Analyze staged files before writing message
- Keep first line concise (50 chars recommended)
- Use active voice in message
- Reference related code if helpful
- One logical change per commit
- Ensure README reflects implementation

73
skills/external/github-dev-pr-workflow/SKILL.md vendored Normal file
View File

@@ -0,0 +1,73 @@
---
name: pr-workflow
description: This skill should be used when user asks to "create a PR", "make a pull request", "open PR for this branch", "submit changes as PR", "push and create PR", or runs /create-pr or /pr-creator commands.
---
# Pull Request Workflow
Complete workflow for creating pull requests following project standards.
## Process
1. **Verify staged changes** exist with `git diff --cached --name-only`
2. **Branch setup**
- If on main/master, create feature branch first: `feature/brief-description` or `fix/brief-description`
- Use `github-dev:commit-creator` subagent to handle staged changes if needed
3. **Documentation check**
- Update README.md or docs based on changes compared to target branch
- For config/API changes, use `mcp__tavily__tavily_search` to verify info and include sources
4. **Analyze all commits**
- Use `git diff <base-branch>...HEAD` to review complete changeset
- PR message must describe all commits, not just latest
- Focus on what changed from reviewer perspective
5. **Create PR**
- Use `/pr-creator` agent or `gh pr create` with parameters:
- `-t` (title): Start with capital letter, use verb, NO "fix:" or "feat:" prefix
- `-b` (body): Brief summary + bullet points with inline markdown links
- `-a @me` (self-assign)
- `-r <reviewer>`: Find via `gh pr list --repo <owner>/<repo> --author @me --limit 5`
6. **PR Body Guidelines**
- **Summary**: Few words or 1 sentence describing changes
- **Changes**: Bullet points with inline links `[src/auth.py:42](src/auth.py#L42)`
- **Examples**: For significant changes, include before/after code examples
- **No test plans**: Never mention test procedures in PR
## Examples
### With inline source links:
```
Update Claude Haiku to version 4.5
- Model ID: claude-3-haiku-20240307 → claude-haiku-4-5-20251001 ([source](https://docs.anthropic.com/en/docs/about-claude/models/overview))
- Pricing: $0.80/$4.00 → $1.00/$5.00 per MTok ([source](https://docs.anthropic.com/en/docs/about-claude/pricing))
- Max output: 4,096 → 64,000 tokens ([source](https://docs.anthropic.com/en/docs/about-claude/models/overview))
```
### With code changes:
```
Refactor authentication to use async context manager
- Replace synchronous auth flow with async/await pattern in [src/auth.py:15-42](src/auth.py#L15-L42)
- Add context manager support for automatic cleanup
Before:
\`\`\`python
def authenticate(token):
session = create_session(token)
return session
\`\`\`
After:
\`\`\`python
async def authenticate(token):
async with create_session(token) as session:
return session
\`\`\`
```

32
skills/external/github-dev-setup/SKILL.md vendored Normal file
View File

@@ -0,0 +1,32 @@
---
name: setup
description: This skill should be used when the user asks "how to setup GitHub CLI", "configure gh", "gh auth not working", "GitHub CLI connection failed", "gh CLI error", or needs help with GitHub authentication.
---
# GitHub CLI Setup
Configure `gh` CLI for GitHub access.
## Quick Setup
```bash
gh auth login
```
Select: GitHub.com → HTTPS → Login with browser
## Verify Authentication
```bash
gh auth status
gh api user --jq '.login'
```
## Troubleshooting
If `gh` commands fail:
1. **Check authentication** - `gh auth status`
2. **Re-login if needed** - `gh auth login`
3. **Check scopes** - Ensure token has repo access
4. **Update gh** - `brew upgrade gh` or equivalent

181
skills/external/linear-tools-linear-usage/SKILL.md vendored Normal file
View File

@@ -0,0 +1,181 @@
---
name: linear-usage
description: This skill should be used when user asks about "Linear issues", "issue tracking best practices", "sprint planning", "Linear project management", or "creating Linear issues".
---
# Linear & Issue Tracking Best Practices
## Issue Writing Guidelines
### Clear Titles
Write titles that describe the problem or outcome:
- **Good:** "Users can't reset password on mobile Safari"
- **Bad:** "Password bug"
- **Good:** "Add export to CSV for user reports"
- **Bad:** "Export feature"
### Effective Descriptions
Include:
1. **Context:** Why this matters
2. **Current behavior:** What happens now (for bugs)
3. **Expected behavior:** What should happen
4. **Steps to reproduce:** For bugs
5. **Acceptance criteria:** Definition of done
### Templates
**Bug report:**
```
## Description
Brief description of the issue.
## Steps to Reproduce
1. Step one
2. Step two
3. Issue occurs
## Expected Behavior
What should happen.
## Actual Behavior
What happens instead.
## Environment
- Browser/OS
- User type
```
**Feature request:**
```
## Problem Statement
What problem does this solve?
## Proposed Solution
High-level approach.
## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
```
## Label Taxonomy
### Recommended Labels
**Type labels:**
- `bug` - Something isn't working
- `feature` - New functionality
- `improvement` - Enhancement to existing feature
- `chore` - Maintenance, refactoring
**Area labels:**
- `frontend`, `backend`, `api`, `mobile`
- Or by feature area: `auth`, `payments`, `onboarding`
**Status labels (if not using workflow states):**
- `needs-triage`, `blocked`, `needs-design`
### Label Best Practices
- Keep label count manageable (15-25 total)
- Use consistent naming convention
- Color-code by category
- Review and prune quarterly
## Priority and Estimation
### Priority Levels
- **Urgent (P0):** Production down, security issue
- **High (P1):** Major functionality broken, key deadline
- **Medium (P2):** Important but not urgent
- **Low (P3):** Nice to have, minor improvements
### Estimation Tips
- Use relative sizing (points) not hours
- Estimate complexity, not time
- Include testing and review time
- Re-estimate if scope changes significantly
## Cycle/Sprint Planning
### Cycle Best Practices
- **Duration:** 1-2 weeks typically
- **Capacity:** Plan for 70-80% to allow for interrupts
- **Carryover:** Review why items didn't complete
- **Retrospective:** Brief review at cycle end
### Planning Process
1. Review backlog priorities
2. Pull issues into cycle
3. Break down large items (>5 points)
4. Assign owners
5. Identify dependencies and blockers
## Project Organization
### Projects vs Initiatives
**Projects:** Focused, time-bound work (1-3 months)
- Single team typically
- Clear deliverable
- Example: "Mobile app v2 launch"
**Initiatives:** Strategic themes
- May span multiple projects
- Longer-term goals
- Example: "Platform reliability"
### Roadmap Tips
- Keep roadmap items high-level
- Update status regularly
- Link to detailed issues/projects
- Share with stakeholders
## Triage Workflows
### Triage Process
1. **Review new issues daily**
2. **Add missing information** (labels, priority)
3. **Assign to appropriate team/person**
4. **Link related issues**
5. **Move to backlog or close if invalid**
### Closing Issues
Close with clear reason:
- **Completed:** Work is done
- **Duplicate:** Link to original
- **Won't fix:** Explain why
- **Invalid:** Missing info, not reproducible
## GitHub Integration
### Linking PRs to Issues
- Reference Linear issue ID in PR title or description
- Linear auto-links and updates status
- Use branch names with issue ID for automatic linking
### Workflow Automation
- PR opened → Issue moves to "In Progress"
- PR merged → Issue moves to "Done"
- Configure in Linear settings

18
skills/external/linear-tools-setup/SKILL.md vendored Normal file
View File

@@ -0,0 +1,18 @@
---
name: setup
description: This skill should be used when user encounters "Linear auth failed", "Linear OAuth error", "Linear MCP error", "Linear not working", "unauthorized", or needs help configuring Linear integration.
---
# Linear Tools Setup
Run `/linear-tools:setup` to configure Linear MCP.
## Quick Fixes
- **OAuth failed** - Re-authenticate via `/mcp` command
- **Unauthorized** - Check Linear workspace permissions
- **Token expired** - Re-run OAuth flow
## Don't Need Linear?
Disable via `/mcp` command to prevent errors.

112
skills/external/mongodb-tools-mongodb-usage/SKILL.md vendored Normal file
View File

@@ -0,0 +1,112 @@
---
name: mongodb-usage
description: This skill should be used when user asks to "query MongoDB", "show database collections", "get collection schema", "list MongoDB databases", "search records in MongoDB", or "check database indexes".
---
# MongoDB Best Practices
## MCP Limitation
**This MCP operates in READ-ONLY mode.** No write, update, or delete operations are possible.
## Schema Design Patterns
### Embedding vs Referencing
**Embed when:**
- Data is accessed together frequently
- Child documents are bounded (won't grow unbounded)
- One-to-few relationships
- Data doesn't change frequently
**Reference when:**
- Data is accessed independently
- Many-to-many relationships
- Documents would exceed 16MB limit
- Frequent updates to referenced data
### Common Patterns
**Subset pattern:** Store frequently accessed subset in parent, full data in separate collection.
**Bucket pattern:** Group time-series data into buckets (e.g., hourly readings in one document).
**Computed pattern:** Store pre-computed values for expensive calculations.
## Index Strategies
### Index Guidelines
- Index fields used in queries, sorts, and aggregation $match stages
- Compound indexes support queries on prefix fields
- Covered queries (all fields in index) are fastest
- Too many indexes slow writes
### Index Types
- **Single field:** Basic index on one field
- **Compound:** Multiple fields, order matters for queries
- **Multikey:** Automatically created for array fields
- **Text:** Full-text search on string content
- **TTL:** Auto-expire documents after time period
### ESR Rule
For compound indexes, order fields by:
1. **E**quality (exact match fields)
2. **S**ort (sort order fields)
3. **R**ange (range query fields like $gt, $lt)
## Aggregation Pipeline
### Performance Tips
- Put `$match` and `$project` early to reduce documents
- Use `$limit` early when possible
- Avoid `$lookup` on large collections without indexes
- Use `$facet` for multiple aggregations in one query
### Common Stages
```javascript
// Filter documents
{ $match: { status: "active" } }
// Reshape documents
{ $project: { name: 1, total: { $sum: "$items.price" } } }
// Group and aggregate
{ $group: { _id: "$category", count: { $sum: 1 } } }
// Sort results
{ $sort: { count: -1 } }
// Join collections
{ $lookup: { from: "orders", localField: "_id", foreignField: "userId", as: "orders" } }
```
## Connection Best Practices
### Connection String Formats
- **Atlas:** `mongodb+srv://user:pass@cluster.mongodb.net/database`
- **Local:** `mongodb://localhost:27017/database`
- **Replica set:** `mongodb://host1,host2,host3/database?replicaSet=rs0`
### Connection Pooling
- Use connection pooling in applications (default in drivers)
- Set appropriate pool size for your workload
- Don't create new connections per request
## Anti-Patterns to Avoid
- **Unbounded arrays:** Arrays that grow without limit
- **Massive documents:** Documents approaching 16MB
- **Too many collections:** Use embedding instead
- **Missing indexes:** Queries doing collection scans
- **$where operator:** Use aggregation instead for security
- **Storing files in documents:** Use GridFS for large files

18
skills/external/mongodb-tools-setup/SKILL.md vendored Normal file
View File

@@ -0,0 +1,18 @@
---
name: setup
description: This skill should be used when user encounters "MongoDB connection failed", "authentication failed", "MongoDB MCP error", "connection string invalid", "authSource error", or needs help configuring MongoDB integration.
---
# MongoDB Tools Setup
Run `/mongodb-tools:setup` to configure MongoDB MCP.
## Quick Fixes
- **Authentication failed** - Add `?authSource=admin` to connection string
- **Invalid connection string** - Use `mongodb://` or `mongodb+srv://` prefix
- **Network timeout** - Whitelist IP in Atlas Network Access
## Don't Need MongoDB?
Disable via `/mcp` command to prevent errors.

27
skills/external/paper-search-tools-paper-search-usage/SKILL.md vendored Normal file
View File

@@ -0,0 +1,27 @@
---
name: paper-search-usage
description: This skill should be used when user asks to "search for papers", "find research papers", "search arXiv", "search PubMed", "find academic papers", "search IEEE", "search Scopus", or "look up scientific literature".
---
# Paper Search MCP
Search academic papers across multiple platforms.
## Supported Platforms
- arXiv (preprints)
- PubMed (biomedical)
- IEEE Xplore (engineering)
- Scopus (multidisciplinary)
- ACM Digital Library (computer science)
- Semantic Scholar (AI-powered)
## Usage
Use `mcp__paper-search__*` tools to search papers by keywords, authors, or topics.
## Best Practices
- Start with broad searches, then narrow down
- Use platform-specific searches for domain-specific papers
- Combine multiple sources for comprehensive literature reviews

18
skills/external/paper-search-tools-setup/SKILL.md vendored Normal file
View File

@@ -0,0 +1,18 @@
---
name: setup
description: This skill should be used when user encounters "paper-search MCP error", "Docker not found", "Docker not running", "paper search not working", or needs help configuring paper search integration.
---
# Paper Search Tools Setup
Run `/paper-search-tools:setup` to configure Paper Search MCP.
## Quick Fixes
- **Docker not found** - Install Docker (see setup command)
- **Docker not running** - Start Docker Desktop
- **Connection failed** - Restart Claude Code after Docker starts
## Don't Need Paper Search?
Disable via `/mcp` command to prevent errors.

333
skills/external/playwright-tools-playwright-testing/SKILL.md vendored Normal file
View File

@@ -0,0 +1,333 @@
---
name: playwright-testing
description: This skill should be used when user asks about "Playwright", "responsiveness test", "test with playwright", "test login flow", "file upload test", "handle authentication in tests", or "fix flaky tests".
---
# Playwright Testing Best Practices
## Test Organization
### File Structure
```
tests/
├── auth/
│ ├── login.spec.ts
│ └── signup.spec.ts
├── dashboard/
│ └── dashboard.spec.ts
├── fixtures/
│ └── test-data.ts
├── pages/
│ └── login.page.ts
└── playwright.config.ts
```
### Naming Conventions
- Files: `feature-name.spec.ts`
- Tests: Describe user behavior, not implementation
- Good: `test('user can reset password via email')`
- Bad: `test('test reset password')`
## Page Object Model
### Basic Pattern
```typescript
// pages/login.page.ts
export class LoginPage {
constructor(private page: Page) {}
async goto() {
await this.page.goto("/login");
}
async login(email: string, password: string) {
await this.page.getByLabel("Email").fill(email);
await this.page.getByLabel("Password").fill(password);
await this.page.getByRole("button", { name: "Sign in" }).click();
}
}
// tests/login.spec.ts
test("successful login", async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.goto();
await loginPage.login("user@example.com", "password");
await expect(page).toHaveURL("/dashboard");
});
```
## Locator Strategies
### Priority Order (Best to Worst)
1. **`getByRole`** - Accessible, resilient
2. **`getByLabel`** - Form inputs
3. **`getByPlaceholder`** - When no label
4. **`getByText`** - Visible text
5. **`getByTestId`** - When no better option
6. **CSS/XPath** - Last resort
### Examples
```typescript
// Preferred
await page.getByRole("button", { name: "Submit" }).click();
await page.getByLabel("Email address").fill("user@example.com");
// Acceptable
await page.getByTestId("submit-button").click();
// Avoid
await page.locator("#submit-btn").click();
await page.locator('//button[@type="submit"]').click();
```
## Authentication Handling
### Storage State (Recommended)
Save logged-in state and reuse across tests:
```typescript
// global-setup.ts
async function globalSetup() {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto("/login");
await page.getByLabel("Email").fill(process.env.TEST_USER_EMAIL);
await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD);
await page.getByRole("button", { name: "Sign in" }).click();
await page.waitForURL("/dashboard");
await page.context().storageState({ path: "auth.json" });
await browser.close();
}
// playwright.config.ts
export default defineConfig({
globalSetup: "./global-setup.ts",
use: {
storageState: "auth.json",
},
});
```
### Multi-User Scenarios
```typescript
// Create different auth states
const adminAuth = "admin-auth.json";
const userAuth = "user-auth.json";
test.describe("admin features", () => {
test.use({ storageState: adminAuth });
// Admin tests
});
test.describe("user features", () => {
test.use({ storageState: userAuth });
// User tests
});
```
## File Upload Handling
### Basic Upload
```typescript
// Single file
await page.getByLabel("Upload file").setInputFiles("path/to/file.pdf");
// Multiple files
await page
.getByLabel("Upload files")
.setInputFiles(["path/to/file1.pdf", "path/to/file2.pdf"]);
// Clear file input
await page.getByLabel("Upload file").setInputFiles([]);
```
### Drag and Drop Upload
```typescript
// Create file from buffer
const buffer = Buffer.from("file content");
await page.getByTestId("dropzone").dispatchEvent("drop", {
dataTransfer: {
files: [{ name: "test.txt", mimeType: "text/plain", buffer }],
},
});
```
### File Download
```typescript
const downloadPromise = page.waitForEvent("download");
await page.getByRole("button", { name: "Download" }).click();
const download = await downloadPromise;
await download.saveAs("downloads/" + download.suggestedFilename());
```
## Waiting Strategies
### Auto-Wait (Preferred)
Playwright auto-waits for elements. Use assertions:
```typescript
// Auto-waits for element to be visible and stable
await page.getByRole("button", { name: "Submit" }).click();
// Auto-waits for condition
await expect(page.getByText("Success")).toBeVisible();
```
### Explicit Waits (When Needed)
```typescript
// Wait for navigation
await page.waitForURL("**/dashboard");
// Wait for network idle
await page.waitForLoadState("networkidle");
// Wait for specific response
await page.waitForResponse((resp) => resp.url().includes("/api/data"));
```
## Network Mocking
### Mock API Responses
```typescript
await page.route("**/api/users", async (route) => {
await route.fulfill({
status: 200,
contentType: "application/json",
body: JSON.stringify([{ id: 1, name: "Test User" }]),
});
});
// Mock error response
await page.route("**/api/users", async (route) => {
await route.fulfill({ status: 500 });
});
```
### Intercept and Modify
```typescript
await page.route("**/api/data", async (route) => {
const response = await route.fetch();
const json = await response.json();
json.modified = true;
await route.fulfill({ response, json });
});
```
## CI/CD Integration
### GitHub Actions Example
```yaml
- name: Run Playwright tests
run: npx playwright test
env:
CI: true
- name: Upload test results
if: always()
uses: actions/upload-artifact@v3
with:
name: playwright-report
path: playwright-report/
```
### Parallel Execution
```typescript
// playwright.config.ts
export default defineConfig({
workers: process.env.CI ? 2 : undefined,
fullyParallel: true,
});
```
## Debugging Failed Tests
### Debug Tools
```bash
# Run with UI mode
npx playwright test --ui
# Run with inspector
npx playwright test --debug
# Show browser
npx playwright test --headed
```
### Trace Viewer
```typescript
// playwright.config.ts
use: {
trace: 'on-first-retry', // Capture trace on failure
}
```
## Flaky Test Fixes
### Common Causes and Solutions
**Race conditions:**
- Use proper assertions instead of hard waits
- Wait for network requests to complete
**Animation issues:**
- Disable animations in test config
- Wait for animation to complete
**Dynamic content:**
- Use flexible locators (text content, not position)
- Wait for loading states to resolve
**Test isolation:**
- Each test should set up its own state
- Don't depend on other tests' side effects
### Anti-Patterns to Avoid
```typescript
// Bad: Hard sleep
await page.waitForTimeout(5000);
// Good: Wait for condition
await expect(page.getByText("Loaded")).toBeVisible();
// Bad: Flaky selector
await page.locator(".btn:nth-child(3)").click();
// Good: Semantic selector
await page.getByRole("button", { name: "Submit" }).click();
```
## Responsive Design Testing
For comprehensive responsive testing across viewport breakpoints, use the **responsive-tester** agent. It automatically:
- Tests pages across 7 standard breakpoints (375px to 1536px)
- Detects horizontal overflow issues
- Verifies mobile-first design patterns
- Checks touch target sizes (44x44px minimum)
- Flags anti-patterns like fixed widths without mobile fallback
Trigger it by asking to "test responsiveness", "check breakpoints", or "test mobile/desktop layout".

414
skills/external/plugin-dev-agent-development/SKILL.md vendored Normal file
View File

@@ -0,0 +1,414 @@
---
name: agent-development
description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
---
# Agent Development for Claude Code Plugins
## Overview
Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.
**Key concepts:**
- Agents are FOR autonomous work, commands are FOR user-initiated actions
- Markdown file format with YAML frontmatter
- Triggering via description field with examples
- System prompt defines agent behavior
- Model and color customization
## Agent File Structure
### Complete Format
```markdown
---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:
<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>
<example>
[Additional example...]
</example>
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---
You are [agent role description]...
**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]
**Analysis Process:**
[Step-by-step workflow]
**Output Format:**
[What to return]
```
## Frontmatter Fields
### name (required)
Agent identifier used for namespacing and invocation.
**Format:** lowercase, numbers, hyphens only
**Length:** 3-50 characters
**Pattern:** Must start and end with alphanumeric
**Good examples:**
- `code-reviewer`
- `test-generator`
- `api-docs-writer`
- `security-analyzer`
**Bad examples:**
- `helper` (too generic)
- `-agent-` (starts/ends with hyphen)
- `my_agent` (underscores not allowed)
- `ag` (too short, < 3 chars)
### description (required)
Defines when Claude should trigger this agent. **This is the most critical field.**
**Must include:**
1. Triggering conditions ("Use this agent when...")
2. Multiple `<example>` blocks showing usage
3. Context, user request, and assistant response in each example
4. `<commentary>` explaining why agent triggers
**Format:**
```
Use this agent when [conditions]. Examples:
<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>
[More examples...]
```
**Best practices:**
- Include 2-4 concrete examples
- Show proactive and reactive triggering
- Cover different phrasings of same intent
- Explain reasoning in commentary
- Be specific about when NOT to use the agent
### model (required)
Which model the agent should use.
**Options:**
- `inherit` - Use same model as parent (recommended)
- `sonnet` - Claude Sonnet (balanced)
- `opus` - Claude Opus (most capable, expensive)
- `haiku` - Claude Haiku (fast, cheap)
**Recommendation:** Use `inherit` unless agent needs specific model capabilities.
### color (required)
Visual identifier for agent in UI.
**Options:** `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`
**Guidelines:**
- Choose distinct colors for different agents in same plugin
- Use consistent colors for similar agent types
- Blue/cyan: Analysis, review
- Green: Success-oriented tasks
- Yellow: Caution, validation
- Red: Critical, security
- Magenta: Creative, generation
### tools (optional)
Restrict agent to specific tools.
**Format:** Array of tool names
```yaml
tools: ["Read", "Write", "Grep", "Bash"]
```
**Default:** If omitted, agent has access to all tools
**Best practice:** Limit tools to minimum needed (principle of least privilege)
**Common tool sets:**
- Read-only analysis: `["Read", "Grep", "Glob"]`
- Code generation: `["Read", "Write", "Grep"]`
- Testing: `["Read", "Bash", "Grep"]`
- Full access: Omit field or use `["*"]`
## System Prompt Design
The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
### Structure
**Standard template:**
```markdown
You are [role] specializing in [domain].
**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]
**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]
**Quality Standards:**
- [Standard 1]
- [Standard 2]
**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]
**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]
```
### Best Practices
✅ **DO:**
- Write in second person ("You are...", "You will...")
- Be specific about responsibilities
- Provide step-by-step process
- Define output format
- Include quality standards
- Address edge cases
- Keep under 10,000 characters
❌ **DON'T:**
- Write in first person ("I am...", "I will...")
- Be vague or generic
- Omit process steps
- Leave output format undefined
- Skip quality guidance
- Ignore error cases
## Creating Agents
### Method 1: AI-Assisted Generation
Use this prompt pattern (extracted from Claude Code):
```
Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
- Clear behavioral boundaries
- Specific methodologies
- Edge case handling
- Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use
Return JSON with:
{
"identifier": "agent-name",
"whenToUse": "Use this agent when... Examples: <example>...</example>",
"systemPrompt": "You are..."
}
```
Then convert to agent file format with frontmatter.
See `examples/agent-creation-prompt.md` for complete template.
### Method 2: Manual Creation
1. Choose agent identifier (3-50 chars, lowercase, hyphens)
2. Write description with examples
3. Select model (usually `inherit`)
4. Choose color for visual identification
5. Define tools (if restricting access)
6. Write system prompt with structure above
7. Save as `agents/agent-name.md`
## Validation Rules
### Identifier Validation
```
✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)
```
**Rules:**
- 3-50 characters
- Lowercase letters, numbers, hyphens only
- Must start and end with alphanumeric
- No underscores, spaces, or special characters
### Description Validation
**Length:** 10-5,000 characters
**Must include:** Triggering conditions and examples
**Best:** 200-1,000 characters with 2-4 examples
### System Prompt Validation
**Length:** 20-10,000 characters
**Best:** 500-3,000 characters
**Structure:** Clear responsibilities, process, output format
## Agent Organization
### Plugin Agents Directory
```
plugin-name/
└── agents/
├── analyzer.md
├── reviewer.md
└── generator.md
```
All `.md` files in `agents/` are auto-discovered.
### Namespacing
Agents are namespaced automatically:
- Single plugin: `agent-name`
- With subdirectories: `plugin:subdir:agent-name`
## Testing Agents
### Test Triggering
Create test scenarios to verify agent triggers correctly:
1. Write agent with specific triggering examples
2. Use similar phrasing to examples in test
3. Check Claude loads the agent
4. Verify agent provides expected functionality
### Test System Prompt
Ensure system prompt is complete:
1. Give agent typical task
2. Check it follows process steps
3. Verify output format is correct
4. Test edge cases mentioned in prompt
5. Confirm quality standards are met
## Quick Reference
### Minimal Agent
```markdown
---
name: simple-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
color: blue
---
You are an agent that [does X].
Process:
1. [Step 1]
2. [Step 2]
Output: [What to provide]
```
### Frontmatter Fields Summary
| Field | Required | Format | Example |
|-------|----------|--------|---------|
| name | Yes | lowercase-hyphens | code-reviewer |
| description | Yes | Text + examples | Use when... <example>... |
| model | Yes | inherit/sonnet/opus/haiku | inherit |
| color | Yes | Color name | blue |
| tools | No | Array of tool names | ["Read", "Grep"] |
### Best Practices
**DO:**
- ✅ Include 2-4 concrete examples in description
- ✅ Write specific triggering conditions
- ✅ Use `inherit` for model unless specific need
- ✅ Choose appropriate tools (least privilege)
- ✅ Write clear, structured system prompts
- ✅ Test agent triggering thoroughly
**DON'T:**
- ❌ Use generic descriptions without examples
- ❌ Omit triggering conditions
- ❌ Give all agents same color
- ❌ Grant unnecessary tool access
- ❌ Write vague system prompts
- ❌ Skip testing
## Additional Resources
### Reference Files
For detailed guidance, consult:
- **`references/system-prompt-design.md`** - Complete system prompt patterns
- **`references/triggering-examples.md`** - Example formats and best practices
- **`references/agent-creation-system-prompt.md`** - The exact prompt from Claude Code
### Example Files
Working examples in `examples/`:
- **`agent-creation-prompt.md`** - AI-assisted agent generation template
- **`complete-agent-examples.md`** - Full agent examples for different use cases
### Utility Scripts
Development tools in `scripts/`:
- **`validate-agent.sh`** - Validate agent file structure
- **`test-agent-trigger.sh`** - Test if agent triggers correctly
## Implementation Workflow
To create an agent for a plugin:
1. Define agent purpose and triggering conditions
2. Choose creation method (AI-assisted or manual)
3. Create `agents/agent-name.md` file
4. Write frontmatter with all required fields
5. Write system prompt following best practices
6. Include 2-4 triggering examples in description
7. Validate with `scripts/validate-agent.sh`
8. Test triggering with real scenarios
9. Document agent in plugin README
Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.

238
skills/external/plugin-dev-agent-development/examples/agent-creation-prompt.md vendored Normal file
View File

@@ -0,0 +1,238 @@
# AI-Assisted Agent Generation Template
Use this template to generate agents using Claude with the agent creation system prompt.
## Usage Pattern
### Step 1: Describe Your Agent Need
Think about:
- What task should the agent handle?
- When should it be triggered?
- Should it be proactive or reactive?
- What are the key responsibilities?
### Step 2: Use the Generation Prompt
Send this to Claude (with the agent-creation-system-prompt loaded):
```
Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
Return ONLY the JSON object, no other text.
```
**Replace [YOUR DESCRIPTION] with your agent requirements.**
### Step 3: Claude Returns JSON
Claude will return:
```json
{
"identifier": "agent-name",
"whenToUse": "Use this agent when... Examples: <example>...</example>",
"systemPrompt": "You are... **Your Core Responsibilities:**..."
}
```
### Step 4: Convert to Agent File
Create `agents/[identifier].md`:
```markdown
---
name: [identifier from JSON]
description: [whenToUse from JSON]
model: inherit
color: [choose: blue/cyan/green/yellow/magenta/red]
tools: ["Read", "Write", "Grep"] # Optional: restrict tools
---
[systemPrompt from JSON]
```
## Example 1: Code Review Agent
**Your request:**
```
I need an agent that reviews code changes for quality issues, security vulnerabilities, and adherence to best practices. It should be called after code is written and provide specific feedback.
```
**Claude generates:**
```json
{
"identifier": "code-quality-reviewer",
"whenToUse": "Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\n\n<example>\nContext: User just implemented a new feature\nuser: \"I've added the authentication feature\"\nassistant: \"Great! Let me review the code quality.\"\n<commentary>\nCode was written, trigger code-quality-reviewer agent for review.\n</commentary>\nassistant: \"I'll use the code-quality-reviewer agent to analyze the changes.\"\n</example>\n\n<example>\nContext: User explicitly requests review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-quality-reviewer agent to perform a thorough review.\"\n<commentary>\nExplicit review request triggers the agent.\n</commentary>\n</example>",
"systemPrompt": "You are an expert code quality reviewer specializing in identifying issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, performance)\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\n3. Check adherence to project best practices and coding standards\n4. Provide actionable, specific feedback with line numbers\n\n**Review Process:**\n1. Read the code changes using available tools\n2. Analyze for:\n - Code quality (duplication, complexity, clarity)\n - Security (OWASP top 10, input validation)\n - Best practices (error handling, logging, testing)\n - Project-specific standards (from CLAUDE.md)\n3. Identify issues with severity (critical/major/minor)\n4. Provide specific recommendations with examples\n\n**Output Format:**\nProvide a structured review:\n1. Summary (2-3 sentences)\n2. Critical Issues (must fix)\n3. Major Issues (should fix)\n4. Minor Issues (nice to fix)\n5. Positive observations\n6. Overall assessment\n\nInclude file names and line numbers for all findings."
}
```
**You create:**
File: `agents/code-quality-reviewer.md`
```markdown
---
name: code-quality-reviewer
description: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:
<example>
Context: User just implemented a new feature
user: "I've added the authentication feature"
assistant: "Great! Let me review the code quality."
<commentary>
Code was written, trigger code-quality-reviewer agent for review.
</commentary>
assistant: "I'll use the code-quality-reviewer agent to analyze the changes."
</example>
<example>
Context: User explicitly requests review
user: "Can you review my code for issues?"
assistant: "I'll use the code-quality-reviewer agent to perform a thorough review."
<commentary>
Explicit review request triggers the agent.
</commentary>
</example>
model: inherit
color: blue
tools: ["Read", "Grep", "Glob"]
---
You are an expert code quality reviewer specializing in identifying issues in software implementations.
**Your Core Responsibilities:**
1. Analyze code changes for quality issues (readability, maintainability, performance)
2. Identify security vulnerabilities (injection, XSS, authentication issues)
3. Check adherence to project best practices and coding standards
4. Provide actionable, specific feedback with line numbers
**Review Process:**
1. Read the code changes using available tools
2. Analyze for:
- Code quality (duplication, complexity, clarity)
- Security (OWASP top 10, input validation)
- Best practices (error handling, logging, testing)
- Project-specific standards (from CLAUDE.md)
3. Identify issues with severity (critical/major/minor)
4. Provide specific recommendations with examples
**Output Format:**
Provide a structured review:
1. Summary (2-3 sentences)
2. Critical Issues (must fix)
3. Major Issues (should fix)
4. Minor Issues (nice to fix)
5. Positive observations
6. Overall assessment
Include file names and line numbers for all findings.
```
## Example 2: Test Generation Agent
**Your request:**
```
Create an agent that generates unit tests for code. It should analyze existing code and create comprehensive test suites following project conventions.
```
**Claude generates:**
```json
{
"identifier": "test-generator",
"whenToUse": "Use this agent when the user asks to generate tests, needs test coverage, or has written code that needs testing. Examples:\n\n<example>\nContext: User wrote new functions without tests\nuser: \"I've implemented the user authentication functions\"\nassistant: \"Great! Let me generate tests for these functions.\"\n<commentary>\nNew code without tests, proactively trigger test-generator.\n</commentary>\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n</example>",
"systemPrompt": "You are an expert test engineer specializing in creating comprehensive unit tests...\n\n**Your Core Responsibilities:**\n1. Analyze code to understand behavior\n2. Generate test cases covering happy paths and edge cases\n3. Follow project testing conventions\n4. Ensure high code coverage\n\n**Test Generation Process:**\n1. Read target code\n2. Identify testable units (functions, classes, methods)\n3. Design test cases (inputs, expected outputs, edge cases)\n4. Generate tests following project patterns\n5. Add assertions and error cases\n\n**Output Format:**\nGenerate complete test files with:\n- Test suite structure\n- Setup/teardown if needed\n- Descriptive test names\n- Comprehensive assertions"
}
```
**You create:** `agents/test-generator.md` with the structure above.
## Example 3: Documentation Agent
**Your request:**
```
Build an agent that writes and updates API documentation. It should analyze code and generate clear, comprehensive docs.
```
**Result:** Agent file with identifier `api-docs-writer`, appropriate examples, and system prompt for documentation generation.
## Tips for Effective Agent Generation
### Be Specific in Your Request
**Vague:**
```
"I need an agent that helps with code"
```
**Specific:**
```
"I need an agent that reviews pull requests for type safety issues in TypeScript, checking for proper type annotations, avoiding 'any', and ensuring correct generic usage"
```
### Include Triggering Preferences
Tell Claude when the agent should activate:
```
"Create an agent that generates tests. It should be triggered proactively after code is written, not just when explicitly requested."
```
### Mention Project Context
```
"Create a code review agent. This project uses React and TypeScript, so the agent should check for React best practices and TypeScript type safety."
```
### Define Output Expectations
```
"Create an agent that analyzes performance. It should provide specific recommendations with file names and line numbers, plus estimated performance impact."
```
## Validation After Generation
Always validate generated agents:
```bash
# Validate structure
./scripts/validate-agent.sh agents/your-agent.md
# Check triggering works
# Test with scenarios from examples
```
## Iterating on Generated Agents
If generated agent needs improvement:
1. Identify what's missing or wrong
2. Manually edit the agent file
3. Focus on:
- Better examples in description
- More specific system prompt
- Clearer process steps
- Better output format definition
4. Re-validate
5. Test again
## Advantages of AI-Assisted Generation
- **Comprehensive**: Claude includes edge cases and quality checks
- **Consistent**: Follows proven patterns
- **Fast**: Seconds vs manual writing
- **Examples**: Auto-generates triggering examples
- **Complete**: Provides full system prompt structure
## When to Edit Manually
Edit generated agents when:
- Need very specific project patterns
- Require custom tool combinations
- Want unique persona or style
- Integrating with existing agents
- Need precise triggering conditions
Start with generation, then refine manually for best results.

427
skills/external/plugin-dev-agent-development/examples/complete-agent-examples.md vendored Normal file
View File

@@ -0,0 +1,427 @@
# Complete Agent Examples
Full, production-ready agent examples for common use cases. Use these as templates for your own agents.
## Example 1: Code Review Agent
**File:** `agents/code-reviewer.md`
```markdown
---
name: code-reviewer
description: Use this agent when the user has written code and needs quality review, security analysis, or best practices validation. Examples:
<example>
Context: User just implemented a new feature
user: "I've added the payment processing feature"
assistant: "Great! Let me review the implementation."
<commentary>
Code written for payment processing (security-critical). Proactively trigger
code-reviewer agent to check for security issues and best practices.
</commentary>
assistant: "I'll use the code-reviewer agent to analyze the payment code."
</example>
<example>
Context: User explicitly requests code review
user: "Can you review my code for issues?"
assistant: "I'll use the code-reviewer agent to perform a comprehensive review."
<commentary>
Explicit code review request triggers the agent.
</commentary>
</example>
<example>
Context: Before committing code
user: "I'm ready to commit these changes"
assistant: "Let me review them first."
<commentary>
Before commit, proactively review code quality.
</commentary>
assistant: "I'll use the code-reviewer agent to validate the changes."
</example>
model: inherit
color: blue
tools: ["Read", "Grep", "Glob"]
---
You are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and opportunities for improvement in software implementations.
**Your Core Responsibilities:**
1. Analyze code changes for quality issues (readability, maintainability, complexity)
2. Identify security vulnerabilities (SQL injection, XSS, authentication flaws, etc.)
3. Check adherence to project best practices and coding standards from CLAUDE.md
4. Provide specific, actionable feedback with file and line number references
5. Recognize and commend good practices
**Code Review Process:**
1. **Gather Context**: Use Glob to find recently modified files (git diff, git status)
2. **Read Code**: Use Read tool to examine changed files
3. **Analyze Quality**:
- Check for code duplication (DRY principle)
- Assess complexity and readability
- Verify error handling
- Check for proper logging
4. **Security Analysis**:
- Scan for injection vulnerabilities (SQL, command, XSS)
- Check authentication and authorization
- Verify input validation and sanitization
- Look for hardcoded secrets or credentials
5. **Best Practices**:
- Follow project-specific standards from CLAUDE.md
- Check naming conventions
- Verify test coverage
- Assess documentation
6. **Categorize Issues**: Group by severity (critical/major/minor)
7. **Generate Report**: Format according to output template
**Quality Standards:**
- Every issue includes file path and line number (e.g., `src/auth.ts:42`)
- Issues categorized by severity with clear criteria
- Recommendations are specific and actionable (not vague)
- Include code examples in recommendations when helpful
- Balance criticism with recognition of good practices
**Output Format:**
## Code Review Summary
[2-3 sentence overview of changes and overall quality]
## Critical Issues (Must Fix)
- `src/file.ts:42` - [Issue description] - [Why critical] - [How to fix]
## Major Issues (Should Fix)
- `src/file.ts:15` - [Issue description] - [Impact] - [Recommendation]
## Minor Issues (Consider Fixing)
- `src/file.ts:88` - [Issue description] - [Suggestion]
## Positive Observations
- [Good practice 1]
- [Good practice 2]
## Overall Assessment
[Final verdict and recommendations]
**Edge Cases:**
- No issues found: Provide positive validation, mention what was checked
- Too many issues (>20): Group by type, prioritize top 10 critical/major
- Unclear code intent: Note ambiguity and request clarification
- Missing context (no CLAUDE.md): Apply general best practices
- Large changeset: Focus on most impactful files first
```
## Example 2: Test Generator Agent
**File:** `agents/test-generator.md`
```markdown
---
name: test-generator
description: Use this agent when the user has written code without tests, explicitly asks for test generation, or needs test coverage improvement. Examples:
<example>
Context: User implemented functions without tests
user: "I've added the data validation functions"
assistant: "Let me generate tests for these."
<commentary>
New code without tests. Proactively trigger test-generator agent.
</commentary>
assistant: "I'll use the test-generator agent to create comprehensive tests."
</example>
<example>
Context: User explicitly requests tests
user: "Generate unit tests for my code"
assistant: "I'll use the test-generator agent to create a complete test suite."
<commentary>
Direct test generation request triggers the agent.
</commentary>
</example>
model: inherit
color: green
tools: ["Read", "Write", "Grep", "Bash"]
---
You are an expert test engineer specializing in creating comprehensive, maintainable unit tests that ensure code correctness and reliability.
**Your Core Responsibilities:**
1. Generate high-quality unit tests with excellent coverage
2. Follow project testing conventions and patterns
3. Include happy path, edge cases, and error scenarios
4. Ensure tests are maintainable and clear
**Test Generation Process:**
1. **Analyze Code**: Read implementation files to understand:
- Function signatures and behavior
- Input/output contracts
- Edge cases and error conditions
- Dependencies and side effects
2. **Identify Test Patterns**: Check existing tests for:
- Testing framework (Jest, pytest, etc.)
- File organization (test/ directory, *.test.ts, etc.)
- Naming conventions
- Setup/teardown patterns
3. **Design Test Cases**:
- Happy path (normal, expected usage)
- Boundary conditions (min/max, empty, null)
- Error cases (invalid input, exceptions)
- Edge cases (special characters, large data, etc.)
4. **Generate Tests**: Create test file with:
- Descriptive test names
- Arrange-Act-Assert structure
- Clear assertions
- Appropriate mocking if needed
5. **Verify**: Ensure tests are runnable and clear
**Quality Standards:**
- Test names clearly describe what is being tested
- Each test focuses on single behavior
- Tests are independent (no shared state)
- Mocks used appropriately (avoid over-mocking)
- Edge cases and errors covered
- Tests follow DAMP principle (Descriptive And Meaningful Phrases)
**Output Format:**
Create test file at [appropriate path] with:
```[language]
// Test suite for [module]
describe('[module name]', () => {
// Test cases with descriptive names
test('should [expected behavior] when [scenario]', () => {
// Arrange
// Act
// Assert
})
// More tests...
})
```
**Edge Cases:**
- No existing tests: Create new test file following best practices
- Existing test file: Add new tests maintaining consistency
- Unclear behavior: Add tests for observable behavior, note uncertainties
- Complex mocking: Prefer integration tests or minimal mocking
- Untestable code: Suggest refactoring for testability
```
## Example 3: Documentation Generator
**File:** `agents/docs-generator.md`
```markdown
---
name: docs-generator
description: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples:
<example>
Context: User implemented new public API
user: "I've added the user management API endpoints"
assistant: "Let me document these endpoints."
<commentary>
New public API needs documentation. Proactively trigger docs-generator.
</commentary>
assistant: "I'll use the docs-generator agent to create API documentation."
</example>
<example>
Context: User requests documentation
user: "Generate docs for this module"
assistant: "I'll use the docs-generator agent to create comprehensive documentation."
<commentary>
Explicit documentation request triggers the agent.
</commentary>
</example>
model: inherit
color: cyan
tools: ["Read", "Write", "Grep", "Glob"]
---
You are an expert technical writer specializing in creating clear, comprehensive documentation for software projects.
**Your Core Responsibilities:**
1. Generate accurate, clear documentation from code
2. Follow project documentation standards
3. Include examples and usage patterns
4. Ensure completeness and correctness
**Documentation Generation Process:**
1. **Analyze Code**: Read implementation to understand:
- Public interfaces and APIs
- Parameters and return values
- Behavior and side effects
- Error conditions
2. **Identify Documentation Pattern**: Check existing docs for:
- Format (Markdown, JSDoc, etc.)
- Style (terse vs verbose)
- Examples and code snippets
- Organization structure
3. **Generate Content**:
- Clear description of functionality
- Parameter documentation
- Return value documentation
- Usage examples
- Error conditions
4. **Format**: Follow project conventions
5. **Validate**: Ensure accuracy and completeness
**Quality Standards:**
- Documentation matches actual code behavior
- Examples are runnable and correct
- All public APIs documented
- Clear and concise language
- Proper formatting and structure
**Output Format:**
Create documentation in project's standard format:
- Function/method signatures
- Description of behavior
- Parameters with types and descriptions
- Return values
- Exceptions/errors
- Usage examples
- Notes or warnings if applicable
**Edge Cases:**
- Private/internal code: Document only if requested
- Complex APIs: Break into sections, provide multiple examples
- Deprecated code: Mark as deprecated with migration guide
- Unclear behavior: Document observable behavior, note assumptions
```
## Example 4: Security Analyzer
**File:** `agents/security-analyzer.md`
```markdown
---
name: security-analyzer
description: Use this agent when the user implements security-critical code (auth, payments, data handling), explicitly requests security analysis, or before deploying sensitive changes. Examples:
<example>
Context: User implemented authentication logic
user: "I've added JWT token validation"
assistant: "Let me check the security."
<commentary>
Authentication code is security-critical. Proactively trigger security-analyzer.
</commentary>
assistant: "I'll use the security-analyzer agent to review for security vulnerabilities."
</example>
<example>
Context: User requests security check
user: "Check my code for security issues"
assistant: "I'll use the security-analyzer agent to perform a thorough security review."
<commentary>
Explicit security review request triggers the agent.
</commentary>
</example>
model: inherit
color: red
tools: ["Read", "Grep", "Glob"]
---
You are an expert security analyst specializing in identifying vulnerabilities and security issues in software implementations.
**Your Core Responsibilities:**
1. Identify security vulnerabilities (OWASP Top 10 and beyond)
2. Analyze authentication and authorization logic
3. Check input validation and sanitization
4. Verify secure data handling and storage
5. Provide specific remediation guidance
**Security Analysis Process:**
1. **Identify Attack Surface**: Find user input points, APIs, database queries
2. **Check Common Vulnerabilities**:
- Injection (SQL, command, XSS, etc.)
- Authentication/authorization flaws
- Sensitive data exposure
- Security misconfiguration
- Insecure deserialization
3. **Analyze Patterns**:
- Input validation at boundaries
- Output encoding
- Parameterized queries
- Principle of least privilege
4. **Assess Risk**: Categorize by severity and exploitability
5. **Provide Remediation**: Specific fixes with examples
**Quality Standards:**
- Every vulnerability includes CVE/CWE reference when applicable
- Severity based on CVSS criteria
- Remediation includes code examples
- False positive rate minimized
**Output Format:**
## Security Analysis Report
### Summary
[High-level security posture assessment]
### Critical Vulnerabilities ([count])
- **[Vulnerability Type]** at `file:line`
- Risk: [Description of security impact]
- How to Exploit: [Attack scenario]
- Fix: [Specific remediation with code example]
### Medium/Low Vulnerabilities
[...]
### Security Best Practices Recommendations
[...]
### Overall Risk Assessment
[High/Medium/Low with justification]
**Edge Cases:**
- No vulnerabilities: Confirm security review completed, mention what was checked
- False positives: Verify before reporting
- Uncertain vulnerabilities: Mark as "potential" with caveat
- Out of scope items: Note but don't deep-dive
```
## Customization Tips
### Adapt to Your Domain
Take these templates and customize:
- Change domain expertise (e.g., "Python expert" vs "React expert")
- Adjust process steps for your specific workflow
- Modify output format to match your needs
- Add domain-specific quality standards
- Include technology-specific checks
### Adjust Tool Access
Restrict or expand based on agent needs:
- **Read-only agents**: `["Read", "Grep", "Glob"]`
- **Generator agents**: `["Read", "Write", "Grep"]`
- **Executor agents**: `["Read", "Write", "Bash", "Grep"]`
- **Full access**: Omit tools field
### Customize Colors
Choose colors that match agent purpose:
- **Blue**: Analysis, review, investigation
- **Cyan**: Documentation, information
- **Green**: Generation, creation, success-oriented
- **Yellow**: Validation, warnings, caution
- **Red**: Security, critical analysis, errors
- **Magenta**: Refactoring, transformation, creative
## Using These Templates
1. Copy template that matches your use case
2. Replace placeholders with your specifics
3. Customize process steps for your domain
4. Adjust examples to your triggering scenarios
5. Validate with `scripts/validate-agent.sh`
6. Test triggering with real scenarios
7. Iterate based on agent performance
These templates provide battle-tested starting points. Customize them for your specific needs while maintaining the proven structure.

207
skills/external/plugin-dev-agent-development/references/agent-creation-system-prompt.md vendored Normal file
View File

@@ -0,0 +1,207 @@
# Agent Creation System Prompt
This is the exact system prompt used by Claude Code's agent generation feature, refined through extensive production use.
## The Prompt
```
You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.
**Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.
When a user describes what they want an agent to do, you will:
1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.
2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.
3. **Architect Comprehensive Instructions**: Develop a system prompt that:
- Establishes clear behavioral boundaries and operational parameters
- Provides specific methodologies and best practices for task execution
- Anticipates edge cases and provides guidance for handling them
- Incorporates any specific requirements or preferences mentioned by the user
- Defines output format expectations when relevant
- Aligns with project-specific coding standards and patterns from CLAUDE.md
4. **Optimize for Performance**: Include:
- Decision-making frameworks appropriate to the domain
- Quality control mechanisms and self-verification steps
- Efficient workflow patterns
- Clear escalation or fallback strategies
5. **Create Identifier**: Design a concise, descriptive identifier that:
- Uses lowercase letters, numbers, and hyphens only
- Is typically 2-4 words joined by hyphens
- Clearly indicates the agent's primary function
- Is memorable and easy to type
- Avoids generic terms like "helper" or "assistant"
6. **Example agent descriptions**:
- In the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.
- Examples should be of the form:
<example>
Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.
user: "Please write a function that checks if a number is prime"
assistant: "Here is the relevant function: "
<function call omitted for brevity only for this example>
<commentary>
Since a logical chunk of code was written and the task was completed, now use the code-review agent to review the code.
</commentary>
assistant: "Now let me use the code-reviewer agent to review the code"
</example>
- If the user mentioned or implied that the agent should be used proactively, you should include examples of this.
- NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.
Your output must be a valid JSON object with exactly these fields:
{
"identifier": "A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')",
"whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.",
"systemPrompt": "The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness"
}
Key principles for your system prompts:
- Be specific rather than generic - avoid vague instructions
- Include concrete examples when they would clarify behavior
- Balance comprehensiveness with clarity - every instruction should add value
- Ensure the agent has enough context to handle variations of the core task
- Make the agent proactive in seeking clarification when needed
- Build in quality assurance and self-correction mechanisms
Remember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual.
```
## Usage Pattern
Use this prompt to generate agent configurations:
```markdown
**User input:** "I need an agent that reviews pull requests for code quality issues"
**You send to Claude with the system prompt above:**
Create an agent configuration based on this request: "I need an agent that reviews pull requests for code quality issues"
**Claude returns JSON:**
{
"identifier": "pr-quality-reviewer",
"whenToUse": "Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\n\n<example>\nContext: User has created a PR and wants quality review\nuser: \"Can you review PR #123 for code quality?\"\nassistant: \"I'll use the pr-quality-reviewer agent to analyze the PR.\"\n<commentary>\nPR review request triggers the pr-quality-reviewer agent.\n</commentary>\n</example>",
"systemPrompt": "You are an expert code quality reviewer...\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n..."
}
```
## Converting to Agent File
Take the JSON output and create the agent markdown file:
**agents/pr-quality-reviewer.md:**
```markdown
---
name: pr-quality-reviewer
description: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:
<example>
Context: User has created a PR and wants quality review
user: "Can you review PR #123 for code quality?"
assistant: "I'll use the pr-quality-reviewer agent to analyze the PR."
<commentary>
PR review request triggers the pr-quality-reviewer agent.
</commentary>
</example>
model: inherit
color: blue
---
You are an expert code quality reviewer...
**Your Core Responsibilities:**
1. Analyze code changes for quality issues
2. Check adherence to best practices
...
```
## Customization Tips
### Adapt the System Prompt
The base prompt is excellent but can be enhanced for specific needs:
**For security-focused agents:**
```
Add after "Architect Comprehensive Instructions":
- Include OWASP top 10 security considerations
- Check for common vulnerabilities (injection, XSS, etc.)
- Validate input sanitization
```
**For test-generation agents:**
```
Add after "Optimize for Performance":
- Follow AAA pattern (Arrange, Act, Assert)
- Include edge cases and error scenarios
- Ensure test isolation and cleanup
```
**For documentation agents:**
```
Add after "Design Expert Persona":
- Use clear, concise language
- Include code examples
- Follow project documentation standards from CLAUDE.md
```
## Best Practices from Internal Implementation
### 1. Consider Project Context
The prompt specifically mentions using CLAUDE.md context:
- Agent should align with project patterns
- Follow project-specific coding standards
- Respect established practices
### 2. Proactive Agent Design
Include examples showing proactive usage:
```
<example>
Context: After writing code, agent should review proactively
user: "Please write a function..."
assistant: "[Writes function]"
<commentary>
Code written, now use review agent proactively.
</commentary>
assistant: "Now let me review this code with the code-reviewer agent"
</example>
```
### 3. Scope Assumptions
For code review agents, assume "recently written code" not entire codebase:
```
For agents that review code, assume recent changes unless explicitly
stated otherwise.
```
### 4. Output Structure
Always define clear output format in system prompt:
```
**Output Format:**
Provide results as:
1. Summary (2-3 sentences)
2. Detailed findings (bullet points)
3. Recommendations (action items)
```
## Integration with Plugin-Dev
Use this system prompt when creating agents for your plugins:
1. Take user request for agent functionality
2. Feed to Claude with this system prompt
3. Get JSON output (identifier, whenToUse, systemPrompt)
4. Convert to agent markdown file with frontmatter
5. Validate with agent validation rules
6. Test triggering conditions
7. Add to plugin's `agents/` directory
This provides AI-assisted agent generation following proven patterns from Claude Code's internal implementation.

411
skills/external/plugin-dev-agent-development/references/system-prompt-design.md vendored Normal file
View File

@@ -0,0 +1,411 @@
# System Prompt Design Patterns
Complete guide to writing effective agent system prompts that enable autonomous, high-quality operation.
## Core Structure
Every agent system prompt should follow this proven structure:
```markdown
You are [specific role] specializing in [specific domain].
**Your Core Responsibilities:**
1. [Primary responsibility - the main task]
2. [Secondary responsibility - supporting task]
3. [Additional responsibilities as needed]
**[Task Name] Process:**
1. [First concrete step]
2. [Second concrete step]
3. [Continue with clear steps]
[...]
**Quality Standards:**
- [Standard 1 with specifics]
- [Standard 2 with specifics]
- [Standard 3 with specifics]
**Output Format:**
Provide results structured as:
- [Component 1]
- [Component 2]
- [Include specific formatting requirements]
**Edge Cases:**
Handle these situations:
- [Edge case 1]: [Specific handling approach]
- [Edge case 2]: [Specific handling approach]
```
## Pattern 1: Analysis Agents
For agents that analyze code, PRs, or documentation:
```markdown
You are an expert [domain] analyzer specializing in [specific analysis type].
**Your Core Responsibilities:**
1. Thoroughly analyze [what] for [specific issues]
2. Identify [patterns/problems/opportunities]
3. Provide actionable recommendations
**Analysis Process:**
1. **Gather Context**: Read [what] using available tools
2. **Initial Scan**: Identify obvious [issues/patterns]
3. **Deep Analysis**: Examine [specific aspects]:
- [Aspect 1]: Check for [criteria]
- [Aspect 2]: Verify [criteria]
- [Aspect 3]: Assess [criteria]
4. **Synthesize Findings**: Group related issues
5. **Prioritize**: Rank by [severity/impact/urgency]
6. **Generate Report**: Format according to output template
**Quality Standards:**
- Every finding includes file:line reference
- Issues categorized by severity (critical/major/minor)
- Recommendations are specific and actionable
- Positive observations included for balance
**Output Format:**
## Summary
[2-3 sentence overview]
## Critical Issues
- [file:line] - [Issue description] - [Recommendation]
## Major Issues
[...]
## Minor Issues
[...]
## Recommendations
[...]
**Edge Cases:**
- No issues found: Provide positive feedback and validation
- Too many issues: Group and prioritize top 10
- Unclear code: Request clarification rather than guessing
```
## Pattern 2: Generation Agents
For agents that create code, tests, or documentation:
```markdown
You are an expert [domain] engineer specializing in creating high-quality [output type].
**Your Core Responsibilities:**
1. Generate [what] that meets [quality standards]
2. Follow [specific conventions/patterns]
3. Ensure [correctness/completeness/clarity]
**Generation Process:**
1. **Understand Requirements**: Analyze what needs to be created
2. **Gather Context**: Read existing [code/docs/tests] for patterns
3. **Design Structure**: Plan [architecture/organization/flow]
4. **Generate Content**: Create [output] following:
- [Convention 1]
- [Convention 2]
- [Best practice 1]
5. **Validate**: Verify [correctness/completeness]
6. **Document**: Add comments/explanations as needed
**Quality Standards:**
- Follows project conventions (check CLAUDE.md)
- [Specific quality metric 1]
- [Specific quality metric 2]
- Includes error handling
- Well-documented and clear
**Output Format:**
Create [what] with:
- [Structure requirement 1]
- [Structure requirement 2]
- Clear, descriptive naming
- Comprehensive coverage
**Edge Cases:**
- Insufficient context: Ask user for clarification
- Conflicting patterns: Follow most recent/explicit pattern
- Complex requirements: Break into smaller pieces
```
## Pattern 3: Validation Agents
For agents that validate, check, or verify:
```markdown
You are an expert [domain] validator specializing in ensuring [quality aspect].
**Your Core Responsibilities:**
1. Validate [what] against [criteria]
2. Identify violations and issues
3. Provide clear pass/fail determination
**Validation Process:**
1. **Load Criteria**: Understand validation requirements
2. **Scan Target**: Read [what] needs validation
3. **Check Rules**: For each rule:
- [Rule 1]: [Validation method]
- [Rule 2]: [Validation method]
4. **Collect Violations**: Document each failure with details
5. **Assess Severity**: Categorize issues
6. **Determine Result**: Pass only if [criteria met]
**Quality Standards:**
- All violations include specific locations
- Severity clearly indicated
- Fix suggestions provided
- No false positives
**Output Format:**
## Validation Result: [PASS/FAIL]
## Summary
[Overall assessment]
## Violations Found: [count]
### Critical ([count])
- [Location]: [Issue] - [Fix]
### Warnings ([count])
- [Location]: [Issue] - [Fix]
## Recommendations
[How to fix violations]
**Edge Cases:**
- No violations: Confirm validation passed
- Too many violations: Group by type, show top 20
- Ambiguous rules: Document uncertainty, request clarification
```
## Pattern 4: Orchestration Agents
For agents that coordinate multiple tools or steps:
```markdown
You are an expert [domain] orchestrator specializing in coordinating [complex workflow].
**Your Core Responsibilities:**
1. Coordinate [multi-step process]
2. Manage [resources/tools/dependencies]
3. Ensure [successful completion/integration]
**Orchestration Process:**
1. **Plan**: Understand full workflow and dependencies
2. **Prepare**: Set up prerequisites
3. **Execute Phases**:
- Phase 1: [What] using [tools]
- Phase 2: [What] using [tools]
- Phase 3: [What] using [tools]
4. **Monitor**: Track progress and handle failures
5. **Verify**: Confirm successful completion
6. **Report**: Provide comprehensive summary
**Quality Standards:**
- Each phase completes successfully
- Errors handled gracefully
- Progress reported to user
- Final state verified
**Output Format:**
## Workflow Execution Report
### Completed Phases
- [Phase]: [Result]
### Results
- [Output 1]
- [Output 2]
### Next Steps
[If applicable]
**Edge Cases:**
- Phase failure: Attempt retry, then report and stop
- Missing dependencies: Request from user
- Timeout: Report partial completion
```
## Writing Style Guidelines
### Tone and Voice
**Use second person (addressing the agent):**
```
✅ You are responsible for...
✅ You will analyze...
✅ Your process should...
❌ The agent is responsible for...
❌ This agent will analyze...
❌ I will analyze...
```
### Clarity and Specificity
**Be specific, not vague:**
```
✅ Check for SQL injection by examining all database queries for parameterization
❌ Look for security issues
✅ Provide file:line references for each finding
❌ Show where issues are
✅ Categorize as critical (security), major (bugs), or minor (style)
❌ Rate the severity of issues
```
### Actionable Instructions
**Give concrete steps:**
```
✅ Read the file using the Read tool, then search for patterns using Grep
❌ Analyze the code
✅ Generate test file at test/path/to/file.test.ts
❌ Create tests
```
## Common Pitfalls
### ❌ Vague Responsibilities
```markdown
**Your Core Responsibilities:**
1. Help the user with their code
2. Provide assistance
3. Be helpful
```
**Why bad:** Not specific enough to guide behavior.
### ✅ Specific Responsibilities
```markdown
**Your Core Responsibilities:**
1. Analyze TypeScript code for type safety issues
2. Identify missing type annotations and improper 'any' usage
3. Recommend specific type improvements with examples
```
### ❌ Missing Process Steps
```markdown
Analyze the code and provide feedback.
```
**Why bad:** Agent doesn't know HOW to analyze.
### ✅ Clear Process
```markdown
**Analysis Process:**
1. Read code files using Read tool
2. Scan for type annotations on all functions
3. Check for 'any' type usage
4. Verify generic type parameters
5. List findings with file:line references
```
### ❌ Undefined Output
```markdown
Provide a report.
```
**Why bad:** Agent doesn't know what format to use.
### ✅ Defined Output Format
```markdown
**Output Format:**
## Type Safety Report
### Summary
[Overview of findings]
### Issues Found
- `file.ts:42` - Missing return type on `processData`
- `utils.ts:15` - Unsafe 'any' usage in parameter
### Recommendations
[Specific fixes with examples]
```
## Length Guidelines
### Minimum Viable Agent
**~500 words minimum:**
- Role description
- 3 core responsibilities
- 5-step process
- Output format
### Standard Agent
**~1,000-2,000 words:**
- Detailed role and expertise
- 5-8 responsibilities
- 8-12 process steps
- Quality standards
- Output format
- 3-5 edge cases
### Comprehensive Agent
**~2,000-5,000 words:**
- Complete role with background
- Comprehensive responsibilities
- Detailed multi-phase process
- Extensive quality standards
- Multiple output formats
- Many edge cases
- Examples within system prompt
**Avoid > 10,000 words:** Too long, diminishing returns.
## Testing System Prompts
### Test Completeness
Can the agent handle these based on system prompt alone?
- [ ] Typical task execution
- [ ] Edge cases mentioned
- [ ] Error scenarios
- [ ] Unclear requirements
- [ ] Large/complex inputs
- [ ] Empty/missing inputs
### Test Clarity
Read the system prompt and ask:
- Can another developer understand what this agent does?
- Are process steps clear and actionable?
- Is output format unambiguous?
- Are quality standards measurable?
### Iterate Based on Results
After testing agent:
1. Identify where it struggled
2. Add missing guidance to system prompt
3. Clarify ambiguous instructions
4. Add process steps for edge cases
5. Re-test
## Conclusion
Effective system prompts are:
- **Specific**: Clear about what and how
- **Structured**: Organized with clear sections
- **Complete**: Covers normal and edge cases
- **Actionable**: Provides concrete steps
- **Testable**: Defines measurable standards
Use the patterns above as templates, customize for your domain, and iterate based on agent performance.

491
skills/external/plugin-dev-agent-development/references/triggering-examples.md vendored Normal file
View File

@@ -0,0 +1,491 @@
# Agent Triggering Examples: Best Practices
Complete guide to writing effective `<example>` blocks in agent descriptions for reliable triggering.
## Example Block Format
The standard format for triggering examples:
```markdown
<example>
Context: [Describe the situation - what led to this interaction]
user: "[Exact user message or request]"
assistant: "[How Claude should respond before triggering]"
<commentary>
[Explanation of why this agent should be triggered in this scenario]
</commentary>
assistant: "[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']"
</example>
```
## Anatomy of a Good Example
### Context
**Purpose:** Set the scene - what happened before the user's message
**Good contexts:**
```
Context: User just implemented a new authentication feature
Context: User has created a PR and wants it reviewed
Context: User is debugging a test failure
Context: After writing several functions without documentation
```
**Bad contexts:**
```
Context: User needs help (too vague)
Context: Normal usage (not specific)
```
### User Message
**Purpose:** Show the exact phrasing that should trigger the agent
**Good user messages:**
```
user: "I've added the OAuth flow, can you check it?"
user: "Review PR #123"
user: "Why is this test failing?"
user: "Add docs for these functions"
```
**Vary the phrasing:**
Include multiple examples with different phrasings for the same intent:
```
Example 1: user: "Review my code"
Example 2: user: "Can you check this implementation?"
Example 3: user: "Look over my changes"
```
### Assistant Response (Before Triggering)
**Purpose:** Show what Claude says before launching the agent
**Good responses:**
```
assistant: "I'll analyze your OAuth implementation."
assistant: "Let me review that PR for you."
assistant: "I'll investigate the test failure."
```
**Proactive example:**
```
assistant: "Great! Now let me review the code quality."
<commentary>
Code was just written, proactively trigger review agent.
</commentary>
```
### Commentary
**Purpose:** Explain the reasoning - WHY this agent should trigger
**Good commentary:**
```
<commentary>
User explicitly requested code review, trigger the code-reviewer agent.
</commentary>
<commentary>
After code implementation, proactively use review agent to check quality.
</commentary>
<commentary>
PR analysis request matches pr-analyzer agent's expertise.
</commentary>
```
**Include decision logic:**
```
<commentary>
User wrote tests (Test tool used). The test-analyzer agent should check
test quality and coverage before continuing.
</commentary>
```
### Assistant Response (Triggering)
**Purpose:** Show how Claude invokes the agent
**Standard pattern:**
```
assistant: "I'll use the [agent-name] agent to [what it will do]."
```
**Examples:**
```
assistant: "I'll use the code-reviewer agent to analyze the changes."
assistant: "Let me use the test-generator agent to create comprehensive tests."
assistant: "I'll use the security-analyzer agent to check for vulnerabilities."
```
## Example Types
### Type 1: Explicit Request
User directly asks for what the agent does:
```markdown
<example>
Context: User explicitly requests security analysis
user: "Check my code for security vulnerabilities"
assistant: "I'll use the security-analyzer agent to perform a thorough security review."
<commentary>
Direct security analysis request triggers the security-analyzer agent.
</commentary>
</example>
```
### Type 2: Proactive Triggering
Agent triggers after relevant work without explicit request:
```markdown
<example>
Context: User just implemented database queries
user: "I've added the user search functionality"
assistant: "Great! Let me review it for security."
<commentary>
Database code written. Proactively trigger security-analyzer to check
for SQL injection and other database security issues.
</commentary>
assistant: "I'll use the security-analyzer agent to check the database code."
</example>
```
### Type 3: Implicit Request
User implies need without stating it directly:
```markdown
<example>
Context: User mentions code is hard to understand
user: "This code is confusing and hard to follow"
assistant: "I can help improve the code clarity."
<commentary>
User indicates complexity issues. Trigger code-simplifier agent to refactor
for better readability.
</commentary>
assistant: "I'll use the code-simplifier agent to suggest improvements."
</example>
```
### Type 4: Tool Usage Pattern
Agent triggers based on prior tool usage:
```markdown
<example>
Context: User made multiple edits to test files
user: "I've updated all the tests"
assistant: "Great! Let me verify test quality."
<commentary>
Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
to ensure tests follow best practices.
</commentary>
assistant: "I'll use the test-quality-analyzer agent to review the tests."
</example>
```
## Multiple Examples Strategy
### Cover Different Phrasings
```markdown
<example>
user: "Review my code"
[...]
</example>
<example>
user: "Can you check my implementation?"
[...]
</example>
<example>
user: "Look over these changes"
[...]
</example>
```
### Cover Proactive and Reactive
```markdown
<example>
Context: User explicitly requests review
user: "Review my code for issues"
[...]
</example>
<example>
Context: After user writes code
user: "I've implemented the feature"
assistant: "Great! Now let me review it."
<commentary>
Code written, proactively review.
</commentary>
[...]
</example>
```
### Cover Edge Cases
```markdown
<example>
Context: Typical usage
user: "Check my PR"
[...]
</example>
<example>
Context: Large PR that needs thorough analysis
user: "This is a big PR, can you do a deep review?"
[...]
<commentary>
Large PR mentioned, use thorough analysis mode.
</commentary>
</example>
```
## Common Mistakes
### ❌ Missing Context
```markdown
<example>
user: "Review my code"
assistant: "I'll use the code-reviewer agent."
</example>
```
**Why bad:** No context about what led to this request.
### ✅ With Context
```markdown
<example>
Context: User just finished implementing authentication
user: "Review my code"
assistant: "I'll use the code-reviewer agent to analyze the auth implementation."
<commentary>
Auth code written, review for security and best practices.
</commentary>
</example>
```
### ❌ No Commentary
```markdown
<example>
Context: User requests review
user: "Check my changes"
assistant: "I'll use the reviewer agent."
</example>
```
**Why bad:** Doesn't explain WHY agent triggers.
### ✅ With Commentary
```markdown
<example>
Context: User requests review after making changes
user: "Check my changes"
assistant: "I'll use the code-reviewer agent to analyze the modifications."
<commentary>
Code review request triggers agent to check quality, security, and adherence to standards.
</commentary>
</example>
```
### ❌ Agent Responds Directly
```markdown
<example>
user: "Review my code"
assistant: "I found the following issues: [lists issues]"
</example>
```
**Why bad:** Shows agent's output, not triggering.
### ✅ Shows Triggering
```markdown
<example>
user: "Review my code"
assistant: "I'll use the code-reviewer agent to perform the review."
<commentary>
Review request triggers the agent.
</commentary>
</example>
```
## How Many Examples?
### Minimum: 2 Examples
Cover at least:
1. Explicit request
2. One variation or proactive trigger
### Recommended: 3-4 Examples
Cover:
1. Explicit request (direct ask)
2. Implicit request (user implies need)
3. Proactive trigger (after relevant work)
4. Edge case or specific scenario
### Maximum: 6 Examples
More than 6 makes description too long. Focus on most important scenarios.
## Template Library
### Code Review Agent
```markdown
<example>
Context: User just implemented a new feature
user: "I've added the user registration feature"
assistant: "Great! Let me review the code quality."
<commentary>
Code written, proactively trigger code-reviewer agent.
</commentary>
assistant: "I'll use the code-reviewer agent to analyze the implementation."
</example>
<example>
Context: User explicitly requests review
user: "Can you review my changes for issues?"
assistant: "I'll use the code-reviewer agent to perform a thorough review."
<commentary>
Explicit review request triggers the agent.
</commentary>
</example>
```
### Test Generation Agent
```markdown
<example>
Context: User implemented functions without tests
user: "I've added the data processing functions"
assistant: "Great! Let me generate tests for these."
<commentary>
New code without tests, proactively trigger test-generator agent.
</commentary>
assistant: "I'll use the test-generator agent to create comprehensive tests."
</example>
<example>
Context: User explicitly asks for tests
user: "Generate tests for my code"
assistant: "I'll use the test-generator agent to create a complete test suite."
<commentary>
Direct test generation request triggers the agent.
</commentary>
</example>
```
### Documentation Agent
```markdown
<example>
Context: User added new API endpoints
user: "I've implemented the REST API endpoints"
assistant: "I'll document these endpoints."
<commentary>
New API code, proactively generate documentation.
</commentary>
assistant: "I'll use the api-docs-writer agent to create comprehensive documentation."
</example>
<example>
Context: User requests documentation
user: "Write docs for this API"
assistant: "I'll use the api-docs-writer agent to generate clear documentation."
<commentary>
Documentation request triggers the agent.
</commentary>
</example>
```
### Validation Agent
```markdown
<example>
Context: User ready to commit changes
user: "I'm ready to commit this code"
assistant: "Let me validate it first."
<commentary>
Before commit, proactively validate with validation-agent.
</commentary>
assistant: "I'll use the code-validator agent to check for issues."
</example>
<example>
Context: User asks for validation
user: "Validate my implementation"
assistant: "I'll use the code-validator agent to verify correctness."
<commentary>
Explicit validation request triggers the agent.
</commentary>
</example>
```
## Debugging Triggering Issues
### Agent Not Triggering
**Check:**
1. Examples include relevant keywords from user message
2. Context matches actual usage scenarios
3. Commentary explains triggering logic clearly
4. Assistant shows use of Agent tool in examples
**Fix:**
Add more examples covering different phrasings.
### Agent Triggers Too Often
**Check:**
1. Examples are too broad or generic
2. Triggering conditions overlap with other agents
3. Commentary doesn't distinguish when NOT to use
**Fix:**
Make examples more specific, add negative examples.
### Agent Triggers in Wrong Scenarios
**Check:**
1. Examples don't match actual intended use
2. Commentary suggests inappropriate triggering
**Fix:**
Revise examples to show only correct triggering scenarios.
## Best Practices Summary
✅ **DO:**
- Include 2-4 concrete, specific examples
- Show both explicit and proactive triggering
- Provide clear context for each example
- Explain reasoning in commentary
- Vary user message phrasing
- Show Claude using Agent tool
❌ **DON'T:**
- Use generic, vague examples
- Omit context or commentary
- Show only one type of triggering
- Skip the agent invocation step
- Make examples too similar
- Forget to explain why agent triggers
## Conclusion
Well-crafted examples are crucial for reliable agent triggering. Invest time in creating diverse, specific examples that clearly demonstrate when and why the agent should be used.

217
skills/external/plugin-dev-agent-development/scripts/validate-agent.sh vendored Executable file
View File

@@ -0,0 +1,217 @@
#!/bin/bash
# Agent File Validator
# Validates agent markdown files for correct structure and content
set -euo pipefail
# Usage
if [ $# -eq 0 ]; then
echo "Usage: $0 <path/to/agent.md>"
echo ""
echo "Validates agent file for:"
echo " - YAML frontmatter structure"
echo " - Required fields (name, description, model, color)"
echo " - Field formats and constraints"
echo " - System prompt presence and length"
echo " - Example blocks in description"
exit 1
fi
AGENT_FILE="$1"
echo "🔍 Validating agent file: $AGENT_FILE"
echo ""
# Check 1: File exists
if [ ! -f "$AGENT_FILE" ]; then
echo "❌ File not found: $AGENT_FILE"
exit 1
fi
echo "✅ File exists"
# Check 2: Starts with ---
FIRST_LINE=$(head -1 "$AGENT_FILE")
if [ "$FIRST_LINE" != "---" ]; then
echo "❌ File must start with YAML frontmatter (---)"
exit 1
fi
echo "✅ Starts with frontmatter"
# Check 3: Has closing ---
if ! tail -n +2 "$AGENT_FILE" | grep -q '^---$'; then
echo "❌ Frontmatter not closed (missing second ---)"
exit 1
fi
echo "✅ Frontmatter properly closed"
# Extract frontmatter and system prompt
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$AGENT_FILE")
SYSTEM_PROMPT=$(awk '/^---$/{i++; next} i>=2' "$AGENT_FILE")
# Check 4: Required fields
echo ""
echo "Checking required fields..."
error_count=0
warning_count=0
# Check name field
NAME=$(echo "$FRONTMATTER" | grep '^name:' | sed 's/name: *//' | sed 's/^"\(.*\)"$/\1/')
if [ -z "$NAME" ]; then
echo "❌ Missing required field: name"
((error_count++))
else
echo "✅ name: $NAME"
# Validate name format
if ! [[ "$NAME" =~ ^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$ ]]; then
echo "❌ name must start/end with alphanumeric and contain only letters, numbers, hyphens"
((error_count++))
fi
# Validate name length
name_length=${#NAME}
if [ $name_length -lt 3 ]; then
echo "❌ name too short (minimum 3 characters)"
((error_count++))
elif [ $name_length -gt 50 ]; then
echo "❌ name too long (maximum 50 characters)"
((error_count++))
fi
# Check for generic names
if [[ "$NAME" =~ ^(helper|assistant|agent|tool)$ ]]; then
echo "⚠️ name is too generic: $NAME"
((warning_count++))
fi
fi
# Check description field
DESCRIPTION=$(echo "$FRONTMATTER" | grep '^description:' | sed 's/description: *//')
if [ -z "$DESCRIPTION" ]; then
echo "❌ Missing required field: description"
((error_count++))
else
desc_length=${#DESCRIPTION}
echo "✅ description: ${desc_length} characters"
if [ $desc_length -lt 10 ]; then
echo "⚠️ description too short (minimum 10 characters recommended)"
((warning_count++))
elif [ $desc_length -gt 5000 ]; then
echo "⚠️ description very long (over 5000 characters)"
((warning_count++))
fi
# Check for example blocks
if ! echo "$DESCRIPTION" | grep -q '<example>'; then
echo "⚠️ description should include <example> blocks for triggering"
((warning_count++))
fi
# Check for "Use this agent when" pattern
if ! echo "$DESCRIPTION" | grep -qi 'use this agent when'; then
echo "⚠️ description should start with 'Use this agent when...'"
((warning_count++))
fi
fi
# Check model field
MODEL=$(echo "$FRONTMATTER" | grep '^model:' | sed 's/model: *//')
if [ -z "$MODEL" ]; then
echo "❌ Missing required field: model"
((error_count++))
else
echo "✅ model: $MODEL"
case "$MODEL" in
inherit|sonnet|opus|haiku)
# Valid model
;;
*)
echo "⚠️ Unknown model: $MODEL (valid: inherit, sonnet, opus, haiku)"
((warning_count++))
;;
esac
fi
# Check color field
COLOR=$(echo "$FRONTMATTER" | grep '^color:' | sed 's/color: *//')
if [ -z "$COLOR" ]; then
echo "❌ Missing required field: color"
((error_count++))
else
echo "✅ color: $COLOR"
case "$COLOR" in
blue|cyan|green|yellow|magenta|red)
# Valid color
;;
*)
echo "⚠️ Unknown color: $COLOR (valid: blue, cyan, green, yellow, magenta, red)"
((warning_count++))
;;
esac
fi
# Check tools field (optional)
TOOLS=$(echo "$FRONTMATTER" | grep '^tools:' | sed 's/tools: *//')
if [ -n "$TOOLS" ]; then
echo "✅ tools: $TOOLS"
else
echo "💡 tools: not specified (agent has access to all tools)"
fi
# Check 5: System prompt
echo ""
echo "Checking system prompt..."
if [ -z "$SYSTEM_PROMPT" ]; then
echo "❌ System prompt is empty"
((error_count++))
else
prompt_length=${#SYSTEM_PROMPT}
echo "✅ System prompt: $prompt_length characters"
if [ $prompt_length -lt 20 ]; then
echo "❌ System prompt too short (minimum 20 characters)"
((error_count++))
elif [ $prompt_length -gt 10000 ]; then
echo "⚠️ System prompt very long (over 10,000 characters)"
((warning_count++))
fi
# Check for second person
if ! echo "$SYSTEM_PROMPT" | grep -q "You are\|You will\|Your"; then
echo "⚠️ System prompt should use second person (You are..., You will...)"
((warning_count++))
fi
# Check for structure
if ! echo "$SYSTEM_PROMPT" | grep -qi "responsibilities\|process\|steps"; then
echo "💡 Consider adding clear responsibilities or process steps"
fi
if ! echo "$SYSTEM_PROMPT" | grep -qi "output"; then
echo "💡 Consider defining output format expectations"
fi
fi
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
if [ $error_count -eq 0 ] && [ $warning_count -eq 0 ]; then
echo "✅ All checks passed!"
exit 0
elif [ $error_count -eq 0 ]; then
echo "⚠️ Validation passed with $warning_count warning(s)"
exit 0
else
echo "❌ Validation failed with $error_count error(s) and $warning_count warning(s)"
exit 1
fi

272
skills/external/plugin-dev-command-development/README.md vendored Normal file
View File

@@ -0,0 +1,272 @@
# Command Development Skill
Comprehensive guidance on creating Claude Code slash commands, including file format, frontmatter options, dynamic arguments, and best practices.
## Overview
This skill provides knowledge about:
- Slash command file format and structure
- YAML frontmatter configuration fields
- Dynamic arguments ($ARGUMENTS, $1, $2, etc.)
- File references with @ syntax
- Bash execution with !` syntax
- Command organization and namespacing
- Best practices for command development
- Plugin-specific features (${CLAUDE_PLUGIN_ROOT}, plugin patterns)
- Integration with plugin components (agents, skills, hooks)
- Validation patterns and error handling
## Skill Structure
### SKILL.md (~2,470 words)
Core skill content covering:
**Fundamentals:**
- Command basics and locations
- File format (Markdown with optional frontmatter)
- YAML frontmatter fields overview
- Dynamic arguments ($ARGUMENTS and positional)
- File references (@ syntax)
- Bash execution (!` syntax)
- Command organization patterns
- Best practices and common patterns
- Troubleshooting
**Plugin-Specific:**
- ${CLAUDE_PLUGIN_ROOT} environment variable
- Plugin command discovery and organization
- Plugin command patterns (configuration, template, multi-script)
- Integration with plugin components (agents, skills, hooks)
- Validation patterns (argument, file, resource, error handling)
### References
Detailed documentation:
- **frontmatter-reference.md**: Complete YAML frontmatter field specifications
- All field descriptions with types and defaults
- When to use each field
- Examples and best practices
- Validation and common errors
- **plugin-features-reference.md**: Plugin-specific command features
- Plugin command discovery and organization
- ${CLAUDE_PLUGIN_ROOT} environment variable usage
- Plugin command patterns (configuration, template, multi-script)
- Integration with plugin agents, skills, and hooks
- Validation patterns and error handling
### Examples
Practical command examples:
- **simple-commands.md**: 10 complete command examples
- Code review commands
- Testing commands
- Deployment commands
- Documentation generators
- Git integration commands
- Analysis and research commands
- **plugin-commands.md**: 10 plugin-specific command examples
- Simple plugin commands with scripts
- Multi-script workflows
- Template-based generation
- Configuration-driven deployment
- Agent and skill integration
- Multi-component workflows
- Validated input commands
- Environment-aware commands
## When This Skill Triggers
Claude Code activates this skill when users:
- Ask to "create a slash command" or "add a command"
- Need to "write a custom command"
- Want to "define command arguments"
- Ask about "command frontmatter" or YAML configuration
- Need to "organize commands" or use namespacing
- Want to create commands with file references
- Ask about "bash execution in commands"
- Need command development best practices
## Progressive Disclosure
The skill uses progressive disclosure:
1. **SKILL.md** (~2,470 words): Core concepts, common patterns, and plugin features overview
2. **References** (~13,500 words total): Detailed specifications
- frontmatter-reference.md (~1,200 words)
- plugin-features-reference.md (~1,800 words)
- interactive-commands.md (~2,500 words)
- advanced-workflows.md (~1,700 words)
- testing-strategies.md (~2,200 words)
- documentation-patterns.md (~2,000 words)
- marketplace-considerations.md (~2,200 words)
3. **Examples** (~6,000 words total): Complete working command examples
- simple-commands.md
- plugin-commands.md
Claude loads references and examples as needed based on task.
## Command Basics Quick Reference
### File Format
```markdown
---
description: Brief description
argument-hint: [arg1] [arg2]
allowed-tools: Read, Bash(git:*)
---
Command prompt content with:
- Arguments: $1, $2, or $ARGUMENTS
- Files: @path/to/file
- Bash: !`command here`
```
### Locations
- **Project**: `.claude/commands/` (shared with team)
- **Personal**: `~/.claude/commands/` (your commands)
- **Plugin**: `plugin-name/commands/` (plugin-specific)
### Key Features
**Dynamic arguments:**
- `$ARGUMENTS` - All arguments as single string
- `$1`, `$2`, `$3` - Positional arguments
**File references:**
- `@path/to/file` - Include file contents
**Bash execution:**
- `!`command`` - Execute and include output
## Frontmatter Fields Quick Reference
| Field | Purpose | Example |
|-------|---------|---------|
| `description` | Brief description for /help | `"Review code for issues"` |
| `allowed-tools` | Restrict tool access | `Read, Bash(git:*)` |
| `model` | Specify model | `sonnet`, `opus`, `haiku` |
| `argument-hint` | Document arguments | `[pr-number] [priority]` |
| `disable-model-invocation` | Manual-only command | `true` |
## Common Patterns
### Simple Review Command
```markdown
---
description: Review code for issues
---
Review this code for quality and potential bugs.
```
### Command with Arguments
```markdown
---
description: Deploy to environment
argument-hint: [environment] [version]
---
Deploy to $1 environment using version $2
```
### Command with File Reference
```markdown
---
description: Document file
argument-hint: [file-path]
---
Generate documentation for @$1
```
### Command with Bash Execution
```markdown
---
description: Show Git status
allowed-tools: Bash(git:*)
---
Current status: !`git status`
Recent commits: !`git log --oneline -5`
```
## Development Workflow
1. **Design command:**
- Define purpose and scope
- Determine required arguments
- Identify needed tools
2. **Create file:**
- Choose appropriate location
- Create `.md` file with command name
- Write basic prompt
3. **Add frontmatter:**
- Start minimal (just description)
- Add fields as needed (allowed-tools, etc.)
- Document arguments with argument-hint
4. **Test command:**
- Invoke with `/command-name`
- Verify arguments work
- Check bash execution
- Test file references
5. **Refine:**
- Improve prompt clarity
- Handle edge cases
- Add examples in comments
- Document requirements
## Best Practices Summary
1. **Single responsibility**: One command, one clear purpose
2. **Clear descriptions**: Make discoverable in `/help`
3. **Document arguments**: Always use argument-hint
4. **Minimal tools**: Use most restrictive allowed-tools
5. **Test thoroughly**: Verify all features work
6. **Add comments**: Explain complex logic
7. **Handle errors**: Consider missing arguments/files
## Status
**Completed enhancements:**
- ✓ Plugin command patterns (${CLAUDE_PLUGIN_ROOT}, discovery, organization)
- ✓ Integration patterns (agents, skills, hooks coordination)
- ✓ Validation patterns (input, file, resource validation, error handling)
**Remaining enhancements (in progress):**
- Advanced workflows (multi-step command sequences)
- Testing strategies (how to test commands effectively)
- Documentation patterns (command documentation best practices)
- Marketplace considerations (publishing and distribution)
## Maintenance
To update this skill:
1. Keep SKILL.md focused on core fundamentals
2. Move detailed specifications to references/
3. Add new examples/ for different use cases
4. Update frontmatter when new fields added
5. Ensure imperative/infinitive form throughout
6. Test examples work with current Claude Code
## Version History
**v0.1.0** (2025-01-15):
- Initial release with basic command fundamentals
- Frontmatter field reference
- 10 simple command examples
- Ready for plugin-specific pattern additions

833
skills/external/plugin-dev-command-development/SKILL.md vendored Normal file
View File

@@ -0,0 +1,833 @@
---
name: command-development
description: This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
---
# Command Development for Claude Code
## Overview
Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.
**Key concepts:**
- Markdown file format for commands
- YAML frontmatter for configuration
- Dynamic arguments and file references
- Bash execution for context
- Command organization and namespacing
## Command Basics
### What is a Slash Command?
A slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:
- **Reusability**: Define once, use repeatedly
- **Consistency**: Standardize common workflows
- **Sharing**: Distribute across team or projects
- **Efficiency**: Quick access to complex prompts
### Critical: Commands are Instructions FOR Claude
**Commands are written for agent consumption, not human consumption.**
When a user invokes `/command-name`, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.
**Correct approach (instructions for Claude):**
```markdown
Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
- Authentication issues
Provide specific line numbers and severity ratings.
```
**Incorrect approach (messages to user):**
```markdown
This command will review your code for security issues.
You'll receive a report with vulnerability details.
```
The first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.
### Command Locations
**Project commands** (shared with team):
- Location: `.claude/commands/`
- Scope: Available in specific project
- Label: Shown as "(project)" in `/help`
- Use for: Team workflows, project-specific tasks
**Personal commands** (available everywhere):
- Location: `~/.claude/commands/`
- Scope: Available in all projects
- Label: Shown as "(user)" in `/help`
- Use for: Personal workflows, cross-project utilities
**Plugin commands** (bundled with plugins):
- Location: `plugin-name/commands/`
- Scope: Available when plugin installed
- Label: Shown as "(plugin-name)" in `/help`
- Use for: Plugin-specific functionality
## File Format
### Basic Structure
Commands are Markdown files with `.md` extension:
```
.claude/commands/
├── review.md # /review command
├── test.md # /test command
└── deploy.md # /deploy command
```
**Simple command:**
```markdown
Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
- Authentication bypass
- Insecure data handling
```
No frontmatter needed for basic commands.
### With YAML Frontmatter
Add configuration using YAML frontmatter:
```markdown
---
description: Review code for security issues
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---
Review this code for security vulnerabilities...
```
## YAML Frontmatter Fields
### description
**Purpose:** Brief description shown in `/help`
**Type:** String
**Default:** First line of command prompt
```yaml
---
description: Review pull request for code quality
---
```
**Best practice:** Clear, actionable description (under 60 characters)
### allowed-tools
**Purpose:** Specify which tools command can use
**Type:** String or Array
**Default:** Inherits from conversation
```yaml
---
allowed-tools: Read, Write, Edit, Bash(git:*)
---
```
**Patterns:**
- `Read, Write, Edit` - Specific tools
- `Bash(git:*)` - Bash with git commands only
- `*` - All tools (rarely needed)
**Use when:** Command requires specific tool access
### model
**Purpose:** Specify model for command execution
**Type:** String (sonnet, opus, haiku)
**Default:** Inherits from conversation
```yaml
---
model: haiku
---
```
**Use cases:**
- `haiku` - Fast, simple commands
- `sonnet` - Standard workflows
- `opus` - Complex analysis
### argument-hint
**Purpose:** Document expected arguments for autocomplete
**Type:** String
**Default:** None
```yaml
---
argument-hint: [pr-number] [priority] [assignee]
---
```
**Benefits:**
- Helps users understand command arguments
- Improves command discovery
- Documents command interface
### disable-model-invocation
**Purpose:** Prevent SlashCommand tool from programmatically calling command
**Type:** Boolean
**Default:** false
```yaml
---
disable-model-invocation: true
---
```
**Use when:** Command should only be manually invoked
## Dynamic Arguments
### Using $ARGUMENTS
Capture all arguments as single string:
```markdown
---
description: Fix issue by number
argument-hint: [issue-number]
---
Fix issue #$ARGUMENTS following our coding standards and best practices.
```
**Usage:**
```
> /fix-issue 123
> /fix-issue 456
```
**Expands to:**
```
Fix issue #123 following our coding standards...
Fix issue #456 following our coding standards...
```
### Using Positional Arguments
Capture individual arguments with `$1`, `$2`, `$3`, etc.:
```markdown
---
description: Review PR with priority and assignee
argument-hint: [pr-number] [priority] [assignee]
---
Review pull request #$1 with priority level $2.
After review, assign to $3 for follow-up.
```
**Usage:**
```
> /review-pr 123 high alice
```
**Expands to:**
```
Review pull request #123 with priority level high.
After review, assign to alice for follow-up.
```
### Combining Arguments
Mix positional and remaining arguments:
```markdown
Deploy $1 to $2 environment with options: $3
```
**Usage:**
```
> /deploy api staging --force --skip-tests
```
**Expands to:**
```
Deploy api to staging environment with options: --force --skip-tests
```
## File References
### Using @ Syntax
Include file contents in command:
```markdown
---
description: Review specific file
argument-hint: [file-path]
---
Review @$1 for:
- Code quality
- Best practices
- Potential bugs
```
**Usage:**
```
> /review-file src/api/users.ts
```
**Effect:** Claude reads `src/api/users.ts` before processing command
### Multiple File References
Reference multiple files:
```markdown
Compare @src/old-version.js with @src/new-version.js
Identify:
- Breaking changes
- New features
- Bug fixes
```
### Static File References
Reference known files without arguments:
```markdown
Review @package.json and @tsconfig.json for consistency
Ensure:
- TypeScript version matches
- Dependencies are aligned
- Build configuration is correct
```
## Bash Execution in Commands
Commands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.
**When to use:**
- Include dynamic context (git status, environment vars, etc.)
- Gather project/repository state
- Build context-aware workflows
**Implementation details:**
For complete syntax, examples, and best practices, see `references/plugin-features-reference.md` section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues
## Command Organization
### Flat Structure
Simple organization for small command sets:
```
.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md
```
**Use when:** 5-15 commands, no clear categories
### Namespaced Structure
Organize commands in subdirectories:
```
.claude/commands/
├── ci/
│ ├── build.md # /build (project:ci)
│ ├── test.md # /test (project:ci)
│ └── lint.md # /lint (project:ci)
├── git/
│ ├── commit.md # /commit (project:git)
│ └── pr.md # /pr (project:git)
└── docs/
├── generate.md # /generate (project:docs)
└── publish.md # /publish (project:docs)
```
**Benefits:**
- Logical grouping by category
- Namespace shown in `/help`
- Easier to find related commands
**Use when:** 15+ commands, clear categories
## Best Practices
### Command Design
1. **Single responsibility:** One command, one task
2. **Clear descriptions:** Self-explanatory in `/help`
3. **Explicit dependencies:** Use `allowed-tools` when needed
4. **Document arguments:** Always provide `argument-hint`
5. **Consistent naming:** Use verb-noun pattern (review-pr, fix-issue)
### Argument Handling
1. **Validate arguments:** Check for required arguments in prompt
2. **Provide defaults:** Suggest defaults when arguments missing
3. **Document format:** Explain expected argument format
4. **Handle edge cases:** Consider missing or invalid arguments
```markdown
---
argument-hint: [pr-number]
---
$IF($1,
Review PR #$1,
Please provide a PR number. Usage: /review-pr [number]
)
```
### File References
1. **Explicit paths:** Use clear file paths
2. **Check existence:** Handle missing files gracefully
3. **Relative paths:** Use project-relative paths
4. **Glob support:** Consider using Glob tool for patterns
### Bash Commands
1. **Limit scope:** Use `Bash(git:*)` not `Bash(*)`
2. **Safe commands:** Avoid destructive operations
3. **Handle errors:** Consider command failures
4. **Keep fast:** Long-running commands slow invocation
### Documentation
1. **Add comments:** Explain complex logic
2. **Provide examples:** Show usage in comments
3. **List requirements:** Document dependencies
4. **Version commands:** Note breaking changes
```markdown
---
description: Deploy application to environment
argument-hint: [environment] [version]
---
<!--
Usage: /deploy [staging|production] [version]
Requires: AWS credentials configured
Example: /deploy staging v1.2.3
-->
Deploy application to $1 environment using version $2...
```
## Common Patterns
### Review Pattern
```markdown
---
description: Review code changes
allowed-tools: Read, Bash(git:*)
---
Files changed: !`git diff --name-only`
Review each file for:
1. Code quality and style
2. Potential bugs or issues
3. Test coverage
4. Documentation needs
Provide specific feedback for each file.
```
### Testing Pattern
```markdown
---
description: Run tests for specific file
argument-hint: [test-file]
allowed-tools: Bash(npm:*)
---
Run tests: !`npm test $1`
Analyze results and suggest fixes for failures.
```
### Documentation Pattern
```markdown
---
description: Generate documentation for file
argument-hint: [source-file]
---
Generate comprehensive documentation for @$1 including:
- Function/class descriptions
- Parameter documentation
- Return value descriptions
- Usage examples
- Edge cases and errors
```
### Workflow Pattern
```markdown
---
description: Complete PR workflow
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---
PR #$1 Workflow:
1. Fetch PR: !`gh pr view $1`
2. Review changes
3. Run checks
4. Approve or request changes
```
## Troubleshooting
**Command not appearing:**
- Check file is in correct directory
- Verify `.md` extension present
- Ensure valid Markdown format
- Restart Claude Code
**Arguments not working:**
- Verify `$1`, `$2` syntax correct
- Check `argument-hint` matches usage
- Ensure no extra spaces
**Bash execution failing:**
- Check `allowed-tools` includes Bash
- Verify command syntax in backticks
- Test command in terminal first
- Check for required permissions
**File references not working:**
- Verify `@` syntax correct
- Check file path is valid
- Ensure Read tool allowed
- Use absolute or project-relative paths
## Plugin-Specific Features
### CLAUDE_PLUGIN_ROOT Variable
Plugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable that resolves to the plugin's absolute path.
**Purpose:**
- Reference plugin files portably
- Execute plugin scripts
- Load plugin configuration
- Access plugin templates
**Basic usage:**
```markdown
---
description: Analyze using plugin script
allowed-tools: Bash(node:*)
---
Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`
Review results and report findings.
```
**Common patterns:**
```markdown
# Execute plugin script
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`
# Load plugin configuration
@${CLAUDE_PLUGIN_ROOT}/config/settings.json
# Use plugin template
@${CLAUDE_PLUGIN_ROOT}/templates/report.md
# Access plugin resources
@${CLAUDE_PLUGIN_ROOT}/docs/reference.md
```
**Why use it:**
- Works across all installations
- Portable between systems
- No hardcoded paths needed
- Essential for multi-file plugins
### Plugin Command Organization
Plugin commands discovered automatically from `commands/` directory:
```
plugin-name/
├── commands/
│ ├── foo.md # /foo (plugin:plugin-name)
│ ├── bar.md # /bar (plugin:plugin-name)
│ └── utils/
│ └── helper.md # /helper (plugin:plugin-name:utils)
└── plugin.json
```
**Namespace benefits:**
- Logical command grouping
- Shown in `/help` output
- Avoid name conflicts
- Organize related commands
**Naming conventions:**
- Use descriptive action names
- Avoid generic names (test, run)
- Consider plugin-specific prefix
- Use hyphens for multi-word names
### Plugin Command Patterns
**Configuration-based pattern:**
```markdown
---
description: Deploy using plugin configuration
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---
Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json
Deploy to $1 using configuration settings.
Monitor deployment and report status.
```
**Template-based pattern:**
```markdown
---
description: Generate docs from template
argument-hint: [component]
---
Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md
Generate documentation for $1 following template structure.
```
**Multi-script pattern:**
```markdown
---
description: Complete build workflow
allowed-tools: Bash(*)
---
Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`
Review outputs and report workflow status.
```
**See `references/plugin-features-reference.md` for detailed patterns.**
## Integration with Plugin Components
Commands can integrate with other plugin components for powerful workflows.
### Agent Integration
Launch plugin agents for complex tasks:
```markdown
---
description: Deep code review
argument-hint: [file-path]
---
Initiate comprehensive review of @$1 using the code-reviewer agent.
The agent will analyze:
- Code structure
- Security issues
- Performance
- Best practices
Agent uses plugin resources:
- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md
```
**Key points:**
- Agent must exist in `plugin/agents/` directory
- Claude uses Task tool to launch agent
- Document agent capabilities
- Reference plugin resources agent uses
### Skill Integration
Leverage plugin skills for specialized knowledge:
```markdown
---
description: Document API with standards
argument-hint: [api-file]
---
Document API in @$1 following plugin standards.
Use the api-docs-standards skill to ensure:
- Complete endpoint documentation
- Consistent formatting
- Example quality
- Error documentation
Generate production-ready API docs.
```
**Key points:**
- Skill must exist in `plugin/skills/` directory
- Mention skill name to trigger invocation
- Document skill purpose
- Explain what skill provides
### Hook Coordination
Design commands that work with plugin hooks:
- Commands can prepare state for hooks to process
- Hooks execute automatically on tool events
- Commands should document expected hook behavior
- Guide Claude on interpreting hook output
See `references/plugin-features-reference.md` for examples of commands that coordinate with hooks
### Multi-Component Workflows
Combine agents, skills, and scripts:
```markdown
---
description: Comprehensive review workflow
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---
Target: @$1
Phase 1 - Static Analysis:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`
Phase 2 - Deep Review:
Launch code-reviewer agent for detailed analysis.
Phase 3 - Standards Check:
Use coding-standards skill for validation.
Phase 4 - Report:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md
Compile findings into report following template.
```
**When to use:**
- Complex multi-step workflows
- Leverage multiple plugin capabilities
- Require specialized analysis
- Need structured outputs
## Validation Patterns
Commands should validate inputs and resources before processing.
### Argument Validation
```markdown
---
description: Deploy with validation
argument-hint: [environment]
---
Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`
If $1 is valid environment:
Deploy to $1
Otherwise:
Explain valid environments: dev, staging, prod
Show usage: /deploy [environment]
```
### File Existence Checks
```markdown
---
description: Process configuration
argument-hint: [config-file]
---
Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`
If file exists:
Process configuration: @$1
Otherwise:
Explain where to place config file
Show expected format
Provide example configuration
```
### Plugin Resource Validation
```markdown
---
description: Run plugin analyzer
allowed-tools: Bash(test:*)
---
Validate plugin setup:
- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`
If all checks pass, run analysis.
Otherwise, report missing components.
```
### Error Handling
```markdown
---
description: Build with error handling
allowed-tools: Bash(*)
---
Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"`
If build succeeded:
Report success and output location
If build failed:
Analyze error output
Suggest likely causes
Provide troubleshooting steps
```
**Best practices:**
- Validate early in command
- Provide helpful error messages
- Suggest corrective actions
- Handle edge cases gracefully
---
For detailed frontmatter field specifications, see `references/frontmatter-reference.md`.
For plugin-specific features and patterns, see `references/plugin-features-reference.md`.
For command pattern examples, see `examples/` directory.

557
skills/external/plugin-dev-command-development/examples/plugin-commands.md vendored Normal file
View File

@@ -0,0 +1,557 @@
# Plugin Command Examples
Practical examples of commands designed for Claude Code plugins, demonstrating plugin-specific patterns and features.
## Table of Contents
1. [Simple Plugin Command](#1-simple-plugin-command)
2. [Script-Based Analysis](#2-script-based-analysis)
3. [Template-Based Generation](#3-template-based-generation)
4. [Multi-Script Workflow](#4-multi-script-workflow)
5. [Configuration-Driven Deployment](#5-configuration-driven-deployment)
6. [Agent Integration](#6-agent-integration)
7. [Skill Integration](#7-skill-integration)
8. [Multi-Component Workflow](#8-multi-component-workflow)
9. [Validated Input Command](#9-validated-input-command)
10. [Environment-Aware Command](#10-environment-aware-command)
---
## 1. Simple Plugin Command
**Use case:** Basic command that uses plugin script
**File:** `commands/analyze.md`
```markdown
---
description: Analyze code quality using plugin tools
argument-hint: [file-path]
allowed-tools: Bash(node:*), Read
---
Analyze @$1 using plugin's quality checker:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/quality-check.js $1`
Review the analysis output and provide:
1. Summary of findings
2. Priority issues to address
3. Suggested improvements
4. Code quality score interpretation
```
**Key features:**
- Uses `${CLAUDE_PLUGIN_ROOT}` for portable path
- Combines file reference with script execution
- Simple single-purpose command
---
## 2. Script-Based Analysis
**Use case:** Run comprehensive analysis using multiple plugin scripts
**File:** `commands/full-audit.md`
```markdown
---
description: Complete code audit using plugin suite
argument-hint: [directory]
allowed-tools: Bash(*)
model: sonnet
---
Running complete audit on $1:
**Security scan:**
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh $1`
**Performance analysis:**
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-analyze.sh $1`
**Best practices check:**
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/best-practices.sh $1`
Analyze all results and create comprehensive report including:
- Critical issues requiring immediate attention
- Performance optimization opportunities
- Security vulnerabilities and fixes
- Overall health score and recommendations
```
**Key features:**
- Multiple script executions
- Organized output sections
- Comprehensive workflow
- Clear reporting structure
---
## 3. Template-Based Generation
**Use case:** Generate documentation following plugin template
**File:** `commands/gen-api-docs.md`
```markdown
---
description: Generate API documentation from template
argument-hint: [api-file]
---
Template structure: @${CLAUDE_PLUGIN_ROOT}/templates/api-documentation.md
API implementation: @$1
Generate complete API documentation following the template format above.
Ensure documentation includes:
- Endpoint descriptions with HTTP methods
- Request/response schemas
- Authentication requirements
- Error codes and handling
- Usage examples with curl commands
- Rate limiting information
Format output as markdown suitable for README or docs site.
```
**Key features:**
- Uses plugin template
- Combines template with source file
- Standardized output format
- Clear documentation structure
---
## 4. Multi-Script Workflow
**Use case:** Orchestrate build, test, and deploy workflow
**File:** `commands/release.md`
```markdown
---
description: Execute complete release workflow
argument-hint: [version]
allowed-tools: Bash(*), Read
---
Executing release workflow for version $1:
**Step 1 - Pre-release validation:**
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/pre-release-check.sh $1`
**Step 2 - Build artifacts:**
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build-release.sh $1`
**Step 3 - Run test suite:**
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh`
**Step 4 - Package release:**
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh $1`
Review all step outputs and report:
1. Any failures or warnings
2. Build artifacts location
3. Test results summary
4. Next steps for deployment
5. Rollback plan if needed
```
**Key features:**
- Multi-step workflow
- Sequential script execution
- Clear step numbering
- Comprehensive reporting
---
## 5. Configuration-Driven Deployment
**Use case:** Deploy using environment-specific plugin configuration
**File:** `commands/deploy.md`
```markdown
---
description: Deploy application to environment
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---
Deployment configuration for $1: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json
Current git state: !`git rev-parse --short HEAD`
Build info: !`cat package.json | grep -E '(name|version)'`
Execute deployment to $1 environment using configuration above.
Deployment checklist:
1. Validate configuration settings
2. Build application for $1
3. Run pre-deployment tests
4. Deploy to target environment
5. Run smoke tests
6. Verify deployment success
7. Update deployment log
Report deployment status and any issues encountered.
```
**Key features:**
- Environment-specific configuration
- Dynamic config file loading
- Pre-deployment validation
- Structured checklist
---
## 6. Agent Integration
**Use case:** Command that launches plugin agent for complex task
**File:** `commands/deep-review.md`
```markdown
---
description: Deep code review using plugin agent
argument-hint: [file-or-directory]
---
Initiate comprehensive code review of @$1 using the code-reviewer agent.
The agent will perform:
1. **Static analysis** - Check for code smells and anti-patterns
2. **Security audit** - Identify potential vulnerabilities
3. **Performance review** - Find optimization opportunities
4. **Best practices** - Ensure code follows standards
5. **Documentation check** - Verify adequate documentation
The agent has access to:
- Plugin's linting rules: ${CLAUDE_PLUGIN_ROOT}/config/lint-rules.json
- Security checklist: ${CLAUDE_PLUGIN_ROOT}/checklists/security.md
- Performance guidelines: ${CLAUDE_PLUGIN_ROOT}/docs/performance.md
Note: This uses the Task tool to launch the plugin's code-reviewer agent for thorough analysis.
```
**Key features:**
- Delegates to plugin agent
- Documents agent capabilities
- References plugin resources
- Clear scope definition
---
## 7. Skill Integration
**Use case:** Command that leverages plugin skill for specialized knowledge
**File:** `commands/document-api.md`
```markdown
---
description: Document API following plugin standards
argument-hint: [api-file]
---
API source code: @$1
Generate API documentation following the plugin's API documentation standards.
Use the api-documentation-standards skill to ensure:
- **OpenAPI compliance** - Follow OpenAPI 3.0 specification
- **Consistent formatting** - Use plugin's documentation style
- **Complete coverage** - Document all endpoints and schemas
- **Example quality** - Provide realistic usage examples
- **Error documentation** - Cover all error scenarios
The skill provides:
- Standard documentation templates
- API documentation best practices
- Common patterns for this codebase
- Quality validation criteria
Generate production-ready API documentation.
```
**Key features:**
- Invokes plugin skill by name
- Documents skill purpose
- Clear expectations
- Leverages skill knowledge
---
## 8. Multi-Component Workflow
**Use case:** Complex workflow using agents, skills, and scripts
**File:** `commands/complete-review.md`
```markdown
---
description: Comprehensive review using all plugin components
argument-hint: [file-path]
allowed-tools: Bash(node:*), Read
---
Target file: @$1
Execute comprehensive review workflow:
**Phase 1: Automated Analysis**
Run plugin analyzer: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`
**Phase 2: Deep Review (Agent)**
Launch the code-quality-reviewer agent for detailed analysis.
Agent will examine:
- Code structure and organization
- Error handling patterns
- Testing coverage
- Documentation quality
**Phase 3: Standards Check (Skill)**
Use the coding-standards skill to validate:
- Naming conventions
- Code formatting
- Best practices adherence
- Framework-specific patterns
**Phase 4: Report Generation**
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md
Compile all findings into comprehensive report following template.
**Phase 5: Recommendations**
Generate prioritized action items:
1. Critical issues (must fix)
2. Important improvements (should fix)
3. Nice-to-have enhancements (could fix)
Include specific file locations and suggested changes for each item.
```
**Key features:**
- Multi-phase workflow
- Combines scripts, agents, skills
- Template-based reporting
- Prioritized outputs
---
## 9. Validated Input Command
**Use case:** Command with input validation and error handling
**File:** `commands/build-env.md`
```markdown
---
description: Build for specific environment with validation
argument-hint: [environment]
allowed-tools: Bash(*)
---
Validate environment argument: !`echo "$1" | grep -E "^(dev|staging|prod)$" && echo "VALID" || echo "INVALID"`
Check build script exists: !`test -x ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh && echo "EXISTS" || echo "MISSING"`
Verify configuration available: !`test -f ${CLAUDE_PLUGIN_ROOT}/config/$1.json && echo "FOUND" || echo "NOT_FOUND"`
If all validations pass:
**Configuration:** @${CLAUDE_PLUGIN_ROOT}/config/$1.json
**Execute build:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh $1 2>&1`
**Validation results:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-build.sh $1 2>&1`
Report build status and any issues.
If validations fail:
- Explain which validation failed
- Provide expected values/locations
- Suggest corrective actions
- Document troubleshooting steps
```
**Key features:**
- Input validation
- Resource existence checks
- Error handling
- Helpful error messages
- Graceful failure handling
---
## 10. Environment-Aware Command
**Use case:** Command that adapts behavior based on environment
**File:** `commands/run-checks.md`
```markdown
---
description: Run environment-appropriate checks
argument-hint: [environment]
allowed-tools: Bash(*), Read
---
Environment: $1
Load environment configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-checks.json
Determine check level: !`echo "$1" | grep -E "^prod$" && echo "FULL" || echo "BASIC"`
**For production environment:**
- Full test suite: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-full.sh`
- Security scan: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh`
- Performance audit: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-check.sh`
- Compliance check: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/compliance.sh`
**For non-production environments:**
- Basic tests: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-basic.sh`
- Quick lint: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh`
Analyze results based on environment requirements:
**Production:** All checks must pass with zero critical issues
**Staging:** No critical issues, warnings acceptable
**Development:** Focus on blocking issues only
Report status and recommend proceed/block decision.
```
**Key features:**
- Environment-aware logic
- Conditional execution
- Different validation levels
- Appropriate reporting per environment
---
## Common Patterns Summary
### Pattern: Plugin Script Execution
```markdown
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/script-name.js $1`
```
Use for: Running plugin-provided Node.js scripts
### Pattern: Plugin Configuration Loading
```markdown
@${CLAUDE_PLUGIN_ROOT}/config/config-name.json
```
Use for: Loading plugin configuration files
### Pattern: Plugin Template Usage
```markdown
@${CLAUDE_PLUGIN_ROOT}/templates/template-name.md
```
Use for: Using plugin templates for generation
### Pattern: Agent Invocation
```markdown
Launch the [agent-name] agent for [task description].
```
Use for: Delegating complex tasks to plugin agents
### Pattern: Skill Reference
```markdown
Use the [skill-name] skill to ensure [requirements].
```
Use for: Leveraging plugin skills for specialized knowledge
### Pattern: Input Validation
```markdown
Validate input: !`echo "$1" | grep -E "^pattern$" && echo "OK" || echo "ERROR"`
```
Use for: Validating command arguments
### Pattern: Resource Validation
```markdown
Check exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/path/file && echo "YES" || echo "NO"`
```
Use for: Verifying required plugin files exist
---
## Development Tips
### Testing Plugin Commands
1. **Test with plugin installed:**
```bash
cd /path/to/plugin
claude /command-name args
```
2. **Verify ${CLAUDE_PLUGIN_ROOT} expansion:**
```bash
# Add debug output to command
!`echo "Plugin root: ${CLAUDE_PLUGIN_ROOT}"`
```
3. **Test across different working directories:**
```bash
cd /tmp && claude /command-name
cd /other/project && claude /command-name
```
4. **Validate resource availability:**
```bash
# Check all plugin resources exist
!`ls -la ${CLAUDE_PLUGIN_ROOT}/scripts/`
!`ls -la ${CLAUDE_PLUGIN_ROOT}/config/`
```
### Common Mistakes to Avoid
1. **Using relative paths instead of ${CLAUDE_PLUGIN_ROOT}:**
```markdown
# Wrong
!`node ./scripts/analyze.js`
# Correct
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`
```
2. **Forgetting to allow required tools:**
```markdown
# Missing allowed-tools
!`bash script.sh` # Will fail without Bash permission
# Correct
---
allowed-tools: Bash(*)
---
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`
```
3. **Not validating inputs:**
```markdown
# Risky - no validation
Deploy to $1 environment
# Better - with validation
Validate: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`
Deploy to $1 environment (if valid)
```
4. **Hardcoding plugin paths:**
```markdown
# Wrong - breaks on different installations
@/home/user/.claude/plugins/my-plugin/config.json
# Correct - works everywhere
@${CLAUDE_PLUGIN_ROOT}/config.json
```
---
For detailed plugin-specific features, see `references/plugin-features-reference.md`.
For general command development, see main `SKILL.md`.

504
skills/external/plugin-dev-command-development/examples/simple-commands.md vendored Normal file
View File

@@ -0,0 +1,504 @@
# Simple Command Examples
Basic slash command patterns for common use cases.
**Important:** All examples below are written as instructions FOR Claude (agent consumption), not messages TO users. Commands tell Claude what to do, not tell users what will happen.
## Example 1: Code Review Command
**File:** `.claude/commands/review.md`
```markdown
---
description: Review code for quality and issues
allowed-tools: Read, Bash(git:*)
---
Review the code in this repository for:
1. **Code Quality:**
- Readability and maintainability
- Consistent style and formatting
- Appropriate abstraction levels
2. **Potential Issues:**
- Logic errors or bugs
- Edge cases not handled
- Performance concerns
3. **Best Practices:**
- Design patterns used correctly
- Error handling present
- Documentation adequate
Provide specific feedback with file and line references.
```
**Usage:**
```
> /review
```
---
## Example 2: Security Review Command
**File:** `.claude/commands/security-review.md`
```markdown
---
description: Review code for security vulnerabilities
allowed-tools: Read, Grep
model: sonnet
---
Perform comprehensive security review checking for:
**Common Vulnerabilities:**
- SQL injection risks
- Cross-site scripting (XSS)
- Authentication/authorization issues
- Insecure data handling
- Hardcoded secrets or credentials
**Security Best Practices:**
- Input validation present
- Output encoding correct
- Secure defaults used
- Error messages safe
- Logging appropriate (no sensitive data)
For each issue found:
- File and line number
- Severity (Critical/High/Medium/Low)
- Description of vulnerability
- Recommended fix
Prioritize issues by severity.
```
**Usage:**
```
> /security-review
```
---
## Example 3: Test Command with File Argument
**File:** `.claude/commands/test-file.md`
```markdown
---
description: Run tests for specific file
argument-hint: [test-file]
allowed-tools: Bash(npm:*), Bash(jest:*)
---
Run tests for $1:
Test execution: !`npm test $1`
Analyze results:
- Tests passed/failed
- Code coverage
- Performance issues
- Flaky tests
If failures found, suggest fixes based on error messages.
```
**Usage:**
```
> /test-file src/utils/helpers.test.ts
```
---
## Example 4: Documentation Generator
**File:** `.claude/commands/document.md`
```markdown
---
description: Generate documentation for file
argument-hint: [source-file]
---
Generate comprehensive documentation for @$1
Include:
**Overview:**
- Purpose and responsibility
- Main functionality
- Dependencies
**API Documentation:**
- Function/method signatures
- Parameter descriptions with types
- Return values with types
- Exceptions/errors thrown
**Usage Examples:**
- Basic usage
- Common patterns
- Edge cases
**Implementation Notes:**
- Algorithm complexity
- Performance considerations
- Known limitations
Format as Markdown suitable for project documentation.
```
**Usage:**
```
> /document src/api/users.ts
```
---
## Example 5: Git Status Summary
**File:** `.claude/commands/git-status.md`
```markdown
---
description: Summarize Git repository status
allowed-tools: Bash(git:*)
---
Repository Status Summary:
**Current Branch:** !`git branch --show-current`
**Status:** !`git status --short`
**Recent Commits:** !`git log --oneline -5`
**Remote Status:** !`git fetch && git status -sb`
Provide:
- Summary of changes
- Suggested next actions
- Any warnings or issues
```
**Usage:**
```
> /git-status
```
---
## Example 6: Deployment Command
**File:** `.claude/commands/deploy.md`
```markdown
---
description: Deploy to specified environment
argument-hint: [environment] [version]
allowed-tools: Bash(kubectl:*), Read
---
Deploy to $1 environment using version $2
**Pre-deployment Checks:**
1. Verify $1 configuration exists
2. Check version $2 is valid
3. Verify cluster accessibility: !`kubectl cluster-info`
**Deployment Steps:**
1. Update deployment manifest with version $2
2. Apply configuration to $1
3. Monitor rollout status
4. Verify pod health
5. Run smoke tests
**Rollback Plan:**
Document current version for rollback if issues occur.
Proceed with deployment? (yes/no)
```
**Usage:**
```
> /deploy staging v1.2.3
```
---
## Example 7: Comparison Command
**File:** `.claude/commands/compare-files.md`
```markdown
---
description: Compare two files
argument-hint: [file1] [file2]
---
Compare @$1 with @$2
**Analysis:**
1. **Differences:**
- Lines added
- Lines removed
- Lines modified
2. **Functional Changes:**
- Breaking changes
- New features
- Bug fixes
- Refactoring
3. **Impact:**
- Affected components
- Required updates elsewhere
- Migration requirements
4. **Recommendations:**
- Code review focus areas
- Testing requirements
- Documentation updates needed
Present as structured comparison report.
```
**Usage:**
```
> /compare-files src/old-api.ts src/new-api.ts
```
---
## Example 8: Quick Fix Command
**File:** `.claude/commands/quick-fix.md`
```markdown
---
description: Quick fix for common issues
argument-hint: [issue-description]
model: haiku
---
Quickly fix: $ARGUMENTS
**Approach:**
1. Identify the issue
2. Find relevant code
3. Propose fix
4. Explain solution
Focus on:
- Simple, direct solution
- Minimal changes
- Following existing patterns
- No breaking changes
Provide code changes with file paths and line numbers.
```
**Usage:**
```
> /quick-fix button not responding to clicks
> /quick-fix typo in error message
```
---
## Example 9: Research Command
**File:** `.claude/commands/research.md`
```markdown
---
description: Research best practices for topic
argument-hint: [topic]
model: sonnet
---
Research best practices for: $ARGUMENTS
**Coverage:**
1. **Current State:**
- How we currently handle this
- Existing implementations
2. **Industry Standards:**
- Common patterns
- Recommended approaches
- Tools and libraries
3. **Comparison:**
- Our approach vs standards
- Gaps or improvements needed
- Migration considerations
4. **Recommendations:**
- Concrete action items
- Priority and effort estimates
- Resources for implementation
Provide actionable guidance based on research.
```
**Usage:**
```
> /research error handling in async operations
> /research API authentication patterns
```
---
## Example 10: Explain Code Command
**File:** `.claude/commands/explain.md`
```markdown
---
description: Explain how code works
argument-hint: [file-or-function]
---
Explain @$1 in detail
**Explanation Structure:**
1. **Overview:**
- What it does
- Why it exists
- How it fits in system
2. **Step-by-Step:**
- Line-by-line walkthrough
- Key algorithms or logic
- Important details
3. **Inputs and Outputs:**
- Parameters and types
- Return values
- Side effects
4. **Edge Cases:**
- Error handling
- Special cases
- Limitations
5. **Usage Examples:**
- How to call it
- Common patterns
- Integration points
Explain at level appropriate for junior engineer.
```
**Usage:**
```
> /explain src/utils/cache.ts
> /explain AuthService.login
```
---
## Key Patterns
### Pattern 1: Read-Only Analysis
```markdown
---
allowed-tools: Read, Grep
---
Analyze but don't modify...
```
**Use for:** Code review, documentation, analysis
### Pattern 2: Git Operations
```markdown
---
allowed-tools: Bash(git:*)
---
!`git status`
Analyze and suggest...
```
**Use for:** Repository status, commit analysis
### Pattern 3: Single Argument
```markdown
---
argument-hint: [target]
---
Process $1...
```
**Use for:** File operations, targeted actions
### Pattern 4: Multiple Arguments
```markdown
---
argument-hint: [source] [target] [options]
---
Process $1 to $2 with $3...
```
**Use for:** Workflows, deployments, comparisons
### Pattern 5: Fast Execution
```markdown
---
model: haiku
---
Quick simple task...
```
**Use for:** Simple, repetitive commands
### Pattern 6: File Comparison
```markdown
Compare @$1 with @$2...
```
**Use for:** Diff analysis, migration planning
### Pattern 7: Context Gathering
```markdown
---
allowed-tools: Bash(git:*), Read
---
Context: !`git status`
Files: @file1 @file2
Analyze...
```
**Use for:** Informed decision making
## Tips for Writing Simple Commands
1. **Start basic:** Single responsibility, clear purpose
2. **Add complexity gradually:** Start without frontmatter
3. **Test incrementally:** Verify each feature works
4. **Use descriptive names:** Command name should indicate purpose
5. **Document arguments:** Always use argument-hint
6. **Provide examples:** Show usage in comments
7. **Handle errors:** Consider missing arguments or files

722
skills/external/plugin-dev-command-development/references/advanced-workflows.md vendored Normal file
View File

@@ -0,0 +1,722 @@
# Advanced Workflow Patterns
Multi-step command sequences and composition patterns for complex workflows.
## Overview
Advanced workflows combine multiple commands, coordinate state across invocations, and create sophisticated automation sequences. These patterns enable building complex functionality from simple command building blocks.
## Multi-Step Command Patterns
### Sequential Workflow Command
Commands that guide users through multi-step processes:
```markdown
---
description: Complete PR review workflow
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read, Grep
---
# PR Review Workflow for #$1
## Step 1: Fetch PR Details
!`gh pr view $1 --json title,body,author,files`
## Step 2: Review Files
Files changed: !`gh pr diff $1 --name-only`
For each file:
- Check code quality
- Verify tests exist
- Review documentation
## Step 3: Run Checks
Test status: !`gh pr checks $1`
Verify:
- All tests passing
- No merge conflicts
- CI/CD successful
## Step 4: Provide Feedback
Summarize:
- Issues found (critical/minor)
- Suggestions for improvement
- Approval recommendation
Would you like to:
1. Approve PR
2. Request changes
3. Leave comments only
Reply with your choice and I'll help complete the action.
```
**Key features:**
- Numbered steps for clarity
- Bash execution for context
- Decision points for user input
- Next action suggestions
### State-Carrying Workflow
Commands that maintain state between invocations:
```markdown
---
description: Initialize deployment workflow
allowed-tools: Write, Bash(git:*)
---
# Initialize Deployment
Creating deployment tracking file...
Current branch: !`git branch --show-current`
Latest commit: !`git log -1 --format=%H`
Deployment state saved to `.claude/deployment-state.local.md`:
\`\`\`markdown
---
initialized: true
branch: $(git branch --show-current)
commit: $(git log -1 --format=%H)
timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)
status: initialized
---
# Deployment Tracking
Branch: $(git branch --show-current)
Started: $(date)
Next steps:
1. Run tests: /deploy-test
2. Build: /deploy-build
3. Deploy: /deploy-execute
\`\`\`
State saved. Run `/deploy-test` to continue.
```
**Next command** (`/deploy-test`):
```markdown
---
description: Run deployment tests
allowed-tools: Read, Bash(npm:*)
---
Reading deployment state from `.claude/deployment-state.local.md`...
Running tests: !`npm test`
Updating state to 'tested'...
Tests complete. Run `/deploy-build` to continue.
```
**Pattern benefits:**
- Persistent state across commands
- Clear workflow progression
- Safety checkpoints
- Resume capability
### Conditional Workflow Branching
Commands that adapt based on conditions:
```markdown
---
description: Smart deployment workflow
argument-hint: [environment]
allowed-tools: Bash(git:*), Bash(npm:*), Read
---
# Deploy to $1
## Pre-flight Checks
Branch: !`git branch --show-current`
Status: !`git status --short`
**Checking conditions:**
1. Branch status:
- If main/master: Require approval
- If feature branch: Warning about target
- If hotfix: Fast-track process
2. Tests:
!`npm test`
- If tests fail: STOP - fix tests first
- If tests pass: Continue
3. Environment:
- If $1 = 'production': Extra validation
- If $1 = 'staging': Standard process
- If $1 = 'dev': Minimal checks
**Workflow decision:**
Based on above, proceeding with: [determined workflow]
[Conditional steps based on environment and status]
Ready to deploy? (yes/no)
```
## Command Composition Patterns
### Command Chaining
Commands designed to work together:
```markdown
---
description: Prepare for code review
---
# Prepare Code Review
Running preparation sequence:
1. Format code: /format-code
2. Run linter: /lint-code
3. Run tests: /test-all
4. Generate coverage: /coverage-report
5. Create review summary: /review-summary
This is a meta-command. After completing each step above,
I'll compile results and prepare comprehensive review materials.
Starting sequence...
```
**Individual commands** are simple:
- `/format-code` - Just formats
- `/lint-code` - Just lints
- `/test-all` - Just tests
**Composition command** orchestrates them.
### Pipeline Pattern
Commands that process output from previous commands:
```markdown
---
description: Analyze test failures
---
# Analyze Test Failures
## Step 1: Get test results
(Run /test-all first if not done)
Reading test output...
## Step 2: Categorize failures
- Flaky tests (random failures)
- Consistent failures
- New failures vs existing
## Step 3: Prioritize
Rank by:
- Impact (critical path vs edge case)
- Frequency (always fails vs sometimes)
- Effort (quick fix vs major work)
## Step 4: Generate fix plan
For each failure:
- Root cause hypothesis
- Suggested fix approach
- Estimated effort
Would you like me to:
1. Fix highest priority failure
2. Generate detailed fix plans for all
3. Create GitHub issues for each
```
### Parallel Execution Pattern
Commands that coordinate multiple simultaneous operations:
```markdown
---
description: Run comprehensive validation
allowed-tools: Bash(*), Read
---
# Comprehensive Validation
Running validations in parallel...
Starting:
- Code quality checks
- Security scanning
- Dependency audit
- Performance profiling
This will take 2-3 minutes. I'll monitor all processes
and report when complete.
[Poll each process and report progress]
All validations complete. Summary:
- Quality: PASS (0 issues)
- Security: WARN (2 minor issues)
- Dependencies: PASS
- Performance: PASS (baseline met)
Details:
[Collated results from all checks]
```
## Workflow State Management
### Using .local.md Files
Store workflow state in plugin-specific files:
```markdown
.claude/plugin-name-workflow.local.md:
---
workflow: deployment
stage: testing
started: 2025-01-15T10:30:00Z
environment: staging
branch: feature/new-api
commit: abc123def
tests_passed: false
build_complete: false
---
# Deployment Workflow State
Current stage: Testing
Started: 2025-01-15 10:30 UTC
Completed steps:
- ✅ Validation
- ✅ Branch check
- ⏳ Testing (in progress)
Pending steps:
- Build
- Deploy
- Smoke tests
```
**Reading state in commands:**
```markdown
---
description: Continue deployment workflow
allowed-tools: Read, Write
---
Reading workflow state from .claude/plugin-name-workflow.local.md...
Current stage: @.claude/plugin-name-workflow.local.md
[Parse YAML frontmatter to determine next step]
Next action based on state: [determined action]
```
### Workflow Recovery
Handle interrupted workflows:
```markdown
---
description: Resume deployment workflow
allowed-tools: Read
---
# Resume Deployment
Checking for interrupted workflow...
State file: @.claude/plugin-name-workflow.local.md
**Workflow found:**
- Started: [timestamp]
- Environment: [env]
- Last completed: [step]
**Recovery options:**
1. Resume from last step
2. Restart from beginning
3. Abort and clean up
Which would you like? (1/2/3)
```
## Workflow Coordination Patterns
### Cross-Command Communication
Commands that signal each other:
```markdown
---
description: Mark feature complete
allowed-tools: Write
---
# Mark Feature Complete
Writing completion marker...
Creating: .claude/feature-complete.flag
This signals other commands that feature is ready for:
- Integration testing (/integration-test will auto-detect)
- Documentation generation (/docs-generate will include)
- Release notes (/release-notes will add)
Feature marked complete.
```
**Other commands check for flag:**
```markdown
---
description: Generate release notes
allowed-tools: Read, Bash(git:*)
---
Checking for completed features...
if [ -f .claude/feature-complete.flag ]; then
Feature ready for release notes
fi
[Include in release notes]
```
### Workflow Locking
Prevent concurrent workflow execution:
```markdown
---
description: Start deployment
allowed-tools: Read, Write, Bash
---
# Start Deployment
Checking for active deployments...
if [ -f .claude/deployment.lock ]; then
ERROR: Deployment already in progress
Started: [timestamp from lock file]
Cannot start concurrent deployment.
Wait for completion or run /deployment-abort
Exit.
fi
Creating deployment lock...
Deployment started. Lock created.
[Proceed with deployment]
```
**Lock cleanup:**
```markdown
---
description: Complete deployment
allowed-tools: Write, Bash
---
Deployment complete.
Removing deployment lock...
rm .claude/deployment.lock
Ready for next deployment.
```
## Advanced Argument Handling
### Optional Arguments with Defaults
```markdown
---
description: Deploy with optional version
argument-hint: [environment] [version]
---
Environment: ${1:-staging}
Version: ${2:-latest}
Deploying ${2:-latest} to ${1:-staging}...
Note: Using defaults for missing arguments:
- Environment defaults to 'staging'
- Version defaults to 'latest'
```
### Argument Validation
```markdown
---
description: Deploy to validated environment
argument-hint: [environment]
---
Environment: $1
Validating environment...
valid_envs="dev staging production"
if ! echo "$valid_envs" | grep -w "$1" > /dev/null; then
ERROR: Invalid environment '$1'
Valid options: dev, staging, production
Exit.
fi
Environment validated. Proceeding...
```
### Argument Transformation
```markdown
---
description: Deploy with shorthand
argument-hint: [env-shorthand]
---
Input: $1
Expanding shorthand:
- d/dev → development
- s/stg → staging
- p/prod → production
case "$1" in
d|dev) ENV="development";;
s|stg) ENV="staging";;
p|prod) ENV="production";;
*) ENV="$1";;
esac
Deploying to: $ENV
```
## Error Handling in Workflows
### Graceful Failure
```markdown
---
description: Resilient deployment workflow
---
# Deployment Workflow
Running steps with error handling...
## Step 1: Tests
!`npm test`
if [ $? -ne 0 ]; then
ERROR: Tests failed
Options:
1. Fix tests and retry
2. Skip tests (NOT recommended)
3. Abort deployment
What would you like to do?
[Wait for user input before continuing]
fi
## Step 2: Build
[Continue only if Step 1 succeeded]
```
### Rollback on Failure
```markdown
---
description: Deployment with rollback
---
# Deploy with Rollback
Saving current state for rollback...
Previous version: !`current-version.sh`
Deploying new version...
!`deploy.sh`
if [ $? -ne 0 ]; then
DEPLOYMENT FAILED
Initiating automatic rollback...
!`rollback.sh`
Rolled back to previous version.
Check logs for failure details.
fi
Deployment complete.
```
### Checkpoint Recovery
```markdown
---
description: Workflow with checkpoints
---
# Multi-Stage Deployment
## Checkpoint 1: Validation
!`validate.sh`
echo "checkpoint:validation" >> .claude/deployment-checkpoints.log
## Checkpoint 2: Build
!`build.sh`
echo "checkpoint:build" >> .claude/deployment-checkpoints.log
## Checkpoint 3: Deploy
!`deploy.sh`
echo "checkpoint:deploy" >> .claude/deployment-checkpoints.log
If any step fails, resume with:
/deployment-resume [last-successful-checkpoint]
```
## Best Practices
### Workflow Design
1. **Clear progression**: Number steps, show current position
2. **Explicit state**: Don't rely on implicit state
3. **User control**: Provide decision points
4. **Error recovery**: Handle failures gracefully
5. **Progress indication**: Show what's done, what's pending
### Command Composition
1. **Single responsibility**: Each command does one thing well
2. **Composable design**: Commands work together easily
3. **Standard interfaces**: Consistent input/output formats
4. **Loose coupling**: Commands don't depend on each other's internals
### State Management
1. **Persistent state**: Use .local.md files
2. **Atomic updates**: Write complete state files atomically
3. **State validation**: Check state file format/completeness
4. **Cleanup**: Remove stale state files
5. **Documentation**: Document state file formats
### Error Handling
1. **Fail fast**: Detect errors early
2. **Clear messages**: Explain what went wrong
3. **Recovery options**: Provide clear next steps
4. **State preservation**: Keep state for recovery
5. **Rollback capability**: Support undoing changes
## Example: Complete Deployment Workflow
### Initialize Command
```markdown
---
description: Initialize deployment
argument-hint: [environment]
allowed-tools: Write, Bash(git:*)
---
# Initialize Deployment to $1
Creating workflow state...
\`\`\`yaml
---
workflow: deployment
environment: $1
branch: !`git branch --show-current`
commit: !`git rev-parse HEAD`
stage: initialized
timestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ`
---
\`\`\`
Written to .claude/deployment-state.local.md
Next: Run /deployment-validate
```
### Validation Command
```markdown
---
description: Validate deployment
allowed-tools: Read, Bash
---
Reading state: @.claude/deployment-state.local.md
Running validation...
- Branch check: PASS
- Tests: PASS
- Build: PASS
Updating state to 'validated'...
Next: Run /deployment-execute
```
### Execution Command
```markdown
---
description: Execute deployment
allowed-tools: Read, Bash, Write
---
Reading state: @.claude/deployment-state.local.md
Executing deployment to [environment]...
!`deploy.sh [environment]`
Deployment complete.
Updating state to 'completed'...
Cleanup: /deployment-cleanup
```
### Cleanup Command
```markdown
---
description: Clean up deployment
allowed-tools: Bash
---
Removing deployment state...
rm .claude/deployment-state.local.md
Deployment workflow complete.
```
This complete workflow demonstrates state management, sequential execution, error handling, and clean separation of concerns across multiple commands.

739
skills/external/plugin-dev-command-development/references/documentation-patterns.md vendored Normal file
View File

@@ -0,0 +1,739 @@
# Command Documentation Patterns
Strategies for creating self-documenting, maintainable commands with excellent user experience.
## Overview
Well-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers.
## Self-Documenting Command Structure
### Complete Command Template
```markdown
---
description: Clear, actionable description under 60 chars
argument-hint: [arg1] [arg2] [optional-arg]
allowed-tools: Read, Bash(git:*)
model: sonnet
---
<!--
COMMAND: command-name
VERSION: 1.0.0
AUTHOR: Team Name
LAST UPDATED: 2025-01-15
PURPOSE:
Detailed explanation of what this command does and why it exists.
USAGE:
/command-name arg1 arg2
ARGUMENTS:
arg1: Description of first argument (required)
arg2: Description of second argument (optional, defaults to X)
EXAMPLES:
/command-name feature-branch main
→ Compares feature-branch with main
/command-name my-branch
→ Compares my-branch with current branch
REQUIREMENTS:
- Git repository
- Branch must exist
- Permissions to read repository
RELATED COMMANDS:
/other-command - Related functionality
/another-command - Alternative approach
TROUBLESHOOTING:
- If branch not found: Check branch name spelling
- If permission denied: Check repository access
CHANGELOG:
v1.0.0 (2025-01-15): Initial release
v0.9.0 (2025-01-10): Beta version
-->
# Command Implementation
[Command prompt content here...]
[Explain what will happen...]
[Guide user through steps...]
[Provide clear output...]
```
### Documentation Comment Sections
**PURPOSE**: Why the command exists
- Problem it solves
- Use cases
- When to use vs when not to use
**USAGE**: Basic syntax
- Command invocation pattern
- Required vs optional arguments
- Default values
**ARGUMENTS**: Detailed argument documentation
- Each argument described
- Type information
- Valid values/ranges
- Defaults
**EXAMPLES**: Concrete usage examples
- Common use cases
- Edge cases
- Expected outputs
**REQUIREMENTS**: Prerequisites
- Dependencies
- Permissions
- Environmental setup
**RELATED COMMANDS**: Connections
- Similar commands
- Complementary commands
- Alternative approaches
**TROUBLESHOOTING**: Common issues
- Known problems
- Solutions
- Workarounds
**CHANGELOG**: Version history
- What changed when
- Breaking changes highlighted
- Migration guidance
## In-Line Documentation Patterns
### Commented Sections
```markdown
---
description: Complex multi-step command
---
<!-- SECTION 1: VALIDATION -->
<!-- This section checks prerequisites before proceeding -->
Checking prerequisites...
- Git repository: !`git rev-parse --git-dir 2>/dev/null`
- Branch exists: [validation logic]
<!-- SECTION 2: ANALYSIS -->
<!-- Analyzes the differences between branches -->
Analyzing differences between $1 and $2...
[Analysis logic...]
<!-- SECTION 3: RECOMMENDATIONS -->
<!-- Provides actionable recommendations -->
Based on analysis, recommend:
[Recommendations...]
<!-- END: Next steps for user -->
```
### Inline Explanations
```markdown
---
description: Deployment command with inline docs
---
# Deploy to $1
## Pre-flight Checks
<!-- We check branch status to prevent deploying from wrong branch -->
Current branch: !`git branch --show-current`
<!-- Production deploys must come from main/master -->
if [ "$1" = "production" ] && [ "$(git branch --show-current)" != "main" ]; then
⚠️ WARNING: Not on main branch for production deploy
This is unusual. Confirm this is intentional.
fi
<!-- Test status ensures we don't deploy broken code -->
Running tests: !`npm test`
✓ All checks passed
## Deployment
<!-- Actual deployment happens here -->
<!-- Uses blue-green strategy for zero-downtime -->
Deploying to $1 environment...
[Deployment steps...]
<!-- Post-deployment verification -->
Verifying deployment health...
[Health checks...]
Deployment complete!
## Next Steps
<!-- Guide user on what to do after deployment -->
1. Monitor logs: /logs $1
2. Run smoke tests: /smoke-test $1
3. Notify team: /notify-deployment $1
```
### Decision Point Documentation
```markdown
---
description: Interactive deployment command
---
# Interactive Deployment
## Configuration Review
Target: $1
Current version: !`cat version.txt`
New version: $2
<!-- DECISION POINT: User confirms configuration -->
<!-- This pause allows user to verify everything is correct -->
<!-- We can't automatically proceed because deployment is risky -->
Review the above configuration.
**Continue with deployment?**
- Reply "yes" to proceed
- Reply "no" to cancel
- Reply "edit" to modify configuration
[Await user input before continuing...]
<!-- After user confirms, we proceed with deployment -->
<!-- All subsequent steps are automated -->
Proceeding with deployment...
```
## Help Text Patterns
### Built-in Help Command
Create a help subcommand for complex commands:
```markdown
---
description: Main command with help
argument-hint: [subcommand] [args]
---
# Command Processor
if [ "$1" = "help" ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
**Command Help**
USAGE:
/command [subcommand] [args]
SUBCOMMANDS:
init [name] Initialize new configuration
deploy [env] Deploy to environment
status Show current status
rollback Rollback last deployment
help Show this help
EXAMPLES:
/command init my-project
/command deploy staging
/command status
/command rollback
For detailed help on a subcommand:
/command [subcommand] --help
Exit.
fi
[Regular command processing...]
```
### Contextual Help
Provide help based on context:
```markdown
---
description: Context-aware command
argument-hint: [operation] [target]
---
# Context-Aware Operation
if [ -z "$1" ]; then
**No operation specified**
Available operations:
- analyze: Analyze target for issues
- fix: Apply automatic fixes
- report: Generate detailed report
Usage: /command [operation] [target]
Examples:
/command analyze src/
/command fix src/app.js
/command report
Run /command help for more details.
Exit.
fi
[Command continues if operation provided...]
```
## Error Message Documentation
### Helpful Error Messages
```markdown
---
description: Command with good error messages
---
# Validation Command
if [ -z "$1" ]; then
❌ ERROR: Missing required argument
The 'file-path' argument is required.
USAGE:
/validate [file-path]
EXAMPLE:
/validate src/app.js
Try again with a file path.
Exit.
fi
if [ ! -f "$1" ]; then
❌ ERROR: File not found: $1
The specified file does not exist or is not accessible.
COMMON CAUSES:
1. Typo in file path
2. File was deleted or moved
3. Insufficient permissions
SUGGESTIONS:
- Check spelling: $1
- Verify file exists: ls -la $(dirname "$1")
- Check permissions: ls -l "$1"
Exit.
fi
[Command continues if validation passes...]
```
### Error Recovery Guidance
```markdown
---
description: Command with recovery guidance
---
# Operation Command
Running operation...
!`risky-operation.sh`
if [ $? -ne 0 ]; then
❌ OPERATION FAILED
The operation encountered an error and could not complete.
WHAT HAPPENED:
The risky-operation.sh script returned a non-zero exit code.
WHAT THIS MEANS:
- Changes may be partially applied
- System may be in inconsistent state
- Manual intervention may be needed
RECOVERY STEPS:
1. Check operation logs: cat /tmp/operation.log
2. Verify system state: /check-state
3. If needed, rollback: /rollback-operation
4. Fix underlying issue
5. Retry operation: /retry-operation
NEED HELP?
- Check troubleshooting guide: /help troubleshooting
- Contact support with error code: ERR_OP_FAILED_001
Exit.
fi
```
## Usage Example Documentation
### Embedded Examples
```markdown
---
description: Command with embedded examples
---
# Feature Command
This command performs feature analysis with multiple options.
## Basic Usage
\`\`\`
/feature analyze src/
\`\`\`
Analyzes all files in src/ directory for feature usage.
## Advanced Usage
\`\`\`
/feature analyze src/ --detailed
\`\`\`
Provides detailed analysis including:
- Feature breakdown by file
- Usage patterns
- Optimization suggestions
## Use Cases
**Use Case 1: Quick overview**
\`\`\`
/feature analyze .
\`\`\`
Get high-level feature summary of entire project.
**Use Case 2: Specific directory**
\`\`\`
/feature analyze src/components
\`\`\`
Focus analysis on components directory only.
**Use Case 3: Comparison**
\`\`\`
/feature analyze src/ --compare baseline.json
\`\`\`
Compare current features against baseline.
---
Now processing your request...
[Command implementation...]
```
### Example-Driven Documentation
```markdown
---
description: Example-heavy command
---
# Transformation Command
## What This Does
Transforms data from one format to another.
## Examples First
### Example 1: JSON to YAML
**Input:** `data.json`
\`\`\`json
{"name": "test", "value": 42}
\`\`\`
**Command:** `/transform data.json yaml`
**Output:** `data.yaml`
\`\`\`yaml
name: test
value: 42
\`\`\`
### Example 2: CSV to JSON
**Input:** `data.csv`
\`\`\`csv
name,value
test,42
\`\`\`
**Command:** `/transform data.csv json`
**Output:** `data.json`
\`\`\`json
[{"name": "test", "value": "42"}]
\`\`\`
### Example 3: With Options
**Command:** `/transform data.json yaml --pretty --sort-keys`
**Result:** Formatted YAML with sorted keys
---
## Your Transformation
File: $1
Format: $2
[Perform transformation...]
```
## Maintenance Documentation
### Version and Changelog
```markdown
<!--
VERSION: 2.1.0
LAST UPDATED: 2025-01-15
AUTHOR: DevOps Team
CHANGELOG:
v2.1.0 (2025-01-15):
- Added support for YAML configuration
- Improved error messages
- Fixed bug with special characters in arguments
v2.0.0 (2025-01-01):
- BREAKING: Changed argument order
- BREAKING: Removed deprecated --old-flag
- Added new validation checks
- Migration guide: /migration-v2
v1.5.0 (2024-12-15):
- Added --verbose flag
- Improved performance by 50%
v1.0.0 (2024-12-01):
- Initial stable release
MIGRATION NOTES:
From v1.x to v2.0:
Old: /command arg1 arg2 --old-flag
New: /command arg2 arg1
The --old-flag is removed. Use --new-flag instead.
DEPRECATION WARNINGS:
- The --legacy-mode flag is deprecated as of v2.1.0
- Will be removed in v3.0.0 (estimated 2025-06-01)
- Use --modern-mode instead
KNOWN ISSUES:
- #123: Slow performance with large files (workaround: use --stream flag)
- #456: Special characters in Windows (fix planned for v2.2.0)
-->
```
### Maintenance Notes
```markdown
<!--
MAINTENANCE NOTES:
CODE STRUCTURE:
- Lines 1-50: Argument parsing and validation
- Lines 51-100: Main processing logic
- Lines 101-150: Output formatting
- Lines 151-200: Error handling
DEPENDENCIES:
- Requires git 2.x or later
- Uses jq for JSON processing
- Needs bash 4.0+ for associative arrays
PERFORMANCE:
- Fast path for small inputs (< 1MB)
- Streams large files to avoid memory issues
- Caches results in /tmp for 1 hour
SECURITY CONSIDERATIONS:
- Validates all inputs to prevent injection
- Uses allowed-tools to limit Bash access
- No credentials in command file
TESTING:
- Unit tests: tests/command-test.sh
- Integration tests: tests/integration/
- Manual test checklist: tests/manual-checklist.md
FUTURE IMPROVEMENTS:
- TODO: Add support for TOML format
- TODO: Implement parallel processing
- TODO: Add progress bar for large files
RELATED FILES:
- lib/parser.sh: Shared parsing logic
- lib/formatter.sh: Output formatting
- config/defaults.yml: Default configuration
-->
```
## README Documentation
Commands should have companion README files:
```markdown
# Command Name
Brief description of what the command does.
## Installation
This command is part of the [plugin-name] plugin.
Install with:
\`\`\`
/plugin install plugin-name
\`\`\`
## Usage
Basic usage:
\`\`\`
/command-name [arg1] [arg2]
\`\`\`
## Arguments
- `arg1`: Description (required)
- `arg2`: Description (optional, defaults to X)
## Examples
### Example 1: Basic Usage
\`\`\`
/command-name value1 value2
\`\`\`
Description of what happens.
### Example 2: Advanced Usage
\`\`\`
/command-name value1 --option
\`\`\`
Description of advanced feature.
## Configuration
Optional configuration file: `.claude/command-name.local.md`
\`\`\`markdown
---
default_arg: value
enable_feature: true
---
\`\`\`
## Requirements
- Git 2.x or later
- jq (for JSON processing)
- Node.js 14+ (optional, for advanced features)
## Troubleshooting
### Issue: Command not found
**Solution:** Ensure plugin is installed and enabled.
### Issue: Permission denied
**Solution:** Check file permissions and allowed-tools setting.
## Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
MIT License - See [LICENSE](LICENSE).
## Support
- Issues: https://github.com/user/plugin/issues
- Docs: https://docs.example.com
- Email: support@example.com
```
## Best Practices
### Documentation Principles
1. **Write for your future self**: Assume you'll forget details
2. **Examples before explanations**: Show, then tell
3. **Progressive disclosure**: Basic info first, details available
4. **Keep it current**: Update docs when code changes
5. **Test your docs**: Verify examples actually work
### Documentation Locations
1. **In command file**: Core usage, examples, inline explanations
2. **README**: Installation, configuration, troubleshooting
3. **Separate docs**: Detailed guides, tutorials, API reference
4. **Comments**: Implementation details for maintainers
### Documentation Style
1. **Clear and concise**: No unnecessary words
2. **Active voice**: "Run the command" not "The command can be run"
3. **Consistent terminology**: Use same terms throughout
4. **Formatted well**: Use headings, lists, code blocks
5. **Accessible**: Assume reader is beginner
### Documentation Maintenance
1. **Version everything**: Track what changed when
2. **Deprecate gracefully**: Warn before removing features
3. **Migration guides**: Help users upgrade
4. **Archive old docs**: Keep old versions accessible
5. **Review regularly**: Ensure docs match reality
## Documentation Checklist
Before releasing a command:
- [ ] Description in frontmatter is clear
- [ ] argument-hint documents all arguments
- [ ] Usage examples in comments
- [ ] Common use cases shown
- [ ] Error messages are helpful
- [ ] Requirements documented
- [ ] Related commands listed
- [ ] Changelog maintained
- [ ] Version number updated
- [ ] README created/updated
- [ ] Examples actually work
- [ ] Troubleshooting section complete
With good documentation, commands become self-service, reducing support burden and improving user experience.

463
skills/external/plugin-dev-command-development/references/frontmatter-reference.md vendored Normal file
View File

@@ -0,0 +1,463 @@
# Command Frontmatter Reference
Complete reference for YAML frontmatter fields in slash commands.
## Frontmatter Overview
YAML frontmatter is optional metadata at the start of command files:
```markdown
---
description: Brief description
allowed-tools: Read, Write
model: sonnet
argument-hint: [arg1] [arg2]
---
Command prompt content here...
```
All fields are optional. Commands work without any frontmatter.
## Field Specifications
### description
**Type:** String
**Required:** No
**Default:** First line of command prompt
**Max Length:** ~60 characters recommended for `/help` display
**Purpose:** Describes what the command does, shown in `/help` output
**Examples:**
```yaml
description: Review code for security issues
```
```yaml
description: Deploy to staging environment
```
```yaml
description: Generate API documentation
```
**Best practices:**
- Keep under 60 characters for clean display
- Start with verb (Review, Deploy, Generate)
- Be specific about what command does
- Avoid redundant "command" or "slash command"
**Good:**
- ✅ "Review PR for code quality and security"
- ✅ "Deploy application to specified environment"
- ✅ "Generate comprehensive API documentation"
**Bad:**
- ❌ "This command reviews PRs" (unnecessary "This command")
- ❌ "Review" (too vague)
- ❌ "A command that reviews pull requests for code quality, security issues, and best practices" (too long)
### allowed-tools
**Type:** String or Array of strings
**Required:** No
**Default:** Inherits from conversation permissions
**Purpose:** Restrict or specify which tools command can use
**Formats:**
**Single tool:**
```yaml
allowed-tools: Read
```
**Multiple tools (comma-separated):**
```yaml
allowed-tools: Read, Write, Edit
```
**Multiple tools (array):**
```yaml
allowed-tools:
- Read
- Write
- Bash(git:*)
```
**Tool Patterns:**
**Specific tools:**
```yaml
allowed-tools: Read, Grep, Edit
```
**Bash with command filter:**
```yaml
allowed-tools: Bash(git:*) # Only git commands
allowed-tools: Bash(npm:*) # Only npm commands
allowed-tools: Bash(docker:*) # Only docker commands
```
**All tools (not recommended):**
```yaml
allowed-tools: "*"
```
**When to use:**
1. **Security:** Restrict command to safe operations
```yaml
allowed-tools: Read, Grep # Read-only command
```
2. **Clarity:** Document required tools
```yaml
allowed-tools: Bash(git:*), Read
```
3. **Bash execution:** Enable bash command output
```yaml
allowed-tools: Bash(git status:*), Bash(git diff:*)
```
**Best practices:**
- Be as restrictive as possible
- Use command filters for Bash (e.g., `git:*` not `*`)
- Only specify when different from conversation permissions
- Document why specific tools are needed
### model
**Type:** String
**Required:** No
**Default:** Inherits from conversation
**Values:** `sonnet`, `opus`, `haiku`
**Purpose:** Specify which Claude model executes the command
**Examples:**
```yaml
model: haiku # Fast, efficient for simple tasks
```
```yaml
model: sonnet # Balanced performance (default)
```
```yaml
model: opus # Maximum capability for complex tasks
```
**When to use:**
**Use `haiku` for:**
- Simple, formulaic commands
- Fast execution needed
- Low complexity tasks
- Frequent invocations
```yaml
---
description: Format code file
model: haiku
---
```
**Use `sonnet` for:**
- Standard commands (default)
- Balanced speed/quality
- Most common use cases
```yaml
---
description: Review code changes
model: sonnet
---
```
**Use `opus` for:**
- Complex analysis
- Architectural decisions
- Deep code understanding
- Critical tasks
```yaml
---
description: Analyze system architecture
model: opus
---
```
**Best practices:**
- Omit unless specific need
- Use `haiku` for speed when possible
- Reserve `opus` for genuinely complex tasks
- Test with different models to find right balance
### argument-hint
**Type:** String
**Required:** No
**Default:** None
**Purpose:** Document expected arguments for users and autocomplete
**Format:**
```yaml
argument-hint: [arg1] [arg2] [optional-arg]
```
**Examples:**
**Single argument:**
```yaml
argument-hint: [pr-number]
```
**Multiple required arguments:**
```yaml
argument-hint: [environment] [version]
```
**Optional arguments:**
```yaml
argument-hint: [file-path] [options]
```
**Descriptive names:**
```yaml
argument-hint: [source-branch] [target-branch] [commit-message]
```
**Best practices:**
- Use square brackets `[]` for each argument
- Use descriptive names (not `arg1`, `arg2`)
- Indicate optional vs required in description
- Match order to positional arguments in command
- Keep concise but clear
**Examples by pattern:**
**Simple command:**
```yaml
---
description: Fix issue by number
argument-hint: [issue-number]
---
Fix issue #$1...
```
**Multi-argument:**
```yaml
---
description: Deploy to environment
argument-hint: [app-name] [environment] [version]
---
Deploy $1 to $2 using version $3...
```
**With options:**
```yaml
---
description: Run tests with options
argument-hint: [test-pattern] [options]
---
Run tests matching $1 with options: $2
```
### disable-model-invocation
**Type:** Boolean
**Required:** No
**Default:** false
**Purpose:** Prevent SlashCommand tool from programmatically invoking command
**Examples:**
```yaml
disable-model-invocation: true
```
**When to use:**
1. **Manual-only commands:** Commands requiring user judgment
```yaml
---
description: Approve deployment to production
disable-model-invocation: true
---
```
2. **Destructive operations:** Commands with irreversible effects
```yaml
---
description: Delete all test data
disable-model-invocation: true
---
```
3. **Interactive workflows:** Commands needing user input
```yaml
---
description: Walk through setup wizard
disable-model-invocation: true
---
```
**Default behavior (false):**
- Command available to SlashCommand tool
- Claude can invoke programmatically
- Still available for manual invocation
**When true:**
- Command only invokable by user typing `/command`
- Not available to SlashCommand tool
- Safer for sensitive operations
**Best practices:**
- Use sparingly (limits Claude's autonomy)
- Document why in command comments
- Consider if command should exist if always manual
## Complete Examples
### Minimal Command
No frontmatter needed:
```markdown
Review this code for common issues and suggest improvements.
```
### Simple Command
Just description:
```markdown
---
description: Review code for issues
---
Review this code for common issues and suggest improvements.
```
### Standard Command
Description and tools:
```markdown
---
description: Review Git changes
allowed-tools: Bash(git:*), Read
---
Current changes: !`git diff --name-only`
Review each changed file for:
- Code quality
- Potential bugs
- Best practices
```
### Complex Command
All common fields:
```markdown
---
description: Deploy application to environment
argument-hint: [app-name] [environment] [version]
allowed-tools: Bash(kubectl:*), Bash(helm:*), Read
model: sonnet
---
Deploy $1 to $2 environment using version $3
Pre-deployment checks:
- Verify $2 configuration
- Check cluster status: !`kubectl cluster-info`
- Validate version $3 exists
Proceed with deployment following deployment runbook.
```
### Manual-Only Command
Restricted invocation:
```markdown
---
description: Approve production deployment
argument-hint: [deployment-id]
disable-model-invocation: true
allowed-tools: Bash(gh:*)
---
<!--
MANUAL APPROVAL REQUIRED
This command requires human judgment and cannot be automated.
-->
Review deployment $1 for production approval:
Deployment details: !`gh api /deployments/$1`
Verify:
- All tests passed
- Security scan clean
- Stakeholder approval
- Rollback plan ready
Type "APPROVED" to confirm deployment.
```
## Validation
### Common Errors
**Invalid YAML syntax:**
```yaml
---
description: Missing quote
allowed-tools: Read, Write
model: sonnet
--- # ❌ Missing closing quote above
```
**Fix:** Validate YAML syntax
**Incorrect tool specification:**
```yaml
allowed-tools: Bash # ❌ Missing command filter
```
**Fix:** Use `Bash(git:*)` format
**Invalid model name:**
```yaml
model: gpt4 # ❌ Not a valid Claude model
```
**Fix:** Use `sonnet`, `opus`, or `haiku`
### Validation Checklist
Before committing command:
- [ ] YAML syntax valid (no errors)
- [ ] Description under 60 characters
- [ ] allowed-tools uses proper format
- [ ] model is valid value if specified
- [ ] argument-hint matches positional arguments
- [ ] disable-model-invocation used appropriately
## Best Practices Summary
1. **Start minimal:** Add frontmatter only when needed
2. **Document arguments:** Always use argument-hint with arguments
3. **Restrict tools:** Use most restrictive allowed-tools that works
4. **Choose right model:** Use haiku for speed, opus for complexity
5. **Manual-only sparingly:** Only use disable-model-invocation when necessary
6. **Clear descriptions:** Make commands discoverable in `/help`
7. **Test thoroughly:** Verify frontmatter works as expected

920
skills/external/plugin-dev-command-development/references/interactive-commands.md vendored Normal file
View File

@@ -0,0 +1,920 @@
# Interactive Command Patterns
Comprehensive guide to creating commands that gather user feedback and make decisions through the AskUserQuestion tool.
## Overview
Some commands need user input that doesn't work well with simple arguments. For example:
- Choosing between multiple complex options with trade-offs
- Selecting multiple items from a list
- Making decisions that require explanation
- Gathering preferences or configuration interactively
For these cases, use the **AskUserQuestion tool** within command execution rather than relying on command arguments.
## When to Use AskUserQuestion
### Use AskUserQuestion When:
1. **Multiple choice decisions** with explanations needed
2. **Complex options** that require context to choose
3. **Multi-select scenarios** (choosing multiple items)
4. **Preference gathering** for configuration
5. **Interactive workflows** that adapt based on answers
### Use Command Arguments When:
1. **Simple values** (file paths, numbers, names)
2. **Known inputs** user already has
3. **Scriptable workflows** that should be automatable
4. **Fast invocations** where prompting would slow down
## AskUserQuestion Basics
### Tool Parameters
```typescript
{
questions: [
{
question: "Which authentication method should we use?",
header: "Auth method", // Short label (max 12 chars)
multiSelect: false, // true for multiple selection
options: [
{
label: "OAuth 2.0",
description: "Industry standard, supports multiple providers"
},
{
label: "JWT",
description: "Stateless, good for APIs"
},
{
label: "Session",
description: "Traditional, server-side state"
}
]
}
]
}
```
**Key points:**
- Users can always choose "Other" to provide custom input (automatic)
- `multiSelect: true` allows selecting multiple options
- Options should be 2-4 choices (not more)
- Can ask 1-4 questions per tool call
## Command Pattern for User Interaction
### Basic Interactive Command
```markdown
---
description: Interactive setup command
allowed-tools: AskUserQuestion, Write
---
# Interactive Plugin Setup
This command will guide you through configuring the plugin with a series of questions.
## Step 1: Gather Configuration
Use the AskUserQuestion tool to ask:
**Question 1 - Deployment target:**
- header: "Deploy to"
- question: "Which deployment platform will you use?"
- options:
- AWS (Amazon Web Services with ECS/EKS)
- GCP (Google Cloud with GKE)
- Azure (Microsoft Azure with AKS)
- Local (Docker on local machine)
**Question 2 - Environment strategy:**
- header: "Environments"
- question: "How many environments do you need?"
- options:
- Single (Just production)
- Standard (Dev, Staging, Production)
- Complete (Dev, QA, Staging, Production)
**Question 3 - Features to enable:**
- header: "Features"
- question: "Which features do you want to enable?"
- multiSelect: true
- options:
- Auto-scaling (Automatic resource scaling)
- Monitoring (Health checks and metrics)
- CI/CD (Automated deployment pipeline)
- Backups (Automated database backups)
## Step 2: Process Answers
Based on the answers received from AskUserQuestion:
1. Parse the deployment target choice
2. Set up environment-specific configuration
3. Enable selected features
4. Generate configuration files
## Step 3: Generate Configuration
Create `.claude/plugin-name.local.md` with:
\`\`\`yaml
---
deployment_target: [answer from Q1]
environments: [answer from Q2]
features:
auto_scaling: [true if selected in Q3]
monitoring: [true if selected in Q3]
ci_cd: [true if selected in Q3]
backups: [true if selected in Q3]
---
# Plugin Configuration
Generated: [timestamp]
Target: [deployment_target]
Environments: [environments]
\`\`\`
## Step 4: Confirm and Next Steps
Confirm configuration created and guide user on next steps.
```
### Multi-Stage Interactive Workflow
```markdown
---
description: Multi-stage interactive workflow
allowed-tools: AskUserQuestion, Read, Write, Bash
---
# Multi-Stage Deployment Setup
This command walks through deployment setup in stages, adapting based on your answers.
## Stage 1: Basic Configuration
Use AskUserQuestion to ask about deployment basics.
Based on answers, determine which additional questions to ask.
## Stage 2: Advanced Options (Conditional)
If user selected "Advanced" deployment in Stage 1:
Use AskUserQuestion to ask about:
- Load balancing strategy
- Caching configuration
- Security hardening options
If user selected "Simple" deployment:
- Skip advanced questions
- Use sensible defaults
## Stage 3: Confirmation
Show summary of all selections.
Use AskUserQuestion for final confirmation:
- header: "Confirm"
- question: "Does this configuration look correct?"
- options:
- Yes (Proceed with setup)
- No (Start over)
- Modify (Let me adjust specific settings)
If "Modify", ask which specific setting to change.
## Stage 4: Execute Setup
Based on confirmed configuration, execute setup steps.
```
## Interactive Question Design
### Question Structure
**Good questions:**
```markdown
Question: "Which database should we use for this project?"
Header: "Database"
Options:
- PostgreSQL (Relational, ACID compliant, best for complex queries)
- MongoDB (Document store, flexible schema, best for rapid iteration)
- Redis (In-memory, fast, best for caching and sessions)
```
**Poor questions:**
```markdown
Question: "Database?" // Too vague
Header: "DB" // Unclear abbreviation
Options:
- Option 1 // Not descriptive
- Option 2
```
### Option Design Best Practices
**Clear labels:**
- Use 1-5 words
- Specific and descriptive
- No jargon without context
**Helpful descriptions:**
- Explain what the option means
- Mention key benefits or trade-offs
- Help user make informed decision
- Keep to 1-2 sentences
**Appropriate number:**
- 2-4 options per question
- Don't overwhelm with too many choices
- Group related options
- "Other" automatically provided
### Multi-Select Questions
**When to use multiSelect:**
```markdown
Use AskUserQuestion for enabling features:
Question: "Which features do you want to enable?"
Header: "Features"
multiSelect: true // Allow selecting multiple
Options:
- Logging (Detailed operation logs)
- Metrics (Performance monitoring)
- Alerts (Error notifications)
- Backups (Automatic backups)
```
User can select any combination: none, some, or all.
**When NOT to use multiSelect:**
```markdown
Question: "Which authentication method?"
multiSelect: false // Only one auth method makes sense
```
Mutually exclusive choices should not use multiSelect.
## Command Patterns with AskUserQuestion
### Pattern 1: Simple Yes/No Decision
```markdown
---
description: Command with confirmation
allowed-tools: AskUserQuestion, Bash
---
# Destructive Operation
This operation will delete all cached data.
Use AskUserQuestion to confirm:
Question: "This will delete all cached data. Are you sure?"
Header: "Confirm"
Options:
- Yes (Proceed with deletion)
- No (Cancel operation)
If user selects "Yes":
Execute deletion
Report completion
If user selects "No":
Cancel operation
Exit without changes
```
### Pattern 2: Multiple Configuration Questions
```markdown
---
description: Multi-question configuration
allowed-tools: AskUserQuestion, Write
---
# Project Configuration Setup
Gather configuration through multiple questions.
Use AskUserQuestion with multiple questions in one call:
**Question 1:**
- question: "Which programming language?"
- header: "Language"
- options: Python, TypeScript, Go, Rust
**Question 2:**
- question: "Which test framework?"
- header: "Testing"
- options: Jest, PyTest, Go Test, Cargo Test
(Adapt based on language from Q1)
**Question 3:**
- question: "Which CI/CD platform?"
- header: "CI/CD"
- options: GitHub Actions, GitLab CI, CircleCI
**Question 4:**
- question: "Which features do you need?"
- header: "Features"
- multiSelect: true
- options: Linting, Type checking, Code coverage, Security scanning
Process all answers together to generate cohesive configuration.
```
### Pattern 3: Conditional Question Flow
```markdown
---
description: Conditional interactive workflow
allowed-tools: AskUserQuestion, Read, Write
---
# Adaptive Configuration
## Question 1: Deployment Complexity
Use AskUserQuestion:
Question: "How complex is your deployment?"
Header: "Complexity"
Options:
- Simple (Single server, straightforward)
- Standard (Multiple servers, load balancing)
- Complex (Microservices, orchestration)
## Conditional Questions Based on Answer
If answer is "Simple":
- No additional questions
- Use minimal configuration
If answer is "Standard":
- Ask about load balancing strategy
- Ask about scaling policy
If answer is "Complex":
- Ask about orchestration platform (Kubernetes, Docker Swarm)
- Ask about service mesh (Istio, Linkerd, None)
- Ask about monitoring (Prometheus, Datadog, CloudWatch)
- Ask about logging aggregation
## Process Conditional Answers
Generate configuration appropriate for selected complexity level.
```
### Pattern 4: Iterative Collection
```markdown
---
description: Collect multiple items iteratively
allowed-tools: AskUserQuestion, Write
---
# Collect Team Members
We'll collect team member information for the project.
## Question: How many team members?
Use AskUserQuestion:
Question: "How many team members should we set up?"
Header: "Team size"
Options:
- 2 people
- 3 people
- 4 people
- 6 people
## Iterate Through Team Members
For each team member (1 to N based on answer):
Use AskUserQuestion for member details:
Question: "What role for team member [number]?"
Header: "Role"
Options:
- Frontend Developer
- Backend Developer
- DevOps Engineer
- QA Engineer
- Designer
Store each member's information.
## Generate Team Configuration
After collecting all N members, create team configuration file with all members and their roles.
```
### Pattern 5: Dependency Selection
```markdown
---
description: Select dependencies with multi-select
allowed-tools: AskUserQuestion
---
# Configure Project Dependencies
## Question: Required Libraries
Use AskUserQuestion with multiSelect:
Question: "Which libraries does your project need?"
Header: "Dependencies"
multiSelect: true
Options:
- React (UI framework)
- Express (Web server)
- TypeORM (Database ORM)
- Jest (Testing framework)
- Axios (HTTP client)
User can select any combination.
## Process Selections
For each selected library:
- Add to package.json dependencies
- Generate sample configuration
- Create usage examples
- Update documentation
```
## Best Practices for Interactive Commands
### Question Design
1. **Clear and specific**: Question should be unambiguous
2. **Concise header**: Max 12 characters for clean display
3. **Helpful options**: Labels are clear, descriptions explain trade-offs
4. **Appropriate count**: 2-4 options per question, 1-4 questions per call
5. **Logical order**: Questions flow naturally
### Error Handling
```markdown
# Handle AskUserQuestion Responses
After calling AskUserQuestion, verify answers received:
If answers are empty or invalid:
Something went wrong gathering responses.
Please try again or provide configuration manually:
[Show alternative approach]
Exit.
If answers look correct:
Process as expected
```
### Progressive Disclosure
```markdown
# Start Simple, Get Detailed as Needed
## Question 1: Setup Type
Use AskUserQuestion:
Question: "How would you like to set up?"
Header: "Setup type"
Options:
- Quick (Use recommended defaults)
- Custom (Configure all options)
- Guided (Step-by-step with explanations)
If "Quick":
Apply defaults, minimal questions
If "Custom":
Ask all available configuration questions
If "Guided":
Ask questions with extra explanation
Provide recommendations along the way
```
### Multi-Select Guidelines
**Good multi-select use:**
```markdown
Question: "Which features do you want to enable?"
multiSelect: true
Options:
- Logging
- Metrics
- Alerts
- Backups
Reason: User might want any combination
```
**Bad multi-select use:**
```markdown
Question: "Which database engine?"
multiSelect: true // ❌ Should be single-select
Reason: Can only use one database engine
```
## Advanced Patterns
### Validation Loop
```markdown
---
description: Interactive with validation
allowed-tools: AskUserQuestion, Bash
---
# Setup with Validation
## Gather Configuration
Use AskUserQuestion to collect settings.
## Validate Configuration
Check if configuration is valid:
- Required dependencies available?
- Settings compatible with each other?
- No conflicts detected?
If validation fails:
Show validation errors
Use AskUserQuestion to ask:
Question: "Configuration has issues. What would you like to do?"
Header: "Next step"
Options:
- Fix (Adjust settings to resolve issues)
- Override (Proceed despite warnings)
- Cancel (Abort setup)
Based on answer, retry or proceed or exit.
```
### Build Configuration Incrementally
```markdown
---
description: Incremental configuration builder
allowed-tools: AskUserQuestion, Write, Read
---
# Incremental Setup
## Phase 1: Core Settings
Use AskUserQuestion for core settings.
Save to `.claude/config-partial.yml`
## Phase 2: Review Core Settings
Show user the core settings:
Based on these core settings, you need to configure:
- [Setting A] (because you chose [X])
- [Setting B] (because you chose [Y])
Ready to continue?
## Phase 3: Detailed Settings
Use AskUserQuestion for settings based on Phase 1 answers.
Merge with core settings.
## Phase 4: Final Review
Present complete configuration.
Use AskUserQuestion for confirmation:
Question: "Is this configuration correct?"
Options:
- Yes (Save and apply)
- No (Start over)
- Modify (Edit specific settings)
```
### Dynamic Options Based on Context
```markdown
---
description: Context-aware questions
allowed-tools: AskUserQuestion, Bash, Read
---
# Context-Aware Setup
## Detect Current State
Check existing configuration:
- Current language: !`detect-language.sh`
- Existing frameworks: !`detect-frameworks.sh`
- Available tools: !`check-tools.sh`
## Ask Context-Appropriate Questions
Based on detected language, ask relevant questions.
If language is TypeScript:
Use AskUserQuestion:
Question: "Which TypeScript features should we enable?"
Options:
- Strict Mode (Maximum type safety)
- Decorators (Experimental decorator support)
- Path Mapping (Module path aliases)
If language is Python:
Use AskUserQuestion:
Question: "Which Python tools should we configure?"
Options:
- Type Hints (mypy for type checking)
- Black (Code formatting)
- Pylint (Linting and style)
Questions adapt to project context.
```
## Real-World Example: Multi-Agent Swarm Launch
**From multi-agent-swarm plugin:**
```markdown
---
description: Launch multi-agent swarm
allowed-tools: AskUserQuestion, Read, Write, Bash
---
# Launch Multi-Agent Swarm
## Interactive Mode (No Task List Provided)
If user didn't provide task list file, help create one interactively.
### Question 1: Agent Count
Use AskUserQuestion:
Question: "How many agents should we launch?"
Header: "Agent count"
Options:
- 2 agents (Best for simple projects)
- 3 agents (Good for medium projects)
- 4 agents (Standard team size)
- 6 agents (Large projects)
- 8 agents (Complex multi-component projects)
### Question 2: Task Definition Approach
Use AskUserQuestion:
Question: "How would you like to define tasks?"
Header: "Task setup"
Options:
- File (I have a task list file ready)
- Guided (Help me create tasks interactively)
- Custom (Other approach)
If "File":
Ask for file path
Validate file exists and has correct format
If "Guided":
Enter iterative task creation mode (see below)
### Question 3: Coordination Mode
Use AskUserQuestion:
Question: "How should agents coordinate?"
Header: "Coordination"
Options:
- Team Leader (One agent coordinates others)
- Collaborative (Agents coordinate as peers)
- Autonomous (Independent work, minimal coordination)
### Iterative Task Creation (If "Guided" Selected)
For each agent (1 to N from Question 1):
**Question A: Agent Name**
Question: "What should we call agent [number]?"
Header: "Agent name"
Options:
- auth-agent
- api-agent
- ui-agent
- db-agent
(Provide relevant suggestions based on common patterns)
**Question B: Task Type**
Question: "What task for [agent-name]?"
Header: "Task type"
Options:
- Authentication (User auth, JWT, OAuth)
- API Endpoints (REST/GraphQL APIs)
- UI Components (Frontend components)
- Database (Schema, migrations, queries)
- Testing (Test suites and coverage)
- Documentation (Docs, README, guides)
**Question C: Dependencies**
Question: "What does [agent-name] depend on?"
Header: "Dependencies"
multiSelect: true
Options:
- [List of previously defined agents]
- No dependencies
**Question D: Base Branch**
Question: "Which base branch for PR?"
Header: "PR base"
Options:
- main
- staging
- develop
Store all task information for each agent.
### Generate Task List File
After collecting all agent task details:
1. Ask for project name
2. Generate task list in proper format
3. Save to `.daisy/swarm/tasks.md`
4. Show user the file path
5. Proceed with launch using generated task list
```
## Best Practices
### Question Writing
1. **Be specific**: "Which database?" not "Choose option?"
2. **Explain trade-offs**: Describe pros/cons in option descriptions
3. **Provide context**: Question text should stand alone
4. **Guide decisions**: Help user make informed choice
5. **Keep concise**: Header max 12 chars, descriptions 1-2 sentences
### Option Design
1. **Meaningful labels**: Specific, clear names
2. **Informative descriptions**: Explain what each option does
3. **Show trade-offs**: Help user understand implications
4. **Consistent detail**: All options equally explained
5. **2-4 options**: Not too few, not too many
### Flow Design
1. **Logical order**: Questions flow naturally
2. **Build on previous**: Later questions use earlier answers
3. **Minimize questions**: Ask only what's needed
4. **Group related**: Ask related questions together
5. **Show progress**: Indicate where in flow
### User Experience
1. **Set expectations**: Tell user what to expect
2. **Explain why**: Help user understand purpose
3. **Provide defaults**: Suggest recommended options
4. **Allow escape**: Let user cancel or restart
5. **Confirm actions**: Summarize before executing
## Common Patterns
### Pattern: Feature Selection
```markdown
Use AskUserQuestion:
Question: "Which features do you need?"
Header: "Features"
multiSelect: true
Options:
- Authentication
- Authorization
- Rate Limiting
- Caching
```
### Pattern: Environment Configuration
```markdown
Use AskUserQuestion:
Question: "Which environment is this?"
Header: "Environment"
Options:
- Development (Local development)
- Staging (Pre-production testing)
- Production (Live environment)
```
### Pattern: Priority Selection
```markdown
Use AskUserQuestion:
Question: "What's the priority for this task?"
Header: "Priority"
Options:
- Critical (Must be done immediately)
- High (Important, do soon)
- Medium (Standard priority)
- Low (Nice to have)
```
### Pattern: Scope Selection
```markdown
Use AskUserQuestion:
Question: "What scope should we analyze?"
Header: "Scope"
Options:
- Current file (Just this file)
- Current directory (All files in directory)
- Entire project (Full codebase scan)
```
## Combining Arguments and Questions
### Use Both Appropriately
**Arguments for known values:**
```markdown
---
argument-hint: [project-name]
allowed-tools: AskUserQuestion, Write
---
Setup for project: $1
Now gather additional configuration...
Use AskUserQuestion for options that require explanation.
```
**Questions for complex choices:**
```markdown
Project name from argument: $1
Now use AskUserQuestion to choose:
- Architecture pattern
- Technology stack
- Deployment strategy
These require explanation, so questions work better than arguments.
```
## Troubleshooting
**Questions not appearing:**
- Verify AskUserQuestion in allowed-tools
- Check question format is correct
- Ensure options array has 2-4 items
**User can't make selection:**
- Check option labels are clear
- Verify descriptions are helpful
- Consider if too many options
- Ensure multiSelect setting is correct
**Flow feels confusing:**
- Reduce number of questions
- Group related questions
- Add explanation between stages
- Show progress through workflow
With AskUserQuestion, commands become interactive wizards that guide users through complex decisions while maintaining the clarity that simple arguments provide for straightforward inputs.

904
skills/external/plugin-dev-command-development/references/marketplace-considerations.md vendored Normal file
View File

@@ -0,0 +1,904 @@
# Marketplace Considerations for Commands
Guidelines for creating commands designed for distribution and marketplace success.
## Overview
Commands distributed through marketplaces need additional consideration beyond personal use commands. They must work across environments, handle diverse use cases, and provide excellent user experience for unknown users.
## Design for Distribution
### Universal Compatibility
**Cross-platform considerations:**
```markdown
---
description: Cross-platform command
allowed-tools: Bash(*)
---
# Platform-Aware Command
Detecting platform...
case "$(uname)" in
Darwin*) PLATFORM="macOS" ;;
Linux*) PLATFORM="Linux" ;;
MINGW*|MSYS*|CYGWIN*) PLATFORM="Windows" ;;
*) PLATFORM="Unknown" ;;
esac
Platform: $PLATFORM
<!-- Adjust behavior based on platform -->
if [ "$PLATFORM" = "Windows" ]; then
# Windows-specific handling
PATH_SEP="\\"
NULL_DEVICE="NUL"
else
# Unix-like handling
PATH_SEP="/"
NULL_DEVICE="/dev/null"
fi
[Platform-appropriate implementation...]
```
**Avoid platform-specific commands:**
```markdown
<!-- BAD: macOS-specific -->
!`pbcopy < file.txt`
<!-- GOOD: Platform detection -->
if command -v pbcopy > /dev/null; then
pbcopy < file.txt
elif command -v xclip > /dev/null; then
xclip -selection clipboard < file.txt
elif command -v clip.exe > /dev/null; then
cat file.txt | clip.exe
else
echo "Clipboard not available on this platform"
fi
```
### Minimal Dependencies
**Check for required tools:**
```markdown
---
description: Dependency-aware command
allowed-tools: Bash(*)
---
# Check Dependencies
Required tools:
- git
- jq
- node
Checking availability...
MISSING_DEPS=""
for tool in git jq node; do
if ! command -v $tool > /dev/null; then
MISSING_DEPS="$MISSING_DEPS $tool"
fi
done
if [ -n "$MISSING_DEPS" ]; then
❌ ERROR: Missing required dependencies:$MISSING_DEPS
INSTALLATION:
- git: https://git-scm.com/downloads
- jq: https://stedolan.github.io/jq/download/
- node: https://nodejs.org/
Install missing tools and try again.
Exit.
fi
✓ All dependencies available
[Continue with command...]
```
**Document optional dependencies:**
```markdown
<!--
DEPENDENCIES:
Required:
- git 2.0+: Version control
- jq 1.6+: JSON processing
Optional:
- gh: GitHub CLI (for PR operations)
- docker: Container operations (for containerized tests)
Feature availability depends on installed tools.
-->
```
### Graceful Degradation
**Handle missing features:**
```markdown
---
description: Feature-aware command
---
# Feature Detection
Detecting available features...
FEATURES=""
if command -v gh > /dev/null; then
FEATURES="$FEATURES github"
fi
if command -v docker > /dev/null; then
FEATURES="$FEATURES docker"
fi
Available features: $FEATURES
if echo "$FEATURES" | grep -q "github"; then
# Full functionality with GitHub integration
echo "✓ GitHub integration available"
else
# Reduced functionality without GitHub
echo "⚠ Limited functionality: GitHub CLI not installed"
echo " Install 'gh' for full features"
fi
[Adapt behavior based on available features...]
```
## User Experience for Unknown Users
### Clear Onboarding
**First-run experience:**
```markdown
---
description: Command with onboarding
allowed-tools: Read, Write
---
# First Run Check
if [ ! -f ".claude/command-initialized" ]; then
**Welcome to Command Name!**
This appears to be your first time using this command.
WHAT THIS COMMAND DOES:
[Brief explanation of purpose and benefits]
QUICK START:
1. Basic usage: /command [arg]
2. For help: /command help
3. Examples: /command examples
SETUP:
No additional setup required. You're ready to go!
✓ Initialization complete
[Create initialization marker]
Ready to proceed with your request...
fi
[Normal command execution...]
```
**Progressive feature discovery:**
```markdown
---
description: Command with tips
---
# Command Execution
[Main functionality...]
---
💡 TIP: Did you know?
You can speed up this command with the --fast flag:
/command --fast [args]
For more tips: /command tips
```
### Comprehensive Error Handling
**Anticipate user mistakes:**
```markdown
---
description: Forgiving command
---
# User Input Handling
Argument: "$1"
<!-- Check for common typos -->
if [ "$1" = "hlep" ] || [ "$1" = "hepl" ]; then
Did you mean: help?
Showing help instead...
[Display help]
Exit.
fi
<!-- Suggest similar commands if not found -->
if [ "$1" != "valid-option1" ] && [ "$1" != "valid-option2" ]; then
❌ Unknown option: $1
Did you mean:
- valid-option1 (most similar)
- valid-option2
For all options: /command help
Exit.
fi
[Command continues...]
```
**Helpful diagnostics:**
```markdown
---
description: Diagnostic command
---
# Operation Failed
The operation could not complete.
**Diagnostic Information:**
Environment:
- Platform: $(uname)
- Shell: $SHELL
- Working directory: $(pwd)
- Command: /command $@
Checking common issues:
- Git repository: $(git rev-parse --git-dir 2>&1)
- Write permissions: $(test -w . && echo "OK" || echo "DENIED")
- Required files: $(test -f config.yml && echo "Found" || echo "Missing")
This information helps debug the issue.
For support, include the above diagnostics.
```
## Distribution Best Practices
### Namespace Awareness
**Avoid name collisions:**
```markdown
---
description: Namespaced command
---
<!--
COMMAND NAME: plugin-name-command
This command is namespaced with the plugin name to avoid
conflicts with commands from other plugins.
Alternative naming approaches:
- Use plugin prefix: /plugin-command
- Use category: /category-command
- Use verb-noun: /verb-noun
Chosen approach: plugin-name prefix
Reasoning: Clearest ownership, least likely to conflict
-->
# Plugin Name Command
[Implementation...]
```
**Document naming rationale:**
```markdown
<!--
NAMING DECISION:
Command name: /deploy-app
Alternatives considered:
- /deploy: Too generic, likely conflicts
- /app-deploy: Less intuitive ordering
- /my-plugin-deploy: Too verbose
Final choice balances:
- Discoverability (clear purpose)
- Brevity (easy to type)
- Uniqueness (unlikely conflicts)
-->
```
### Configurability
**User preferences:**
```markdown
---
description: Configurable command
allowed-tools: Read
---
# Load User Configuration
Default configuration:
- verbose: false
- color: true
- max_results: 10
Checking for user config: .claude/plugin-name.local.md
if [ -f ".claude/plugin-name.local.md" ]; then
# Parse YAML frontmatter for settings
VERBOSE=$(grep "^verbose:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
COLOR=$(grep "^color:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
MAX_RESULTS=$(grep "^max_results:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
echo "✓ Using user configuration"
else
echo "Using default configuration"
echo "Create .claude/plugin-name.local.md to customize"
fi
[Use configuration in command...]
```
**Sensible defaults:**
```markdown
---
description: Command with smart defaults
---
# Smart Defaults
Configuration:
- Format: ${FORMAT:-json} # Defaults to json
- Output: ${OUTPUT:-stdout} # Defaults to stdout
- Verbose: ${VERBOSE:-false} # Defaults to false
These defaults work for 80% of use cases.
Override with arguments:
/command --format yaml --output file.txt --verbose
Or set in .claude/plugin-name.local.md:
\`\`\`yaml
---
format: yaml
output: custom.txt
verbose: true
---
\`\`\`
```
### Version Compatibility
**Version checking:**
```markdown
---
description: Version-aware command
---
<!--
COMMAND VERSION: 2.1.0
COMPATIBILITY:
- Requires plugin version: >= 2.0.0
- Breaking changes from v1.x documented in MIGRATION.md
VERSION HISTORY:
- v2.1.0: Added --new-feature flag
- v2.0.0: BREAKING: Changed argument order
- v1.0.0: Initial release
-->
# Version Check
Command version: 2.1.0
Plugin version: [detect from plugin.json]
if [ "$PLUGIN_VERSION" < "2.0.0" ]; then
❌ ERROR: Incompatible plugin version
This command requires plugin version >= 2.0.0
Current version: $PLUGIN_VERSION
Update plugin:
/plugin update plugin-name
Exit.
fi
✓ Version compatible
[Command continues...]
```
**Deprecation warnings:**
```markdown
---
description: Command with deprecation warnings
---
# Deprecation Check
if [ "$1" = "--old-flag" ]; then
⚠️ DEPRECATION WARNING
The --old-flag option is deprecated as of v2.0.0
It will be removed in v3.0.0 (est. June 2025)
Use instead: --new-flag
Example:
Old: /command --old-flag value
New: /command --new-flag value
See migration guide: /command migrate
Continuing with deprecated behavior for now...
fi
[Handle both old and new flags during deprecation period...]
```
## Marketplace Presentation
### Command Discovery
**Descriptive naming:**
```markdown
---
description: Review pull request with security and quality checks
---
<!-- GOOD: Descriptive name and description -->
```
```markdown
---
description: Do the thing
---
<!-- BAD: Vague description -->
```
**Searchable keywords:**
```markdown
<!--
KEYWORDS: security, code-review, quality, validation, audit
These keywords help users discover this command when searching
for related functionality in the marketplace.
-->
```
### Showcase Examples
**Compelling demonstrations:**
```markdown
---
description: Advanced code analysis command
---
# Code Analysis Command
This command performs deep code analysis with actionable insights.
## Demo: Quick Security Audit
Try it now:
\`\`\`
/analyze-code src/ --security
\`\`\`
**What you'll get:**
- Security vulnerability detection
- Code quality metrics
- Performance bottleneck identification
- Actionable recommendations
**Sample output:**
\`\`\`
Security Analysis Results
=========================
🔴 Critical (2):
- SQL injection risk in users.js:45
- XSS vulnerability in display.js:23
🟡 Warnings (5):
- Unvalidated input in api.js:67
...
Recommendations:
1. Fix critical issues immediately
2. Review warnings before next release
3. Run /analyze-code --fix for auto-fixes
\`\`\`
---
Ready to analyze your code...
[Command implementation...]
```
### User Reviews and Feedback
**Feedback mechanism:**
```markdown
---
description: Command with feedback
---
# Command Complete
[Command results...]
---
**How was your experience?**
This helps improve the command for everyone.
Rate this command:
- 👍 Helpful
- 👎 Not helpful
- 🐛 Found a bug
- 💡 Have a suggestion
Reply with an emoji or:
- /command feedback
Your feedback matters!
```
**Usage analytics preparation:**
```markdown
<!--
ANALYTICS NOTES:
Track for improvement:
- Most common arguments
- Failure rates
- Average execution time
- User satisfaction scores
Privacy-preserving:
- No personally identifiable information
- Aggregate statistics only
- User opt-out respected
-->
```
## Quality Standards
### Professional Polish
**Consistent branding:**
```markdown
---
description: Branded command
---
# ✨ Command Name
Part of the [Plugin Name] suite
[Command functionality...]
---
**Need Help?**
- Documentation: https://docs.example.com
- Support: support@example.com
- Community: https://community.example.com
Powered by Plugin Name v2.1.0
```
**Attention to detail:**
```markdown
<!-- Details that matter -->
✓ Use proper emoji/symbols consistently
✓ Align output columns neatly
✓ Format numbers with thousands separators
✓ Use color/formatting appropriately
✓ Provide progress indicators
✓ Show estimated time remaining
✓ Confirm successful operations
```
### Reliability
**Idempotency:**
```markdown
---
description: Idempotent command
---
# Safe Repeated Execution
Checking if operation already completed...
if [ -f ".claude/operation-completed.flag" ]; then
ℹ️ Operation already completed
Completed at: $(cat .claude/operation-completed.flag)
To re-run:
1. Remove flag: rm .claude/operation-completed.flag
2. Run command again
Otherwise, no action needed.
Exit.
fi
Performing operation...
[Safe, repeatable operation...]
Marking complete...
echo "$(date)" > .claude/operation-completed.flag
```
**Atomic operations:**
```markdown
---
description: Atomic command
---
# Atomic Operation
This operation is atomic - either fully succeeds or fully fails.
Creating temporary workspace...
TEMP_DIR=$(mktemp -d)
Performing changes in isolated environment...
[Make changes in $TEMP_DIR]
if [ $? -eq 0 ]; then
✓ Changes validated
Applying changes atomically...
mv $TEMP_DIR/* ./target/
✓ Operation complete
else
❌ Changes failed validation
Rolling back...
rm -rf $TEMP_DIR
No changes applied. Safe to retry.
fi
```
## Testing for Distribution
### Pre-Release Checklist
```markdown
<!--
PRE-RELEASE CHECKLIST:
Functionality:
- [ ] Works on macOS
- [ ] Works on Linux
- [ ] Works on Windows (WSL)
- [ ] All arguments tested
- [ ] Error cases handled
- [ ] Edge cases covered
User Experience:
- [ ] Clear description
- [ ] Helpful error messages
- [ ] Examples provided
- [ ] First-run experience good
- [ ] Documentation complete
Distribution:
- [ ] No hardcoded paths
- [ ] Dependencies documented
- [ ] Configuration options clear
- [ ] Version number set
- [ ] Changelog updated
Quality:
- [ ] No TODO comments
- [ ] No debug code
- [ ] Performance acceptable
- [ ] Security reviewed
- [ ] Privacy considered
Support:
- [ ] README complete
- [ ] Troubleshooting guide
- [ ] Support contact provided
- [ ] Feedback mechanism
- [ ] License specified
-->
```
### Beta Testing
**Beta release approach:**
```markdown
---
description: Beta command (v0.9.0)
---
# 🧪 Beta Command
**This is a beta release**
Features may change based on feedback.
BETA STATUS:
- Version: 0.9.0
- Stability: Experimental
- Support: Limited
- Feedback: Encouraged
Known limitations:
- Performance not optimized
- Some edge cases not handled
- Documentation incomplete
Help improve this command:
- Report issues: /command report-issue
- Suggest features: /command suggest
- Join beta testers: /command join-beta
---
[Command implementation...]
---
**Thank you for beta testing!**
Your feedback helps make this command better.
```
## Maintenance and Updates
### Update Strategy
**Versioned commands:**
```markdown
<!--
VERSION STRATEGY:
Major (X.0.0): Breaking changes
- Document all breaking changes
- Provide migration guide
- Support old version briefly
Minor (x.Y.0): New features
- Backward compatible
- Announce new features
- Update examples
Patch (x.y.Z): Bug fixes
- No user-facing changes
- Update changelog
- Security fixes prioritized
Release schedule:
- Patches: As needed
- Minors: Monthly
- Majors: Annually or as needed
-->
```
**Update notifications:**
```markdown
---
description: Update-aware command
---
# Check for Updates
Current version: 2.1.0
Latest version: [check if available]
if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then
📢 UPDATE AVAILABLE
New version: $LATEST_VERSION
Current: $CURRENT_VERSION
What's new:
- Feature improvements
- Bug fixes
- Performance enhancements
Update with:
/plugin update plugin-name
Release notes: https://releases.example.com/v$LATEST_VERSION
fi
[Command continues...]
```
## Best Practices Summary
### Distribution Design
1. **Universal**: Works across platforms and environments
2. **Self-contained**: Minimal dependencies, clear requirements
3. **Graceful**: Degrades gracefully when features unavailable
4. **Forgiving**: Anticipates and handles user mistakes
5. **Helpful**: Clear errors, good defaults, excellent docs
### Marketplace Success
1. **Discoverable**: Clear name, good description, searchable keywords
2. **Professional**: Polished presentation, consistent branding
3. **Reliable**: Tested thoroughly, handles edge cases
4. **Maintainable**: Versioned, updated regularly, supported
5. **User-focused**: Great UX, responsive to feedback
### Quality Standards
1. **Complete**: Fully documented, all features working
2. **Tested**: Works in real environments, edge cases handled
3. **Secure**: No vulnerabilities, safe operations
4. **Performant**: Reasonable speed, resource-efficient
5. **Ethical**: Privacy-respecting, user consent
With these considerations, commands become marketplace-ready and delight users across diverse environments and use cases.

609
skills/external/plugin-dev-command-development/references/plugin-features-reference.md vendored Normal file
View File

@@ -0,0 +1,609 @@
# Plugin-Specific Command Features Reference
This reference covers features and patterns specific to commands bundled in Claude Code plugins.
## Table of Contents
- [Plugin Command Discovery](#plugin-command-discovery)
- [CLAUDE_PLUGIN_ROOT Environment Variable](#claude_plugin_root-environment-variable)
- [Plugin Command Patterns](#plugin-command-patterns)
- [Integration with Plugin Components](#integration-with-plugin-components)
- [Validation Patterns](#validation-patterns)
## Plugin Command Discovery
### Auto-Discovery
Claude Code automatically discovers commands in plugins using the following locations:
```
plugin-name/
├── commands/ # Auto-discovered commands
│ ├── foo.md # /foo (plugin:plugin-name)
│ └── bar.md # /bar (plugin:plugin-name)
└── plugin.json # Plugin manifest
```
**Key points:**
- Commands are discovered at plugin load time
- No manual registration required
- Commands appear in `/help` with "(plugin:plugin-name)" label
- Subdirectories create namespaces
### Namespaced Plugin Commands
Organize commands in subdirectories for logical grouping:
```
plugin-name/
└── commands/
├── review/
│ ├── security.md # /security (plugin:plugin-name:review)
│ └── style.md # /style (plugin:plugin-name:review)
└── deploy/
├── staging.md # /staging (plugin:plugin-name:deploy)
└── prod.md # /prod (plugin:plugin-name:deploy)
```
**Namespace behavior:**
- Subdirectory name becomes namespace
- Shown as "(plugin:plugin-name:namespace)" in `/help`
- Helps organize related commands
- Use when plugin has 5+ commands
### Command Naming Conventions
**Plugin command names should:**
1. Be descriptive and action-oriented
2. Avoid conflicts with common command names
3. Use hyphens for multi-word names
4. Consider prefixing with plugin name for uniqueness
**Examples:**
```
Good:
- /mylyn-sync (plugin-specific prefix)
- /analyze-performance (descriptive action)
- /docker-compose-up (clear purpose)
Avoid:
- /test (conflicts with common name)
- /run (too generic)
- /do-stuff (not descriptive)
```
## CLAUDE_PLUGIN_ROOT Environment Variable
### Purpose
`${CLAUDE_PLUGIN_ROOT}` is a special environment variable available in plugin commands that resolves to the absolute path of the plugin directory.
**Why it matters:**
- Enables portable paths within plugin
- Allows referencing plugin files and scripts
- Works across different installations
- Essential for multi-file plugin operations
### Basic Usage
Reference files within your plugin:
```markdown
---
description: Analyze using plugin script
allowed-tools: Bash(node:*), Read
---
Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`
Read template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md
```
**Expands to:**
```
Run analysis: !`node /path/to/plugins/plugin-name/scripts/analyze.js`
Read template: @/path/to/plugins/plugin-name/templates/report.md
```
### Common Patterns
#### 1. Executing Plugin Scripts
```markdown
---
description: Run custom linter from plugin
allowed-tools: Bash(node:*)
---
Lint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1`
Review the linting output and suggest fixes.
```
#### 2. Loading Configuration Files
```markdown
---
description: Deploy using plugin configuration
allowed-tools: Read, Bash(*)
---
Configuration: @${CLAUDE_PLUGIN_ROOT}/config/deploy-config.json
Deploy application using the configuration above for $1 environment.
```
#### 3. Accessing Plugin Resources
```markdown
---
description: Generate report from template
---
Use this template: @${CLAUDE_PLUGIN_ROOT}/templates/api-report.md
Generate a report for @$1 following the template format.
```
#### 4. Multi-Step Plugin Workflows
```markdown
---
description: Complete plugin workflow
allowed-tools: Bash(*), Read
---
Step 1 - Prepare: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1`
Step 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json
Step 3 - Execute: !`${CLAUDE_PLUGIN_ROOT}/bin/execute $1`
Review results and report status.
```
### Best Practices
1. **Always use for plugin-internal paths:**
```markdown
# Good
@${CLAUDE_PLUGIN_ROOT}/templates/foo.md
# Bad
@./templates/foo.md # Relative to current directory, not plugin
```
2. **Validate file existence:**
```markdown
---
description: Use plugin config if exists
allowed-tools: Bash(test:*), Read
---
!`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "exists" || echo "missing"`
If config exists, load it: @${CLAUDE_PLUGIN_ROOT}/config.json
Otherwise, use defaults...
```
3. **Document plugin file structure:**
```markdown
<!--
Plugin structure:
${CLAUDE_PLUGIN_ROOT}/
├── scripts/analyze.js (analysis script)
├── templates/ (report templates)
└── config/ (configuration files)
-->
```
4. **Combine with arguments:**
```markdown
Run: !`${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2`
```
### Troubleshooting
**Variable not expanding:**
- Ensure command is loaded from plugin
- Check bash execution is allowed
- Verify syntax is exact: `${CLAUDE_PLUGIN_ROOT}`
**File not found errors:**
- Verify file exists in plugin directory
- Check file path is correct relative to plugin root
- Ensure file permissions allow reading/execution
**Path with spaces:**
- Bash commands automatically handle spaces
- File references work with spaces in paths
- No special quoting needed
## Plugin Command Patterns
### Pattern 1: Configuration-Based Commands
Commands that load plugin-specific configuration:
```markdown
---
description: Deploy using plugin settings
allowed-tools: Read, Bash(*)
---
Load configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json
Deploy to $1 environment using:
1. Configuration settings above
2. Current git branch: !`git branch --show-current`
3. Application version: !`cat package.json | grep version`
Execute deployment and monitor progress.
```
**When to use:** Commands that need consistent settings across invocations
### Pattern 2: Template-Based Generation
Commands that use plugin templates:
```markdown
---
description: Generate documentation from template
argument-hint: [component-name]
---
Template: @${CLAUDE_PLUGIN_ROOT}/templates/component-docs.md
Generate documentation for $1 component following the template structure.
Include:
- Component purpose and usage
- API reference
- Examples
- Testing guidelines
```
**When to use:** Standardized output generation
### Pattern 3: Multi-Script Workflow
Commands that orchestrate multiple plugin scripts:
```markdown
---
description: Complete build and test workflow
allowed-tools: Bash(*)
---
Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Validate: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`
Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
Review all outputs and report:
1. Build status
2. Validation results
3. Test results
4. Recommended next steps
```
**When to use:** Complex plugin workflows with multiple steps
### Pattern 4: Environment-Aware Commands
Commands that adapt to environment:
```markdown
---
description: Deploy based on environment
argument-hint: [dev|staging|prod]
---
Environment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json
Environment check: !`echo "Deploying to: $1"`
Deploy application using $1 environment configuration.
Verify deployment and run smoke tests.
```
**When to use:** Commands that behave differently per environment
### Pattern 5: Plugin Data Management
Commands that manage plugin-specific data:
```markdown
---
description: Save analysis results to plugin cache
allowed-tools: Bash(*), Read, Write
---
Cache directory: ${CLAUDE_PLUGIN_ROOT}/cache/
Analyze @$1 and save results to cache:
!`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt`
Store analysis for future reference and comparison.
```
**When to use:** Commands that need persistent data storage
## Integration with Plugin Components
### Invoking Plugin Agents
Commands can trigger plugin agents using the Task tool:
```markdown
---
description: Deep analysis using plugin agent
argument-hint: [file-path]
---
Initiate deep code analysis of @$1 using the code-analyzer agent.
The agent will:
1. Analyze code structure
2. Identify patterns
3. Suggest improvements
4. Generate detailed report
Note: This uses the Task tool to launch the plugin's code-analyzer agent.
```
**Key points:**
- Agent must be defined in plugin's `agents/` directory
- Claude will automatically use Task tool to launch agent
- Agent has access to same plugin resources
### Invoking Plugin Skills
Commands can reference plugin skills for specialized knowledge:
```markdown
---
description: API documentation with best practices
argument-hint: [api-file]
---
Document the API in @$1 following our API documentation standards.
Use the api-docs-standards skill to ensure documentation includes:
- Endpoint descriptions
- Parameter specifications
- Response formats
- Error codes
- Usage examples
Note: This leverages the plugin's api-docs-standards skill for consistency.
```
**Key points:**
- Skill must be defined in plugin's `skills/` directory
- Mention skill by name to hint Claude should invoke it
- Skills provide specialized domain knowledge
### Coordinating with Plugin Hooks
Commands can be designed to work with plugin hooks:
```markdown
---
description: Commit with pre-commit validation
allowed-tools: Bash(git:*)
---
Stage changes: !\`git add $1\`
Commit changes: !\`git commit -m "$2"\`
Note: This commit will trigger the plugin's pre-commit hook for validation.
Review hook output for any issues.
```
**Key points:**
- Hooks execute automatically on events
- Commands can prepare state for hooks
- Document hook interaction in command
### Multi-Component Plugin Commands
Commands that coordinate multiple plugin components:
```markdown
---
description: Comprehensive code review workflow
argument-hint: [file-path]
---
File to review: @$1
Execute comprehensive review:
1. **Static Analysis** (via plugin scripts)
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`
2. **Deep Review** (via plugin agent)
Launch the code-reviewer agent for detailed analysis.
3. **Best Practices** (via plugin skill)
Use the code-standards skill to ensure compliance.
4. **Documentation** (via plugin template)
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md
Generate final report combining all outputs.
```
**When to use:** Complex workflows leveraging multiple plugin capabilities
## Validation Patterns
### Input Validation
Commands should validate inputs before processing:
```markdown
---
description: Deploy to environment with validation
argument-hint: [environment]
---
Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`
$IF($1 in [dev, staging, prod],
Deploy to $1 environment using validated configuration,
ERROR: Invalid environment '$1'. Must be one of: dev, staging, prod
)
```
**Validation approaches:**
1. Bash validation using grep/test
2. Inline validation in prompt
3. Script-based validation
### File Existence Checks
Verify required files exist:
```markdown
---
description: Process configuration file
argument-hint: [config-file]
---
Check file: !`test -f $1 && echo "EXISTS" || echo "MISSING"`
Process configuration if file exists: @$1
If file doesn't exist, explain:
- Expected location
- Required format
- How to create it
```
### Required Arguments
Validate required arguments provided:
```markdown
---
description: Create deployment with version
argument-hint: [environment] [version]
---
Validate inputs: !`test -n "$1" -a -n "$2" && echo "OK" || echo "MISSING"`
$IF($1 AND $2,
Deploy version $2 to $1 environment,
ERROR: Both environment and version required. Usage: /deploy [env] [version]
)
```
### Plugin Resource Validation
Verify plugin resources available:
```markdown
---
description: Run analysis with plugin tools
allowed-tools: Bash(test:*)
---
Validate plugin setup:
- Config exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`
- Scripts exist: !`test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo "✓" || echo "✗"`
- Tools available: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
If all checks pass, proceed with analysis.
Otherwise, report missing components and installation steps.
```
### Output Validation
Validate command execution results:
```markdown
---
description: Build and validate output
allowed-tools: Bash(*)
---
Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Validate output:
- Exit code: !`echo $?`
- Output exists: !`test -d dist && echo "✓" || echo "✗"`
- File count: !`find dist -type f | wc -l`
Report build status and any validation failures.
```
### Graceful Error Handling
Handle errors gracefully with helpful messages:
```markdown
---
description: Process file with error handling
argument-hint: [file-path]
---
Try processing: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo "ERROR: $?"`
If processing succeeded:
- Report results
- Suggest next steps
If processing failed:
- Explain likely causes
- Provide troubleshooting steps
- Suggest alternative approaches
```
## Best Practices Summary
### Plugin Commands Should:
1. **Use ${CLAUDE_PLUGIN_ROOT} for all plugin-internal paths**
- Scripts, templates, configuration, resources
2. **Validate inputs early**
- Check required arguments
- Verify file existence
- Validate argument formats
3. **Document plugin structure**
- Explain required files
- Document script purposes
- Clarify dependencies
4. **Integrate with plugin components**
- Reference agents for complex tasks
- Use skills for specialized knowledge
- Coordinate with hooks when relevant
5. **Provide helpful error messages**
- Explain what went wrong
- Suggest how to fix
- Offer alternatives
6. **Handle edge cases**
- Missing files
- Invalid arguments
- Failed script execution
- Missing dependencies
7. **Keep commands focused**
- One clear purpose per command
- Delegate complex logic to scripts
- Use agents for multi-step workflows
8. **Test across installations**
- Verify paths work everywhere
- Test with different arguments
- Validate error cases
---
For general command development, see main SKILL.md.
For command examples, see examples/ directory.

702
skills/external/plugin-dev-command-development/references/testing-strategies.md vendored Normal file
View File

@@ -0,0 +1,702 @@
# Command Testing Strategies
Comprehensive strategies for testing slash commands before deployment and distribution.
## Overview
Testing commands ensures they work correctly, handle edge cases, and provide good user experience. A systematic testing approach catches issues early and builds confidence in command reliability.
## Testing Levels
### Level 1: Syntax and Structure Validation
**What to test:**
- YAML frontmatter syntax
- Markdown format
- File location and naming
**How to test:**
```bash
# Validate YAML frontmatter
head -n 20 .claude/commands/my-command.md | grep -A 10 "^---"
# Check for closing frontmatter marker
head -n 20 .claude/commands/my-command.md | grep -c "^---" # Should be 2
# Verify file has .md extension
ls .claude/commands/*.md
# Check file is in correct location
test -f .claude/commands/my-command.md && echo "Found" || echo "Missing"
```
**Automated validation script:**
```bash
#!/bin/bash
# validate-command.sh
COMMAND_FILE="$1"
if [ ! -f "$COMMAND_FILE" ]; then
echo "ERROR: File not found: $COMMAND_FILE"
exit 1
fi
# Check .md extension
if [[ ! "$COMMAND_FILE" =~ \.md$ ]]; then
echo "ERROR: File must have .md extension"
exit 1
fi
# Validate YAML frontmatter if present
if head -n 1 "$COMMAND_FILE" | grep -q "^---"; then
# Count frontmatter markers
MARKERS=$(head -n 50 "$COMMAND_FILE" | grep -c "^---")
if [ "$MARKERS" -ne 2 ]; then
echo "ERROR: Invalid YAML frontmatter (need exactly 2 '---' markers)"
exit 1
fi
echo "✓ YAML frontmatter syntax valid"
fi
# Check for empty file
if [ ! -s "$COMMAND_FILE" ]; then
echo "ERROR: File is empty"
exit 1
fi
echo "✓ Command file structure valid"
```
### Level 2: Frontmatter Field Validation
**What to test:**
- Field types correct
- Values in valid ranges
- Required fields present (if any)
**Validation script:**
```bash
#!/bin/bash
# validate-frontmatter.sh
COMMAND_FILE="$1"
# Extract YAML frontmatter
FRONTMATTER=$(sed -n '/^---$/,/^---$/p' "$COMMAND_FILE" | sed '1d;$d')
if [ -z "$FRONTMATTER" ]; then
echo "No frontmatter to validate"
exit 0
fi
# Check 'model' field if present
if echo "$FRONTMATTER" | grep -q "^model:"; then
MODEL=$(echo "$FRONTMATTER" | grep "^model:" | cut -d: -f2 | tr -d ' ')
if ! echo "sonnet opus haiku" | grep -qw "$MODEL"; then
echo "ERROR: Invalid model '$MODEL' (must be sonnet, opus, or haiku)"
exit 1
fi
echo "✓ Model field valid: $MODEL"
fi
# Check 'allowed-tools' field format
if echo "$FRONTMATTER" | grep -q "^allowed-tools:"; then
echo "✓ allowed-tools field present"
# Could add more sophisticated validation here
fi
# Check 'description' length
if echo "$FRONTMATTER" | grep -q "^description:"; then
DESC=$(echo "$FRONTMATTER" | grep "^description:" | cut -d: -f2-)
LENGTH=${#DESC}
if [ "$LENGTH" -gt 80 ]; then
echo "WARNING: Description length $LENGTH (recommend < 60 chars)"
else
echo "✓ Description length acceptable: $LENGTH chars"
fi
fi
echo "✓ Frontmatter fields valid"
```
### Level 3: Manual Command Invocation
**What to test:**
- Command appears in `/help`
- Command executes without errors
- Output is as expected
**Test procedure:**
```bash
# 1. Start Claude Code
claude --debug
# 2. Check command appears in help
> /help
# Look for your command in the list
# 3. Invoke command without arguments
> /my-command
# Check for reasonable error or behavior
# 4. Invoke with valid arguments
> /my-command arg1 arg2
# Verify expected behavior
# 5. Check debug logs
tail -f ~/.claude/debug-logs/latest
# Look for errors or warnings
```
### Level 4: Argument Testing
**What to test:**
- Positional arguments work ($1, $2, etc.)
- $ARGUMENTS captures all arguments
- Missing arguments handled gracefully
- Invalid arguments detected
**Test matrix:**
| Test Case | Command | Expected Result |
|-----------|---------|-----------------|
| No args | `/cmd` | Graceful handling or useful message |
| One arg | `/cmd arg1` | $1 substituted correctly |
| Two args | `/cmd arg1 arg2` | $1 and $2 substituted |
| Extra args | `/cmd a b c d` | All captured or extras ignored appropriately |
| Special chars | `/cmd "arg with spaces"` | Quotes handled correctly |
| Empty arg | `/cmd ""` | Empty string handled |
**Test script:**
```bash
#!/bin/bash
# test-command-arguments.sh
COMMAND="$1"
echo "Testing argument handling for /$COMMAND"
echo
echo "Test 1: No arguments"
echo " Command: /$COMMAND"
echo " Expected: [describe expected behavior]"
echo " Manual test required"
echo
echo "Test 2: Single argument"
echo " Command: /$COMMAND test-value"
echo " Expected: 'test-value' appears in output"
echo " Manual test required"
echo
echo "Test 3: Multiple arguments"
echo " Command: /$COMMAND arg1 arg2 arg3"
echo " Expected: All arguments used appropriately"
echo " Manual test required"
echo
echo "Test 4: Special characters"
echo " Command: /$COMMAND \"value with spaces\""
echo " Expected: Entire phrase captured"
echo " Manual test required"
```
### Level 5: File Reference Testing
**What to test:**
- @ syntax loads file contents
- Non-existent files handled
- Large files handled appropriately
- Multiple file references work
**Test procedure:**
```bash
# Create test files
echo "Test content" > /tmp/test-file.txt
echo "Second file" > /tmp/test-file-2.txt
# Test single file reference
> /my-command /tmp/test-file.txt
# Verify file content is read
# Test non-existent file
> /my-command /tmp/nonexistent.txt
# Verify graceful error handling
# Test multiple files
> /my-command /tmp/test-file.txt /tmp/test-file-2.txt
# Verify both files processed
# Test large file
dd if=/dev/zero of=/tmp/large-file.bin bs=1M count=100
> /my-command /tmp/large-file.bin
# Verify reasonable behavior (may truncate or warn)
# Cleanup
rm /tmp/test-file*.txt /tmp/large-file.bin
```
### Level 6: Bash Execution Testing
**What to test:**
- !` commands execute correctly
- Command output included in prompt
- Command failures handled
- Security: only allowed commands run
**Test procedure:**
```bash
# Create test command with bash execution
cat > .claude/commands/test-bash.md << 'EOF'
---
description: Test bash execution
allowed-tools: Bash(echo:*), Bash(date:*)
---
Current date: !`date`
Test output: !`echo "Hello from bash"`
Analysis of output above...
EOF
# Test in Claude Code
> /test-bash
# Verify:
# 1. Date appears correctly
# 2. Echo output appears
# 3. No errors in debug logs
# Test with disallowed command (should fail or be blocked)
cat > .claude/commands/test-forbidden.md << 'EOF'
---
description: Test forbidden command
allowed-tools: Bash(echo:*)
---
Trying forbidden: !`ls -la /`
EOF
> /test-forbidden
# Verify: Permission denied or appropriate error
```
### Level 7: Integration Testing
**What to test:**
- Commands work with other plugin components
- Commands interact correctly with each other
- State management works across invocations
- Workflow commands execute in sequence
**Test scenarios:**
**Scenario 1: Command + Hook Integration**
```bash
# Setup: Command that triggers a hook
# Test: Invoke command, verify hook executes
# Command: .claude/commands/risky-operation.md
# Hook: PreToolUse that validates the operation
> /risky-operation
# Verify: Hook executes and validates before command completes
```
**Scenario 2: Command Sequence**
```bash
# Setup: Multi-command workflow
> /workflow-init
# Verify: State file created
> /workflow-step2
# Verify: State file read, step 2 executes
> /workflow-complete
# Verify: State file cleaned up
```
**Scenario 3: Command + MCP Integration**
```bash
# Setup: Command uses MCP tools
# Test: Verify MCP server accessible
> /mcp-command
# Verify:
# 1. MCP server starts (if stdio)
# 2. Tool calls succeed
# 3. Results included in output
```
## Automated Testing Approaches
### Command Test Suite
Create a test suite script:
```bash
#!/bin/bash
# test-commands.sh - Command test suite
TEST_DIR=".claude/commands"
FAILED_TESTS=0
echo "Command Test Suite"
echo "=================="
echo
for cmd_file in "$TEST_DIR"/*.md; do
cmd_name=$(basename "$cmd_file" .md)
echo "Testing: $cmd_name"
# Validate structure
if ./validate-command.sh "$cmd_file"; then
echo " ✓ Structure valid"
else
echo " ✗ Structure invalid"
((FAILED_TESTS++))
fi
# Validate frontmatter
if ./validate-frontmatter.sh "$cmd_file"; then
echo " ✓ Frontmatter valid"
else
echo " ✗ Frontmatter invalid"
((FAILED_TESTS++))
fi
echo
done
echo "=================="
echo "Tests complete"
echo "Failed: $FAILED_TESTS"
exit $FAILED_TESTS
```
### Pre-Commit Hook
Validate commands before committing:
```bash
#!/bin/bash
# .git/hooks/pre-commit
echo "Validating commands..."
COMMANDS_CHANGED=$(git diff --cached --name-only | grep "\.claude/commands/.*\.md")
if [ -z "$COMMANDS_CHANGED" ]; then
echo "No commands changed"
exit 0
fi
for cmd in $COMMANDS_CHANGED; do
echo "Checking: $cmd"
if ! ./scripts/validate-command.sh "$cmd"; then
echo "ERROR: Command validation failed: $cmd"
exit 1
fi
done
echo "✓ All commands valid"
```
### Continuous Testing
Test commands in CI/CD:
```yaml
# .github/workflows/test-commands.yml
name: Test Commands
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Validate command structure
run: |
for cmd in .claude/commands/*.md; do
echo "Testing: $cmd"
./scripts/validate-command.sh "$cmd"
done
- name: Validate frontmatter
run: |
for cmd in .claude/commands/*.md; do
./scripts/validate-frontmatter.sh "$cmd"
done
- name: Check for TODOs
run: |
if grep -r "TODO" .claude/commands/; then
echo "ERROR: TODOs found in commands"
exit 1
fi
```
## Edge Case Testing
### Test Edge Cases
**Empty arguments:**
```bash
> /cmd ""
> /cmd '' ''
```
**Special characters:**
```bash
> /cmd "arg with spaces"
> /cmd arg-with-dashes
> /cmd arg_with_underscores
> /cmd arg/with/slashes
> /cmd 'arg with "quotes"'
```
**Long arguments:**
```bash
> /cmd $(python -c "print('a' * 10000)")
```
**Unusual file paths:**
```bash
> /cmd ./file
> /cmd ../file
> /cmd ~/file
> /cmd "/path with spaces/file"
```
**Bash command edge cases:**
```markdown
# Commands that might fail
!`exit 1`
!`false`
!`command-that-does-not-exist`
# Commands with special output
!`echo ""`
!`cat /dev/null`
!`yes | head -n 1000000`
```
## Performance Testing
### Response Time Testing
```bash
#!/bin/bash
# test-command-performance.sh
COMMAND="$1"
echo "Testing performance of /$COMMAND"
echo
for i in {1..5}; do
echo "Run $i:"
START=$(date +%s%N)
# Invoke command (manual step - record time)
echo " Invoke: /$COMMAND"
echo " Start time: $START"
echo " (Record end time manually)"
echo
done
echo "Analyze results:"
echo " - Average response time"
echo " - Variance"
echo " - Acceptable threshold: < 3 seconds for fast commands"
```
### Resource Usage Testing
```bash
# Monitor Claude Code during command execution
# In terminal 1:
claude --debug
# In terminal 2:
watch -n 1 'ps aux | grep claude'
# Execute command and observe:
# - Memory usage
# - CPU usage
# - Process count
```
## User Experience Testing
### Usability Checklist
- [ ] Command name is intuitive
- [ ] Description is clear in `/help`
- [ ] Arguments are well-documented
- [ ] Error messages are helpful
- [ ] Output is formatted readably
- [ ] Long-running commands show progress
- [ ] Results are actionable
- [ ] Edge cases have good UX
### User Acceptance Testing
Recruit testers:
```markdown
# Testing Guide for Beta Testers
## Command: /my-new-command
### Test Scenarios
1. **Basic usage:**
- Run: `/my-new-command`
- Expected: [describe]
- Rate clarity: 1-5
2. **With arguments:**
- Run: `/my-new-command arg1 arg2`
- Expected: [describe]
- Rate usefulness: 1-5
3. **Error case:**
- Run: `/my-new-command invalid-input`
- Expected: Helpful error message
- Rate error message: 1-5
### Feedback Questions
1. Was the command easy to understand?
2. Did the output meet your expectations?
3. What would you change?
4. Would you use this command regularly?
```
## Testing Checklist
Before releasing a command:
### Structure
- [ ] File in correct location
- [ ] Correct .md extension
- [ ] Valid YAML frontmatter (if present)
- [ ] Markdown syntax correct
### Functionality
- [ ] Command appears in `/help`
- [ ] Description is clear
- [ ] Command executes without errors
- [ ] Arguments work as expected
- [ ] File references work
- [ ] Bash execution works (if used)
### Edge Cases
- [ ] Missing arguments handled
- [ ] Invalid arguments detected
- [ ] Non-existent files handled
- [ ] Special characters work
- [ ] Long inputs handled
### Integration
- [ ] Works with other commands
- [ ] Works with hooks (if applicable)
- [ ] Works with MCP (if applicable)
- [ ] State management works
### Quality
- [ ] Performance acceptable
- [ ] No security issues
- [ ] Error messages helpful
- [ ] Output formatted well
- [ ] Documentation complete
### Distribution
- [ ] Tested by others
- [ ] Feedback incorporated
- [ ] README updated
- [ ] Examples provided
## Debugging Failed Tests
### Common Issues and Solutions
**Issue: Command not appearing in /help**
```bash
# Check file location
ls -la .claude/commands/my-command.md
# Check permissions
chmod 644 .claude/commands/my-command.md
# Check syntax
head -n 20 .claude/commands/my-command.md
# Restart Claude Code
claude --debug
```
**Issue: Arguments not substituting**
```bash
# Verify syntax
grep '\$1' .claude/commands/my-command.md
grep '\$ARGUMENTS' .claude/commands/my-command.md
# Test with simple command first
echo "Test: \$1 and \$2" > .claude/commands/test-args.md
```
**Issue: Bash commands not executing**
```bash
# Check allowed-tools
grep "allowed-tools" .claude/commands/my-command.md
# Verify command syntax
grep '!\`' .claude/commands/my-command.md
# Test command manually
date
echo "test"
```
**Issue: File references not working**
```bash
# Check @ syntax
grep '@' .claude/commands/my-command.md
# Verify file exists
ls -la /path/to/referenced/file
# Check permissions
chmod 644 /path/to/referenced/file
```
## Best Practices
1. **Test early, test often**: Validate as you develop
2. **Automate validation**: Use scripts for repeatable checks
3. **Test edge cases**: Don't just test the happy path
4. **Get feedback**: Have others test before wide release
5. **Document tests**: Keep test scenarios for regression testing
6. **Monitor in production**: Watch for issues after release
7. **Iterate**: Improve based on real usage data

711
skills/external/plugin-dev-hook-development/SKILL.md vendored Normal file
View File

@@ -0,0 +1,711 @@
---
name: hook-development
description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
---
# Hook Development for Claude Code Plugins
## Overview
Hooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.
**Key capabilities:**
- Validate tool calls before execution (PreToolUse)
- React to tool results (PostToolUse)
- Enforce completion standards (Stop, SubagentStop)
- Load project context (SessionStart)
- Automate workflows across the development lifecycle
## Hook Types
### Prompt-Based Hooks (Recommended)
Use LLM-driven decision making for context-aware validation:
```json
{
"type": "prompt",
"prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT",
"timeout": 30
}
```
**Supported events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse
**Benefits:**
- Context-aware decisions based on natural language reasoning
- Flexible evaluation logic without bash scripting
- Better edge case handling
- Easier to maintain and extend
### Command Hooks
Execute bash commands for deterministic checks:
```json
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
"timeout": 60
}
```
**Use for:**
- Fast deterministic validations
- File system operations
- External tool integrations
- Performance-critical checks
## Hook Configuration Formats
### Plugin hooks.json Format
**For plugin hooks** in `hooks/hooks.json`, use wrapper format:
```json
{
"description": "Brief explanation of hooks (optional)",
"hooks": {
"PreToolUse": [...],
"Stop": [...],
"SessionStart": [...]
}
}
```
**Key points:**
- `description` field is optional
- `hooks` field is required wrapper containing actual hook events
- This is the **plugin-specific format**
**Example:**
```json
{
"description": "Validation hooks for code quality",
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh"
}
]
}
]
}
}
```
### Settings Format (Direct)
**For user settings** in `.claude/settings.json`, use direct format:
```json
{
"PreToolUse": [...],
"Stop": [...],
"SessionStart": [...]
}
```
**Key points:**
- No wrapper - events directly at top level
- No description field
- This is the **settings format**
**Important:** The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in `{"hooks": {...}}`.
## Hook Events
### PreToolUse
Execute before any tool runs. Use to approve, deny, or modify tool calls.
**Example (prompt-based):**
```json
{
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "prompt",
"prompt": "Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'."
}
]
}
]
}
```
**Output for PreToolUse:**
```json
{
"hookSpecificOutput": {
"permissionDecision": "allow|deny|ask",
"updatedInput": {"field": "modified_value"}
},
"systemMessage": "Explanation for Claude"
}
```
### PostToolUse
Execute after tool completes. Use to react to results, provide feedback, or log.
**Example:**
```json
{
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "prompt",
"prompt": "Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback."
}
]
}
]
}
```
**Output behavior:**
- Exit 0: stdout shown in transcript
- Exit 2: stderr fed back to Claude
- systemMessage included in context
### Stop
Execute when main agent considers stopping. Use to validate completeness.
**Example:**
```json
{
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue."
}
]
}
]
}
```
**Decision output:**
```json
{
"decision": "approve|block",
"reason": "Explanation",
"systemMessage": "Additional context"
}
```
### SubagentStop
Execute when subagent considers stopping. Use to ensure subagent completed its task.
Similar to Stop hook, but for subagents.
### UserPromptSubmit
Execute when user submits a prompt. Use to add context, validate, or block prompts.
**Example:**
```json
{
"UserPromptSubmit": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings."
}
]
}
]
}
```
### SessionStart
Execute when Claude Code session begins. Use to load context and set environment.
**Example:**
```json
{
"SessionStart": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
}
]
}
]
}
```
**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`:
```bash
echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
```
See `examples/load-context.sh` for complete example.
### SessionEnd
Execute when session ends. Use for cleanup, logging, and state preservation.
### PreCompact
Execute before context compaction. Use to add critical information to preserve.
### Notification
Execute when Claude sends notifications. Use to react to user notifications.
## Hook Output Format
### Standard Output (All Hooks)
```json
{
"continue": true,
"suppressOutput": false,
"systemMessage": "Message for Claude"
}
```
- `continue`: If false, halt processing (default true)
- `suppressOutput`: Hide output from transcript (default false)
- `systemMessage`: Message shown to Claude
### Exit Codes
- `0` - Success (stdout shown in transcript)
- `2` - Blocking error (stderr fed back to Claude)
- Other - Non-blocking error
## Hook Input Format
All hooks receive JSON via stdin with common fields:
```json
{
"session_id": "abc123",
"transcript_path": "/path/to/transcript.txt",
"cwd": "/current/working/dir",
"permission_mode": "ask|allow",
"hook_event_name": "PreToolUse"
}
```
**Event-specific fields:**
- **PreToolUse/PostToolUse:** `tool_name`, `tool_input`, `tool_result`
- **UserPromptSubmit:** `user_prompt`
- **Stop/SubagentStop:** `reason`
Access fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc.
## Environment Variables
Available in all command hooks:
- `$CLAUDE_PROJECT_DIR` - Project root path
- `$CLAUDE_PLUGIN_ROOT` - Plugin directory (use for portable paths)
- `$CLAUDE_ENV_FILE` - SessionStart only: persist env vars here
- `$CLAUDE_CODE_REMOTE` - Set if running in remote context
**Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:**
```json
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
}
```
## Plugin Hook Configuration
In plugins, define hooks in `hooks/hooks.json`:
```json
{
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "prompt",
"prompt": "Validate file write safety"
}
]
}
],
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Verify task completion"
}
]
}
],
"SessionStart": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh",
"timeout": 10
}
]
}
]
}
```
Plugin hooks merge with user's hooks and run in parallel.
## Matchers
### Tool Name Matching
**Exact match:**
```json
"matcher": "Write"
```
**Multiple tools:**
```json
"matcher": "Read|Write|Edit"
```
**Wildcard (all tools):**
```json
"matcher": "*"
```
**Regex patterns:**
```json
"matcher": "mcp__.*__delete.*" // All MCP delete tools
```
**Note:** Matchers are case-sensitive.
### Common Patterns
```json
// All MCP tools
"matcher": "mcp__.*"
// Specific plugin's MCP tools
"matcher": "mcp__plugin_asana_.*"
// All file operations
"matcher": "Read|Write|Edit"
// Bash commands only
"matcher": "Bash"
```
## Security Best Practices
### Input Validation
Always validate inputs in command hooks:
```bash
#!/bin/bash
set -euo pipefail
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
# Validate tool name format
if [[ ! "$tool_name" =~ ^[a-zA-Z0-9_]+$ ]]; then
echo '{"decision": "deny", "reason": "Invalid tool name"}' >&2
exit 2
fi
```
### Path Safety
Check for path traversal and sensitive files:
```bash
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
# Deny path traversal
if [[ "$file_path" == *".."* ]]; then
echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2
exit 2
fi
# Deny sensitive files
if [[ "$file_path" == *".env"* ]]; then
echo '{"decision": "deny", "reason": "Sensitive file"}' >&2
exit 2
fi
```
See `examples/validate-write.sh` and `examples/validate-bash.sh` for complete examples.
### Quote All Variables
```bash
# GOOD: Quoted
echo "$file_path"
cd "$CLAUDE_PROJECT_DIR"
# BAD: Unquoted (injection risk)
echo $file_path
cd $CLAUDE_PROJECT_DIR
```
### Set Appropriate Timeouts
```json
{
"type": "command",
"command": "bash script.sh",
"timeout": 10
}
```
**Defaults:** Command hooks (60s), Prompt hooks (30s)
## Performance Considerations
### Parallel Execution
All matching hooks run **in parallel**:
```json
{
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{"type": "command", "command": "check1.sh"}, // Parallel
{"type": "command", "command": "check2.sh"}, // Parallel
{"type": "prompt", "prompt": "Validate..."} // Parallel
]
}
]
}
```
**Design implications:**
- Hooks don't see each other's output
- Non-deterministic ordering
- Design for independence
### Optimization
1. Use command hooks for quick deterministic checks
2. Use prompt hooks for complex reasoning
3. Cache validation results in temp files
4. Minimize I/O in hot paths
## Temporarily Active Hooks
Create hooks that activate conditionally by checking for a flag file or configuration:
**Pattern: Flag file activation**
```bash
#!/bin/bash
# Only active when flag file exists
FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-strict-validation"
if [ ! -f "$FLAG_FILE" ]; then
# Flag not present, skip validation
exit 0
fi
# Flag present, run validation
input=$(cat)
# ... validation logic ...
```
**Pattern: Configuration-based activation**
```bash
#!/bin/bash
# Check configuration for activation
CONFIG_FILE="$CLAUDE_PROJECT_DIR/.claude/plugin-config.json"
if [ -f "$CONFIG_FILE" ]; then
enabled=$(jq -r '.strictMode // false' "$CONFIG_FILE")
if [ "$enabled" != "true" ]; then
exit 0 # Not enabled, skip
fi
fi
# Enabled, run hook logic
input=$(cat)
# ... hook logic ...
```
**Use cases:**
- Enable strict validation only when needed
- Temporary debugging hooks
- Project-specific hook behavior
- Feature flags for hooks
**Best practice:** Document activation mechanism in plugin README so users know how to enable/disable temporary hooks.
## Hook Lifecycle and Limitations
### Hooks Load at Session Start
**Important:** Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code.
**Cannot hot-swap hooks:**
- Editing `hooks/hooks.json` won't affect current session
- Adding new hook scripts won't be recognized
- Changing hook commands/prompts won't update
- Must restart Claude Code: exit and run `claude` again
**To test hook changes:**
1. Edit hook configuration or scripts
2. Exit Claude Code session
3. Restart: `claude` or `cc`
4. New hook configuration loads
5. Test hooks with `claude --debug`
### Hook Validation at Startup
Hooks are validated when Claude Code starts:
- Invalid JSON in hooks.json causes loading failure
- Missing scripts cause warnings
- Syntax errors reported in debug mode
Use `/hooks` command to review loaded hooks in current session.
## Debugging Hooks
### Enable Debug Mode
```bash
claude --debug
```
Look for hook registration, execution logs, input/output JSON, and timing information.
### Test Hook Scripts
Test command hooks directly:
```bash
echo '{"tool_name": "Write", "tool_input": {"file_path": "/test"}}' | \
bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh
echo "Exit code: $?"
```
### Validate JSON Output
Ensure hooks output valid JSON:
```bash
output=$(./your-hook.sh < test-input.json)
echo "$output" | jq .
```
## Quick Reference
### Hook Events Summary
| Event | When | Use For |
|-------|------|---------|
| PreToolUse | Before tool | Validation, modification |
| PostToolUse | After tool | Feedback, logging |
| UserPromptSubmit | User input | Context, validation |
| Stop | Agent stopping | Completeness check |
| SubagentStop | Subagent done | Task validation |
| SessionStart | Session begins | Context loading |
| SessionEnd | Session ends | Cleanup, logging |
| PreCompact | Before compact | Preserve context |
| Notification | User notified | Logging, reactions |
### Best Practices
**DO:**
- ✅ Use prompt-based hooks for complex logic
- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portability
- ✅ Validate all inputs in command hooks
- ✅ Quote all bash variables
- ✅ Set appropriate timeouts
- ✅ Return structured JSON output
- ✅ Test hooks thoroughly
**DON'T:**
- ❌ Use hardcoded paths
- ❌ Trust user input without validation
- ❌ Create long-running hooks
- ❌ Rely on hook execution order
- ❌ Modify global state unpredictably
- ❌ Log sensitive information
## Additional Resources
### Reference Files
For detailed patterns and advanced techniques, consult:
- **`references/patterns.md`** - Common hook patterns (8+ proven patterns)
- **`references/migration.md`** - Migrating from basic to advanced hooks
- **`references/advanced.md`** - Advanced use cases and techniques
### Example Hook Scripts
Working examples in `examples/`:
- **`validate-write.sh`** - File write validation example
- **`validate-bash.sh`** - Bash command validation example
- **`load-context.sh`** - SessionStart context loading example
### Utility Scripts
Development tools in `scripts/`:
- **`validate-hook-schema.sh`** - Validate hooks.json structure and syntax
- **`test-hook.sh`** - Test hooks with sample input before deployment
- **`hook-linter.sh`** - Check hook scripts for common issues and best practices
### External Resources
- **Official Docs**: https://docs.claude.com/en/docs/claude-code/hooks
- **Examples**: See security-guidance plugin in marketplace
- **Testing**: Use `claude --debug` for detailed logs
- **Validation**: Use `jq` to validate hook JSON output
## Implementation Workflow
To implement hooks in a plugin:
1. Identify events to hook into (PreToolUse, Stop, SessionStart, etc.)
2. Decide between prompt-based (flexible) or command (deterministic) hooks
3. Write hook configuration in `hooks/hooks.json`
4. For command hooks, create hook scripts
5. Use ${CLAUDE_PLUGIN_ROOT} for all file references
6. Validate configuration with `scripts/validate-hook-schema.sh hooks/hooks.json`
7. Test hooks with `scripts/test-hook.sh` before deployment
8. Test in Claude Code with `claude --debug`
9. Document hooks in plugin README
Focus on prompt-based hooks for most use cases. Reserve command hooks for performance-critical or deterministic checks.

55
skills/external/plugin-dev-hook-development/examples/load-context.sh vendored Executable file
View File

@@ -0,0 +1,55 @@
#!/bin/bash
# Example SessionStart hook for loading project context
# This script detects project type and sets environment variables
set -euo pipefail
# Navigate to project directory
cd "$CLAUDE_PROJECT_DIR" || exit 1
echo "Loading project context..."
# Detect project type and set environment
if [ -f "package.json" ]; then
echo "📦 Node.js project detected"
echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
# Check if TypeScript
if [ -f "tsconfig.json" ]; then
echo "export USES_TYPESCRIPT=true" >> "$CLAUDE_ENV_FILE"
fi
elif [ -f "Cargo.toml" ]; then
echo "🦀 Rust project detected"
echo "export PROJECT_TYPE=rust" >> "$CLAUDE_ENV_FILE"
elif [ -f "go.mod" ]; then
echo "🐹 Go project detected"
echo "export PROJECT_TYPE=go" >> "$CLAUDE_ENV_FILE"
elif [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
echo "🐍 Python project detected"
echo "export PROJECT_TYPE=python" >> "$CLAUDE_ENV_FILE"
elif [ -f "pom.xml" ]; then
echo "☕ Java (Maven) project detected"
echo "export PROJECT_TYPE=java" >> "$CLAUDE_ENV_FILE"
echo "export BUILD_SYSTEM=maven" >> "$CLAUDE_ENV_FILE"
elif [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
echo "☕ Java/Kotlin (Gradle) project detected"
echo "export PROJECT_TYPE=java" >> "$CLAUDE_ENV_FILE"
echo "export BUILD_SYSTEM=gradle" >> "$CLAUDE_ENV_FILE"
else
echo "❓ Unknown project type"
echo "export PROJECT_TYPE=unknown" >> "$CLAUDE_ENV_FILE"
fi
# Check for CI configuration
if [ -f ".github/workflows" ] || [ -f ".gitlab-ci.yml" ] || [ -f ".circleci/config.yml" ]; then
echo "export HAS_CI=true" >> "$CLAUDE_ENV_FILE"
fi
echo "Project context loaded successfully"
exit 0

43
skills/external/plugin-dev-hook-development/examples/validate-bash.sh vendored Executable file
View File

@@ -0,0 +1,43 @@
#!/bin/bash
# Example PreToolUse hook for validating Bash commands
# This script demonstrates bash command validation patterns
set -euo pipefail
# Read input from stdin
input=$(cat)
# Extract command
command=$(echo "$input" | jq -r '.tool_input.command // empty')
# Validate command exists
if [ -z "$command" ]; then
echo '{"continue": true}' # No command to validate
exit 0
fi
# Check for obviously safe commands (quick approval)
if [[ "$command" =~ ^(ls|pwd|echo|date|whoami)(\s|$) ]]; then
exit 0
fi
# Check for destructive operations
if [[ "$command" == *"rm -rf"* ]] || [[ "$command" == *"rm -fr"* ]]; then
echo '{"hookSpecificOutput": {"permissionDecision": "deny"}, "systemMessage": "Dangerous command detected: rm -rf"}' >&2
exit 2
fi
# Check for other dangerous commands
if [[ "$command" == *"dd if="* ]] || [[ "$command" == *"mkfs"* ]] || [[ "$command" == *"> /dev/"* ]]; then
echo '{"hookSpecificOutput": {"permissionDecision": "deny"}, "systemMessage": "Dangerous system operation detected"}' >&2
exit 2
fi
# Check for privilege escalation
if [[ "$command" == sudo* ]] || [[ "$command" == su* ]]; then
echo '{"hookSpecificOutput": {"permissionDecision": "ask"}, "systemMessage": "Command requires elevated privileges"}' >&2
exit 2
fi
# Approve the operation
exit 0

38
skills/external/plugin-dev-hook-development/examples/validate-write.sh vendored Executable file
View File

@@ -0,0 +1,38 @@
#!/bin/bash
# Example PreToolUse hook for validating Write/Edit operations
# This script demonstrates file write validation patterns
set -euo pipefail
# Read input from stdin
input=$(cat)
# Extract file path and content
file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
# Validate path exists
if [ -z "$file_path" ]; then
echo '{"continue": true}' # No path to validate
exit 0
fi
# Check for path traversal
if [[ "$file_path" == *".."* ]]; then
echo '{"hookSpecificOutput": {"permissionDecision": "deny"}, "systemMessage": "Path traversal detected in: '"$file_path"'"}' >&2
exit 2
fi
# Check for system directories
if [[ "$file_path" == /etc/* ]] || [[ "$file_path" == /sys/* ]] || [[ "$file_path" == /usr/* ]]; then
echo '{"hookSpecificOutput": {"permissionDecision": "deny"}, "systemMessage": "Cannot write to system directory: '"$file_path"'"}' >&2
exit 2
fi
# Check for sensitive files
if [[ "$file_path" == *.env ]] || [[ "$file_path" == *secret* ]] || [[ "$file_path" == *credentials* ]]; then
echo '{"hookSpecificOutput": {"permissionDecision": "ask"}, "systemMessage": "Writing to potentially sensitive file: '"$file_path"'"}' >&2
exit 2
fi
# Approve the operation
exit 0

479
skills/external/plugin-dev-hook-development/references/advanced.md vendored Normal file
View File

@@ -0,0 +1,479 @@
# Advanced Hook Use Cases
This reference covers advanced hook patterns and techniques for sophisticated automation workflows.
## Multi-Stage Validation
Combine command and prompt hooks for layered validation:
```json
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh",
"timeout": 5
},
{
"type": "prompt",
"prompt": "Deep analysis of bash command: $TOOL_INPUT",
"timeout": 15
}
]
}
]
}
```
**Use case:** Fast deterministic checks followed by intelligent analysis
**Example quick-check.sh:**
```bash
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')
# Immediate approval for safe commands
if [[ "$command" =~ ^(ls|pwd|echo|date|whoami)$ ]]; then
exit 0
fi
# Let prompt hook handle complex cases
exit 0
```
The command hook quickly approves obviously safe commands, while the prompt hook analyzes everything else.
## Conditional Hook Execution
Execute hooks based on environment or context:
```bash
#!/bin/bash
# Only run in CI environment
if [ -z "$CI" ]; then
echo '{"continue": true}' # Skip in non-CI
exit 0
fi
# Run validation logic in CI
input=$(cat)
# ... validation code ...
```
**Use cases:**
- Different behavior in CI vs local development
- Project-specific validation
- User-specific rules
**Example: Skip certain checks for trusted users:**
```bash
#!/bin/bash
# Skip detailed checks for admin users
if [ "$USER" = "admin" ]; then
exit 0
fi
# Full validation for other users
input=$(cat)
# ... validation code ...
```
## Hook Chaining via State
Share state between hooks using temporary files:
```bash
# Hook 1: Analyze and save state
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')
# Analyze command
risk_level=$(calculate_risk "$command")
echo "$risk_level" > /tmp/hook-state-$$
exit 0
```
```bash
# Hook 2: Use saved state
#!/bin/bash
risk_level=$(cat /tmp/hook-state-$$ 2>/dev/null || echo "unknown")
if [ "$risk_level" = "high" ]; then
echo "High risk operation detected" >&2
exit 2
fi
```
**Important:** This only works for sequential hook events (e.g., PreToolUse then PostToolUse), not parallel hooks.
## Dynamic Hook Configuration
Modify hook behavior based on project configuration:
```bash
#!/bin/bash
cd "$CLAUDE_PROJECT_DIR" || exit 1
# Read project-specific config
if [ -f ".claude-hooks-config.json" ]; then
strict_mode=$(jq -r '.strict_mode' .claude-hooks-config.json)
if [ "$strict_mode" = "true" ]; then
# Apply strict validation
# ...
else
# Apply lenient validation
# ...
fi
fi
```
**Example .claude-hooks-config.json:**
```json
{
"strict_mode": true,
"allowed_commands": ["ls", "pwd", "grep"],
"forbidden_paths": ["/etc", "/sys"]
}
```
## Context-Aware Prompt Hooks
Use transcript and session context for intelligent decisions:
```json
{
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Review the full transcript at $TRANSCRIPT_PATH. Check: 1) Were tests run after code changes? 2) Did the build succeed? 3) Were all user questions answered? 4) Is there any unfinished work? Return 'approve' only if everything is complete."
}
]
}
]
}
```
The LLM can read the transcript file and make context-aware decisions.
## Performance Optimization
### Caching Validation Results
```bash
#!/bin/bash
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
cache_key=$(echo -n "$file_path" | md5sum | cut -d' ' -f1)
cache_file="/tmp/hook-cache-$cache_key"
# Check cache
if [ -f "$cache_file" ]; then
cache_age=$(($(date +%s) - $(stat -f%m "$cache_file" 2>/dev/null || stat -c%Y "$cache_file")))
if [ "$cache_age" -lt 300 ]; then # 5 minute cache
cat "$cache_file"
exit 0
fi
fi
# Perform validation
result='{"decision": "approve"}'
# Cache result
echo "$result" > "$cache_file"
echo "$result"
```
### Parallel Execution Optimization
Since hooks run in parallel, design them to be independent:
```json
{
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "bash check-size.sh", // Independent
"timeout": 2
},
{
"type": "command",
"command": "bash check-path.sh", // Independent
"timeout": 2
},
{
"type": "prompt",
"prompt": "Check content safety", // Independent
"timeout": 10
}
]
}
]
}
```
All three hooks run simultaneously, reducing total latency.
## Cross-Event Workflows
Coordinate hooks across different events:
**SessionStart - Set up tracking:**
```bash
#!/bin/bash
# Initialize session tracking
echo "0" > /tmp/test-count-$$
echo "0" > /tmp/build-count-$$
```
**PostToolUse - Track events:**
```bash
#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
if [ "$tool_name" = "Bash" ]; then
command=$(echo "$input" | jq -r '.tool_result')
if [[ "$command" == *"test"* ]]; then
count=$(cat /tmp/test-count-$$ 2>/dev/null || echo "0")
echo $((count + 1)) > /tmp/test-count-$$
fi
fi
```
**Stop - Verify based on tracking:**
```bash
#!/bin/bash
test_count=$(cat /tmp/test-count-$$ 2>/dev/null || echo "0")
if [ "$test_count" -eq 0 ]; then
echo '{"decision": "block", "reason": "No tests were run"}' >&2
exit 2
fi
```
## Integration with External Systems
### Slack Notifications
```bash
#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
decision="blocked"
# Send notification to Slack
curl -X POST "$SLACK_WEBHOOK" \
-H 'Content-Type: application/json' \
-d "{\"text\": \"Hook ${decision} ${tool_name} operation\"}" \
2>/dev/null
echo '{"decision": "deny"}' >&2
exit 2
```
### Database Logging
```bash
#!/bin/bash
input=$(cat)
# Log to database
psql "$DATABASE_URL" -c "INSERT INTO hook_logs (event, data) VALUES ('PreToolUse', '$input')" \
2>/dev/null
exit 0
```
### Metrics Collection
```bash
#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
# Send metrics to monitoring system
echo "hook.pretooluse.${tool_name}:1|c" | nc -u -w1 statsd.local 8125
exit 0
```
## Security Patterns
### Rate Limiting
```bash
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')
# Track command frequency
rate_file="/tmp/hook-rate-$$"
current_minute=$(date +%Y%m%d%H%M)
if [ -f "$rate_file" ]; then
last_minute=$(head -1 "$rate_file")
count=$(tail -1 "$rate_file")
if [ "$current_minute" = "$last_minute" ]; then
if [ "$count" -gt 10 ]; then
echo '{"decision": "deny", "reason": "Rate limit exceeded"}' >&2
exit 2
fi
count=$((count + 1))
else
count=1
fi
else
count=1
fi
echo "$current_minute" > "$rate_file"
echo "$count" >> "$rate_file"
exit 0
```
### Audit Logging
```bash
#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
timestamp=$(date -Iseconds)
# Append to audit log
echo "$timestamp | $USER | $tool_name | $input" >> ~/.claude/audit.log
exit 0
```
### Secret Detection
```bash
#!/bin/bash
input=$(cat)
content=$(echo "$input" | jq -r '.tool_input.content')
# Check for common secret patterns
if echo "$content" | grep -qE "(api[_-]?key|password|secret|token).{0,20}['\"]?[A-Za-z0-9]{20,}"; then
echo '{"decision": "deny", "reason": "Potential secret detected in content"}' >&2
exit 2
fi
exit 0
```
## Testing Advanced Hooks
### Unit Testing Hook Scripts
```bash
# test-hook.sh
#!/bin/bash
# Test 1: Approve safe command
result=$(echo '{"tool_input": {"command": "ls"}}' | bash validate-bash.sh)
if [ $? -eq 0 ]; then
echo "✓ Test 1 passed"
else
echo "✗ Test 1 failed"
fi
# Test 2: Block dangerous command
result=$(echo '{"tool_input": {"command": "rm -rf /"}}' | bash validate-bash.sh)
if [ $? -eq 2 ]; then
echo "✓ Test 2 passed"
else
echo "✗ Test 2 failed"
fi
```
### Integration Testing
Create test scenarios that exercise the full hook workflow:
```bash
# integration-test.sh
#!/bin/bash
# Set up test environment
export CLAUDE_PROJECT_DIR="/tmp/test-project"
export CLAUDE_PLUGIN_ROOT="$(pwd)"
mkdir -p "$CLAUDE_PROJECT_DIR"
# Test SessionStart hook
echo '{}' | bash hooks/session-start.sh
if [ -f "/tmp/session-initialized" ]; then
echo "✓ SessionStart hook works"
else
echo "✗ SessionStart hook failed"
fi
# Clean up
rm -rf "$CLAUDE_PROJECT_DIR"
```
## Best Practices for Advanced Hooks
1. **Keep hooks independent**: Don't rely on execution order
2. **Use timeouts**: Set appropriate limits for each hook type
3. **Handle errors gracefully**: Provide clear error messages
4. **Document complexity**: Explain advanced patterns in README
5. **Test thoroughly**: Cover edge cases and failure modes
6. **Monitor performance**: Track hook execution time
7. **Version configuration**: Use version control for hook configs
8. **Provide escape hatches**: Allow users to bypass hooks when needed
## Common Pitfalls
### ❌ Assuming Hook Order
```bash
# BAD: Assumes hooks run in specific order
# Hook 1 saves state, Hook 2 reads it
# This can fail because hooks run in parallel!
```
### ❌ Long-Running Hooks
```bash
# BAD: Hook takes 2 minutes to run
sleep 120
# This will timeout and block the workflow
```
### ❌ Uncaught Exceptions
```bash
# BAD: Script crashes on unexpected input
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
cat "$file_path" # Fails if file doesn't exist
```
### ✅ Proper Error Handling
```bash
# GOOD: Handles errors gracefully
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
if [ ! -f "$file_path" ]; then
echo '{"continue": true, "systemMessage": "File not found, skipping check"}' >&2
exit 0
fi
```
## Conclusion
Advanced hook patterns enable sophisticated automation while maintaining reliability and performance. Use these techniques when basic hooks are insufficient, but always prioritize simplicity and maintainability.

369
skills/external/plugin-dev-hook-development/references/migration.md vendored Normal file
View File

@@ -0,0 +1,369 @@
# Migrating from Basic to Advanced Hooks
This guide shows how to migrate from basic command hooks to advanced prompt-based hooks for better maintainability and flexibility.
## Why Migrate?
Prompt-based hooks offer several advantages:
- **Natural language reasoning**: LLM understands context and intent
- **Better edge case handling**: Adapts to unexpected scenarios
- **No bash scripting required**: Simpler to write and maintain
- **More flexible validation**: Can handle complex logic without coding
## Migration Example: Bash Command Validation
### Before (Basic Command Hook)
**Configuration:**
```json
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash validate-bash.sh"
}
]
}
]
}
```
**Script (validate-bash.sh):**
```bash
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')
# Hard-coded validation logic
if [[ "$command" == *"rm -rf"* ]]; then
echo "Dangerous command detected" >&2
exit 2
fi
```
**Problems:**
- Only checks for exact "rm -rf" pattern
- Doesn't catch variations like `rm -fr` or `rm -r -f`
- Misses other dangerous commands (`dd`, `mkfs`, etc.)
- No context awareness
- Requires bash scripting knowledge
### After (Advanced Prompt Hook)
**Configuration:**
```json
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "Command: $TOOL_INPUT.command. Analyze for: 1) Destructive operations (rm -rf, dd, mkfs, etc) 2) Privilege escalation (sudo) 3) Network operations without user consent. Return 'approve' or 'deny' with explanation.",
"timeout": 15
}
]
}
]
}
```
**Benefits:**
- Catches all variations and patterns
- Understands intent, not just literal strings
- No script file needed
- Easy to extend with new criteria
- Context-aware decisions
- Natural language explanation in denial
## Migration Example: File Write Validation
### Before (Basic Command Hook)
**Configuration:**
```json
{
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "bash validate-write.sh"
}
]
}
]
}
```
**Script (validate-write.sh):**
```bash
#!/bin/bash
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
# Check for path traversal
if [[ "$file_path" == *".."* ]]; then
echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2
exit 2
fi
# Check for system paths
if [[ "$file_path" == "/etc/"* ]] || [[ "$file_path" == "/sys/"* ]]; then
echo '{"decision": "deny", "reason": "System file"}' >&2
exit 2
fi
```
**Problems:**
- Hard-coded path patterns
- Doesn't understand symlinks
- Missing edge cases (e.g., `/etc` vs `/etc/`)
- No consideration of file content
### After (Advanced Prompt Hook)
**Configuration:**
```json
{
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "prompt",
"prompt": "File path: $TOOL_INPUT.file_path. Content preview: $TOOL_INPUT.content (first 200 chars). Verify: 1) Not system directories (/etc, /sys, /usr) 2) Not credentials (.env, tokens, secrets) 3) No path traversal 4) Content doesn't expose secrets. Return 'approve' or 'deny'."
}
]
}
]
}
```
**Benefits:**
- Context-aware (considers content too)
- Handles symlinks and edge cases
- Natural understanding of "system directories"
- Can detect secrets in content
- Easy to extend criteria
## When to Keep Command Hooks
Command hooks still have their place:
### 1. Deterministic Performance Checks
```bash
#!/bin/bash
# Check file size quickly
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
size=$(stat -f%z "$file_path" 2>/dev/null || stat -c%s "$file_path" 2>/dev/null)
if [ "$size" -gt 10000000 ]; then
echo '{"decision": "deny", "reason": "File too large"}' >&2
exit 2
fi
```
**Use command hooks when:** Validation is purely mathematical or deterministic.
### 2. External Tool Integration
```bash
#!/bin/bash
# Run security scanner
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
scan_result=$(security-scanner "$file_path")
if [ "$?" -ne 0 ]; then
echo "Security scan failed: $scan_result" >&2
exit 2
fi
```
**Use command hooks when:** Integrating with external tools that provide yes/no answers.
### 3. Very Fast Checks (< 50ms)
```bash
#!/bin/bash
# Quick regex check
command=$(echo "$input" | jq -r '.tool_input.command')
if [[ "$command" =~ ^(ls|pwd|echo)$ ]]; then
exit 0 # Safe commands
fi
```
**Use command hooks when:** Performance is critical and logic is simple.
## Hybrid Approach
Combine both for multi-stage validation:
```json
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh",
"timeout": 5
},
{
"type": "prompt",
"prompt": "Deep analysis of bash command: $TOOL_INPUT",
"timeout": 15
}
]
}
]
}
```
The command hook does fast deterministic checks, while the prompt hook handles complex reasoning.
## Migration Checklist
When migrating hooks:
- [ ] Identify the validation logic in the command hook
- [ ] Convert hard-coded patterns to natural language criteria
- [ ] Test with edge cases the old hook missed
- [ ] Verify LLM understands the intent
- [ ] Set appropriate timeout (usually 15-30s for prompt hooks)
- [ ] Document the new hook in README
- [ ] Remove or archive old script files
## Migration Tips
1. **Start with one hook**: Don't migrate everything at once
2. **Test thoroughly**: Verify prompt hook catches what command hook caught
3. **Look for improvements**: Use migration as opportunity to enhance validation
4. **Keep scripts for reference**: Archive old scripts in case you need to reference the logic
5. **Document reasoning**: Explain why prompt hook is better in README
## Complete Migration Example
### Original Plugin Structure
```
my-plugin/
├── .claude-plugin/plugin.json
├── hooks/hooks.json
└── scripts/
├── validate-bash.sh
├── validate-write.sh
└── check-tests.sh
```
### After Migration
```
my-plugin/
├── .claude-plugin/plugin.json
├── hooks/hooks.json # Now uses prompt hooks
└── scripts/ # Archive or delete
└── archive/
├── validate-bash.sh
├── validate-write.sh
└── check-tests.sh
```
### Updated hooks.json
```json
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "Validate bash command safety: destructive ops, privilege escalation, network access"
}
]
},
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "prompt",
"prompt": "Validate file write safety: system paths, credentials, path traversal, content secrets"
}
]
}
],
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Verify tests were run if code was modified"
}
]
}
]
}
```
**Result:** Simpler, more maintainable, more powerful.
## Common Migration Patterns
### Pattern: String Contains → Natural Language
**Before:**
```bash
if [[ "$command" == *"sudo"* ]]; then
echo "Privilege escalation" >&2
exit 2
fi
```
**After:**
```
"Check for privilege escalation (sudo, su, etc)"
```
### Pattern: Regex → Intent
**Before:**
```bash
if [[ "$file" =~ \.(env|secret|key|token)$ ]]; then
echo "Credential file" >&2
exit 2
fi
```
**After:**
```
"Verify not writing to credential files (.env, secrets, keys, tokens)"
```
### Pattern: Multiple Conditions → Criteria List
**Before:**
```bash
if [ condition1 ] || [ condition2 ] || [ condition3 ]; then
echo "Invalid" >&2
exit 2
fi
```
**After:**
```
"Check: 1) condition1 2) condition2 3) condition3. Deny if any fail."
```
## Conclusion
Migrating to prompt-based hooks makes plugins more maintainable, flexible, and powerful. Reserve command hooks for deterministic checks and external tool integration.

346
skills/external/plugin-dev-hook-development/references/patterns.md vendored Normal file
View File

@@ -0,0 +1,346 @@
# Common Hook Patterns
This reference provides common, proven patterns for implementing Claude Code hooks. Use these patterns as starting points for typical hook use cases.
## Pattern 1: Security Validation
Block dangerous file writes using prompt-based hooks:
```json
{
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "prompt",
"prompt": "File path: $TOOL_INPUT.file_path. Verify: 1) Not in /etc or system directories 2) Not .env or credentials 3) Path doesn't contain '..' traversal. Return 'approve' or 'deny'."
}
]
}
]
}
```
**Use for:** Preventing writes to sensitive files or system directories.
## Pattern 2: Test Enforcement
Ensure tests run before stopping:
```json
{
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Review transcript. If code was modified (Write/Edit tools used), verify tests were executed. If no tests were run, block with reason 'Tests must be run after code changes'."
}
]
}
]
}
```
**Use for:** Enforcing quality standards and preventing incomplete work.
## Pattern 3: Context Loading
Load project-specific context at session start:
```json
{
"SessionStart": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
}
]
}
]
}
```
**Example script (load-context.sh):**
```bash
#!/bin/bash
cd "$CLAUDE_PROJECT_DIR" || exit 1
# Detect project type
if [ -f "package.json" ]; then
echo "📦 Node.js project detected"
echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
elif [ -f "Cargo.toml" ]; then
echo "🦀 Rust project detected"
echo "export PROJECT_TYPE=rust" >> "$CLAUDE_ENV_FILE"
fi
```
**Use for:** Automatically detecting and configuring project-specific settings.
## Pattern 4: Notification Logging
Log all notifications for audit or analysis:
```json
{
"Notification": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-notification.sh"
}
]
}
]
}
```
**Use for:** Tracking user notifications or integration with external logging systems.
## Pattern 5: MCP Tool Monitoring
Monitor and validate MCP tool usage:
```json
{
"PreToolUse": [
{
"matcher": "mcp__.*__delete.*",
"hooks": [
{
"type": "prompt",
"prompt": "Deletion operation detected. Verify: Is this deletion intentional? Can it be undone? Are there backups? Return 'approve' only if safe."
}
]
}
]
}
```
**Use for:** Protecting against destructive MCP operations.
## Pattern 6: Build Verification
Ensure project builds after code changes:
```json
{
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Check if code was modified. If Write/Edit tools were used, verify the project was built (npm run build, cargo build, etc). If not built, block and request build."
}
]
}
]
}
```
**Use for:** Catching build errors before committing or stopping work.
## Pattern 7: Permission Confirmation
Ask user before dangerous operations:
```json
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "Command: $TOOL_INPUT.command. If command contains 'rm', 'delete', 'drop', or other destructive operations, return 'ask' to confirm with user. Otherwise 'approve'."
}
]
}
]
}
```
**Use for:** User confirmation on potentially destructive commands.
## Pattern 8: Code Quality Checks
Run linters or formatters on file edits:
```json
{
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-quality.sh"
}
]
}
]
}
```
**Example script (check-quality.sh):**
```bash
#!/bin/bash
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
# Run linter if applicable
if [[ "$file_path" == *.js ]] || [[ "$file_path" == *.ts ]]; then
npx eslint "$file_path" 2>&1 || true
fi
```
**Use for:** Automatic code quality enforcement.
## Pattern Combinations
Combine multiple patterns for comprehensive protection:
```json
{
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "prompt",
"prompt": "Validate file write safety"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "Validate bash command safety"
}
]
}
],
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Verify tests run and build succeeded"
}
]
}
],
"SessionStart": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
}
]
}
]
}
```
This provides multi-layered protection and automation.
## Pattern 9: Temporarily Active Hooks
Create hooks that only run when explicitly enabled via flag files:
```bash
#!/bin/bash
# Hook only active when flag file exists
FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-security-scan"
if [ ! -f "$FLAG_FILE" ]; then
# Quick exit when disabled
exit 0
fi
# Flag present, run validation
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
# Run security scan
security-scanner "$file_path"
```
**Activation:**
```bash
# Enable the hook
touch .enable-security-scan
# Disable the hook
rm .enable-security-scan
```
**Use for:**
- Temporary debugging hooks
- Feature flags for development
- Project-specific validation that's opt-in
- Performance-intensive checks only when needed
**Note:** Must restart Claude Code after creating/removing flag files for hooks to recognize changes.
## Pattern 10: Configuration-Driven Hooks
Use JSON configuration to control hook behavior:
```bash
#!/bin/bash
CONFIG_FILE="$CLAUDE_PROJECT_DIR/.claude/my-plugin.local.json"
# Read configuration
if [ -f "$CONFIG_FILE" ]; then
strict_mode=$(jq -r '.strictMode // false' "$CONFIG_FILE")
max_file_size=$(jq -r '.maxFileSize // 1000000' "$CONFIG_FILE")
else
# Defaults
strict_mode=false
max_file_size=1000000
fi
# Skip if not in strict mode
if [ "$strict_mode" != "true" ]; then
exit 0
fi
# Apply configured limits
input=$(cat)
file_size=$(echo "$input" | jq -r '.tool_input.content | length')
if [ "$file_size" -gt "$max_file_size" ]; then
echo '{"decision": "deny", "reason": "File exceeds configured size limit"}' >&2
exit 2
fi
```
**Configuration file (.claude/my-plugin.local.json):**
```json
{
"strictMode": true,
"maxFileSize": 500000,
"allowedPaths": ["/tmp", "/home/user/projects"]
}
```
**Use for:**
- User-configurable hook behavior
- Per-project settings
- Team-specific rules
- Dynamic validation criteria

164
skills/external/plugin-dev-hook-development/scripts/README.md vendored Normal file
View File

@@ -0,0 +1,164 @@
# Hook Development Utility Scripts
These scripts help validate, test, and lint hook implementations before deployment.
## validate-hook-schema.sh
Validates `hooks.json` configuration files for correct structure and common issues.
**Usage:**
```bash
./validate-hook-schema.sh path/to/hooks.json
```
**Checks:**
- Valid JSON syntax
- Required fields present
- Valid hook event names
- Proper hook types (command/prompt)
- Timeout values in valid ranges
- Hardcoded path detection
- Prompt hook event compatibility
**Example:**
```bash
cd my-plugin
./validate-hook-schema.sh hooks/hooks.json
```
## test-hook.sh
Tests individual hook scripts with sample input before deploying to Claude Code.
**Usage:**
```bash
./test-hook.sh [options] <hook-script> <test-input.json>
```
**Options:**
- `-v, --verbose` - Show detailed execution information
- `-t, --timeout N` - Set timeout in seconds (default: 60)
- `--create-sample <event-type>` - Generate sample test input
**Example:**
```bash
# Create sample test input
./test-hook.sh --create-sample PreToolUse > test-input.json
# Test a hook script
./test-hook.sh my-hook.sh test-input.json
# Test with verbose output and custom timeout
./test-hook.sh -v -t 30 my-hook.sh test-input.json
```
**Features:**
- Sets up proper environment variables (CLAUDE_PROJECT_DIR, CLAUDE_PLUGIN_ROOT)
- Measures execution time
- Validates output JSON
- Shows exit codes and their meanings
- Captures environment file output
## hook-linter.sh
Checks hook scripts for common issues and best practices violations.
**Usage:**
```bash
./hook-linter.sh <hook-script.sh> [hook-script2.sh ...]
```
**Checks:**
- Shebang presence
- `set -euo pipefail` usage
- Stdin input reading
- Proper error handling
- Variable quoting (injection prevention)
- Exit code usage
- Hardcoded paths
- Long-running code detection
- Error output to stderr
- Input validation
**Example:**
```bash
# Lint single script
./hook-linter.sh ../examples/validate-write.sh
# Lint multiple scripts
./hook-linter.sh ../examples/*.sh
```
## Typical Workflow
1. **Write your hook script**
```bash
vim my-plugin/scripts/my-hook.sh
```
2. **Lint the script**
```bash
./hook-linter.sh my-plugin/scripts/my-hook.sh
```
3. **Create test input**
```bash
./test-hook.sh --create-sample PreToolUse > test-input.json
# Edit test-input.json as needed
```
4. **Test the hook**
```bash
./test-hook.sh -v my-plugin/scripts/my-hook.sh test-input.json
```
5. **Add to hooks.json**
```bash
# Edit my-plugin/hooks/hooks.json
```
6. **Validate configuration**
```bash
./validate-hook-schema.sh my-plugin/hooks/hooks.json
```
7. **Test in Claude Code**
```bash
claude --debug
```
## Tips
- Always test hooks before deploying to avoid breaking user workflows
- Use verbose mode (`-v`) to debug hook behavior
- Check the linter output for security and best practice issues
- Validate hooks.json after any changes
- Create different test inputs for various scenarios (safe operations, dangerous operations, edge cases)
## Common Issues
### Hook doesn't execute
Check:
- Script has shebang (`#!/bin/bash`)
- Script is executable (`chmod +x`)
- Path in hooks.json is correct (use `${CLAUDE_PLUGIN_ROOT}`)
### Hook times out
- Reduce timeout in hooks.json
- Optimize hook script performance
- Remove long-running operations
### Hook fails silently
- Check exit codes (should be 0 or 2)
- Ensure errors go to stderr (`>&2`)
- Validate JSON output structure
### Injection vulnerabilities
- Always quote variables: `"$variable"`
- Use `set -euo pipefail`
- Validate all input fields
- Run the linter to catch issues

153
skills/external/plugin-dev-hook-development/scripts/hook-linter.sh vendored Executable file
View File

@@ -0,0 +1,153 @@
#!/bin/bash
# Hook Linter
# Checks hook scripts for common issues and best practices
set -euo pipefail
# Usage
if [ $# -eq 0 ]; then
echo "Usage: $0 <hook-script.sh> [hook-script2.sh ...]"
echo ""
echo "Checks hook scripts for:"
echo " - Shebang presence"
echo " - set -euo pipefail usage"
echo " - Input reading from stdin"
echo " - Proper error handling"
echo " - Variable quoting"
echo " - Exit code usage"
echo " - Hardcoded paths"
echo " - Timeout considerations"
exit 1
fi
check_script() {
local script="$1"
local warnings=0
local errors=0
echo "🔍 Linting: $script"
echo ""
if [ ! -f "$script" ]; then
echo "❌ Error: File not found"
return 1
fi
# Check 1: Executable
if [ ! -x "$script" ]; then
echo "⚠️ Not executable (chmod +x $script)"
((warnings++))
fi
# Check 2: Shebang
first_line=$(head -1 "$script")
if [[ ! "$first_line" =~ ^#!/ ]]; then
echo "❌ Missing shebang (#!/bin/bash)"
((errors++))
fi
# Check 3: set -euo pipefail
if ! grep -q "set -euo pipefail" "$script"; then
echo "⚠️ Missing 'set -euo pipefail' (recommended for safety)"
((warnings++))
fi
# Check 4: Reads from stdin
if ! grep -q "cat\|read" "$script"; then
echo "⚠️ Doesn't appear to read input from stdin"
((warnings++))
fi
# Check 5: Uses jq for JSON parsing
if grep -q "tool_input\|tool_name" "$script" && ! grep -q "jq" "$script"; then
echo "⚠️ Parses hook input but doesn't use jq"
((warnings++))
fi
# Check 6: Unquoted variables
if grep -E '\$[A-Za-z_][A-Za-z0-9_]*[^"]' "$script" | grep -v '#' | grep -q .; then
echo "⚠️ Potentially unquoted variables detected (injection risk)"
echo " Always use double quotes: \"\$variable\" not \$variable"
((warnings++))
fi
# Check 7: Hardcoded paths
if grep -E '^[^#]*/home/|^[^#]*/usr/|^[^#]*/opt/' "$script" | grep -q .; then
echo "⚠️ Hardcoded absolute paths detected"
echo " Use \$CLAUDE_PROJECT_DIR or \$CLAUDE_PLUGIN_ROOT"
((warnings++))
fi
# Check 8: Uses CLAUDE_PLUGIN_ROOT
if ! grep -q "CLAUDE_PLUGIN_ROOT\|CLAUDE_PROJECT_DIR" "$script"; then
echo "💡 Tip: Use \$CLAUDE_PLUGIN_ROOT for plugin-relative paths"
fi
# Check 9: Exit codes
if ! grep -q "exit 0\|exit 2" "$script"; then
echo "⚠️ No explicit exit codes (should exit 0 or 2)"
((warnings++))
fi
# Check 10: JSON output for decision hooks
if grep -q "PreToolUse\|Stop" "$script"; then
if ! grep -q "permissionDecision\|decision" "$script"; then
echo "💡 Tip: PreToolUse/Stop hooks should output decision JSON"
fi
fi
# Check 11: Long-running commands
if grep -E 'sleep [0-9]{3,}|while true' "$script" | grep -v '#' | grep -q .; then
echo "⚠️ Potentially long-running code detected"
echo " Hooks should complete quickly (< 60s)"
((warnings++))
fi
# Check 12: Error messages to stderr
if grep -q 'echo.*".*error\|Error\|denied\|Denied' "$script"; then
if ! grep -q '>&2' "$script"; then
echo "⚠️ Error messages should be written to stderr (>&2)"
((warnings++))
fi
fi
# Check 13: Input validation
if ! grep -q "if.*empty\|if.*null\|if.*-z" "$script"; then
echo "💡 Tip: Consider validating input fields aren't empty"
fi
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
if [ $errors -eq 0 ] && [ $warnings -eq 0 ]; then
echo "✅ No issues found"
return 0
elif [ $errors -eq 0 ]; then
echo "⚠️ Found $warnings warning(s)"
return 0
else
echo "❌ Found $errors error(s) and $warnings warning(s)"
return 1
fi
}
echo "🔎 Hook Script Linter"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
total_errors=0
for script in "$@"; do
if ! check_script "$script"; then
((total_errors++))
fi
echo ""
done
if [ $total_errors -eq 0 ]; then
echo "✅ All scripts passed linting"
exit 0
else
echo "❌ $total_errors script(s) had errors"
exit 1
fi

252
skills/external/plugin-dev-hook-development/scripts/test-hook.sh vendored Executable file
View File

@@ -0,0 +1,252 @@
#!/bin/bash
# Hook Testing Helper
# Tests a hook with sample input and shows output
set -euo pipefail
# Usage
show_usage() {
echo "Usage: $0 [options] <hook-script> <test-input.json>"
echo ""
echo "Options:"
echo " -h, --help Show this help message"
echo " -v, --verbose Show detailed execution information"
echo " -t, --timeout N Set timeout in seconds (default: 60)"
echo ""
echo "Examples:"
echo " $0 validate-bash.sh test-input.json"
echo " $0 -v -t 30 validate-write.sh write-input.json"
echo ""
echo "Creates sample test input with:"
echo " $0 --create-sample <event-type>"
exit 0
}
# Create sample input
create_sample() {
event_type="$1"
case "$event_type" in
PreToolUse)
cat <<'EOF'
{
"session_id": "test-session",
"transcript_path": "/tmp/transcript.txt",
"cwd": "/tmp/test-project",
"permission_mode": "ask",
"hook_event_name": "PreToolUse",
"tool_name": "Write",
"tool_input": {
"file_path": "/tmp/test.txt",
"content": "Test content"
}
}
EOF
;;
PostToolUse)
cat <<'EOF'
{
"session_id": "test-session",
"transcript_path": "/tmp/transcript.txt",
"cwd": "/tmp/test-project",
"permission_mode": "ask",
"hook_event_name": "PostToolUse",
"tool_name": "Bash",
"tool_result": "Command executed successfully"
}
EOF
;;
Stop|SubagentStop)
cat <<'EOF'
{
"session_id": "test-session",
"transcript_path": "/tmp/transcript.txt",
"cwd": "/tmp/test-project",
"permission_mode": "ask",
"hook_event_name": "Stop",
"reason": "Task appears complete"
}
EOF
;;
UserPromptSubmit)
cat <<'EOF'
{
"session_id": "test-session",
"transcript_path": "/tmp/transcript.txt",
"cwd": "/tmp/test-project",
"permission_mode": "ask",
"hook_event_name": "UserPromptSubmit",
"user_prompt": "Test user prompt"
}
EOF
;;
SessionStart|SessionEnd)
cat <<'EOF'
{
"session_id": "test-session",
"transcript_path": "/tmp/transcript.txt",
"cwd": "/tmp/test-project",
"permission_mode": "ask",
"hook_event_name": "SessionStart"
}
EOF
;;
*)
echo "Unknown event type: $event_type"
echo "Valid types: PreToolUse, PostToolUse, Stop, SubagentStop, UserPromptSubmit, SessionStart, SessionEnd"
exit 1
;;
esac
}
# Parse arguments
VERBOSE=false
TIMEOUT=60
while [ $# -gt 0 ]; do
case "$1" in
-h|--help)
show_usage
;;
-v|--verbose)
VERBOSE=true
shift
;;
-t|--timeout)
TIMEOUT="$2"
shift 2
;;
--create-sample)
create_sample "$2"
exit 0
;;
*)
break
;;
esac
done
if [ $# -ne 2 ]; then
echo "Error: Missing required arguments"
echo ""
show_usage
fi
HOOK_SCRIPT="$1"
TEST_INPUT="$2"
# Validate inputs
if [ ! -f "$HOOK_SCRIPT" ]; then
echo "❌ Error: Hook script not found: $HOOK_SCRIPT"
exit 1
fi
if [ ! -x "$HOOK_SCRIPT" ]; then
echo "⚠️ Warning: Hook script is not executable. Attempting to run with bash..."
HOOK_SCRIPT="bash $HOOK_SCRIPT"
fi
if [ ! -f "$TEST_INPUT" ]; then
echo "❌ Error: Test input not found: $TEST_INPUT"
exit 1
fi
# Validate test input JSON
if ! jq empty "$TEST_INPUT" 2>/dev/null; then
echo "❌ Error: Test input is not valid JSON"
exit 1
fi
echo "🧪 Testing hook: $HOOK_SCRIPT"
echo "📥 Input: $TEST_INPUT"
echo ""
if [ "$VERBOSE" = true ]; then
echo "Input JSON:"
jq . "$TEST_INPUT"
echo ""
fi
# Set up environment
export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-/tmp/test-project}"
export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(pwd)}"
export CLAUDE_ENV_FILE="${CLAUDE_ENV_FILE:-/tmp/test-env-$$}"
if [ "$VERBOSE" = true ]; then
echo "Environment:"
echo " CLAUDE_PROJECT_DIR=$CLAUDE_PROJECT_DIR"
echo " CLAUDE_PLUGIN_ROOT=$CLAUDE_PLUGIN_ROOT"
echo " CLAUDE_ENV_FILE=$CLAUDE_ENV_FILE"
echo ""
fi
# Run the hook
echo "▶️ Running hook (timeout: ${TIMEOUT}s)..."
echo ""
start_time=$(date +%s)
set +e
output=$(timeout "$TIMEOUT" bash -c "cat '$TEST_INPUT' | $HOOK_SCRIPT" 2>&1)
exit_code=$?
set -e
end_time=$(date +%s)
duration=$((end_time - start_time))
# Analyze results
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Results:"
echo ""
echo "Exit Code: $exit_code"
echo "Duration: ${duration}s"
echo ""
case $exit_code in
0)
echo "✅ Hook approved/succeeded"
;;
2)
echo "🚫 Hook blocked/denied"
;;
124)
echo "⏱️ Hook timed out after ${TIMEOUT}s"
;;
*)
echo "⚠️ Hook returned unexpected exit code: $exit_code"
;;
esac
echo ""
echo "Output:"
if [ -n "$output" ]; then
echo "$output"
echo ""
# Try to parse as JSON
if echo "$output" | jq empty 2>/dev/null; then
echo "Parsed JSON output:"
echo "$output" | jq .
fi
else
echo "(no output)"
fi
# Check for environment file
if [ -f "$CLAUDE_ENV_FILE" ]; then
echo ""
echo "Environment file created:"
cat "$CLAUDE_ENV_FILE"
rm -f "$CLAUDE_ENV_FILE"
fi
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
if [ $exit_code -eq 0 ] || [ $exit_code -eq 2 ]; then
echo "✅ Test completed successfully"
exit 0
else
echo "❌ Test failed"
exit 1
fi

159
skills/external/plugin-dev-hook-development/scripts/validate-hook-schema.sh vendored Executable file
View File

@@ -0,0 +1,159 @@
#!/bin/bash
# Hook Schema Validator
# Validates hooks.json structure and checks for common issues
set -euo pipefail
# Usage
if [ $# -eq 0 ]; then
echo "Usage: $0 <path/to/hooks.json>"
echo ""
echo "Validates hook configuration file for:"
echo " - Valid JSON syntax"
echo " - Required fields"
echo " - Hook type validity"
echo " - Matcher patterns"
echo " - Timeout ranges"
exit 1
fi
HOOKS_FILE="$1"
if [ ! -f "$HOOKS_FILE" ]; then
echo "❌ Error: File not found: $HOOKS_FILE"
exit 1
fi
echo "🔍 Validating hooks configuration: $HOOKS_FILE"
echo ""
# Check 1: Valid JSON
echo "Checking JSON syntax..."
if ! jq empty "$HOOKS_FILE" 2>/dev/null; then
echo "❌ Invalid JSON syntax"
exit 1
fi
echo "✅ Valid JSON"
# Check 2: Root structure
echo ""
echo "Checking root structure..."
VALID_EVENTS=("PreToolUse" "PostToolUse" "UserPromptSubmit" "Stop" "SubagentStop" "SessionStart" "SessionEnd" "PreCompact" "Notification")
for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
found=false
for valid_event in "${VALID_EVENTS[@]}"; do
if [ "$event" = "$valid_event" ]; then
found=true
break
fi
done
if [ "$found" = false ]; then
echo "⚠️ Unknown event type: $event"
fi
done
echo "✅ Root structure valid"
# Check 3: Validate each hook
echo ""
echo "Validating individual hooks..."
error_count=0
warning_count=0
for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
hook_count=$(jq -r ".\"$event\" | length" "$HOOKS_FILE")
for ((i=0; i<hook_count; i++)); do
# Check matcher exists
matcher=$(jq -r ".\"$event\"[$i].matcher // empty" "$HOOKS_FILE")
if [ -z "$matcher" ]; then
echo "❌ $event[$i]: Missing 'matcher' field"
((error_count++))
continue
fi
# Check hooks array exists
hooks=$(jq -r ".\"$event\"[$i].hooks // empty" "$HOOKS_FILE")
if [ -z "$hooks" ] || [ "$hooks" = "null" ]; then
echo "❌ $event[$i]: Missing 'hooks' array"
((error_count++))
continue
fi
# Validate each hook in the array
hook_array_count=$(jq -r ".\"$event\"[$i].hooks | length" "$HOOKS_FILE")
for ((j=0; j<hook_array_count; j++)); do
hook_type=$(jq -r ".\"$event\"[$i].hooks[$j].type // empty" "$HOOKS_FILE")
if [ -z "$hook_type" ]; then
echo "❌ $event[$i].hooks[$j]: Missing 'type' field"
((error_count++))
continue
fi
if [ "$hook_type" != "command" ] && [ "$hook_type" != "prompt" ]; then
echo "❌ $event[$i].hooks[$j]: Invalid type '$hook_type' (must be 'command' or 'prompt')"
((error_count++))
continue
fi
# Check type-specific fields
if [ "$hook_type" = "command" ]; then
command=$(jq -r ".\"$event\"[$i].hooks[$j].command // empty" "$HOOKS_FILE")
if [ -z "$command" ]; then
echo "❌ $event[$i].hooks[$j]: Command hooks must have 'command' field"
((error_count++))
else
# Check for hardcoded paths
if [[ "$command" == /* ]] && [[ "$command" != *'${CLAUDE_PLUGIN_ROOT}'* ]]; then
echo "⚠️ $event[$i].hooks[$j]: Hardcoded absolute path detected. Consider using \${CLAUDE_PLUGIN_ROOT}"
((warning_count++))
fi
fi
elif [ "$hook_type" = "prompt" ]; then
prompt=$(jq -r ".\"$event\"[$i].hooks[$j].prompt // empty" "$HOOKS_FILE")
if [ -z "$prompt" ]; then
echo "❌ $event[$i].hooks[$j]: Prompt hooks must have 'prompt' field"
((error_count++))
fi
# Check if prompt-based hooks are used on supported events
if [ "$event" != "Stop" ] && [ "$event" != "SubagentStop" ] && [ "$event" != "UserPromptSubmit" ] && [ "$event" != "PreToolUse" ]; then
echo "⚠️ $event[$i].hooks[$j]: Prompt hooks may not be fully supported on $event (best on Stop, SubagentStop, UserPromptSubmit, PreToolUse)"
((warning_count++))
fi
fi
# Check timeout
timeout=$(jq -r ".\"$event\"[$i].hooks[$j].timeout // empty" "$HOOKS_FILE")
if [ -n "$timeout" ] && [ "$timeout" != "null" ]; then
if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
echo "❌ $event[$i].hooks[$j]: Timeout must be a number"
((error_count++))
elif [ "$timeout" -gt 600 ]; then
echo "⚠️ $event[$i].hooks[$j]: Timeout $timeout seconds is very high (max 600s)"
((warning_count++))
elif [ "$timeout" -lt 5 ]; then
echo "⚠️ $event[$i].hooks[$j]: Timeout $timeout seconds is very low"
((warning_count++))
fi
fi
done
done
done
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
if [ $error_count -eq 0 ] && [ $warning_count -eq 0 ]; then
echo "✅ All checks passed!"
exit 0
elif [ $error_count -eq 0 ]; then
echo "⚠️ Validation passed with $warning_count warning(s)"
exit 0
else
echo "❌ Validation failed with $error_count error(s) and $warning_count warning(s)"
exit 1
fi

553
skills/external/plugin-dev-mcp-integration/SKILL.md vendored Normal file
View File

@@ -0,0 +1,553 @@
---
name: mcp-integration
description: This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.
---
# MCP Integration for Claude Code Plugins
## Overview
Model Context Protocol (MCP) enables Claude Code plugins to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within Claude Code.
**Key capabilities:**
- Connect to external services (databases, APIs, file systems)
- Provide 10+ related tools from a single service
- Handle OAuth and complex authentication flows
- Bundle MCP servers with plugins for automatic setup
## MCP Server Configuration Methods
Plugins can bundle MCP servers in two ways:
### Method 1: Dedicated .mcp.json (Recommended)
Create `.mcp.json` at plugin root:
```json
{
"database-tools": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
"env": {
"DB_URL": "${DB_URL}"
}
}
}
```
**Benefits:**
- Clear separation of concerns
- Easier to maintain
- Better for multiple servers
### Method 2: Inline in plugin.json
Add `mcpServers` field to plugin.json:
```json
{
"name": "my-plugin",
"version": "1.0.0",
"mcpServers": {
"plugin-api": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
"args": ["--port", "8080"]
}
}
}
```
**Benefits:**
- Single configuration file
- Good for simple single-server plugins
## MCP Server Types
### stdio (Local Process)
Execute local MCP servers as child processes. Best for local tools and custom servers.
**Configuration:**
```json
{
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
"env": {
"LOG_LEVEL": "debug"
}
}
}
```
**Use cases:**
- File system access
- Local database connections
- Custom MCP servers
- NPM-packaged MCP servers
**Process management:**
- Claude Code spawns and manages the process
- Communicates via stdin/stdout
- Terminates when Claude Code exits
### SSE (Server-Sent Events)
Connect to hosted MCP servers with OAuth support. Best for cloud services.
**Configuration:**
```json
{
"asana": {
"type": "sse",
"url": "https://mcp.asana.com/sse"
}
}
```
**Use cases:**
- Official hosted MCP servers (Asana, GitHub, etc.)
- Cloud services with MCP endpoints
- OAuth-based authentication
- No local installation needed
**Authentication:**
- OAuth flows handled automatically
- User prompted on first use
- Tokens managed by Claude Code
### HTTP (REST API)
Connect to RESTful MCP servers with token authentication.
**Configuration:**
```json
{
"api-service": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}",
"X-Custom-Header": "value"
}
}
}
```
**Use cases:**
- REST API-based MCP servers
- Token-based authentication
- Custom API backends
- Stateless interactions
### WebSocket (Real-time)
Connect to WebSocket MCP servers for real-time bidirectional communication.
**Configuration:**
```json
{
"realtime-service": {
"type": "ws",
"url": "wss://mcp.example.com/ws",
"headers": {
"Authorization": "Bearer ${TOKEN}"
}
}
}
```
**Use cases:**
- Real-time data streaming
- Persistent connections
- Push notifications from server
- Low-latency requirements
## Environment Variable Expansion
All MCP configurations support environment variable substitution:
**${CLAUDE_PLUGIN_ROOT}** - Plugin directory (always use for portability):
```json
{
"command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server"
}
```
**User environment variables** - From user's shell:
```json
{
"env": {
"API_KEY": "${MY_API_KEY}",
"DATABASE_URL": "${DB_URL}"
}
}
```
**Best practice:** Document all required environment variables in plugin README.
## MCP Tool Naming
When MCP servers provide tools, they're automatically prefixed:
**Format:** `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`
**Example:**
- Plugin: `asana`
- Server: `asana`
- Tool: `create_task`
- **Full name:** `mcp__plugin_asana_asana__asana_create_task`
### Using MCP Tools in Commands
Pre-allow specific MCP tools in command frontmatter:
```markdown
---
allowed-tools: [
"mcp__plugin_asana_asana__asana_create_task",
"mcp__plugin_asana_asana__asana_search_tasks"
]
---
```
**Wildcard (use sparingly):**
```markdown
---
allowed-tools: ["mcp__plugin_asana_asana__*"]
---
```
**Best practice:** Pre-allow specific tools, not wildcards, for security.
## Lifecycle Management
**Automatic startup:**
- MCP servers start when plugin enables
- Connection established before first tool use
- Restart required for configuration changes
**Lifecycle:**
1. Plugin loads
2. MCP configuration parsed
3. Server process started (stdio) or connection established (SSE/HTTP/WS)
4. Tools discovered and registered
5. Tools available as `mcp__plugin_...__...`
**Viewing servers:**
Use `/mcp` command to see all servers including plugin-provided ones.
## Authentication Patterns
### OAuth (SSE/HTTP)
OAuth handled automatically by Claude Code:
```json
{
"type": "sse",
"url": "https://mcp.example.com/sse"
}
```
User authenticates in browser on first use. No additional configuration needed.
### Token-Based (Headers)
Static or environment variable tokens:
```json
{
"type": "http",
"url": "https://api.example.com",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}
```
Document required environment variables in README.
### Environment Variables (stdio)
Pass configuration to MCP server:
```json
{
"command": "python",
"args": ["-m", "my_mcp_server"],
"env": {
"DATABASE_URL": "${DB_URL}",
"API_KEY": "${API_KEY}",
"LOG_LEVEL": "info"
}
}
```
## Integration Patterns
### Pattern 1: Simple Tool Wrapper
Commands use MCP tools with user interaction:
```markdown
# Command: create-item.md
---
allowed-tools: ["mcp__plugin_name_server__create_item"]
---
Steps:
1. Gather item details from user
2. Use mcp__plugin_name_server__create_item
3. Confirm creation
```
**Use for:** Adding validation or preprocessing before MCP calls.
### Pattern 2: Autonomous Agent
Agents use MCP tools autonomously:
```markdown
# Agent: data-analyzer.md
Analysis Process:
1. Query data via mcp__plugin_db_server__query
2. Process and analyze results
3. Generate insights report
```
**Use for:** Multi-step MCP workflows without user interaction.
### Pattern 3: Multi-Server Plugin
Integrate multiple MCP servers:
```json
{
"github": {
"type": "sse",
"url": "https://mcp.github.com/sse"
},
"jira": {
"type": "sse",
"url": "https://mcp.jira.com/sse"
}
}
```
**Use for:** Workflows spanning multiple services.
## Security Best Practices
### Use HTTPS/WSS
Always use secure connections:
```json
✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"
```
### Token Management
**DO:**
- ✅ Use environment variables for tokens
- ✅ Document required env vars in README
- ✅ Let OAuth flow handle authentication
**DON'T:**
- ❌ Hardcode tokens in configuration
- ❌ Commit tokens to git
- ❌ Share tokens in documentation
### Permission Scoping
Pre-allow only necessary MCP tools:
```markdown
✅ allowed-tools: [
"mcp__plugin_api_server__read_data",
"mcp__plugin_api_server__create_item"
]
❌ allowed-tools: ["mcp__plugin_api_server__*"]
```
## Error Handling
### Connection Failures
Handle MCP server unavailability:
- Provide fallback behavior in commands
- Inform user of connection issues
- Check server URL and configuration
### Tool Call Errors
Handle failed MCP operations:
- Validate inputs before calling MCP tools
- Provide clear error messages
- Check rate limiting and quotas
### Configuration Errors
Validate MCP configuration:
- Test server connectivity during development
- Validate JSON syntax
- Check required environment variables
## Performance Considerations
### Lazy Loading
MCP servers connect on-demand:
- Not all servers connect at startup
- First tool use triggers connection
- Connection pooling managed automatically
### Batching
Batch similar requests when possible:
```
# Good: Single query with filters
tasks = search_tasks(project="X", assignee="me", limit=50)
# Avoid: Many individual queries
for id in task_ids:
task = get_task(id)
```
## Testing MCP Integration
### Local Testing
1. Configure MCP server in `.mcp.json`
2. Install plugin locally (`.claude-plugin/`)
3. Run `/mcp` to verify server appears
4. Test tool calls in commands
5. Check `claude --debug` logs for connection issues
### Validation Checklist
- [ ] MCP configuration is valid JSON
- [ ] Server URL is correct and accessible
- [ ] Required environment variables documented
- [ ] Tools appear in `/mcp` output
- [ ] Authentication works (OAuth or tokens)
- [ ] Tool calls succeed from commands
- [ ] Error cases handled gracefully
## Debugging
### Enable Debug Logging
```bash
claude --debug
```
Look for:
- MCP server connection attempts
- Tool discovery logs
- Authentication flows
- Tool call errors
### Common Issues
**Server not connecting:**
- Check URL is correct
- Verify server is running (stdio)
- Check network connectivity
- Review authentication configuration
**Tools not available:**
- Verify server connected successfully
- Check tool names match exactly
- Run `/mcp` to see available tools
- Restart Claude Code after config changes
**Authentication failing:**
- Clear cached auth tokens
- Re-authenticate
- Check token scopes and permissions
- Verify environment variables set
## Quick Reference
### MCP Server Types
| Type | Transport | Best For | Auth |
|------|-----------|----------|------|
| stdio | Process | Local tools, custom servers | Env vars |
| SSE | HTTP | Hosted services, cloud APIs | OAuth |
| HTTP | REST | API backends, token auth | Tokens |
| ws | WebSocket | Real-time, streaming | Tokens |
### Configuration Checklist
- [ ] Server type specified (stdio/SSE/HTTP/ws)
- [ ] Type-specific fields complete (command or url)
- [ ] Authentication configured
- [ ] Environment variables documented
- [ ] HTTPS/WSS used (not HTTP/WS)
- [ ] ${CLAUDE_PLUGIN_ROOT} used for paths
### Best Practices
**DO:**
- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portable paths
- ✅ Document required environment variables
- ✅ Use secure connections (HTTPS/WSS)
- ✅ Pre-allow specific MCP tools in commands
- ✅ Test MCP integration before publishing
- ✅ Handle connection and tool errors gracefully
**DON'T:**
- ❌ Hardcode absolute paths
- ❌ Commit credentials to git
- ❌ Use HTTP instead of HTTPS
- ❌ Pre-allow all tools with wildcards
- ❌ Skip error handling
- ❌ Forget to document setup
## Additional Resources
### Reference Files
For detailed information, consult:
- **`references/server-types.md`** - Deep dive on each server type
- **`references/authentication.md`** - Authentication patterns and OAuth
- **`references/tool-usage.md`** - Using MCP tools in commands and agents
### Example Configurations
Working examples in `examples/`:
- **`stdio-server.json`** - Local stdio MCP server
- **`sse-server.json`** - Hosted SSE server with OAuth
- **`http-server.json`** - REST API with token auth
### External Resources
- **Official MCP Docs**: https://modelcontextprotocol.io/
- **Claude Code MCP Docs**: https://docs.claude.com/en/docs/claude-code/mcp
- **MCP SDK**: @modelcontextprotocol/sdk
- **Testing**: Use `claude --debug` and `/mcp` command
## Implementation Workflow
To add MCP integration to a plugin:
1. Choose MCP server type (stdio, SSE, HTTP, ws)
2. Create `.mcp.json` at plugin root with configuration
3. Use ${CLAUDE_PLUGIN_ROOT} for all file references
4. Document required environment variables in README
5. Test locally with `/mcp` command
6. Pre-allow MCP tools in relevant commands
7. Handle authentication (OAuth or tokens)
8. Test error cases (connection failures, auth errors)
9. Document MCP integration in plugin README
Focus on stdio for custom/local servers, SSE for hosted services with OAuth.

20
skills/external/plugin-dev-mcp-integration/examples/http-server.json vendored Normal file
View File

@@ -0,0 +1,20 @@
{
"_comment": "Example HTTP MCP server configuration for REST APIs",
"rest-api": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}",
"Content-Type": "application/json",
"X-API-Version": "2024-01-01"
}
},
"internal-service": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}",
"X-Service-Name": "claude-plugin"
}
}
}

19
skills/external/plugin-dev-mcp-integration/examples/sse-server.json vendored Normal file
View File

@@ -0,0 +1,19 @@
{
"_comment": "Example SSE MCP server configuration for hosted cloud services",
"asana": {
"type": "sse",
"url": "https://mcp.asana.com/sse"
},
"github": {
"type": "sse",
"url": "https://mcp.github.com/sse"
},
"custom-service": {
"type": "sse",
"url": "https://mcp.example.com/sse",
"headers": {
"X-API-Version": "v1",
"X-Client-ID": "${CLIENT_ID}"
}
}
}

Some files were not shown because too many files have changed in this diff Show More