commit afb8ef033a9c59ce3c40043967b01ab6b59b4d3c Author: Zhongwei Li Date: Sat Nov 29 18:50:09 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..f4adc8a --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "meta", + "description": "Meta-tools for creating and managing Claude Code components. Generate skills, commands, agents, hooks, and plugins with proper structure and validation.", + "version": "0.4.0", + "author": { + "name": "Jace Babin", + "email": "jbabin91@gmail.com", + "url": "https://github.com/jbabin91" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..1b810d6 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# meta + +Meta-tools for creating and managing Claude Code components. Generate skills, commands, agents, hooks, and plugins with proper structure and validation. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..0b86a7f --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,73 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jbabin91/super-claude:plugins/meta", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "de5395772c9415bead27ac144359b723803f78a9", + "treeHash": "40e7e349f413d8784d05702cbaba742ff5e6ba4ef13ea8965f32e2ad4b2e258f", + "generatedAt": "2025-11-28T10:17:57.964890Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "meta", + "description": "Meta-tools for creating and managing Claude Code components. Generate skills, commands, agents, hooks, and plugins with proper structure and validation.", + "version": "0.4.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "6b26573306a5f8b925f7d54ab0ea99961f4032c2999812f8b1a226e98276c803" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "9ee4120ce034b35d31574dbde937acda749359ae07332d2e32834034f2c9039a" + }, + { + "path": "skills/skill-rules.json", + "sha256": "5cb47ed661554f348c4eb932164690c8ba39d1026cb5904422330ff4b27cec6c" + }, + { + "path": "skills/skill-validator/SKILL.md", + "sha256": "8351bfc1fb033c1241d85e791a9388b022e0d6aa395a4f5f6a03481ded51d4e3" + }, + { + "path": "skills/command-creator/SKILL.md", + "sha256": "726f10870d1b3082a54e7d68fc92ef55d3ad66a7942477141ba71751dc132a19" + }, + { + "path": "skills/agent-creator/SKILL.md", + "sha256": "284382cb7f570103467be99f656b271a2d8e6897e09c324b2662d821adbb39f1" + }, + { + "path": "skills/skill-creator/SKILL.md", + "sha256": "aa4640285b36dff12bfa9f7b9f826649b13ba4d6a199eb9e1b0548f1570bcf55" + }, + { + "path": "skills/skill-creator/templates/skill_template.md", + "sha256": "149d0daad7dcb59ce2da781f006fdb55e76d0a1923293a0102263e4a13df7e71" + }, + { + "path": "skills/plugin-creator/SKILL.md", + "sha256": "25746b29d6055274f8209b4ff8a217e7a5f182a107bbca8dd44857c6af71d6c1" + }, + { + "path": "skills/hook-creator/SKILL.md", + "sha256": "aea9faf1bf9a0a43a6d7bf575f966ecf1135bc1c6a7887a9cd871369f5eb1b6a" + } + ], + "dirSha256": "40e7e349f413d8784d05702cbaba742ff5e6ba4ef13ea8965f32e2ad4b2e258f" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/agent-creator/SKILL.md b/skills/agent-creator/SKILL.md new file mode 100644 index 0000000..e2a2033 --- /dev/null +++ b/skills/agent-creator/SKILL.md @@ -0,0 +1,575 @@ +--- +name: agent-creator +version: 1.0.0 +description: | + Create specialized agents for Claude Code that handle specific tasks autonomously. + Generate agent definitions with proper configuration and best practices. + Use when: creating agents, generating sub-agents, setting up autonomous workflows. + Activates for: "create agent", "generate agent", "new agent", "sub-agent", "make agent" +--- + +# Agent Creator + +Generate specialized agents for autonomous task handling in Claude Code. + +## When to Use + +- Creating task-specific agents (code review, testing, research) +- Building autonomous workflows +- Specialized analysis agents +- Multi-step task automation +- Agent-driven development patterns + +## Agent System Overview + +Agents are specialized Claude instances with: + +- **Focused purpose**: Specific task or domain +- **Autonomy**: Can make decisions and use tools +- **Context**: Loaded with relevant skills and knowledge +- **Model selection**: Choose appropriate model (haiku, sonnet, opus) + +## Core Workflow + +### 1. Gather Requirements + +Ask the user: + +- **Purpose**: What specific task does this agent handle? +- **Model**: Which model? (haiku=fast/cheap, sonnet=balanced, opus=complex) +- **Skills**: Which skills should the agent have access to? +- **Tools**: Which tools can the agent use? +- **Constraints**: Any limitations or guardrails? +- **Location**: Project-local or global? + +### 2. Generate Agent Definition + +**Location:** + +- Global: `~/.claude/skills/super-claude/plugins/[plugin]/agents/agent-name.md` +- Project: `/path/to/project/.claude/agents/agent-name.md` + +**Format:** + +```markdown +--- +name: agent-name +model: sonnet|haiku|opus +description: Clear description of agent's purpose +--- + +# Agent Name + +## Purpose + +Specific task this agent handles autonomously. + +## Capabilities + +- Capability 1 +- Capability 2 +- Capability 3 + +## Model + +**sonnet** - Balanced performance and cost +(or haiku for speed, opus for complex reasoning) + +## Skills Used + +- skill-1: Purpose +- skill-2: Purpose + +## Tools Available + +- Read: For reading files +- Write: For creating files +- Bash: For running commands +- etc. + +## Operational Principles + +1. Principle 1 (e.g., "Always verify before modifying") +2. Principle 2 (e.g., "Test changes immediately") +3. Principle 3 (e.g., "Provide detailed reports") + +## Workflow + +1. Step 1: Action +2. Step 2: Action +3. Step 3: Action + +## Quality Standards + +- Standard 1 +- Standard 2 +- Standard 3 + +## Example Tasks + +### Task 1: [Description] + +Input: [what user provides] +Process: [how agent handles it] +Output: [what agent produces] + +### Task 2: [Description] + +Input: [what user provides] +Process: [how agent handles it] +Output: [what agent produces] + +## Limitations + +- Limitation 1 +- Limitation 2 + +## Success Criteria + +- How to determine if agent completed task successfully +``` + +### 3. Validate Agent + +Ensure: + +- ✅ Purpose is clear and focused +- ✅ Model choice is appropriate +- ✅ Skills and tools are relevant +- ✅ Workflow is well-defined +- ✅ Quality standards are specific + +## Example Agents + +### Code Review Agent + +```markdown +--- +name: code-reviewer +model: sonnet +description: Performs systematic code reviews with focus on quality, security, and best practices +--- + +# Code Review Agent + +## Purpose + +Autonomous code review agent that provides comprehensive feedback on code quality, security, and adherence to best practices. + +## Capabilities + +- Static code analysis +- Security vulnerability detection +- Performance optimization suggestions +- Best practice enforcement +- Test coverage analysis + +## Model + +**sonnet** - Balanced reasoning for code analysis + +## Skills Used + +- typescript/tsc-validation: Type checking +- testing/coverage-improve: Coverage analysis +- security-checker: Vulnerability scanning + +## Tools Available + +- Read: Analyze source files +- Grep: Search for patterns +- Bash: Run linters and type checkers + +## Operational Principles + +1. Never modify code without explicit approval +2. Provide specific, actionable feedback +3. Include code examples in suggestions +4. Prioritize security and type safety +5. Be constructive, not critical + +## Workflow + +1. Read files to review (git diff or specified files) +2. Run static analysis tools (TypeScript, ESLint) +3. Check for security vulnerabilities +4. Analyze test coverage +5. Review code patterns and best practices +6. Generate detailed report with: + - Issues found (categorized by severity) + - Specific recommendations + - Code examples for fixes + - Overall assessment + +## Quality Standards + +- All suggestions must be specific and actionable +- Include code examples for proposed changes +- Categorize issues: critical, high, medium, low +- Provide rationale for each recommendation + +## Example Tasks + +### Task 1: Review Pull Request + +Input: PR number or branch name +Process: + +1. Get git diff +2. Analyze changed files +3. Run type checker and linters +4. Check test coverage +5. Generate review report + Output: Detailed review with specific feedback + +### Task 2: Security Audit + +Input: Directory or file patterns +Process: + +1. Scan for common vulnerabilities +2. Check dependency security +3. Analyze authentication/authorization +4. Review data handling + Output: Security report with risk ratings + +## Limitations + +- Cannot execute code (static analysis only) +- Requires tools to be installed (TypeScript, ESLint, etc.) +- Limited to languages and tools specified in skills + +## Success Criteria + +- All code analyzed without errors +- Report includes specific, actionable feedback +- Recommendations include code examples +- Issues categorized by severity +``` + +### Test Generation Agent + +```markdown +--- +name: test-generator +model: sonnet +description: Automatically generates comprehensive test suites with high coverage +--- + +# Test Generator Agent + +## Purpose + +Generate comprehensive test suites for TypeScript/React code with focus on coverage and edge cases. + +## Capabilities + +- Unit test generation +- Integration test creation +- Edge case identification +- Mock generation +- Test coverage analysis + +## Model + +**sonnet** - Balanced for code understanding and generation + +## Skills Used + +- testing/vitest-integration +- typescript/tsc-validation +- react-tools/component-testing + +## Tools Available + +- Read: Analyze source code +- Write: Create test files +- Bash: Run tests and check coverage + +## Operational Principles + +1. Achieve 80%+ coverage minimum +2. Test happy path and edge cases +3. Generate realistic test data +4. Include accessibility tests for components +5. Mock external dependencies properly + +## Workflow + +1. Read source file to test +2. Analyze: + - Functions and methods + - Edge cases and error paths + - Dependencies to mock +3. Generate test file with: + - Proper imports and setup + - Happy path tests + - Edge case tests + - Error handling tests + - Mock configurations +4. Run tests to verify they pass +5. Check coverage and add tests if needed + +## Quality Standards + +- 80%+ code coverage +- All public APIs tested +- Edge cases covered +- Mocks are realistic +- Tests are maintainable + +## Example Tasks + +### Task 1: Generate Component Tests + +Input: React component file +Process: + +1. Analyze component props and behavior +2. Identify user interactions +3. Generate test file with: + - Render tests + - Interaction tests + - Prop variation tests + - Accessibility tests +4. Verify tests pass + Output: Complete test file with high coverage + +### Task 2: Generate API Tests + +Input: API endpoint/handler file +Process: + +1. Analyze endpoint logic +2. Identify request/response schemas +3. Generate tests for: + - Valid requests + - Invalid requests + - Error cases + - Edge cases +4. Mock dependencies + Output: Complete API test suite + +## Limitations + +- Requires existing source code +- Cannot test external integrations without mocks +- Test quality depends on source code quality + +## Success Criteria + +- Tests are generated and pass +- 80%+ coverage achieved +- All edge cases considered +- Mocks are properly configured +``` + +### Research Agent + +```markdown +--- +name: researcher +model: opus +description: Conducts thorough research and analysis on technical topics +--- + +# Research Agent + +## Purpose + +Autonomous research agent for in-depth technical investigation and analysis. + +## Capabilities + +- Codebase exploration +- Pattern analysis +- Dependency investigation +- Best practice research +- Technology comparison + +## Model + +**opus** - Complex reasoning for thorough analysis + +## Skills Used + +- All skills from typescript plugin +- All skills from testing plugin +- Documentation analysis skills + +## Tools Available + +- Read: Explore codebases +- Grep: Search for patterns +- Glob: Find files +- Bash: Run analysis commands +- WebFetch: Research external sources + +## Operational Principles + +1. Be thorough and systematic +2. Document all findings +3. Provide evidence for conclusions +4. Consider multiple perspectives +5. Organize information clearly + +## Workflow + +1. Understand research question +2. Plan investigation approach +3. Gather information: + - Explore codebase + - Search for patterns + - Research external sources +4. Analyze findings +5. Draw conclusions +6. Generate comprehensive report + +## Quality Standards + +- Thorough investigation +- Well-organized findings +- Evidence-based conclusions +- Clear, actionable recommendations + +## Example Tasks + +### Task 1: Technology Comparison + +Input: "Compare date-fns vs dayjs for our use case" +Process: + +1. Research both libraries +2. Compare: + - Bundle sizes + - Features + - Timezone support + - TypeScript support + - Community/maintenance +3. Analyze project requirements +4. Make recommendation + Output: Detailed comparison report with recommendation + +### Task 2: Codebase Analysis + +Input: "Analyze how authentication works in this codebase" +Process: + +1. Find authentication-related files +2. Trace authentication flow +3. Identify patterns and practices +4. Document architecture +5. Note potential issues + Output: Architecture documentation with diagrams + +## Limitations + +- Time-intensive (use opus sparingly) +- Requires good research skills configuration + +## Success Criteria + +- Question fully answered +- Findings are comprehensive +- Conclusions are evidence-based +- Report is well-organized +``` + +## Agent Categories + +### Code Quality + +- code-reviewer +- refactoring-assistant +- documentation-generator + +### Testing + +- test-generator +- coverage-analyzer +- e2e-test-creator + +### Development + +- feature-implementer +- bug-fixer +- api-designer + +### Research + +- researcher +- technology-evaluator +- pattern-analyzer + +### Operations + +- deployment-manager +- dependency-updater +- performance-optimizer + +## Model Selection Guide + +### Haiku (Fast & Cheap) + +- Simple, repetitive tasks +- Quick analysis +- High-volume operations +- Examples: formatter, simple validators + +### Sonnet (Balanced) + +- Most common choice +- Code review +- Test generation +- Refactoring +- Examples: code-reviewer, test-generator + +### Opus (Complex Reasoning) + +- Deep analysis +- Research tasks +- Architecture decisions +- Complex problem-solving +- Examples: researcher, architect + +## Best Practices + +1. **Single Responsibility**: One clear purpose per agent +2. **Clear Constraints**: Define what agent can/cannot do +3. **Quality Standards**: Specific success criteria +4. **Appropriate Model**: Match model to task complexity +5. **Tool Access**: Only tools needed for the task + +## Anti-Patterns + +- ❌ Multi-purpose agents (do one thing well) +- ❌ Vague purpose or workflow +- ❌ No quality standards +- ❌ Wrong model choice (opus for simple tasks) +- ❌ Too many tool permissions + +## Troubleshooting + +### Agent Not Performing Well + +**Solution**: + +- Check model selection (may need upgrade/downgrade) +- Refine operational principles +- Add more specific skills +- Clarify success criteria + +### Agent Taking Too Long + +**Solution**: + +- Use faster model (sonnet → haiku) +- Narrow scope +- Add time constraints +- Break into smaller agents + +## References + +- [Claude Code Agents Documentation](https://docs.claude.com/en/docs/claude-code/agents) +- [super-claude Agent Examples](../../agents/) +- [obra/superpowers Agent Patterns](https://github.com/obra/superpowers) diff --git a/skills/command-creator/SKILL.md b/skills/command-creator/SKILL.md new file mode 100644 index 0000000..17ef32f --- /dev/null +++ b/skills/command-creator/SKILL.md @@ -0,0 +1,342 @@ +--- +name: command-creator +version: 1.0.0 +description: | + Create custom slash commands for Claude Code with proper markdown structure and YAML frontmatter. + Use when: creating commands, generating slash commands, making workflow automations. + Activates for: "create command", "generate command", "new command", "slash command", "make command" +--- + +# Command Creator + +Generate custom slash commands for Claude Code with proper structure. + +## When to Use + +- Creating project-specific commands +- Automating repetitive workflows +- Building team-shared commands +- Standardizing common operations + +## Command Structure + +Commands are markdown files in the `commands/` directory with YAML frontmatter: + +```markdown +--- +description: Brief description of what this command does +--- + +# Command instructions + +Detailed instructions for Claude to follow when this command is executed. + +## Context + +Information about when and how to use this command. + +## Examples + +Example usage and expected outcomes. +``` + +## Core Workflow + +### 1. Gather Requirements + +Ask the user: + +- **Command name**: `/command-name` (what should user type?) +- **Purpose**: What does this command do? +- **Parameters**: Does it need arguments? +- **Context**: When should it be used? +- **Location**: Project-local or global? + +### 2. Generate Command File + +**Location:** + +- Global: `~/.claude/skills/super-claude/plugins/[plugin]/commands/command-name.md` +- Project: `/path/to/project/.claude/commands/command-name.md` + +**Format:** + +```markdown +--- +description: One-line description (required) +--- + +# Command Name + +## Purpose + +Clear explanation of what this command does. + +## Usage + +\`\`\` +/command-name [arguments] +\`\`\` + +## Instructions for Claude + +Step-by-step instructions for Claude to follow: + +1. First action +2. Second action +3. Third action + +## Parameters + +- `arg1`: Description of first argument +- `arg2`: Description of second argument (optional) + +## Examples + +### Example 1: Common Use Case + +\`\`\` +/command-name value1 value2 +\`\`\` +Expected outcome: [description] + +### Example 2: With Options + +\`\`\` +/command-name --option value +\`\`\` +Expected outcome: [description] + +## Notes + +- Important consideration 1 +- Important consideration 2 +``` + +### 3. Validate Command + +Ensure: + +- ✅ Description is clear and concise +- ✅ Instructions are actionable +- ✅ Examples are realistic +- ✅ Parameter descriptions are complete +- ✅ File is in correct location + +## Example Commands + +### Project Setup Command + +```markdown +--- +description: Initialize a new TanStack Start project with drizzle and better-auth +--- + +# Setup TanStack Fullstack + +## Purpose + +Quickly scaffold a new TanStack Start project with database and authentication. + +## Usage + +\`\`\` +/setup-tanstack-fullstack [project-name] +\`\`\` + +## Instructions for Claude + +1. Create new directory with project-name +2. Initialize TanStack Start project +3. Install and configure Drizzle ORM with Postgres +4. Set up better-auth with Drizzle adapter +5. Create initial database schema +6. Set up environment variables +7. Create README with setup instructions + +## Parameters + +- `project-name`: Name of the new project directory + +## Examples + +### Example: Create New Project + +\`\`\` +/setup-tanstack-fullstack my-app +\`\`\` + +Creates: + +- my-app/ directory +- TanStack Start configuration +- Drizzle + Postgres setup +- better-auth integration +- Initial schema and migrations +``` + +### Code Review Command + +```markdown +--- +description: Perform comprehensive code review with focus areas +--- + +# Review Code + +## Purpose + +Systematic code review checking for common issues and best practices. + +## Usage + +\`\`\` +/review-code [--focus=area] +\`\`\` + +## Instructions for Claude + +1. Analyze current file or git diff +2. Check for: + - Type safety issues + - Accessibility concerns + - Performance problems + - Security vulnerabilities + - Best practice violations +3. If --focus provided, emphasize that area +4. Provide specific, actionable feedback +5. Suggest improvements with code examples + +## Parameters + +- `--focus`: Optional focus area (security, performance, accessibility, types) + +## Examples + +### Example: General Review + +\`\`\` +/review-code +\`\`\` + +### Example: Security Focus + +\`\`\` +/review-code --focus=security +\`\`\` +``` + +### Deployment Command + +```markdown +--- +description: Deploy to Cloudflare Pages with pre-deployment checks +--- + +# Deploy Cloudflare + +## Purpose + +Deploy current project to Cloudflare Pages with safety checks. + +## Usage + +\`\`\` +/deploy-cloudflare [--environment=prod|staging] +\`\`\` + +## Instructions for Claude + +1. Run pre-deployment checks: + - All tests passing + - No TypeScript errors + - No ESLint errors + - Build succeeds +2. Confirm environment variables are set +3. Build production bundle +4. Deploy to Cloudflare Pages +5. Verify deployment successful +6. Provide deployment URL + +## Parameters + +- `--environment`: Target environment (default: staging) + +## Examples + +### Example: Deploy to Staging + +\`\`\` +/deploy-cloudflare +\`\`\` + +### Example: Deploy to Production + +\`\`\` +/deploy-cloudflare --environment=prod +\`\`\` +``` + +## Command Categories + +### Project Setup + +- `/setup-*`: Initialize new projects +- `/scaffold-*`: Create project structure + +### Code Generation + +- `/generate-*`: Create code/files +- `/create-*`: Create components/modules + +### Code Quality + +- `/review-*`: Code review commands +- `/fix-*`: Auto-fix issues +- `/lint-*`: Linting operations + +### Testing + +- `/test-*`: Run tests +- `/coverage-*`: Coverage analysis + +### Deployment + +- `/deploy-*`: Deployment operations +- `/release-*`: Release management + +### Documentation + +- `/docs-*`: Generate documentation +- `/explain-*`: Explain code/concepts + +## Best Practices + +1. **Clear Names**: Use descriptive command names +2. **Single Purpose**: One command = one clear action +3. **Good Defaults**: Sensible default parameters +4. **Safe Operations**: Confirm destructive actions +5. **Helpful Output**: Provide clear feedback + +## Anti-Patterns + +- ❌ Generic names (helper, util, do-thing) +- ❌ Multiple unrelated actions in one command +- ❌ Missing parameter descriptions +- ❌ No examples +- ❌ Destructive operations without confirmation + +## Troubleshooting + +### Command Not Found + +**Solution**: Ensure file is in `commands/` directory and Claude Code has been restarted + +### Command Parameters Not Working + +**Solution**: Check parameter format in examples, ensure clear documentation + +## References + +- [Claude Code Commands Documentation](https://docs.claude.com/en/docs/claude-code/commands) +- [super-claude Command Examples](../../commands/) diff --git a/skills/hook-creator/SKILL.md b/skills/hook-creator/SKILL.md new file mode 100644 index 0000000..d7787dc --- /dev/null +++ b/skills/hook-creator/SKILL.md @@ -0,0 +1,382 @@ +--- +name: hook-creator +version: 1.0.0 +description: | + Create event hooks for Claude Code that trigger on specific events. + Generate hooks with proper JSON configuration for automating workflows. + Use when: creating hooks, setting up event triggers, automating on file saves or tool calls. + Activates for: "create hook", "generate hook", "new hook", "event hook", "make hook" +--- + +# Hook Creator + +Generate event-driven hooks for Claude Code with proper configuration. + +## When to Use + +- Automating actions on specific events +- Running checks before/after tool calls +- Formatting code on save +- Validating inputs before processing +- Triggering notifications or logging + +## Hook System Overview + +Hooks allow you to run shell commands or scripts in response to Claude Code events: + +**Event Types:** + +- `user-prompt-submit` - Before Claude processes user input +- `tool-call` - Before/after tool execution +- `session-start` - When Claude Code session begins +- `session-end` - When session ends + +## Core Workflow + +### 1. Gather Requirements + +Ask the user: + +- **Event type**: Which event should trigger this hook? +- **When**: Before or after the event? +- **Action**: What command/script to run? +- **Filtering**: Specific tools, file types, or conditions? +- **Location**: Project-local or global? + +### 2. Generate Hook Configuration + +**Location:** + +- Global: `~/.claude/skills/super-claude/plugins/[plugin]/hooks/hooks.json` +- Project: `/path/to/project/.claude/hooks/hooks.json` + +**Format:** + +```json +{ + "hooks": [ + { + "name": "hook-name", + "event": "event-type", + "when": "before|after", + "command": "shell command to execute", + "filter": { + "tool": "specific-tool-name", + "filePattern": "*.ts" + }, + "description": "What this hook does" + } + ] +} +``` + +### 3. Validate Hook + +Ensure: + +- ✅ Event type is valid +- ✅ Command is executable +- ✅ Filter criteria are specific +- ✅ Hook has clear description +- ✅ No security issues (careful with shell commands) + +## Example Hooks + +### Prettier on Save + +```json +{ + "hooks": [ + { + "name": "format-on-save", + "event": "tool-call", + "when": "after", + "command": "prettier --write $FILE", + "filter": { + "tool": "Write", + "filePattern": "*.{ts,tsx,js,jsx,md,json}" + }, + "description": "Automatically format files after writing" + } + ] +} +``` + +### Type Check Before Commit + +```json +{ + "hooks": [ + { + "name": "type-check-pre-commit", + "event": "user-prompt-submit", + "when": "before", + "command": "npm run type-check", + "filter": { + "promptPattern": "commit|create.*commit" + }, + "description": "Run type check before git commits" + } + ] +} +``` + +### Run Tests After Edit + +```json +{ + "hooks": [ + { + "name": "test-after-edit", + "event": "tool-call", + "when": "after", + "command": "npm test -- --related $FILE --run", + "filter": { + "tool": "Edit", + "filePattern": "*.{ts,tsx}" + }, + "description": "Run related tests after editing source files" + } + ] +} +``` + +### Validate API Schema + +```json +{ + "hooks": [ + { + "name": "validate-openapi-schema", + "event": "tool-call", + "when": "after", + "command": "npm run validate:openapi", + "filter": { + "tool": "Write", + "filePattern": "**/api/**/*.ts" + }, + "description": "Validate OpenAPI schema after API changes" + } + ] +} +``` + +### Accessibility Check + +```json +{ + "hooks": [ + { + "name": "a11y-check-components", + "event": "tool-call", + "when": "after", + "command": "npm run a11y:check $FILE", + "filter": { + "tool": "Write", + "filePattern": "**/components/**/*.tsx" + }, + "description": "Run accessibility checks on component changes" + } + ] +} +``` + +### Session Start Setup + +```json +{ + "hooks": [ + { + "name": "session-start-checks", + "event": "session-start", + "when": "after", + "command": "./scripts/check-dependencies.sh", + "description": "Check dependencies and environment on session start" + } + ] +} +``` + +## Hook Configuration + +### Event Types + +**user-prompt-submit** + +- Triggers when user submits a prompt +- Use `when: "before"` to validate/modify input +- Use `when: "after"` to log/process completed requests + +**tool-call** + +- Triggers on tool execution (Read, Write, Edit, Bash, etc.) +- Use `filter.tool` to specify which tool +- Access file path via `$FILE` variable + +**session-start** + +- Triggers when Claude Code session begins +- Good for environment checks, setup tasks + +**session-end** + +- Triggers when session ends +- Good for cleanup, logging, backups + +### Filter Options + +```json +{ + "filter": { + "tool": "Write", // Specific tool name + "filePattern": "*.ts", // Glob pattern for files + "promptPattern": "commit|deploy", // Regex for prompt content + "fileType": "typescript" // File type detection + } +} +``` + +### Variables + +Available in commands: + +- `$FILE` - File path being operated on +- `$TOOL` - Tool name being used +- `$PROJECT` - Project root directory +- `$PWD` - Current working directory + +## Hook Categories + +### Code Quality + +- Format on save (Prettier, ESLint --fix) +- Lint before commit +- Type check before operations + +### Testing + +- Run tests after edits +- Update snapshots +- Coverage checks + +### Validation + +- Schema validation +- API contract checking +- Accessibility testing + +### Git Operations + +- Pre-commit checks +- Commit message validation +- Branch protection + +### Environment + +- Dependency checks +- Environment variable validation +- Configuration verification + +## Best Practices + +1. **Specific Filters**: Don't run on every event - be selective +2. **Fast Commands**: Hooks should complete quickly (< 2 seconds) +3. **Error Handling**: Commands should fail gracefully +4. **Clear Descriptions**: Explain what the hook does +5. **Test Hooks**: Verify they work before deploying + +## Security Considerations + +⚠️ **Important**: Hooks execute shell commands + +- ✅ Use absolute paths when possible +- ✅ Validate inputs and file paths +- ✅ Avoid user-controlled variables in commands +- ✅ Review hook commands carefully +- ❌ Never execute arbitrary code from untrusted sources +- ❌ Avoid hooks that modify system files +- ❌ Don't use hooks for sensitive operations without safeguards + +## Anti-Patterns + +- ❌ Running slow operations (> 5 seconds) +- ❌ Hooks with side effects that aren't clear +- ❌ Too many hooks (performance impact) +- ❌ Hooks without filters (run on everything) +- ❌ Destructive operations without confirmation + +## Troubleshooting + +### Hook Not Firing + +**Solution**: + +- Check hooks.json syntax is valid +- Verify event type is correct +- Check filter criteria match your use case +- Restart Claude Code + +### Hook Command Fails + +**Solution**: + +- Test command in terminal first +- Check file paths are correct +- Verify required tools are installed +- Check command output/errors + +### Hook Slows Down Workflow + +**Solution**: + +- Add more specific filters +- Optimize command execution +- Consider running async if possible +- Remove unnecessary hooks + +## Advanced Patterns + +### Conditional Execution + +```json +{ + "name": "conditional-hook", + "event": "tool-call", + "when": "after", + "command": "if [ -f package.json ]; then npm test; fi", + "description": "Run tests only if package.json exists" +} +``` + +### Chained Commands + +```json +{ + "name": "format-and-lint", + "event": "tool-call", + "when": "after", + "command": "prettier --write $FILE && eslint --fix $FILE", + "filter": { + "tool": "Write", + "filePattern": "*.ts" + }, + "description": "Format and lint TypeScript files" +} +``` + +### Background Execution + +```json +{ + "name": "background-validation", + "event": "tool-call", + "when": "after", + "command": "npm run validate &", + "description": "Run validation in background" +} +``` + +## References + +- [Claude Code Hooks Documentation](https://docs.claude.com/en/docs/claude-code/hooks) +- [super-claude Hook Examples](../../hooks/) diff --git a/skills/plugin-creator/SKILL.md b/skills/plugin-creator/SKILL.md new file mode 100644 index 0000000..b4ec537 --- /dev/null +++ b/skills/plugin-creator/SKILL.md @@ -0,0 +1,465 @@ +--- +name: plugin-creator +version: 1.0.0 +description: | + Create complete Claude Code plugins with proper structure including skills, commands, agents, and hooks. + Generates plugin manifests and directory structures for distribution. + Use when: building plugins, creating plugin packages, distributing skills to marketplace. + Activates for: "create plugin", "generate plugin", "new plugin", "plugin package", "make plugin" +--- + +# Plugin Creator + +Generate complete Claude Code plugins with proper structure and configuration. + +## When to Use + +- Creating shareable plugin packages +- Building complete tool collections +- Organizing related skills/commands/agents +- Distributing functionality to teams +- Contributing to plugin marketplaces + +## Plugin Structure + +A complete plugin includes: + +```sh +plugin-name/ +├── .claude-plugin/ +│ └── plugin.json # Plugin manifest +├── skills/ # Optional: Skill definitions +│ ├── skill-1.md +│ └── skill-2.md +├── commands/ # Optional: Slash commands +│ ├── command-1.md +│ └── command-2.md +├── agents/ # Optional: Agent definitions +│ ├── agent-1.md +│ └── agent-2.md +├── hooks/ # Optional: Event hooks +│ └── hooks.json +├── README.md # Documentation +└── LICENSE # Optional: License file +``` + +## Core Workflow + +### 1. Gather Requirements + +Ask the user: + +- **Plugin name**: Kebab-case identifier +- **Purpose**: What problem does this plugin solve? +- **Components**: What will it include (skills/commands/agents/hooks)? +- **Target audience**: Who will use this? +- **Distribution**: Public marketplace or private? +- **Dependencies**: Required tools or other plugins? + +### 2. Generate Plugin Structure + +#### Create Directory Structure + +```bash +mkdir -p plugin-name/.claude-plugin +mkdir -p plugin-name/skills +mkdir -p plugin-name/commands +mkdir -p plugin-name/agents +mkdir -p plugin-name/hooks +``` + +#### Generate plugin.json + +```json +{ + "name": "plugin-name", + "version": "1.0.0", + "description": "Clear description of what this plugin does", + "author": { + "name": "Author Name", + "email": "email@example.com", + "github": "github-username" + }, + "license": "MIT", + "category": "appropriate-category", + "keywords": ["keyword1", "keyword2", "keyword3"], + "skills": ["skill-1", "skill-2"], + "commands": ["command-1", "command-2"], + "agents": ["agent-1", "agent-2"], + "repository": { + "type": "git", + "url": "https://github.com/username/plugin-name" + }, + "homepage": "https://github.com/username/plugin-name", + "requires": { + "tools": ["git", "npm"], + "plugins": [] + } +} +``` + +#### Generate README.md + +```markdown +# Plugin Name + +> Brief description + +## Features + +- Feature 1 +- Feature 2 +- Feature 3 + +## Installation + +\`\`\`bash +/plugin marketplace add username/plugin-name +/plugin install plugin-name +\`\`\` + +## Usage + +### Skills + +- **skill-1**: Description +- **skill-2**: Description + +### Commands + +- `/command-1`: Description +- `/command-2`: Description + +### Agents + +- **agent-1**: Description + +## Examples + +[Usage examples] + +## Requirements + +- Tool 1 +- Tool 2 + +## License + +MIT +``` + +### 3. Add Components + +Use the creator skills to add components: + +- **skill-creator**: Add skills +- **command-creator**: Add commands +- **agent-creator**: Add agents +- **hook-creator**: Add hooks + +### 4. Validate Plugin + +Ensure: + +- ✅ plugin.json is valid JSON +- ✅ All referenced components exist +- ✅ Directory structure is correct +- ✅ README is comprehensive +- ✅ License is appropriate +- ✅ Keywords are relevant + +## Example Plugins + +### TanStack Tools Plugin + +```sh +tanstack-tools/ +├── .claude-plugin/ +│ └── plugin.json +├── skills/ +│ ├── tanstack-router-setup.md +│ ├── tanstack-query-hook.md +│ ├── tanstack-form-schema.md +│ ├── tanstack-table-config.md +│ └── tanstack-start-project.md +├── commands/ +│ ├── setup-tanstack-start.md +│ └── generate-query-hook.md +├── README.md +└── LICENSE +``` + +**plugin.json:** + +```json +{ + "name": "tanstack-tools", + "version": "1.0.0", + "description": "Comprehensive TanStack ecosystem tools for Router, Query, Forms, Table, and Start", + "author": { + "name": "Jace Babin", + "email": "jbabin91@gmail.com", + "github": "jbabin91" + }, + "license": "MIT", + "category": "framework", + "keywords": [ + "tanstack", + "router", + "query", + "forms", + "table", + "start", + "react" + ], + "skills": [ + "tanstack-router-setup", + "tanstack-query-hook", + "tanstack-form-schema", + "tanstack-table-config", + "tanstack-start-project" + ], + "commands": ["setup-tanstack-start", "generate-query-hook"], + "requires": { + "tools": ["npm", "git"], + "packages": ["@tanstack/router", "@tanstack/react-query"] + } +} +``` + +### API Tools Plugin + +```sh +api-tools/ +├── .claude-plugin/ +│ └── plugin.json +├── skills/ +│ ├── drizzle-setup.md +│ ├── drizzle-schema-generator.md +│ ├── better-auth-setup.md +│ ├── hono-rpc-endpoint.md +│ └── elysia-setup.md +├── commands/ +│ ├── init-drizzle.md +│ ├── generate-api-client.md +│ └── setup-auth.md +├── agents/ +│ └── api-designer.md +├── README.md +└── LICENSE +``` + +**plugin.json:** + +```json +{ + "name": "api-tools", + "version": "1.0.0", + "description": "Backend API development tools for Hono, Elysia, Drizzle, and better-auth", + "author": { + "name": "Jace Babin", + "email": "jbabin91@gmail.com", + "github": "jbabin91" + }, + "license": "MIT", + "category": "backend", + "keywords": [ + "api", + "backend", + "hono", + "elysia", + "drizzle", + "better-auth", + "openapi" + ], + "skills": [ + "drizzle-setup", + "drizzle-schema-generator", + "better-auth-setup", + "hono-rpc-endpoint", + "elysia-setup" + ], + "commands": ["init-drizzle", "generate-api-client", "setup-auth"], + "agents": ["api-designer"], + "requires": { + "tools": ["npm", "node"], + "packages": ["drizzle-orm", "better-auth"] + } +} +``` + +### Component Library Plugin + +```sh +design-system-tools/ +├── .claude-plugin/ +│ └── plugin.json +├── skills/ +│ ├── component-generator.md +│ ├── component-a11y-validator.md +│ ├── storybook-story.md +│ └── design-tokens-validator.md +├── commands/ +│ ├── create-component.md +│ ├── validate-a11y.md +│ └── generate-stories.md +├── agents/ +│ ├── component-reviewer.md +│ └── a11y-auditor.md +├── hooks/ +│ └── hooks.json +├── README.md +└── LICENSE +``` + +## Plugin Categories + +### Framework-Specific + +- tanstack-tools +- react-tools +- next-tools +- vue-tools + +### Backend + +- api-tools +- database-tools +- auth-tools + +### DevOps + +- deployment-tools +- ci-cd-tools +- monitoring-tools + +### Code Quality + +- testing +- linting-tools +- security-tools + +### Meta + +- skill-tools (this plugin!) +- marketplace-tools +- template-tools + +## Plugin Manifest Fields + +### Required Fields + +```json +{ + "name": "plugin-identifier", // Required: kebab-case + "version": "1.0.0", // Required: semantic versioning + "description": "Clear description" // Required: what it does +} +``` + +### Recommended Fields + +```json +{ + "author": { + "name": "Author Name", + "email": "email@example.com", + "github": "username" + }, + "license": "MIT", + "category": "framework", + "keywords": ["keyword1", "keyword2"], + "repository": { + "type": "git", + "url": "https://github.com/username/plugin" + }, + "homepage": "https://github.com/username/plugin" +} +``` + +### Optional Fields + +```json +{ + "skills": ["skill-1", "skill-2"], // List of included skills + "commands": ["cmd-1", "cmd-2"], // List of commands + "agents": ["agent-1"], // List of agents + "requires": { + "tools": ["git", "npm"], // Required CLI tools + "plugins": ["other-plugin"], // Plugin dependencies + "packages": ["package-name"] // npm package dependencies + } +} +``` + +## Distribution + +### Public Marketplace + +1. Create GitHub repository +2. Add marketplace.json (if creating marketplace) +3. Tag releases with versions +4. Share repository URL + +Users install via: + +```bash +/plugin marketplace add username/plugin-name +/plugin install plugin-name +``` + +### Private/Work Distribution + +1. Host on private Git server +2. Share repository URL with team +3. Add to team marketplace + +Users install via: + +```bash +/plugin marketplace add git@internal:plugins/plugin-name +/plugin install plugin-name +``` + +## Best Practices + +1. **Clear Purpose**: Plugin should solve one specific problem domain +2. **Good Documentation**: Comprehensive README with examples +3. **Semantic Versioning**: Follow semver for releases +4. **Minimal Dependencies**: Only require what's necessary +5. **Test Before Release**: Validate all components work +6. **Helpful Keywords**: Make plugin discoverable + +## Anti-Patterns + +- ❌ Kitchen-sink plugins (too many unrelated features) +- ❌ Missing documentation +- ❌ No examples +- ❌ Unclear versioning +- ❌ Missing license +- ❌ Poor component organization + +## Troubleshooting + +### Plugin Not Loading + +**Solution**: + +- Validate plugin.json syntax +- Check directory structure +- Verify all referenced files exist +- Restart Claude Code + +### Components Not Found + +**Solution**: + +- Check component names match manifest +- Verify files are in correct directories +- Check file extensions (.md for skills/commands/agents) + +## References + +- [Claude Code Plugins Documentation](https://docs.claude.com/en/docs/claude-code/plugins) +- [super-claude Plugin Examples](../../plugins/) +- [Plugin Manifest Spec](https://docs.claude.com/en/docs/claude-code/plugins#manifest) diff --git a/skills/skill-creator/SKILL.md b/skills/skill-creator/SKILL.md new file mode 100644 index 0000000..cfa7117 --- /dev/null +++ b/skills/skill-creator/SKILL.md @@ -0,0 +1,704 @@ +--- +name: skill-creator +version: 1.0.0 +description: | + Create new Claude Code skills with proper structure, validation, and best practices. + Generates skills that follow Anthropic specifications and community patterns. + Use when you need custom skills for specific workflows, either globally or per-project. +category: meta +tags: [skill-generation, meta, automation, claude-code] +model: sonnet +triggers: + keywords: [create skill, generate skill, new skill, custom skill, skill for] + patterns: ['create.*skill', 'generate.*skill', 'make.*skill'] + contexts: [development, skill-creation] +--- + +# Skill Creator + +A meta-skill for generating new Claude Code skills with proper structure and validation. + +## When to Use + +- Creating project-specific skills (e.g., "Odyssey design system components") +- Building work-related skills (e.g., "SD API client generation") +- Generating custom workflow automations +- Standardizing team practices into reusable skills +- Converting manual processes into automated skills + +## Core Workflow + +### 1. Gather Requirements + +Ask the user: + +- **Purpose**: What problem does this skill solve? +- **Triggers**: What keywords/phrases should activate it? +- **Context**: When should it be used (file types, project types)? +- **Location**: Where to save (global or project-local)? +- **Dependencies**: Required tools, packages, or other skills? + +### 2. Generate Skill Structure + +**Template Reference:** See `templates/skill_template.md` for the complete skill template with all available fields and examples. + +Create a properly formatted SKILL.md with: + +```yaml +--- +# OFFICIAL CLAUDE CODE FIELDS (recognized by Claude Code) +name: skill-identifier # Required: kebab-case +description: | # Required: What it does AND when to activate + Clear description of what it does and when to use it. + IMPORTANT: Include activation triggers in the description itself. + Example: "Generate React components. Use when creating new UI components." +allowed-tools: [] # Optional: Restrict to specific tools + +# EXTENDED METADATA (ignored by Claude Code, useful for organization) +version: 1.0.0 # Track changes (skills are files, not packages) +--- + +# Skill Name + +Brief overview (1-2 sentences). + +## When to Use + +- Concrete trigger 1 +- Concrete trigger 2 +- Specific scenario 3 + +## Core Workflow + +### 1. First Step +Description and instructions + +### 2. Second Step +Description and instructions + +## Best Practices + +- Practice 1 +- Practice 2 + +## Example Workflows + +### Scenario 1: Common Use Case +Step-by-step example + +### Scenario 2: Edge Case +How to handle edge cases + +## Integration Points + +- Works with: [other skills] +- Calls: [agents/tools] +- Required by: [dependent skills] + +## Troubleshooting + +### Issue 1 +Symptom: [description] +Solution: [fix] + +### Issue 2 +Symptom: [description] +Solution: [fix] + +## References + +- [External documentation links] +``` + +### 3. Validate Against Specifications + +Ensure the skill follows: + +**Anthropic Best Practices:** + +- ✅ Clear, actionable instructions +- ✅ Specific triggers (not generic) +- ✅ Real examples (not placeholders) +- ✅ Token-efficient (< 500 lines for core content) +- ✅ Progressive disclosure (link to API_REFERENCE.md if needed) + +**RED-GREEN-REFACTOR Ready:** + +- ✅ Can be tested without the skill (RED phase) +- ✅ Verifiable compliance (GREEN phase) +- ✅ Hardened against rationalizations (REFACTOR phase) + +**Community Patterns:** + +- ✅ No TODOs or placeholders in production +- ✅ No "YOUR_KEY_HERE" style configs +- ✅ Specific, not generic labels +- ✅ Context-aware activation + +### 4. Save to Appropriate Location + +**Global Skills** (general use across all projects): + +```txt +~/.claude/skills/super-claude/plugins/[category]/skills/skill-name.md +``` + +**Project-Local Skills** (specific to one project): + +```txt +/path/to/project/.claude/skills/skill-name.md +``` + +**Note**: Project-local skills are perfect for work-specific or proprietary patterns that shouldn't be shared globally. + +### 5. Test the Skill + +Provide testing guidance: + +- RED: Try the workflow WITHOUT the skill, note failures +- GREEN: Enable the skill, verify it works +- REFACTOR: Identify edge cases, harden the skill + +## Skill Types + +### Standard Skill (Most Common) + +General-purpose automation or guidance for specific tasks. + +### Component Generator + +Creates code/files following specific patterns. + +### Workflow Orchestrator + +Coordinates multiple steps or tools. + +### Validation/Checker + +Ensures code/config meets standards. + +### Migration Helper + +Assists in moving between technologies. + +## Advanced Features + +### Progressive Disclosure + +If skill exceeds 500 lines, split into: + +- **SKILL.md**: Core instructions (< 500 lines) +- **API_REFERENCE.md**: Advanced topics (loaded on-demand) + +Link from SKILL.md: + +```markdown +For advanced usage, see [API_REFERENCE.md](./API_REFERENCE.md) +``` + +### Context-Aware Activation + +Make skills activate automatically: + +```yaml +triggers: + keywords: [specific, technical, terms] + patterns: ['regex.*patterns'] + contexts: [file-types, project-types] +``` + +### Dependencies + +Declare requirements: + +```yaml +requires: + tools: [git, npm, docker] + skills: [typescript/tsc-validation] + packages: ['@types/node'] +``` + +## Auto-Activation System + +### Overview + +Skills can auto-activate based on user prompts using the skill-rules.json system. This enables Claude to proactively suggest relevant skills before responding. + +**For complete details, see:** [SKILL_ACTIVATION_GUIDE.md](../../docs/SKILL_ACTIVATION_GUIDE.md) + +### When to Add Activation Rules + +Add skill-rules.json entries when: + +- Skill is part of a plugin (not project-local) +- Skill should auto-activate from specific keywords +- Skill addresses a common workflow pattern +- Skill is high-value and frequently needed + +**Skip activation rules for:** + +- One-off project-specific skills +- Rarely-used experimental skills +- Skills that should only run on explicit user request + +### Creating skill-rules.json Entries + +**For plugin developers:** Add entries to `plugins/{plugin}/skills/skill-rules.json` + +**Schema:** + +```json +{ + "plugin": { + "name": "plugin-name", + "version": "1.0.0", + "namespace": "namespace" + }, + "skills": { + "skill-name": { + "type": "domain", + "enforcement": "suggest", + "priority": "high", + "description": "Brief description of what the skill does", + "promptTriggers": { + "keywords": ["keyword1", "keyword2"], + "intentPatterns": ["pattern1", "pattern2"] + } + } + } +} +``` + +### Writing Good Keywords + +**✅ Good Keywords** (specific, unambiguous): + +```json +"keywords": [ + "create skill", + "new skill", + "skill template", + "generate skill", + "skill development" +] +``` + +**❌ Bad Keywords** (too generic): + +```json +"keywords": [ + "create", + "new", + "help", + "build" +] +``` + +**Rules for keywords:** + +- Minimum 2 words for specificity +- Include the domain (e.g., "skill", "hook", "component") +- Match how users naturally ask for help +- Case-insensitive literal matching +- No regex needed for keywords + +### Writing Good Intent Patterns + +**✅ Good Patterns** (capture intent, not exact wording): + +```json +"intentPatterns": [ + "(create|add|generate|build).*?skill", + "how to.*?(create|add|build).*?skill", + "skill.*?(template|generator|builder)", + "need.*?skill.*?(for|to)", + "(make|write).*?skill" +] +``` + +**❌ Bad Patterns** (too broad or too narrow): + +```json +"intentPatterns": [ + ".*skill.*", + "^create exactly this specific phrase$" +] +``` + +**Rules for patterns:** + +- Use regex with case-insensitive flag (`i`) +- Include action verbs: create, add, generate, build, make +- Include domain terms: skill, hook, component, etc. +- Use `.*?` for flexible matching between keywords +- Capture natural variations of the same intent + +### Priority Guidelines + +**critical** - Must run for safety/correctness: + +```json +"priority": "critical" +// Examples: security validators, syntax checkers +``` + +**high** - Highly recommended: + +```json +"priority": "high" +// Examples: skill-creator, component-generator +``` + +**medium** - Useful but optional: + +```json +"priority": "medium" +// Examples: documentation generators, formatters +``` + +**low** - Nice-to-have: + +```json +"priority": "low" +// Examples: experimental features, rarely-used tools +``` + +### Example: skill-creator Activation Rules + +```json +{ + "plugin": { + "name": "meta", + "version": "1.0.0", + "namespace": "claude" + }, + "skills": { + "skill-creator": { + "type": "domain", + "enforcement": "suggest", + "priority": "high", + "description": "Generate new Claude Code skills with proper structure and validation", + "promptTriggers": { + "keywords": [ + "create skill", + "new skill", + "skill development", + "generate skill", + "skill template" + ], + "intentPatterns": [ + "(create|add|generate|build).*?skill", + "how to.*?(create|add|build).*?skill", + "skill.*?(template|generator|builder)", + "need.*?skill.*?(for|to)", + "(make|write).*?skill" + ] + } + } + } +} +``` + +### Migration Tool + +Use `/generate-skill-rules` to auto-generate entries from existing SKILL.md YAML frontmatter: + +```sh +# Preview generated rules +/generate-skill-rules --plugin plugins/tanstack-tools --namespace tanstack + +# Write to skill-rules.json +/generate-skill-rules --plugin plugins/api-tools --namespace api --write +``` + +### Testing Activation Rules + +**Test in isolated project:** + +```sh +# 1. Create test project +mkdir test-activation && cd test-activation + +# 2. Copy hook and rules +mkdir -p .claude/hooks .claude/skills/your-plugin +cp {hook-path}/skill-activation-prompt.ts .claude/hooks/ +cp {plugin-path}/skill-rules.json .claude/skills/your-plugin/ + +# 3. Test with prompts +echo '{"prompt":"create a new skill","cwd":"'$(pwd)'"}' | \ + bun run .claude/hooks/skill-activation-prompt.ts +``` + +**Expected output:** + +```txt +============================================================ +SKILL ACTIVATION CHECK +============================================================ + +[RECOMMENDED] SKILLS: + -> skill-creator + +ACTION: Use Skill tool BEFORE responding +============================================================ +``` + +### Workflow: Adding Auto-Activation to New Skills + +When creating a skill that should auto-activate: + +1. **Create the SKILL.md** (as normal) + +2. **Identify triggers** by asking: + - What keywords would users type to need this skill? + - What questions or requests indicate this intent? + - How do users naturally express this need? + +3. **Add to skill-rules.json**: + + ```json + { + "skills": { + "new-skill": { + "type": "domain", + "enforcement": "suggest", + "priority": "high", + "description": "What the skill does", + "promptTriggers": { + "keywords": ["keyword1", "keyword2"], + "intentPatterns": ["pattern1", "pattern2"] + } + } + } + } + ``` + +4. **Test the triggers**: + - Try prompts that SHOULD activate it + - Try prompts that should NOT activate it + - Refine keywords/patterns based on results + +5. **Document in SKILL.md**: + + ```markdown + ## Auto-Activation + + This skill auto-activates when you mention: + + - Creating/generating {domain objects} + - Specific workflow requests + - Related keywords + + Triggered by: create skill, new skill, generate skill + ``` + +### Project-Level Overrides + +Users can customize activation in their projects via `.claude/skills/skill-rules.json`: + +```json +{ + "version": "1.0", + "overrides": { + "claude/skill-creator": { + "priority": "critical" + } + }, + "disabled": ["claude/skill-validator"], + "global": { + "maxSkillsPerPrompt": 3, + "priorityThreshold": "medium" + } +} +``` + +**Command for users:** `/workflow:configure` + +## Example: Creating a Project-Specific Skill + +**User Request:** +"Create a skill for generating Odyssey design system components" + +**Generated Skill:** + +Location: `/path/to/odyssey-project/.claude/skills/odyssey-components.md` + +```yaml +--- +name: odyssey-components +version: 1.0.0 +description: | + Generate components following Odyssey design system guidelines. + Ensures consistency with design tokens, patterns, and accessibility standards. +category: design-system +tags: [odyssey, components, design-system, react] +model: sonnet +requires: + tools: [npm] + packages: ["@odyssey/design-tokens", "@odyssey/components"] +triggers: + keywords: [odyssey, odyssey component, design system] + patterns: ["create.*odyssey", "generate.*odyssey"] +--- + +# Odyssey Components + +Generate React components that follow Odyssey design system standards. + +## When to Use + +- Creating new Odyssey components +- Ensuring design system compliance +- Maintaining consistency across products + +## Component Structure + +All components follow this pattern: + +\`\`\` +components/ + └── ComponentName/ + ├── ComponentName.tsx + ├── ComponentName.stories.tsx + ├── ComponentName.test.tsx + └── index.ts +\`\`\` + +## Design Token Usage + +Always use design tokens from `@odyssey/design-tokens`: + +\`\`\`typescript +import { tokens } from '@odyssey/design-tokens' + +const styles = { + color: tokens.color.primary.base, + spacing: tokens.spacing.md, + borderRadius: tokens.borderRadius.md +} +\`\`\` + +## Accessibility Requirements + +All components must: +- Meet WCAG AAA standards +- Include proper ARIA labels +- Support keyboard navigation +- Provide focus indicators + +## Example: Button Component + +[Detailed example following Odyssey patterns] +``` + +## Common Skill Patterns + +### API Client Generator + +```yaml +name: project-api-client +purpose: Generate type-safe API clients from OpenAPI schemas +includes: OpenAPI schema parsing, type generation, RPC helpers +location: project-local (for proprietary APIs) +``` + +### Component Library Helper + +```yaml +name: design-system-components +purpose: Generate components following project design system +includes: Component patterns, theme support, testing +location: project-local (for proprietary design systems) +``` + +### Database Schema Generator + +```yaml +name: drizzle-schema-from-db +purpose: Generate Drizzle schemas from existing Postgres database +includes: Type inference, relationship mapping, migration helpers +location: global (reusable across projects) +``` + +### Deployment Automation + +```yaml +name: coolify-deployment +purpose: Automate deployment to Coolify platform +includes: Docker config, environment setup, rollback procedures +location: global (reusable deployment pattern) +``` + +## Best Practices + +1. **Be Specific**: Don't create "helper" or "utility" skills - be explicit about what they do +2. **Include Examples**: Real, working examples - not placeholders +3. **Test First**: RED-GREEN-REFACTOR methodology ensures quality +4. **Token Efficiency**: Keep core content under 500 lines +5. **Clear Triggers**: Specific keywords that clearly indicate when to activate +6. **Validate**: Always check against Claude Code and Anthropic specs + +## Anti-Patterns to Avoid + +- ❌ Generic names ("helper", "utils", "tool") +- ❌ TODOs or placeholders in production +- ❌ Narrative examples tied to specific sessions +- ❌ Code embedded in flowcharts +- ❌ Missing activation triggers +- ❌ Over 500 lines without progressive disclosure +- ❌ Untested skills + +## Integration with Other Tools + +### shadcn CLI Integration + +```bash +# Generate skill that wraps shadcn commands +pnpm dlx shadcn@latest add [component] +pnpm dlx shadcn@latest add @coss/[component] +``` + +### Registry Support + +Skills can integrate with component registries: + +- shadcn/ui registry +- coss.com/ui registry +- Custom private registries + +## Troubleshooting + +### Skill Not Activating + +**Symptom**: Skill exists but doesn't trigger +**Solution**: + +- Check triggers section in YAML frontmatter +- Ensure keywords are specific enough +- Verify file is in correct location +- Check Claude Code loaded the skill (restart if needed) + +### Skill Too Generic + +**Symptom**: Skill triggers too often or in wrong contexts +**Solution**: + +- Make keywords more specific +- Add context restrictions +- Use regex patterns to narrow activation + +### Skill Too Large + +**Symptom**: Skill exceeds 500 lines +**Solution**: + +- Implement progressive disclosure +- Move advanced content to API_REFERENCE.md +- Keep core workflow in SKILL.md + +## References + +- [Claude Code Skills Documentation](https://docs.claude.com/en/docs/claude-code/skills) +- [Anthropic Best Practices](https://docs.claude.com/en/docs/claude-code) +- [obra/superpowers](https://github.com/obra/superpowers) - Community patterns +- [super-claude CREATING_SKILLS.md](../../docs/CREATING_SKILLS.md) - RED-GREEN-REFACTOR guide diff --git a/skills/skill-creator/templates/skill_template.md b/skills/skill-creator/templates/skill_template.md new file mode 100644 index 0000000..3223864 --- /dev/null +++ b/skills/skill-creator/templates/skill_template.md @@ -0,0 +1,196 @@ +--- +# ============================================================================ +# OFFICIAL CLAUDE CODE FIELDS (recognized by Claude Code) +# Reference: https://docs.claude.com/en/docs/claude-code/skills.md +# ============================================================================ + +name: skill-identifier # Required: kebab-case, unique identifier +description: | # Required: What it does AND when to activate it + Brief description of what this skill does and when to use it. + IMPORTANT: Include activation triggers in the description itself since + Claude Code only uses the description field for discovery. + + Examples: "Use when...", "Activates for...", "Helps with..." + Good: "Generate React components with TypeScript. Use when creating new UI components." + Bad: "Helps with components" (too vague) + +allowed-tools: [] # Optional: Restrict to specific tools +# Example: allowed-tools: [Read, Grep, Glob] # Read-only skill +# Available tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task, etc. + +# ============================================================================ +# EXTENDED METADATA (not used by Claude Code, but useful for humans/tooling) +# These fields are ignored by Claude Code but help with organization +# ============================================================================ + +version: 1.0.0 # Track changes since skills are files, not versioned packages +--- + +# Skill Name + +Brief overview of what this skill does (1-2 sentences maximum). + +## When to Use + +- User action or request that triggers this skill +- Specific scenario where this skill is helpful +- Problem this skill solves + +## Prerequisites + +- Required tools/setup (if any) +- Expected environment or configuration +- Dependencies that must be installed + +## Core Workflow + +### 1. Step One + +Description of first step with details. + +```bash +# Example command or code +example-command --flag value +``` + +### 2. Step Two + +Description of second step with examples. + +### 3. Step Three + +Final steps and completion criteria. + +## Best Practices + +- Practice 1: Why and when to apply it +- Practice 2: Common pitfall to avoid +- Practice 3: Optimization or efficiency tip + +## Example Workflows + +### Scenario 1: [Common Use Case] + +**User Request:** "Help me do X" + +**Steps:** + +1. First action +2. Second action +3. Expected outcome + +**Example:** + +```typescript +// Example code demonstrating the workflow +function example() { + // ... +} +``` + +### Scenario 2: [Advanced Use Case] + +**User Request:** "I need to handle Y edge case" + +**Steps:** + +1. Handle edge case +2. Validate result +3. Confirm success + +## Troubleshooting + +### Issue 1: Common Problem + +**Symptom:** What the user sees + +**Solution:** + +- Step 1 to fix +- Step 2 to verify +- Alternative approach if needed + +### Issue 2: Another Problem + +**Symptom:** What the user sees + +**Solution:** + +- How to resolve +- How to prevent in future + +## References + +- [Related Documentation](https://example.com) +- [Official Guide](https://example.com) +- [Community Resources](https://example.com) + +--- + +## Template Notes (Remove before publishing) + +### What Claude Code Actually Uses + +**Claude Code ONLY recognizes these fields:** + +- `name` - Skill identifier (required) +- `description` - What it does AND when to activate (required) +- `allowed-tools` - Tool restrictions (optional) + +**Extended metadata (ignored by Claude Code, but useful for humans):** + +- `version` - Track changes since skills are files, not versioned packages + +Note: Author info is in the plugin's `plugin.json`, not individual skill files. + +All activation hints, keywords, and patterns should go directly in the `description` field since that's the only field Claude Code uses for skill discovery. + +### File Organization + +Skills can have supporting files loaded progressively: + +```sh +skill-name/ +├── SKILL.md (this file, required) +├── reference.md (optional, advanced topics) +├── examples.md (optional, detailed examples) +├── scripts/ (optional, helper scripts) +└── templates/ (optional, code templates) +``` + +### Activation Best Practices + +**Claude Code only uses the `description` field for discovery!** + +Put ALL activation hints directly in the description: + +```yaml +description: | + Generate React components with TypeScript and Tailwind CSS. + Use when: creating new components, scaffolding UI elements, building design system. + Activates for: "create component", "new component", "generate component" +``` + +**Good description examples:** + +> "Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with .xlsx files or data analysis requests." +> +> "Refactor TypeScript imports, organize import statements, remove unused imports. Use when cleaning up imports or seeing import-related errors." + +**Bad description (too vague):** + +> "Helps with data" ❌ - No activation triggers, no use cases + +### Model Selection + +Claude Code automatically picks the appropriate model. The `model` field in YAML is ignored. + +### Tool Restrictions + +Use `allowed-tools` to create read-only or limited-permission skills: + +```yaml +allowed-tools: [Read, Grep, Glob] # Read-only, no file modifications +``` + +Available tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task, etc. diff --git a/skills/skill-rules.json b/skills/skill-rules.json new file mode 100644 index 0000000..7d2bc86 --- /dev/null +++ b/skills/skill-rules.json @@ -0,0 +1,147 @@ +{ + "plugin": { + "name": "meta", + "version": "1.0.0", + "namespace": "meta" + }, + + "skills": { + "skill-creator": { + "type": "domain", + "enforcement": "suggest", + "priority": "high", + "description": "Generate new Claude Code skills with proper structure and validation", + "promptTriggers": { + "keywords": [ + "create skill", + "new skill", + "skill development", + "generate skill", + "skill template" + ], + "intentPatterns": [ + "(create|add|generate|build).*?skill", + "how to.*?(create|add|build).*?skill", + "skill.*?(template|generator|builder)", + "need.*?skill.*?(for|to)", + "(make|write).*?skill" + ] + } + }, + + "hook-creator": { + "type": "domain", + "enforcement": "suggest", + "priority": "high", + "description": "Generate Claude Code hooks for workflow automation", + "promptTriggers": { + "keywords": [ + "create hook", + "new hook", + "hook development", + "generate hook", + "pre-commit", + "post-commit", + "hook automation" + ], + "intentPatterns": [ + "(create|add|generate|build).*?hook", + "how to.*?(create|add|build).*?hook", + "(pre|post)[-\\s](commit|push|merge)", + "hook.*?(template|generator|builder)", + "automat(e|ion).*?(before|after).*?(commit|push)" + ] + } + }, + + "command-creator": { + "type": "domain", + "enforcement": "suggest", + "priority": "high", + "description": "Generate slash commands for Claude Code", + "promptTriggers": { + "keywords": [ + "create command", + "new command", + "slash command", + "generate command", + "command development" + ], + "intentPatterns": [ + "(create|add|generate|build).*?command", + "how to.*?(create|add|build).*?command", + "slash.*?command", + "command.*?(template|generator|builder)", + "custom.*?command" + ] + } + }, + + "agent-creator": { + "type": "domain", + "enforcement": "suggest", + "priority": "high", + "description": "Generate specialized agents for complex tasks", + "promptTriggers": { + "keywords": [ + "create agent", + "new agent", + "agent development", + "generate agent", + "specialized agent" + ], + "intentPatterns": [ + "(create|add|generate|build).*?agent", + "how to.*?(create|add|build).*?agent", + "agent.*?(template|generator|builder)", + "specialized.*?agent", + "(task|workflow).*?agent" + ] + } + }, + + "plugin-creator": { + "type": "domain", + "enforcement": "suggest", + "priority": "high", + "description": "Generate new Claude Code plugin structure", + "promptTriggers": { + "keywords": [ + "create plugin", + "new plugin", + "plugin development", + "generate plugin", + "plugin structure" + ], + "intentPatterns": [ + "(create|add|generate|build).*?plugin", + "how to.*?(create|add|build).*?plugin", + "plugin.*?(template|generator|builder|scaffold)", + "new.*?marketplace.*?plugin" + ] + } + }, + + "skill-validator": { + "type": "domain", + "enforcement": "suggest", + "priority": "medium", + "description": "Validate skill files for correctness and best practices", + "promptTriggers": { + "keywords": [ + "validate skill", + "check skill", + "skill validation", + "verify skill", + "skill quality" + ], + "intentPatterns": [ + "(validate|check|verify|test).*?skill", + "skill.*?(valid|correct|quality|check)", + "is.*?skill.*?(valid|correct)", + "review.*?skill" + ] + } + } + } +} diff --git a/skills/skill-validator/SKILL.md b/skills/skill-validator/SKILL.md new file mode 100644 index 0000000..d9de5fe --- /dev/null +++ b/skills/skill-validator/SKILL.md @@ -0,0 +1,386 @@ +--- +name: skill-validator +version: 1.0.0 +description: | + Validate Claude Code skills, commands, agents, hooks, and plugins against specifications. + Checks structure, format, best practices, and common issues before committing or distributing. + Use when: validating skills, checking plugins, linting components, ensuring quality. + Activates for: "validate skill", "check skill", "validate plugin", "lint skill", "verify skill" +--- + +# Skill Validator + +Validate Claude Code components against specifications and best practices. + +## When to Use + +- Before committing skills/plugins +- Before distributing to marketplace +- During skill development (catch issues early) +- Reviewing community contributions +- Ensuring quality standards + +## Validation Checks + +### Skills (SKILL.md) + +#### Structure Checks + +- ✅ YAML frontmatter present and valid +- ✅ Required fields: name, version, description +- ✅ Name is kebab-case +- ✅ Version follows semantic versioning +- ✅ Description is clear and includes triggers + +#### Content Checks + +- ✅ Has "When to Use" section +- ✅ Has workflow or instructions +- ✅ Includes examples +- ✅ Under 500 lines (or has progressive disclosure) +- ✅ No TODOs or placeholders +- ✅ No generic labels (helper, util, tool) + +#### Best Practices + +- ✅ Specific triggers (not too generic) +- ✅ Real examples (not placeholders) +- ✅ Clear, actionable instructions +- ✅ Integration points documented +- ✅ Troubleshooting section present + +### Commands + +#### Structure Checks + +- ✅ YAML frontmatter with description +- ✅ Clear command name +- ✅ Usage examples provided +- ✅ Parameters documented + +#### Content Checks + +- ✅ Purpose is clear +- ✅ Instructions are actionable +- ✅ Examples show real usage +- ✅ Parameter descriptions complete + +### Agents + +#### Structure Checks + +- ✅ YAML frontmatter present +- ✅ Model specified (haiku/sonnet/opus) +- ✅ Purpose is clear +- ✅ Workflow defined + +#### Content Checks + +- ✅ Single responsibility +- ✅ Operational principles defined +- ✅ Quality standards specified +- ✅ Success criteria clear +- ✅ Appropriate model for task complexity + +### Hooks + +#### Structure Checks + +- ✅ Valid JSON format +- ✅ Event type is valid +- ✅ Command is specified +- ✅ Description provided + +#### Safety Checks + +- ✅ No arbitrary code execution +- ✅ File paths are validated +- ✅ Commands are safe +- ✅ Filters are specific (not too broad) + +### Plugins + +#### Structure Checks + +- ✅ `.claude-plugin/plugin.json` exists +- ✅ Valid JSON format +- ✅ Required fields present +- ✅ Referenced components exist +- ✅ Directory structure correct + +#### Manifest Checks + +- ✅ Name is kebab-case +- ✅ Version follows semver +- ✅ Description is clear +- ✅ Keywords are relevant +- ✅ Author info present (if distributing) + +## Core Workflow + +### 1. Identify Component Type + +Determine what to validate: + +- Skill (SKILL.md) +- Command (.md in commands/) +- Agent (.md in agents/) +- Hook (hooks.json) +- Plugin (entire plugin directory) + +### 2. Run Validation Checks + +Execute appropriate checks based on component type. + +### 3. Report Issues + +Categorize by severity: + +- **Error**: Must fix (prevents functionality) +- **Warning**: Should fix (best practice violation) +- **Info**: Consider fixing (minor improvement) + +### 4. Provide Fixes + +For each issue, provide: + +- Description of problem +- Why it's an issue +- How to fix it +- Code example if applicable + +## Validation Examples + +### Skill Validation + +**Input:** `skills/my-skill.md` + +**Checks:** + +```txt +✅ YAML frontmatter valid +✅ Name: my-skill (kebab-case) +✅ Version: 1.0.0 (semver) +✅ Description present +⚠️ No triggers defined +⚠️ Missing "When to Use" section +✅ Has examples +✅ 342 lines (under 500) +❌ Contains TODO on line 45 +❌ Uses generic label "helper" in title +``` + +**Report:** + +```txt +Errors (2): + 1. Line 45: TODO found - remove before publishing + 2. Line 12: Generic label "helper" - be more specific + +Warnings (2): + 1. No triggers defined - skill won't auto-activate + 2. Missing "When to Use" section - users won't know when to apply + +Info (0): + None + +Score: 6/10 - Fix errors before publishing +``` + +### Plugin Validation + +**Input:** `my-plugin/` + +**Checks:** + +```txt +✅ plugin.json exists +✅ Valid JSON +✅ Name: my-plugin +✅ Version: 1.0.0 +⚠️ No description +❌ Referenced skill "skill-1" not found in skills/ +✅ Directory structure correct +⚠️ No README.md +⚠️ No LICENSE file +``` + +**Report:** + +```txt +Errors (1): + 1. plugin.json references "skill-1" but skills/skill-1.md doesn't exist + +Warnings (3): + 1. plugin.json missing description field + 2. README.md not found - add documentation + 3. LICENSE file missing - add if distributing publicly + +Info (0): + None + +Score: 5/10 - Fix errors, address warnings +``` + +## Validation Rules + +### Severity Levels + +**Error (Must Fix):** + +- Invalid YAML/JSON syntax +- Missing required fields +- Referenced files don't exist +- TODOs in production code +- Security issues in hooks +- Invalid semantic version + +**Warning (Should Fix):** + +- Missing recommended fields +- No triggers (skill won't auto-activate) +- Missing documentation sections +- Generic/vague naming +- No examples +- No license (public distribution) + +**Info (Consider):** + +- Could improve clarity +- Additional documentation helpful +- Consider progressive disclosure (long skills) + +### Common Issues + +#### Generic Naming + +```txt +❌ my-helper +❌ utils-tool +❌ component-stuff + +✅ shadcn-component-generator +✅ drizzle-schema-generator +✅ tanstack-query-hook +``` + +#### Missing Triggers + +```yaml +❌ Missing entirely + +✅ triggers: + keywords: [specific, technical, terms] + patterns: ["regex.*patterns"] +``` + +#### TODOs in Production + +```markdown +❌ ## Feature X +TODO: Implement this later + +✅ ## Feature X +Complete implementation +``` + +#### Vague Descriptions + +```txt +❌ "Helps with things" +❌ "Utility for stuff" + +✅ "Generate type-safe API clients from OpenAPI schemas" +✅ "Validate React components for WCAG AAA accessibility" +``` + +## Validation Output Format + +```txt +Component: [name] +Type: [skill|command|agent|hook|plugin] +Location: [file path] + +Structure: [✅|⚠️|❌] +Content: [✅|⚠️|❌] +Best Practices: [✅|⚠️|❌] + +Errors (must fix): [count] + 1. [description] + 2. [description] + +Warnings (should fix): [count] + 1. [description] + 2. [description] + +Info (consider): [count] + 1. [description] + +Overall Score: [0-10] +Status: [Ready|Needs work|Not ready] + +Recommendations: + - [specific action 1] + - [specific action 2] +``` + +## Validation Best Practices + +1. **Validate Early**: Check during development, not just before publishing +2. **Fix Errors First**: Don't publish with errors +3. **Address Warnings**: They indicate best practice violations +4. **Review Info**: Consider suggestions for improvements +5. **Re-validate**: After fixes, validate again + +## Integration + +### With Hooks + +Auto-validate before commits: + +```json +{ + "name": "validate-before-commit", + "event": "user-prompt-submit", + "when": "before", + "command": "claude-validate --skills", + "filter": { + "promptPattern": "commit" + } +} +``` + +### With Commands + +Create validation command: + +```markdown +--- +description: Validate all skills in current plugin +--- + +# Validate Skills + +Run skill-validator on all SKILL.md files in current plugin. + +## Usage + +\`\`\` +/validate-skills +\`\`\` +``` + +### With CI/CD + +Add to GitHub Actions: + +```yaml +- name: Validate Skills + run: claude-validate --all --strict +``` + +## References + +- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code) +- [Anthropic Best Practices](https://docs.claude.com/en/docs/claude-code/best-practices) +- [super-claude CREATING_SKILLS.md](../../docs/CREATING_SKILLS.md)