diff --git a/home/dot_claude/skills/subagent-creator/SKILL.md b/home/dot_claude/skills/subagent-creator/SKILL.md new file mode 100644 index 0000000..3510e5e --- /dev/null +++ b/home/dot_claude/skills/subagent-creator/SKILL.md @@ -0,0 +1,364 @@ +--- +name: subagent-creator +description: Guide for creating Claude Code plugins including sub-agents, commands, skills, and hooks. Use when users want to create or modify Claude Code extensions, automation workflows, or specialized AI assistants. +--- + +# Subagent & Plugin Creator + +This skill provides guidance for extending Claude Code through sub-agents, commands, skills, and hooks. + +## Extension Types Overview + +Claude Code supports four primary extension types: + +1. **Sub-agents** - Specialized AI assistants with custom system prompts and tool access +2. **Commands** - User-invoked slash commands for explicit workflows +3. **Skills** - Model-invoked capabilities that Claude autonomously uses based on context +4. **Hooks** - Shell commands that execute automatically at lifecycle events + +## When to Use Each Type + +### Sub-agents +Create sub-agents when: +- Tasks require specialized expertise in a specific domain +- The workflow needs a different tool set than the main conversation +- Context isolation is beneficial (e.g., code review without polluting main context) +- Reusable specialized personas are valuable across projects + +### Commands +Create commands when: +- Users need explicit, repeatable workflows +- The task follows a predictable pattern (e.g., TDD workflow, gitingest) +- Direct user invocation is preferred over model decision +- The workflow is simple enough for a single markdown file + +### Skills +Create skills when: +- Claude should autonomously decide when to apply specialized knowledge +- Multiple supporting resources are needed (scripts, references, templates) +- Progressive disclosure of context is important +- The capability should be discoverable across conversations + +### Hooks +Create hooks when: +- Automation must happen at specific lifecycle points +- Deterministic behavior is required (not model-dependent) +- Integration with external tools is needed (formatters, linters, notifications) +- Enforcement of policies or conventions is necessary + +## Creating Sub-agents + +### Quick Creation Process + +1. Use `/agents` command to access the creation interface +2. Choose storage location: + - `.claude/agents/` for project-level (team-shared, version controlled) + - `~/.claude/agents/` for user-level (personal, cross-project) +3. Describe the sub-agent's purpose and when it should be used +4. Select available tools or inherit all tools from main conversation +5. Generate initial configuration with Claude's assistance +6. Customize the system prompt for specific requirements + +### File Structure + +Sub-agents use markdown files with YAML frontmatter: + +```markdown +--- +name: unique-lowercase-identifier +description: Natural language purpose statement that helps Claude decide when to delegate +tools: Read, Write, Bash, Grep, Glob # Optional: omit to inherit all tools +model: sonnet # Optional: specify 'sonnet', 'haiku', 'opus', or 'inherit' +skills: skill-name-1, skill-name-2 # Optional: auto-load specific skills +--- + +System prompt content here. This defines the sub-agent's expertise, +behavior, constraints, and workflow instructions. + +Use imperative/infinitive form for all instructions. +``` + +### Required Fields + +- `name` - Unique identifier using lowercase with hyphens +- `description` - Clear statement of purpose and usage context (critical for automatic delegation) + +### Optional Fields + +- `tools` - Comma-separated list restricting tool access (omit for full access) +- `model` - Specify model alias or use 'inherit' for parent's model +- `skills` - Comma-separated skill names to auto-load into sub-agent context + +### Storage Locations Priority + +1. Project agents: `.claude/agents/` (highest priority, team-shared) +2. User agents: `~/.claude/agents/` (personal, lower priority) +3. Plugin agents: Defined in plugin manifest + +### Best Practices for Sub-agents + +- **Single-purpose focus**: Create specialized sub-agents rather than multi-function ones +- **Detailed prompts**: Include specific instructions, examples, and constraints +- **Limit tool access**: Grant only necessary tools for security and performance +- **Clear descriptions**: Enable accurate automatic delegation with specific trigger scenarios +- **Version control**: Store project sub-agents in repositories for team collaboration + +### Invocation Methods + +**Automatic delegation**: Claude delegates based on task matching sub-agent description +**Explicit request**: "Use the code-reviewer sub-agent to check my recent changes" + +### Advanced Features + +- **Chaining**: Complex workflows can chain multiple sub-agents sequentially +- **Resumable**: Sub-agents receive unique IDs for continuation across sessions +- **Context preservation**: Each operates in isolated context, preventing main conversation pollution + +## Creating Commands + +### File Structure + +Commands are simple markdown files without YAML frontmatter: + +```markdown +Command instructions here using imperative form. + +Can reference $ARGUMENTS for user-provided parameters. + +Example: "Follow the Test-Driven Development workflow for implementing $ARGUMENTS." +``` + +### Storage Locations + +- Project commands: `.claude/commands/` +- User commands: `~/.claude/commands/` +- Plugin commands: `commands/` directory in plugin structure + +### Command Best Practices + +- Keep commands focused on single workflows +- Use clear, actionable language +- Reference $ARGUMENTS when user input is needed +- Include structured steps for complex workflows +- Test with various argument patterns + +### Examples + +See existing commands: +- `home/dot_claude/commands/tdd/tdd.md` - Test-driven development workflow +- `home/dot_claude/commands/gitingest/gitingest.md` - Repository ingestion + +## Creating Skills + +Skills are the most complex extension type, supporting bundled resources and progressive disclosure. + +### Core Structure + +``` +skill-name/ +├── SKILL.md (required) +│ ├── YAML frontmatter metadata +│ └── Markdown instructions +└── Bundled Resources (optional) + ├── scripts/ - Executable code + ├── references/ - Documentation loaded as needed + └── assets/ - Output templates and resources +``` + +### SKILL.md Format + +```markdown +--- +name: lowercase-with-hyphens (max 64 chars) +description: What it does and when to use it (max 1024 chars) - CRITICAL for discovery +allowed-tools: Read, Grep, Glob # Optional: restrict tool access +--- + +# Skill Name + +Purpose statement and overview. + +## When to Use This Skill + +Specific scenarios and trigger conditions. + +## How to Use + +Detailed instructions referencing any bundled resources. +``` + +### Bundled Resources + +**scripts/** - Executable code for deterministic reliability +- Use when same code is repeatedly rewritten +- Token efficient, may execute without loading into context +- Examples: `scripts/rotate_pdf.py`, `scripts/init_skill.py` + +**references/** - Documentation loaded as needed +- Use for schemas, API docs, domain knowledge, policies +- Keeps SKILL.md lean while maintaining discoverability +- Examples: `references/api_docs.md`, `references/schema.md` +- For large files (>10k words), include grep search patterns in SKILL.md + +**assets/** - Files used in output +- Use for templates, images, boilerplate, fonts +- Not loaded into context, used in final output +- Examples: `assets/logo.png`, `assets/template.html` + +### Storage Locations + +- Project skills: `.claude/skills/` (team-shared, version controlled) +- User skills: `~/.claude/skills/` (personal, cross-project) +- Plugin skills: `skills/` directory in plugin structure + +### Progressive Disclosure Design + +1. **Metadata** (name + description) - Always in context (~100 words) +2. **SKILL.md body** - When skill triggers (<5k words) +3. **Bundled resources** - As needed by Claude (unlimited) + +### Skills Best Practices + +- **Focused scope**: One capability per skill, not multi-function +- **Specific descriptions**: Include trigger terms and file types +- **Imperative form**: Use verb-first instructions throughout +- **Avoid duplication**: Information lives in SKILL.md OR references, not both +- **Test discovery**: Verify Claude activates skill for relevant queries + +### Skill Creation Workflow + +1. Understand concrete usage examples +2. Plan reusable resources (scripts, references, assets) +3. Initialize structure (or use `scripts/init_skill.py` if available) +4. Implement bundled resources first +5. Write SKILL.md with clear purpose and instructions +6. Test and iterate based on real usage + +## Creating Hooks + +Hooks provide deterministic automation at specific lifecycle points. + +### Available Hook Events + +- **PreToolUse** - Executes before tool calls, can block them +- **PermissionRequest** - Runs when permission dialogs appear +- **PostToolUse** - Executes after tool calls complete +- **UserPromptSubmit** - Runs when users submit prompts +- **Notification** - Triggers when Claude sends notifications +- **Stop** - Runs when Claude finishes responding +- **SubagentStop** - Executes when subagent tasks complete +- **PreCompact** - Runs before compaction operations +- **SessionStart** - Executes at session start or resumption +- **SessionEnd** - Triggers when sessions terminate + +### Common Use Cases + +- Automated code formatting (Prettier, gofmt, black) +- Command logging for compliance +- Custom permission controls for sensitive files +- Desktop notifications for user input requirements +- Automated feedback for code convention violations + +### Configuration Storage + +Hooks are configured in `~/.claude/settings.json` and can be scoped to: +- User level: Apply across all projects +- Project level: Apply only to specific project + +### Hook Format + +Hooks are shell commands that execute in the user's environment. They receive context through environment variables and stdin. + +### Security Considerations + +**CRITICAL**: Hooks run automatically with current environment credentials. Review all hook code thoroughly before registration to prevent: +- Data exfiltration +- Credential exposure +- Unintended system modifications + +Only install hooks from trusted sources. + +### Hooks Best Practices + +- Keep hooks idempotent +- Handle errors gracefully +- Log appropriately for debugging +- Test in isolated environment first +- Document hook purpose and behavior +- Minimize execution time to avoid latency + +## Plugin Structure + +For distributing multiple extensions together, use the plugin system: + +``` +plugin-name/ +├── .claude-plugin/ +│ └── plugin.json # Metadata descriptor +├── commands/ # Slash commands (optional) +├── agents/ # Sub-agents (optional) +├── skills/ # Agent skills (optional) +└── hooks/ + └── hooks.json # Event handlers (optional) +``` + +### Plugin Development Workflow + +1. Create plugin structure with desired components +2. Use local test marketplace during development +3. Install with `/plugin install` +4. Iterate through uninstall/reinstall cycles +5. Share via plugin marketplace or git repository + +## Writing Style Guidelines + +**All extension content should use imperative/infinitive form:** +- ✓ "To accomplish X, do Y" +- ✓ "Execute command to achieve result" +- ✗ "You should do X" +- ✗ "If you need to do X" + +Use objective, instructional language for AI consumption. + +## Storage Location Decision Matrix + +| Extension Type | Project-Level | User-Level | +|---------------|---------------|------------| +| Sub-agents | `.claude/agents/` | `~/.claude/agents/` | +| Commands | `.claude/commands/` | `~/.claude/commands/` | +| Skills | `.claude/skills/` | `~/.claude/skills/` | +| Hooks | Project settings.json | `~/.claude/settings.json` | + +**Choose project-level when:** +- Team collaboration is required +- Version control is beneficial +- Project-specific expertise is needed + +**Choose user-level when:** +- Personal workflows are being automated +- Cross-project reuse is desired +- Experimental or temporary extensions + +## Troubleshooting + +### Sub-agents Not Being Used +- Verify description is specific enough for automatic delegation +- Check file naming and location +- Validate YAML frontmatter syntax + +### Skills Not Activating +- Make description more specific with concrete trigger scenarios +- Include file types and operations in description +- Verify correct file path and valid YAML syntax +- Check for proper YAML delimiters + +### Commands Not Found +- Verify file is in correct directory +- Check command name matches file/directory name +- Ensure markdown syntax is valid + +### Hooks Not Executing +- Verify event name matches available hook events +- Check shell command syntax and permissions +- Review security restrictions +- Test command independently first