Initial commit

2025-11-29 18:16:51 +08:00
commit 4e8a12140c
88 changed files with 17078 additions and 0 deletions
--- a/skills/sub-agent-creator/README.md
+++ b/skills/sub-agent-creator/README.md
@@ -0,0 +1,243 @@
+# Sub-Agent Creator
+
+Automates creation of Claude Code sub-agents following Anthropic's official patterns, with proper frontmatter, tool configuration, and system prompts.
+
+## Overview
+
+This skill guides users through creating production-ready sub-agents for Claude Code. It handles:
+- YAML frontmatter generation with required fields (`name`, `description`)
+- Tool permission configuration (security-focused minimal access)
+- Model selection (inherit, sonnet, opus, haiku)
+- System prompt structuring with role, approach, and constraints
+- Validation and testing guidance
+
+## When to Use
+
+Use this skill when you need to:
+- Create specialized sub-agents for specific tasks (code review, debugging, data analysis)
+- Set up proactive agents that auto-trigger on task patterns
+- Configure secure tool permissions for agents
+- Build team-shared project-level agents (`.claude/agents/`)
+- Create personal user-level agents (`~/.claude/agents/`)
+
+## Trigger Phrases
+
+- "create a sub-agent for [purpose]"
+- "generate a new sub-agent"
+- "set up a sub-agent to handle [task]"
+- "build a specialized agent for [domain]"
+- "help me create a sub-agent"
+- "make a proactive agent that [behavior]"
+
+## Features
+
+### Interactive Workflow
+Guides you through 5 phases:
+1. **Information Gathering** - Purpose, name, description, location
+2. **Technical Configuration** - Model, tools, system prompt components
+3. **File Generation** - Create properly formatted sub-agent file
+4. **Validation & Testing** - Verify configuration and provide test instructions
+5. **Next Steps** - Guidance on refinement and best practices
+
+### Security-First Tool Configuration
+- Defaults to minimal tool access
+- Warns about overly broad permissions
+- Recommends read-only tools for analysis agents
+- Requires explicit confirmation for "all tools" access
+
+### Official Pattern Compliance
+- Follows Anthropic's sub-agent specification exactly
+- Proper YAML frontmatter with required fields
+- Correct storage locations (project vs. user level)
+- Proactive description patterns for auto-delegation
+
+### Reference Materials
+Includes examples of production-ready sub-agents:
+- **code-reviewer** - Code quality, security, maintainability analysis
+- **debugger** - Root cause analysis and error resolution
+- **data-scientist** - SQL queries, statistical analysis, data visualization
+
+## Prerequisites
+
+None - this skill works in any project or environment. Sub-agents are created as standalone markdown files.
+
+## Installation
+
+This skill is available in the **claudex** marketplace.
+
+### Local Installation (for development)
+```bash
+# Copy to local skills directory
+cp -r sub-agent-creator ~/.claude/skills/
+
+# Verify installation
+ls ~/.claude/skills/sub-agent-creator/SKILL.md
+```
+
+### Marketplace Installation
+```json
+// .claude/settings.json
+{
+  "extraKnownMarketplaces": {
+    "claudex": {
+      "source": {
+        "source": "github",
+        "repo": "cskiro/claudex"
+      }
+    }
+  },
+  "enabledPlugins": [
+    "sub-agent-creator@claudex"
+  ]
+}
+```
+
+## Usage Examples
+
+### Example 1: Create a Code Reviewer
+
+**User:** "Create a sub-agent for code review"
+
+**Skill guides you through:**
+1. Name suggestion: `code-reviewer`
+2. Description: "Use PROACTIVELY to review code quality after significant changes"
+3. Location: Project-level (`.claude/agents/`) for team sharing
+4. Model: `inherit` (consistent with main session)
+5. Tools: `Read, Grep, Glob, Bash` (read + search + execution)
+6. System prompt: Focus on security, maintainability, best practices
+
+**Result:** `.claude/agents/code-reviewer.md` ready to use
+
+---
+
+### Example 2: Create a Data Analysis Agent
+
+**User:** "Set up a sub-agent to handle SQL queries"
+
+**Skill guides you through:**
+1. Name: `data-scientist`
+2. Description: "Use PROACTIVELY when data analysis or SQL queries are requested"
+3. Location: User-level (`~/.claude/agents/`) for personal use across projects
+4. Model: `sonnet` (balanced performance for data tasks)
+5. Tools: `Read, Write, Bash, Grep, Glob` (data access + output generation)
+6. System prompt: SQL expertise, statistical analysis, visualization recommendations
+
+**Result:** `~/.claude/agents/data-scientist.md` ready to use
+
+---
+
+### Example 3: Create a Debugging Specialist
+
+**User:** "Build a specialized agent for debugging test failures"
+
+**Skill guides you through:**
+1. Name: `debugger`
+2. Description: "Use PROACTIVELY when tests fail or errors occur"
+3. Location: Project-level for team consistency
+4. Model: `inherit`
+5. Tools: `Read, Edit, Bash, Grep, Glob` (investigate + fix)
+6. System prompt: Root cause analysis, hypothesis testing, minimal fixes
+
+**Result:** `.claude/agents/debugger.md` ready to use
+
+## File Structure
+
+```
+sub-agent-creator/
+├── SKILL.md              # Main skill manifest
+├── README.md             # This file
+├── CHANGELOG.md          # Version history
+├── data/
+│   ├── models.yaml       # Available model options with guidance
+│   └── tools.yaml        # Available tools with security notes
+├── templates/
+│   └── agent-template.md # System prompt structure template
+└── examples/
+    ├── code-reviewer.md  # Example: Code review sub-agent
+    ├── debugger.md       # Example: Debugging sub-agent
+    └── data-scientist.md # Example: Data analysis sub-agent
+```
+
+## Configuration
+
+No configuration required - skill works out of the box.
+
+## Best Practices
+
+1. **Start with Minimal Tools** - Grant only necessary capabilities, expand as needed
+2. **Use "PROACTIVELY" in Descriptions** - Enables automatic delegation
+3. **Be Specific in System Prompts** - Include concrete examples and edge cases
+4. **Test Before Deploy** - Verify agent loads and behaves correctly
+5. **Iterate Based on Usage** - Refine after observing real-world behavior
+6. **Document for Teams** - Project-level agents need clear usage guidance
+
+## Validation
+
+The skill performs these validation checks:
+- ✅ YAML frontmatter is valid
+- ✅ Required fields present (`name`, `description`)
+- ✅ Tools list is valid (if specified)
+- ✅ Model value is valid (if specified)
+- ✅ No security issues (exposed secrets, overly broad permissions)
+- ✅ Description is specific enough for auto-delegation
+
+## Troubleshooting
+
+### Agent doesn't load
+```bash
+# Check YAML syntax
+cat ~/.claude/agents/agent-name.md | head -10
+
+# Verify frontmatter
+# Should show:
+---
+name: agent-name
+description: ...
+---
+```
+
+### Agent has incorrect tools
+Edit the agent file and update the `tools:` field:
+```yaml
+---
+name: my-agent
+description: ...
+tools: Read, Grep, Glob  # Add/remove tools here
+---
+```
+
+### Agent triggers too aggressively
+Refine the `description` field to be more specific:
+```yaml
+# Too broad
+description: Use for code analysis
+
+# Better
+description: Use PROACTIVELY to analyze code quality when reviewing pull requests
+```
+
+## Official Resources
+
+- **Anthropic Sub-Agent Docs:** https://docs.claude.com/en/docs/claude-code/sub-agents
+- **Claude Code Documentation:** https://docs.claude.com
+- **Claudex Marketplace:** https://github.com/cskiro/claudex
+
+## Contributing
+
+Found a bug or have a feature request? Open an issue in the [claudex repository](https://github.com/cskiro/claudex/issues).
+
+## License
+
+MIT License - see [LICENSE](https://github.com/cskiro/claudex/blob/main/LICENSE) for details.
+
+## Version
+
+**Current Version:** 0.1.0
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history and updates.
+
+---
+
+**Maintained by:** Connor
+**Status:** Proof of Concept
+**Last Updated:** 2025-11-02