building-agents — Skillopedia

Building Agents Skill You are an expert at creating Claude Code agents (subagents). Agents are specialized assistants that handle delegated tasks with independent context and dedicated resources. When to Create an Agent vs Other Components Use an AGENT when: - The task requires specialized, focused expertise - You need independent context and isolation from the main conversation - The task involves heavy computation or long-running operations - You want explicit invocation rather than automatic activation - The task benefits from dedicated tool permissions Use a SKILL instead when: - You want…

, name):\n errors.append(f\"Invalid name '{name}': must be lowercase letters, numbers, and hyphens only\")\n\n # Validate name length\n if len(name) > 64:\n errors.append(f\"Invalid name '{name}': exceeds 64 character limit (length: {len(name)})\")\n\n # Check for underscores\n if '_' in name:\n errors.append(f\"Invalid name '{name}': underscores not allowed, use hyphens instead\")\n\n # Check for uppercase\n if name != name.lower():\n errors.append(f\"Invalid name '{name}': must be lowercase\")\n\n if 'description' not in frontmatter:\n errors.append(\"Missing required field: 'description'\")\n else:\n description = frontmatter['description']\n\n # Validate description length\n if len(description) > 1024:\n errors.append(f\"Description too long: {len(description)} characters (max 1024)\")\n\n # Warn if description is too short\n if len(description) \u003c 20:\n errors.append(f\"Warning: Description is very short ({len(description)} chars). Consider adding more detail about when to use this agent.\")\n\n # Validate capabilities field (recommended)\n if 'capabilities' not in frontmatter:\n errors.append(\"Recommendation: Add 'capabilities' field listing specialized tasks this agent can perform (e.g., capabilities: [\\\"task1\\\", \\\"task2\\\"])\")\n else:\n capabilities = frontmatter['capabilities']\n\n # Validate capabilities is a list\n if not isinstance(capabilities, list):\n errors.append(f\"Invalid capabilities field: must be an array (e.g., [\\\"task1\\\", \\\"task2\\\"])\")\n else:\n # Validate each capability is a string\n for i, cap in enumerate(capabilities):\n if not isinstance(cap, str):\n errors.append(f\"Invalid capability at index {i}: must be a string\")\n elif len(cap.strip()) == 0:\n errors.append(f\"Invalid capability at index {i}: cannot be empty\")\n # Recommend kebab-case format\n elif not re.match(r'^[a-z0-9-]+

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

, cap):\n errors.append(f\"Recommendation: Capability '{cap}' should use kebab-case (lowercase with hyphens)\")\n\n # Warn if too many capabilities\n if len(capabilities) > 10:\n errors.append(f\"Warning: {len(capabilities)} capabilities listed. Consider keeping it focused (3-7 is ideal)\")\n\n # Warn if no capabilities\n if len(capabilities) == 0:\n errors.append(\"Warning: Capabilities array is empty. Add task descriptions to help Claude understand when to invoke this agent.\")\n\n # Validate optional fields\n if 'tools' in frontmatter:\n tools = frontmatter['tools']\n valid_tools = [\n 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'Bash',\n 'WebFetch', 'WebSearch', 'NotebookEdit', 'Task',\n 'TodoWrite', 'BashOutput', 'KillShell'\n ]\n\n if isinstance(tools, str):\n tool_list = [t.strip() for t in tools.split(',')]\n for tool in tool_list:\n if tool not in valid_tools:\n errors.append(f\"Warning: Unknown tool '{tool}'. Valid tools: {', '.join(valid_tools)}\")\n\n # Warn about Task tool in agents (subagents can't spawn subagents)\n if 'Task' in tool_list:\n errors.append(\"Warning: Agent has 'Task' tool but subagents cannot spawn other subagents. Consider removing Task or using a skill for orchestration patterns.\")\n\n if 'model' in frontmatter:\n model = frontmatter['model']\n valid_models = ['sonnet', 'opus', 'haiku', 'inherit']\n if model not in valid_models:\n errors.append(f\"Invalid model '{model}'. Valid models: {', '.join(valid_models)}\")\n\n # Validate color field (optional but recommended)\n if 'color' in frontmatter:\n color = frontmatter['color']\n # Validate hex color format: #RRGGBB\n if not isinstance(color, str):\n errors.append(f\"Invalid color type: must be a string (e.g., \\\"#3498DB\\\")\")\n elif not re.match(r'^#[0-9A-Fa-f]{6}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

, color):\n errors.append(f\"Invalid color format '{color}': must be 6-digit hex with # prefix (e.g., \\\"#3498DB\\\")\")\n else:\n errors.append(\"Recommendation: Add 'color' field for visual identification in terminal (e.g., color: \\\"#3498DB\\\")\")\n\n # Check for body content\n body = content[match.end():]\n if len(body.strip()) \u003c 100:\n errors.append(\"Warning: Agent body is very short. Consider adding more detailed instructions, examples, and guidelines.\")\n\n # Check for common sections\n if '## Your Capabilities' not in body and '## Capabilities' not in body:\n errors.append(\"Recommendation: Add a capabilities section to document what the agent can do\")\n\n if '## Your Workflow' not in body and '## Workflow' not in body:\n errors.append(\"Recommendation: Add a workflow section to document the agent's process\")\n\n return len(errors) == 0, errors\n\n\ndef main():\n if len(sys.argv) \u003c 2:\n print(\"Usage: validate-agent.py \u003cagent-file.md>\")\n sys.exit(1)\n\n agent_file = sys.argv[1]\n is_valid, errors = validate_agent(agent_file)\n\n if is_valid:\n print(f\"✓ Agent '{agent_file}' is valid!\")\n sys.exit(0)\n else:\n print(f\"✗ Agent '{agent_file}' has validation issues:\\n\")\n for error in errors:\n if error.startswith(\"Warning:\") or error.startswith(\"Recommendation:\"):\n print(f\" ⚠️ {error}\")\n else:\n print(f\" ❌ {error}\")\n\n # Exit with error only for critical issues (not warnings)\n critical_errors = [e for e in errors if not (e.startswith(\"Warning:\") or e.startswith(\"Recommendation:\"))]\n sys.exit(1 if critical_errors else 0)\n\n\nif __name__ == '__main__':\n main()\n","content_type":"text/x-python; charset=utf-8","language":"python","size":7374,"content_sha256":"48338c94becec6883b81b0b5b81477596d7c3c691f016074d51fcccdb1d083c2"},{"filename":"skill-report.json","content":"{\n \"schema_version\": \"2.0\",\n \"meta\": {\n \"generated_at\": \"2026-01-16T19:42:17.172Z\",\n \"slug\": \"c0ntr0lledcha0s-building-agents\",\n \"source_url\": \"https://github.com/C0ntr0lledCha0s/claude-code-plugin-automations/tree/main/agent-builder/skills/building-agents\",\n \"source_ref\": \"main\",\n \"model\": \"claude\",\n \"analysis_version\": \"3.0.0\",\n \"source_type\": \"community\",\n \"content_hash\": \"8fb547fbe6c624fac4be0cc2d4c35fedd7f401aa5d3dd33d0283afb6be1854e6\",\n \"tree_hash\": \"1e7be0dbb7d2e0689a060418a756a19f1d59a96463d4bb4405dd4ee558f58a09\"\n },\n \"skill\": {\n \"name\": \"building-agents\",\n \"description\": \"Expert at creating and modifying Claude Code agents (subagents). Auto-invokes when the user wants to create, update, modify, enhance, validate, or standardize agents, or when modifying agent YAML frontmatter fields (especially 'model', 'tools', 'description'), needs help designing agent architecture, or wants to understand agent capabilities. Also auto-invokes proactively when Claude is about to write agent files (*/agents/*.md), create modular agent architectures, or implement tasks that involve creating agent components.\",\n \"summary\": \"Expert at creating and modifying Claude Code agents (subagents). Auto-invokes when the user wants to...\",\n \"icon\": \"🤖\",\n \"version\": \"2.0.0\",\n \"author\": \"C0ntr0lledCha0s\",\n \"license\": \"MIT\",\n \"category\": \"coding\",\n \"tags\": [\n \"agent-builder\",\n \"claude-code\",\n \"automation\",\n \"subagent\",\n \"code-generation\"\n ],\n \"supported_tools\": [\n \"claude\",\n \"claude-code\"\n ],\n \"risk_factors\": [\n \"scripts\",\n \"filesystem\",\n \"external_commands\"\n ]\n },\n \"security_audit\": {\n \"risk_level\": \"low\",\n \"is_blocked\": false,\n \"safe_to_publish\": true,\n \"summary\": \"Pure prompt-based skill for Claude Code agent creation. Static findings are false positives: hex color codes misidentified as MD5 hashes, markdown code blocks misidentified as shell backticks, and CLI command examples misidentified as reconnaissance. The skill includes a Python validation script that safely reads user-specified files without network access or credential handling.\",\n \"risk_factor_evidence\": [\n {\n \"factor\": \"scripts\",\n \"evidence\": [\n {\n \"file\": \"scripts/validate-agent.py\",\n \"line_start\": 1,\n \"line_end\": 188\n }\n ]\n },\n {\n \"factor\": \"filesystem\",\n \"evidence\": [\n {\n \"file\": \"SKILL.md\",\n \"line_start\": 33,\n \"line_end\": 35\n }\n ]\n },\n {\n \"factor\": \"external_commands\",\n \"evidence\": [\n {\n \"file\": \"SKILL.md\",\n \"line_start\": 441,\n \"line_end\": 451\n }\n ]\n }\n ],\n \"critical_findings\": [],\n \"high_findings\": [],\n \"medium_findings\": [],\n \"low_findings\": [\n {\n \"title\": \"Bash tool in allowed-tools\",\n \"description\": \"The skill declares Bash in allowed-tools for running validation scripts. This is documented, expected behavior for an agent-builder skill, and runs within Claude Code's sandbox.\",\n \"locations\": [\n {\n \"file\": \"SKILL.md\",\n \"line_start\": 5,\n \"line_end\": 5\n }\n ]\n }\n ],\n \"dangerous_patterns\": [],\n \"files_scanned\": 9,\n \"total_lines\": 3548,\n \"audit_model\": \"claude\",\n \"audited_at\": \"2026-01-16T19:42:17.172Z\"\n },\n \"content\": {\n \"user_title\": \"Create Claude Code agents\",\n \"value_statement\": \"Building Claude Code agents requires understanding schema standards, security best practices, and proper tool configuration. This skill provides expert guidance for creating robust, secure agents following established patterns and includes validation to ensure quality before deployment.\",\n \"seo_keywords\": [\n \"claude-code agent builder\",\n \"create claude agents\",\n \"agent development\",\n \"subagent creation\",\n \"claude code automation\",\n \"agent schema\",\n \"claude agent templates\",\n \"agent validation\",\n \"claude code\",\n \"agent builder\"\n ],\n \"actual_capabilities\": [\n \"Design agent architecture with proper YAML frontmatter and markdown body structure\",\n \"Apply naming conventions, tool permissions, and model selection best practices\",\n \"Create agents using comprehensive templates with examples and error handling\",\n \"Validate agents using the included Python validation script for schema compliance\",\n \"Migrate existing agents to current schema standards with update patterns\"\n ],\n \"limitations\": [\n \"Cannot invoke the Task tool from within agents (subagent architectural limitation)\",\n \"Does not generate agent code beyond providing templates and patterns\",\n \"Validation script only checks schema, not runtime behavior or output quality\"\n ],\n \"use_cases\": [\n {\n \"target_user\": \"Plugin Developers\",\n \"title\": \"Build plugin agents\",\n \"description\": \"Create specialized agents for your plugin following established patterns, colors, and schema conventions\"\n },\n {\n \"target_user\": \"Team Leads\",\n \"title\": \"Standardize agent quality\",\n \"description\": \"Ensure all team agents meet schema compliance, security standards, and documentation requirements\"\n },\n {\n \"target_user\": \"Power Users\",\n \"title\": \"Extend Claude capabilities\",\n \"description\": \"Create custom subagents for specific domains like code review, security analysis, or documentation\"\n }\n ],\n \"prompt_templates\": [\n {\n \"title\": \"Create new agent\",\n \"scenario\": \"Need a specialized subagent\",\n \"prompt\": \"Create a new agent named code-reviewer with blue color theme. It should review code for bugs and security issues. Use Read, Grep, Glob tools and sonnet model.\"\n },\n {\n \"title\": \"Review existing agent\",\n \"scenario\": \"Check agent quality\",\n \"prompt\": \"Review the security-auditor agent using the agent checklist. Check schema compliance, security, and content quality. Provide a score and recommendations.\"\n },\n {\n \"title\": \"Migrate old agent\",\n \"scenario\": \"Update legacy agent\",\n \"prompt\": \"Migrate my-agent.md from old schema to current standards. Check validation status and apply update patterns for tool permissions and description clarity.\"\n },\n {\n \"title\": \"Generate from template\",\n \"scenario\": \"Quick agent scaffold\",\n \"prompt\": \"Generate a new agent file using the agent template. Name it test-runner with red color. It should execute tests and report results. Include Bash tool for running test commands.\"\n }\n ],\n \"output_examples\": [\n {\n \"input\": \"Create a new agent for code review\",\n \"output\": [\n \"Agent created: code-reviewer\",\n \"Color: #3498DB (Blue - analysis domain)\",\n \"Tools: Read, Grep, Glob (minimal, read-only)\",\n \"Model: sonnet (balanced performance)\",\n \"Next steps: Run validation with python3 scripts/validate-agent.py\"\n ]\n },\n {\n \"input\": \"Review my existing agent against best practices\",\n \"output\": [\n \"Schema compliance: Passed\",\n \"Naming: Passed (lowercase-hyphens, 12 chars)\",\n \"Tools: Warning - Bash included without input validation guidance\",\n \"Documentation: Passed (capabilities and workflow sections present)\",\n \"Recommendation: Add input validation section or remove Bash from tools\"\n ]\n }\n ],\n \"best_practices\": [\n \"Start with minimal tool permissions and add only when necessary\",\n \"Use the validation script before committing agents to catch schema issues\",\n \"Follow domain color conventions for visual consistency across related agents\"\n ],\n \"anti_patterns\": [\n \"Including Task tool in agents (subagents cannot spawn other subagents)\",\n \"Over-permissioning tools like granting Bash without input validation\",\n \"Creating agents with vague descriptions that do not specify when to invoke\"\n ],\n \"faq\": [\n {\n \"question\": \"What tools should I grant to my agent?\",\n \"answer\": \"Start minimal with Read, Grep, Glob. Add Write/Edit only for file modification. Include Bash only for test execution or system operations. Always validate inputs when Bash is enabled.\"\n },\n {\n \"question\": \"Can agents spawn other agents?\",\n \"answer\": \"No. Subagents cannot use the Task tool. For orchestration, create a skill instead (skills run in the main thread and can use Task).\"\n },\n {\n \"question\": \"How do I validate an agent?\",\n \"answer\": \"Run the validation script: python3 agent-builder/skills/building-agents/scripts/validate-agent.py path/to/agent.md. It checks YAML syntax, naming conventions, required fields, and tool permissions.\"\n },\n {\n \"question\": \"Is my data safe with this skill?\",\n \"answer\": \"Yes. The skill only accesses files you specify. The validation script uses safe YAML parsing and does not make network requests or collect sensitive data.\"\n },\n {\n \"question\": \"How is this different from skills or commands?\",\n \"answer\": \"Agents are specialized subagents with independent context, invoked explicitly via Task. Skills auto-invoke based on context. Commands are user-triggered workflows with parameters.\"\n },\n {\n \"question\": \"What model should I choose?\",\n \"answer\": \"Use haiku for simple tasks (search, summaries), sonnet for most tasks (balanced), opus for complex reasoning. Match model complexity to the task requirements.\"\n }\n ]\n },\n \"file_structure\": [\n {\n \"name\": \"references\",\n \"type\": \"dir\",\n \"path\": \"references\",\n \"children\": [\n {\n \"name\": \"agent-examples.md\",\n \"type\": \"file\",\n \"path\": \"references/agent-examples.md\",\n \"lines\": 411\n },\n {\n \"name\": \"agent-update-patterns.md\",\n \"type\": \"file\",\n \"path\": \"references/agent-update-patterns.md\",\n \"lines\": 640\n },\n {\n \"name\": \"color-palette.md\",\n \"type\": \"file\",\n \"path\": \"references/color-palette.md\",\n \"lines\": 179\n },\n {\n \"name\": \"migration-guide.md\",\n \"type\": \"file\",\n \"path\": \"references/migration-guide.md\",\n \"lines\": 725\n }\n ]\n },\n {\n \"name\": \"scripts\",\n \"type\": \"dir\",\n \"path\": \"scripts\",\n \"children\": [\n {\n \"name\": \"validate-agent.py\",\n \"type\": \"file\",\n \"path\": \"scripts/validate-agent.py\",\n \"lines\": 188\n }\n ]\n },\n {\n \"name\": \"templates\",\n \"type\": \"dir\",\n \"path\": \"templates\",\n \"children\": [\n {\n \"name\": \"agent-checklist.md\",\n \"type\": \"file\",\n \"path\": \"templates/agent-checklist.md\",\n \"lines\": 418\n },\n {\n \"name\": \"agent-template.md\",\n \"type\": \"file\",\n \"path\": \"templates/agent-template.md\",\n \"lines\": 192\n }\n ]\n },\n {\n \"name\": \"SKILL.md\",\n \"type\": \"file\",\n \"path\": \"SKILL.md\",\n \"lines\": 514\n }\n ]\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":11429,"content_sha256":"de15d92b44dfb1a554a2392d3b71bb63c72f03112a50508d2b4e550f751071e4"},{"filename":"templates/agent-checklist.md","content":"# Agent Quality Checklist\n\nUse this checklist to review agent quality before deployment or during maintenance reviews.\n\n---\n\n## Quick Assessment\n\n**Agent Name**: ________________\n**Review Date**: ________________\n**Reviewer**: ________________\n**Overall Score**: _____ / 10\n\n---\n\n## 1. Schema Compliance (10 points)\n\n### Required Fields\n- [ ] **Name** present and valid (2 pts)\n - [ ] Lowercase letters, numbers, hyphens only\n - [ ] Max 64 characters\n - [ ] Descriptive and unique\n\n- [ ] **Description** present and clear (3 pts)\n - [ ] Under 1024 characters\n - [ ] Explains what agent does\n - [ ] Specifies when to invoke\n - [ ] Actionable and specific\n\n### Optional Fields\n- [ ] **Tools** specified appropriately (3 pts)\n - [ ] Minimal necessary permissions\n - [ ] No unnecessary tools\n - [ ] Properly comma-separated\n\n- [ ] **Model** selection is appropriate (2 pts)\n - [ ] Uses version alias (haiku/sonnet/opus) OR specific version\n - [ ] Matches task complexity\n - [ ] Cost-effective choice\n\n### Format\n- [ ] **YAML frontmatter** valid\n - [ ] Starts with `---`\n - [ ] Valid YAML syntax\n - [ ] Ends with `---`\n - [ ] Followed by markdown body\n\n**Schema Score**: _____ / 10\n\n---\n\n## 2. Security (10 points)\n\n### Tool Permissions\n- [ ] **Minimal permissions** (3 pts)\n - [ ] Only grants necessary tools\n - [ ] No over-permissioning\n - [ ] Removes unused tools\n\n- [ ] **Bash access** (if applicable) (3 pts)\n - [ ] Justified need for Bash\n - [ ] Input validation documented\n - [ ] Command injection prevention\n - [ ] Proper escaping/quoting\n\n- [ ] **Write permissions** (if applicable) (2 pts)\n - [ ] Justified need for Write/Edit\n - [ ] File validation documented\n - [ ] No arbitrary file writes\n\n### Security Patterns\n- [ ] **No hardcoded secrets** (2 pts)\n - [ ] No API keys in agent body\n - [ ] No passwords or tokens\n - [ ] Uses environment variables\n\n**Security Score**: _____ / 10\n\n**Critical Issues** (must fix before deployment):\n- [ ] None identified\n- [ ] Issues listed below:\n\n---\n\n## 3. Content Quality (10 points)\n\n### Core Sections\n- [ ] **Role definition** clear (2 pts)\n - [ ] \"You are...\" statement present\n - [ ] Expertise area specified\n - [ ] Boundaries defined\n\n- [ ] **Capabilities** documented (2 pts)\n - [ ] Lists what agent can do\n - [ ] Specific and concrete\n - [ ] 3-5 key capabilities\n\n- [ ] **Workflow** documented (2 pts)\n - [ ] Step-by-step process\n - [ ] Actionable steps\n - [ ] Logical flow\n\n- [ ] **Examples** provided (2 pts)\n - [ ] 2-3 concrete examples\n - [ ] Real-world scenarios\n - [ ] Expected outputs shown\n\n- [ ] **Best practices** listed (1 pt)\n - [ ] Guidelines present\n - [ ] Standards specified\n - [ ] Quality expectations\n\n- [ ] **Error handling** documented (1 pt)\n - [ ] Common errors listed\n - [ ] Graceful degradation\n - [ ] User-friendly messages\n\n**Content Quality Score**: _____ / 10\n\n**Missing Sections**:\n- [ ] _______________________\n- [ ] _______________________\n\n---\n\n## 4. Maintainability (10 points)\n\n### Structure & Organization\n- [ ] **Clear headings** (2 pts)\n - [ ] 5+ section headings\n - [ ] Logical organization\n - [ ] Easy navigation\n\n- [ ] **Formatting** (2 pts)\n - [ ] Uses lists where appropriate\n - [ ] Code blocks for examples\n - [ ] Bold/italic for emphasis\n\n- [ ] **Readability** (2 pts)\n - [ ] Clear, concise writing\n - [ ] No overly long lines\n - [ ] Good use of whitespace\n\n### Documentation\n- [ ] **Comments** (if needed) (1 pt)\n - [ ] Complex sections explained\n - [ ] Changelog present (if versioned)\n - [ ] TODOs documented\n\n- [ ] **Consistency** (2 pts)\n - [ ] Consistent terminology\n - [ ] Consistent formatting\n - [ ] Follows conventions\n\n- [ ] **Length** appropriate (1 pt)\n - [ ] Not too brief (>100 words)\n - [ ] Not too verbose (\u003c2000 words)\n - [ ] Balanced detail\n\n**Maintainability Score**: _____ / 10\n\n---\n\n## 5. Functionality (Qualitative)\n\n### Does it work?\n- [ ] **Agent invokes successfully**\n - [ ] No loading errors\n - [ ] Appears in agent list\n\n- [ ] **Produces expected output**\n - [ ] Follows documented workflow\n - [ ] Quality meets standards\n - [ ] Handles edge cases\n\n- [ ] **Performance acceptable**\n - [ ] Completes in reasonable time\n - [ ] Model choice is appropriate\n - [ ] Resource usage is acceptable\n\n**Issues Found** (during testing):\n- [ ] _______________________\n- [ ] _______________________\n\n---\n\n## 6. Alignment & Overlap\n\n### Purpose Clarity\n- [ ] **Unique purpose**\n - [ ] Not redundant with other agents\n - [ ] Clear differentiation\n - [ ] Fills specific need\n\n- [ ] **Appropriate scope**\n - [ ] Not too broad (does too much)\n - [ ] Not too narrow (too trivial)\n - [ ] Focused on one domain\n\n### Comparison (if similar agents exist)\n- [ ] **Compared with**: _______________________\n- [ ] **Key differences**: _______________________\n- [ ] **Recommendation**:\n - [ ] Keep both (different purposes)\n - [ ] Merge into one\n - [ ] Specialize further\n - [ ] Deprecate one\n\n---\n\n## Overall Assessment\n\n### Scores Summary\n\n| Category | Score | Weight | Weighted |\n|----------|-------|--------|----------|\n| Schema Compliance | ___ / 10 | 1.0 | ___ |\n| Security | ___ / 10 | 1.0 | ___ |\n| Content Quality | ___ / 10 | 1.0 | ___ |\n| Maintainability | ___ / 10 | 1.0 | ___ |\n| **Total** | | | **___ / 10** |\n\n### Rating\n\n- **9-10**: Excellent - Ready for production\n- **7-8**: Good - Minor improvements recommended\n- **5-6**: Fair - Significant improvements needed\n- **0-4**: Poor - Major revision required\n\n**Agent Rating**: _______________\n\n---\n\n## Action Items\n\n### Critical (Must Fix)\n1. _______________________\n2. _______________________\n\n### High Priority (Should Fix)\n1. _______________________\n2. _______________________\n\n### Medium Priority (Nice to Have)\n1. _______________________\n2. _______________________\n\n### Low Priority (Optional)\n1. _______________________\n2. _______________________\n\n---\n\n## Automated Assessment\n\n### Run These Commands\n\n```bash\n# Validation\npython3 agent-builder/skills/building-agents/scripts/validate-agent.py path/to/agent.md\n\n# Enhancement analysis\npython3 agent-builder/skills/building-agents/scripts/enhance-agent.py agent-name\n\n# Comparison (if similar agents exist)\n/agent-builder:agents:compare agent-name similar-agent\n```\n\n### Automated Scores\n\n| Tool | Score | Notes |\n|------|-------|-------|\n| validate-agent.py | PASS / FAIL | _____________ |\n| enhance-agent.py | ___ / 10 | _____________ |\n| compare similarity | ___ % | _____________ |\n\n---\n\n## Review Notes\n\n### Strengths\n- _______________________\n- _______________________\n- _______________________\n\n### Weaknesses\n- _______________________\n- _______________________\n- _______________________\n\n### Recommendations\n- _______________________\n- _______________________\n- _______________________\n\n---\n\n## Decision\n\n- [ ] **Approve** - Ready to use\n- [ ] **Approve with conditions** - Minor fixes needed\n- [ ] **Revise** - Significant changes required\n- [ ] **Reject** - Not viable, start over\n\n**Reviewer Signature**: ________________\n**Date**: ________________\n\n---\n\n## Follow-Up\n\n### Next Review Date\nRecommended: ________________\n\n### Tracking\n- **Issue/Ticket**: ________________\n- **Git Commit**: ________________\n- **Documentation Updated**: Yes / No\n\n---\n\n## Appendix: Scoring Guidelines\n\n### Schema Compliance Scoring\n\n**10/10** - Perfect schema\n- All required fields present and valid\n- Optional fields used appropriately\n- Follows all conventions\n\n**7-9/10** - Good schema\n- Required fields present\n- Minor improvements possible\n\n**4-6/10** - Needs work\n- Some fields missing or invalid\n- Doesn't fully follow conventions\n\n**0-3/10** - Poor schema\n- Missing critical fields\n- Invalid format\n- Won't load properly\n\n### Security Scoring\n\n**10/10** - Excellent security\n- Minimal necessary permissions\n- All risks addressed\n- Best practices followed\n\n**7-9/10** - Good security\n- Reasonable permissions\n- Most risks addressed\n- Minor improvements possible\n\n**4-6/10** - Security concerns\n- Over-permissioned\n- Some risks unaddressed\n- Needs hardening\n\n**0-3/10** - Security issues\n- Dangerous permissions\n- No input validation\n- Critical vulnerabilities\n\n### Content Quality Scoring\n\n**10/10** - Comprehensive documentation\n- All sections present\n- Excellent examples\n- Clear and thorough\n\n**7-9/10** - Good documentation\n- Most sections present\n- Some examples\n- Generally clear\n\n**4-6/10** - Incomplete documentation\n- Missing key sections\n- Few/no examples\n- Unclear in places\n\n**0-3/10** - Poor documentation\n- Most sections missing\n- No examples\n- Confusing or vague\n\n### Maintainability Scoring\n\n**10/10** - Highly maintainable\n- Well-structured\n- Excellent formatting\n- Very readable\n\n**7-9/10** - Maintainable\n- Good structure\n- Decent formatting\n- Readable\n\n**4-6/10** - Needs improvement\n- Poor structure\n- Inconsistent formatting\n- Hard to read\n\n**0-3/10** - Unmaintainable\n- No structure\n- No formatting\n- Unreadable\n\n---\n\n## Related Resources\n\n- [Update Patterns](../references/agent-update-patterns.md) - Common update scenarios\n- [Migration Guide](../references/migration-guide.md) - Schema migrations\n- [SKILL.md](../SKILL.md) - Complete building guide\n- [Agent Template](./agent-template.md) - Standard template\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9234,"content_sha256":"4fe33ac16f5adad0300a0852871290bb413a7126203f1771b86fbd58d7e3875e"},{"filename":"templates/agent-template.md","content":"---\nname: agent-name\ncolor: \"#3498DB\"\ndescription: Brief description of what the agent does and when Claude should invoke it (be specific about use cases)\ncapabilities: [\"task1\", \"task2\", \"task3\"]\n# NOTE: Do NOT include Task - subagents cannot spawn other subagents\n# For orchestration patterns, use skills instead\ntools: Read, Grep, Glob\nmodel: sonnet\n---\n\n# Agent Name\n\nYou are a [role description] with expertise in [domain]. Your role is to [primary purpose].\n\n## Your Identity\n\nYou are delegated from [parent context/orchestrator] to handle [specific domain] tasks. You have deep expertise in:\n- [Expertise area 1]\n- [Expertise area 2]\n- [Expertise area 3]\n\n## Available Resources\n\n[If this agent uses resources from a skill, document them here]\n\n**Templates:**\n- `path/to/template1` - Description\n- `path/to/template2` - Description\n\n**Scripts:**\n- `path/to/script1` - Description\n- `path/to/script2` - Description\n\n**References:**\n- `path/to/reference1` - Description\n\n## Your Capabilities\n\n1. **Capability 1**: Description of what you can do\n2. **Capability 2**: Description of what you can do\n3. **Capability 3**: Description of what you can do\n\n## Your Workflow\n\nWhen invoked, follow these steps:\n\n1. **Analyze**: Understand the request and gather necessary context\n2. **Plan**: Break down the task into actionable steps\n3. **Execute**: Perform the task systematically\n4. **Validate**: Check your work and ensure quality\n5. **Report**: Provide clear results using the reporting format below\n\n## Execution Guidelines\n\n### When Creating [Component Type]\n1. [Specific step 1]\n2. [Specific step 2]\n3. [Specific step 3]\n4. [Specific step 4]\n\n### When Updating [Component Type]\n1. [Specific step 1]\n2. [Specific step 2]\n3. [Specific step 3]\n\n## Error Handling\n\n### [Error Category 1]\n```\n❌ [Error type]: [Error description]\n\n Current: [What caused the error]\n\n Problem: [Why this is an error]\n\n Fix: [How to resolve it]\n```\n\n### [Error Category 2]\n```\n⚠️ [Warning type]: [Warning description]\n\n Found: [What triggered the warning]\n\n Risk: [Potential issues]\n\n Fix: [Recommended action]\n```\n\n### Validation Failures\n- If [condition], then [action]\n- If [condition], then [action]\n- If [condition], then [action]\n\n## Reporting Format\n\nWhen completing tasks, return results in this format:\n\n```markdown\n## [Operation Type] Complete\n\n**Action**: [action performed]\n**Target**: [what was affected]\n**Status**: ✅ Success | ⚠️ Warnings | ❌ Failed\n\n### Summary\n- [Key result 1]\n- [Key result 2]\n- [Key result 3]\n\n### Details\n[Detailed information about what was done]\n\n### Validation\n- [Check 1]: ✅ Passed | ❌ Failed\n- [Check 2]: ✅ Passed | ❌ Failed\n\n### Next Steps\n1. [Recommendation 1]\n2. [Recommendation 2]\n```\n\n## Examples\n\n### Example 1: [Common Scenario]\nWhen the user asks [specific request]:\n\n**Input:** [What was requested]\n\n**Steps taken:**\n1. [Step 1 with details]\n2. [Step 2 with details]\n3. [Step 3 with details]\n\n**Output:** [What was produced]\n\n### Example 2: [Edge Case Scenario]\nWhen faced with [unusual situation]:\n\n**Input:** [What was requested]\n\n**Challenge:** [Why this is tricky]\n\n**Resolution:**\n1. [How you handle it]\n2. [Special considerations]\n\n**Output:** [Result]\n\n### Example 3: [Error Scenario]\nWhen [error condition] occurs:\n\n**Detection:** [How you identify the error]\n\n**Response:** [How you handle it]\n\n**User guidance:** [What you tell the user]\n\n## Important Constraints\n\n### Subagent Limitation\n**IMPORTANT**: This agent runs as a subagent and **cannot spawn other subagents**.\n- The Task tool will not work from within this agent\n- For multi-agent coordination, recommend actions to the user/main thread\n- Skills will still auto-invoke based on context\n\n### DO:\n- ✅ [What the agent should always do]\n- ✅ [What the agent should always do]\n- ✅ [What the agent should always do]\n- ✅ [What the agent should always do]\n\n### DON'T:\n- ❌ [What the agent should never do]\n- ❌ [What the agent should never do]\n- ❌ [What the agent should never do]\n- ❌ Do NOT try to delegate to other agents via Task tool\n\n## Integration Notes\n\n[If this agent is part of a larger system, document how it integrates]\n\n**Invoked by:** [Parent orchestrator/context]\n**Returns to:** [Where results go]\n**Coordinates with:** [Other agents/components]\n\nReturn comprehensive results including:\n- [Required output 1]\n- [Required output 2]\n- [Required output 3]\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4410,"content_sha256":"78bdc2a5a51d58d1e7f15caa5d8d5688ea32350049be8640bb61a3bb48682a8e"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Building Agents Skill","type":"text"}]},{"type":"paragraph","content":[{"text":"You are an expert at creating Claude Code agents (subagents). Agents are specialized assistants that handle delegated tasks with independent context and dedicated resources.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Create an Agent vs Other Components","type":"text"}]},{"type":"paragraph","content":[{"text":"Use an AGENT when:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The task requires specialized, focused expertise","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You need independent context and isolation from the main conversation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The task involves heavy computation or long-running operations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You want explicit invocation rather than automatic activation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The task benefits from dedicated tool permissions","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Use a SKILL instead when:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You want automatic, context-aware assistance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The expertise should be \"always on\" and auto-invoked","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You need progressive disclosure of context","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Use a COMMAND instead when:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The user explicitly triggers a specific workflow","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You need parameterized inputs via command arguments","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Agent Schema & Structure","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"File Location","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Project-level","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":".claude/agents/agent-name.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User-level","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"~/.claude/agents/agent-name.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Plugin-level","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"plugin-dir/agents/agent-name.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"File Format","type":"text"}]},{"type":"paragraph","content":[{"text":"Single Markdown file with YAML frontmatter and Markdown body.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Required Fields","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"---\nname: agent-name # Unique identifier (lowercase-hyphens, max 64 chars)\ndescription: Brief description of what the agent does and when to use it (max 1024 chars)\n---","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Optional Fields","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"---\ncolor: \"#3498DB\" # Hex color for terminal display (6-digit with #)\ncapabilities: [\"task1\", \"task2\", \"task3\"] # Array of specialized tasks the agent can perform (helps Claude decide when to invoke)\ntools: Read, Grep, Glob, Bash # Comma-separated list (omit to inherit all tools)\nmodel: sonnet # sonnet, opus, haiku, or inherit\n---","type":"text"}]},{"type":"paragraph","content":[{"text":"Note on ","type":"text","marks":[{"type":"strong"}]},{"text":"color","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" field","type":"text","marks":[{"type":"strong"}]},{"text":": The color is displayed in the terminal when the agent is invoked, helping users visually identify which agent is running. Use a 6-digit hex color with ","type":"text"},{"text":"#","type":"text","marks":[{"type":"code_inline"}]},{"text":" prefix (e.g., ","type":"text"},{"text":"\"#9B59B6\"","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Choose colors that reflect the agent's domain or plugin family for visual consistency.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note on ","type":"text","marks":[{"type":"strong"}]},{"text":"capabilities","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" field","type":"text","marks":[{"type":"strong"}]},{"text":": This array lists specific tasks the agent specializes in, helping Claude autonomously determine when to invoke the agent. Use kebab-case strings (e.g., ","type":"text"},{"text":"\"analyze-security\"","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\"generate-tests\"","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\"review-architecture\"","type":"text","marks":[{"type":"code_inline"}]},{"text":"). This field is recommended but optional - if omitted, Claude relies solely on the description for invocation decisions.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Subagent Architecture Constraints","type":"text"}]},{"type":"paragraph","content":[{"text":"CRITICAL","type":"text","marks":[{"type":"strong"}]},{"text":": Agents run as subagents and ","type":"text"},{"text":"cannot spawn other subagents","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Subagent Limitation:\n┌─────────────────────────────────────────┐\n│ Main Thread │\n│ - Can use Task tool ✓ │\n│ │\n│ ┌─────────────────────────────────┐ │\n│ │ Subagent (your agent) │ │\n│ │ - CANNOT use Task tool ✗ │ │\n│ │ - Skills still auto-invoke ✓ │ │\n│ └─────────────────────────────────┘ │\n└─────────────────────────────────────────┘","type":"text"}]},{"type":"paragraph","content":[{"text":"Implications:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"DO NOT","type":"text","marks":[{"type":"strong"}]},{"text":" include ","type":"text"},{"text":"Task","type":"text","marks":[{"type":"code_inline"}]},{"text":" in agent tools - it creates false expectations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For orchestration patterns","type":"text","marks":[{"type":"strong"}]},{"text":", create a skill instead (skills run in main thread)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skills auto-invoke","type":"text","marks":[{"type":"strong"}]},{"text":" within agent context, so agents get skill expertise without Task","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When to Use Skill vs Agent for Orchestration:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Need to coordinate multiple agents? → Create a ","type":"text"},{"text":"skill","type":"text","marks":[{"type":"strong"}]},{"text":" (runs in main thread, can use Task)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Need focused execution of a specific task? → Create an ","type":"text"},{"text":"agent","type":"text","marks":[{"type":"strong"}]},{"text":" (specialized executor)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Naming Conventions","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lowercase letters, numbers, and hyphens only","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No underscores or special characters","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Max 64 characters","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Action-oriented","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"code-reviewer","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"test-runner","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"api-designer","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Descriptive","type":"text","marks":[{"type":"strong"}]},{"text":": Name should indicate the agent's purpose","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Agent Body Content","type":"text"}]},{"type":"paragraph","content":[{"text":"The Markdown body should include:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Role Definition","type":"text","marks":[{"type":"strong"}]},{"text":": Clear statement of the agent's identity and purpose","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Capabilities","type":"text","marks":[{"type":"strong"}]},{"text":": What the agent can do","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Workflow","type":"text","marks":[{"type":"strong"}]},{"text":": Step-by-step process the agent follows","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best Practices","type":"text","marks":[{"type":"strong"}]},{"text":": Guidelines and standards the agent should follow","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Examples","type":"text","marks":[{"type":"strong"}]},{"text":": Concrete examples of expected behavior","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Template Structure","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"---\nname: agent-name\ncolor: \"#3498DB\"\ndescription: One-line description of agent purpose and when to invoke it\ncapabilities: [\"task1\", \"task2\", \"task3\"]\ntools: Read, Grep, Glob, Bash\nmodel: sonnet\n---\n\n# Agent Name\n\nYou are a [role description] with expertise in [domain]. Your role is to [primary purpose].\n\n## Your Capabilities\n\n1. **Capability 1**: Description\n2. **Capability 2**: Description\n3. **Capability 3**: Description\n\n## Your Workflow\n\nWhen invoked, follow these steps:\n\n1. **Step 1**: Action and rationale\n2. **Step 2**: Action and rationale\n3. **Step 3**: Action and rationale\n\n## Best Practices & Guidelines\n\n- Guideline 1\n- Guideline 2\n- Guideline 3\n\n## Examples\n\n### Example 1: [Scenario]\n[Expected behavior and approach]\n\n### Example 2: [Scenario]\n[Expected behavior and approach]\n\n## Important Reminders\n\n- Reminder 1\n- Reminder 2\n- Reminder 3","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Tool Selection Strategy","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Minimal Permissions (Recommended Start)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"tools: Read, Grep, Glob","type":"text"}]},{"type":"paragraph","content":[{"text":"Use for: Research, analysis, read-only operations","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"File Modification","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"tools: Read, Write, Edit, Grep, Glob","type":"text"}]},{"type":"paragraph","content":[{"text":"Use for: Code generation, file editing, refactoring","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"System Operations","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"tools: Read, Write, Edit, Grep, Glob, Bash","type":"text"}]},{"type":"paragraph","content":[{"text":"Use for: Testing, building, git operations, system commands","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Web Access","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"tools: Read, Grep, Glob, WebFetch, WebSearch","type":"text"}]},{"type":"paragraph","content":[{"text":"Use for: Documentation lookup, external data fetching","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Full Access","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# Omit the tools field entirely","type":"text"}]},{"type":"paragraph","content":[{"text":"Use with caution: Agent inherits all available tools","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Model Selection","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"haiku","type":"text","marks":[{"type":"strong"}]},{"text":": Fast, simple tasks (searches, summaries, quick analysis)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"sonnet","type":"text","marks":[{"type":"strong"}]},{"text":": Default for most tasks (balanced performance and cost)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"opus","type":"text","marks":[{"type":"strong"}]},{"text":": Complex reasoning, critical decisions, heavy analysis","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"inherit","type":"text","marks":[{"type":"strong"}]},{"text":": Use the model from the parent context (default if omitted)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Color Selection","type":"text"}]},{"type":"paragraph","content":[{"text":"Colors provide visual identification when agents run in the terminal.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Format","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"6-digit hex color with ","type":"text"},{"text":"#","type":"text","marks":[{"type":"code_inline"}]},{"text":" prefix: ","type":"text"},{"text":"\"#RRGGBB\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Must be quoted in YAML: ","type":"text"},{"text":"color: \"#3498DB\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Recommended Color Palettes by Domain","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Domain","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Primary","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Accent","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Meta/Building","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#9B59B6","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#8E44AD","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purple shades for meta-programming agents","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"GitHub/Git","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#3498DB","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#2980B9","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Blue shades for version control","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Testing/QA","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#E74C3C","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#C0392B","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Red shades for testing agents","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Documentation","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#27AE60","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#229954","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Green shades for docs","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Security","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#F39C12","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#D68910","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Orange/gold for security analysis","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Performance","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#1ABC9C","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#16A085","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Teal for optimization agents","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Research","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#9B59B6","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"#8E44AD","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purple for research/exploration","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Plugin Color Families","type":"text"}]},{"type":"paragraph","content":[{"text":"When creating agents for a plugin, use related shades to create visual cohesion:","type":"text"}]},{"type":"paragraph","content":[{"text":"Example: agent-builder plugin","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"meta-architect: \"#9B59B6\" # Primary purple\nagent-builder: \"#8E44AD\" # Darker purple\nskill-builder: \"#7D3C98\" # Even darker\ncommand-builder: \"#5B2C6F\" # Darkest\nhook-builder: \"#6C3483\" # Mid-dark","type":"text"}]},{"type":"paragraph","content":[{"text":"Example: github-workflows plugin","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"workflow-orchestrator: \"#3498DB\" # Primary blue\nissue-manager: \"#2980B9\" # Darker blue\npr-reviewer: \"#1F618D\" # Even darker\nrelease-manager: \"#1A5276\" # Darkest","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Best Practices","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Consistency","type":"text","marks":[{"type":"strong"}]},{"text":": Use related colors for agents in the same plugin","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Contrast","type":"text","marks":[{"type":"strong"}]},{"text":": Ensure colors are visible on both light and dark terminals","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Meaning","type":"text","marks":[{"type":"strong"}]},{"text":": Choose colors that intuitively match the agent's purpose","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Avoid","type":"text","marks":[{"type":"strong"}]},{"text":": Very dark colors (","type":"text"},{"text":"#000000","type":"text","marks":[{"type":"code_inline"}]},{"text":") or very light colors (","type":"text"},{"text":"#FFFFFF","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Creating an Agent","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Gather Requirements","type":"text"}]},{"type":"paragraph","content":[{"text":"Ask the user:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What is the agent's primary purpose?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What tasks should it perform?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What tools does it need?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Should it have specialized knowledge or constraints?","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Design the Agent","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Choose a clear, descriptive name (lowercase-hyphens)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Select a color that matches the agent's domain (see Color Selection)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Write a concise description (focus on WHEN to use)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Select minimal necessary tools","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Choose appropriate model","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Structure the prompt for clarity","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Write the Agent File","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use proper YAML frontmatter syntax","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Include clear role definition","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document capabilities and workflow","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Provide examples and guidelines","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add important reminders","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Validate the Agent","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check naming convention (lowercase-hyphens, max 64 chars)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify required fields (name, description)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate YAML syntax","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review tool permissions for security","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ensure description is clear and actionable","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5: Test the Agent","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Place in ","type":"text"},{"text":".claude/agents/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test invocation via Task tool","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify behavior matches expectations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Iterate based on results","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Validation Script","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill includes a validation script:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"validate-agent.py - Schema Validator","type":"text"}]},{"type":"paragraph","content":[{"text":"Python script for validating agent files.","type":"text"}]},{"type":"paragraph","content":[{"text":"Usage:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 {baseDir}/scripts/validate-agent.py \u003cagent-file>","type":"text"}]},{"type":"paragraph","content":[{"text":"What It Checks:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"YAML frontmatter syntax","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Required fields present (name, description)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Naming convention compliance (lowercase-hyphens, max 64 chars)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tool permissions validation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Model selection validation","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Returns:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Exit code 0 if valid","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Exit code 1 with error messages if invalid","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Use Cases:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CI/CD validation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-commit hooks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Automated testing","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Integration with other tools","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 validate-agent.py .claude/agents/code-reviewer.md\n\n✅ Agent validation passed\n Name: code-reviewer\n Tools: Read, Grep, Glob\n Model: sonnet","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Security Considerations","type":"text"}]},{"type":"paragraph","content":[{"text":"When creating agents, always:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Minimize Tool Permissions","type":"text","marks":[{"type":"strong"}]},{"text":": Only grant necessary tools","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate Inputs","type":"text","marks":[{"type":"strong"}]},{"text":": Check for command injection, path traversal","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Avoid Secrets","type":"text","marks":[{"type":"strong"}]},{"text":": Never hardcode API keys or credentials","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Restrict Scope","type":"text","marks":[{"type":"strong"}]},{"text":": Keep agents focused on specific tasks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review Commands","type":"text","marks":[{"type":"strong"}]},{"text":": Carefully audit any Bash operations","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Common Agent Patterns","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 1: Code Analysis Agent","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"---\nname: security-auditor\ncolor: \"#F39C12\"\ndescription: Specialized security auditor for identifying vulnerabilities, insecure patterns, and compliance issues. Use when reviewing code for security concerns.\ntools: Read, Grep, Glob\nmodel: sonnet\n---","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 2: Testing Agent","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"---\nname: test-runner\ncolor: \"#E74C3C\"\ndescription: Automated test execution and reporting agent. Use when running test suites, analyzing failures, or validating test coverage.\ntools: Read, Grep, Glob, Bash\nmodel: haiku\n---","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 3: Documentation Agent","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"---\nname: doc-generator\ncolor: \"#27AE60\"\ndescription: Technical documentation writer specializing in API docs, README files, and inline code documentation. Use when creating or updating documentation.\ntools: Read, Write, Grep, Glob\nmodel: sonnet\n---","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 4: Refactoring Agent","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"---\nname: code-refactor\ncolor: \"#1ABC9C\"\ndescription: Expert code refactoring specialist for improving code quality, removing duplication, and applying design patterns. Use for large-scale refactoring tasks.\ntools: Read, Write, Edit, Grep, Glob, Bash\nmodel: sonnet\n---","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Maintaining and Updating Agents","type":"text"}]},{"type":"paragraph","content":[{"text":"Agents need regular maintenance to stay effective.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"When to Update an Agent","type":"text"}]},{"type":"paragraph","content":[{"text":"Update agents when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Requirements change","type":"text","marks":[{"type":"strong"}]},{"text":": New features or different scope","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance issues","type":"text","marks":[{"type":"strong"}]},{"text":": Too slow, too expensive, not accurate enough","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Security concerns","type":"text","marks":[{"type":"strong"}]},{"text":": New vulnerabilities or permission needs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best practices evolve","type":"text","marks":[{"type":"strong"}]},{"text":": New patterns become standard","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User feedback","type":"text","marks":[{"type":"strong"}]},{"text":": Agent doesn't meet expectations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validation fails","type":"text","marks":[{"type":"strong"}]},{"text":": Schema or content issues detected","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Maintenance Checklist","type":"text"}]},{"type":"paragraph","content":[{"text":"When reviewing agents for updates:","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Schema compliance","type":"text","marks":[{"type":"strong"}]},{"text":": Valid YAML, required fields present","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Security","type":"text","marks":[{"type":"strong"}]},{"text":": Minimal tool permissions, no hardcoded secrets","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Content quality","type":"text","marks":[{"type":"strong"}]},{"text":": Clear role, documented workflow, examples","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Maintainability","type":"text","marks":[{"type":"strong"}]},{"text":": Good structure, consistent formatting","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Common Update Scenarios","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Scenario 1: Reduce Tool Permissions","type":"text"}]},{"type":"paragraph","content":[{"text":"Problem","type":"text","marks":[{"type":"strong"}]},{"text":": Agent has Bash but doesn't need it ","type":"text"},{"text":"Solution","type":"text","marks":[{"type":"strong"}]},{"text":": Edit the tools field to remove Bash, use minimal set like ","type":"text"},{"text":"Read, Grep, Glob","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Scenario 2: Improve Performance/Cost","type":"text"}]},{"type":"paragraph","content":[{"text":"Problem","type":"text","marks":[{"type":"strong"}]},{"text":": Agent uses opus but could use sonnet ","type":"text"},{"text":"Solution","type":"text","marks":[{"type":"strong"}]},{"text":": Change model field from ","type":"text"},{"text":"opus","type":"text","marks":[{"type":"code_inline"}]},{"text":" to ","type":"text"},{"text":"sonnet","type":"text","marks":[{"type":"code_inline"}]},{"text":" (3x faster, 5x cheaper)","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Scenario 3: Add Missing Documentation","type":"text"}]},{"type":"paragraph","content":[{"text":"Problem","type":"text","marks":[{"type":"strong"}]},{"text":": Agent lacks examples and error handling ","type":"text"},{"text":"Solution","type":"text","marks":[{"type":"strong"}]},{"text":": Add Examples section with 2-3 concrete scenarios, add Error Handling section","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Scenario 4: Fix Security Issues","type":"text"}]},{"type":"paragraph","content":[{"text":"Problem","type":"text","marks":[{"type":"strong"}]},{"text":": Agent has Bash without input validation guidance ","type":"text"},{"text":"Solution","type":"text","marks":[{"type":"strong"}]},{"text":": Either remove Bash from tools, or add Input Validation section to agent body","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Modernization Checklist","type":"text"}]},{"type":"paragraph","content":[{"text":"Signs an agent needs modernization:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Created before current guidelines","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Uses outdated patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Missing key sections (examples, error handling)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Over-permissioned tools","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Modernization steps:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update to current schema (check required fields)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Apply security best practices","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add missing sections (workflow, examples, error handling)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optimize tool permissions (minimal necessary)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optimize model selection (cost/performance)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Improve description clarity (when to invoke)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add concrete examples (2-3 scenarios)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document edge cases","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Version Control Best Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"When updating agents:","type":"text"}]},{"type":"paragraph","content":[{"text":"Before making changes:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"git add .claude/agents/my-agent.md\ngit commit -m \"backup: agent before major update\"","type":"text"}]},{"type":"paragraph","content":[{"text":"After changes:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 {baseDir}/scripts/validate-agent.py my-agent.md # Verify validity\ngit add .claude/agents/my-agent.md\ngit commit -m \"refactor(agent): improve my-agent security and docs\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Validation Checklist","type":"text"}]},{"type":"paragraph","content":[{"text":"Before finalizing an agent, verify:","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Name is lowercase-hyphens, max 64 characters","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Description is clear and actionable (max 1024 characters)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Color is 6-digit hex with # prefix (e.g., ","type":"text"},{"text":"\"#3498DB\"","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"YAML frontmatter is valid syntax","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Tools are minimal and necessary","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Model choice is appropriate for task complexity","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Role and capabilities are clearly defined","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Workflow is documented step-by-step","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Security considerations are addressed","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Examples and guidelines are included","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"File is placed in correct directory","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference Documentation","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Templates","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"{baseDir}/templates/agent-template.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Comprehensive agent template with all sections","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"References","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"{baseDir}/references/agent-examples.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Real-world examples and patterns","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Quick Reference","type":"text"}]},{"type":"paragraph","content":[{"text":"For creating new agents:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Start with ","type":"text"},{"text":"agent-template.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as a foundation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Follow patterns from ","type":"text"},{"text":"agent-examples.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run validation: ","type":"text"},{"text":"python3 {baseDir}/scripts/validate-agent.py \u003cagent-file>","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"For updating existing agents:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review the Maintenance Checklist above","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Apply Modernization steps as needed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Re-validate after changes","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For quality assurance:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check against Validation Checklist","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Compare against patterns in ","type":"text"},{"text":"agent-examples.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ensure minimal tool permissions","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Your Role","type":"text"}]},{"type":"paragraph","content":[{"text":"When the user asks to create an agent:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Gather requirements through questions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommend whether an agent is the right choice","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Design the agent structure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate the agent file with proper schema","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate naming, syntax, and security","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Place the file in the correct location","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Provide usage instructions","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Be proactive in:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Suggesting better component types if applicable","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommending minimal tool permissions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identifying security risks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optimizing model selection for cost/performance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Providing clear examples and documentation","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Your goal is to help users create robust, secure, and well-designed agents that follow Claude Code best practices.","type":"text"}]}]},"metadata":{"date":"2026-06-05","name":"building-agents","author":"@skillopedia","source":{"stars":336,"repo_name":"marketplace","origin_url":"https://github.com/aiskillstore/marketplace/blob/HEAD/skills/c0ntr0lledcha0s/building-agents/SKILL.md","repo_owner":"aiskillstore","body_sha256":"fecd6c2ada07815f0826844dce8bd85b4c6adcd3bcc013ce5f423bd100b7fc5f","cluster_key":"1db3abbf2636172e96361364203bd574ac53d8c96bfb0d7dd58d4264dcc40b0c","clean_bundle":{"format":"clean-skill-bundle-v1","source":"aiskillstore/marketplace/skills/c0ntr0lledcha0s/building-agents/SKILL.md","attachments":[{"id":"cf75f346-932c-531b-85b2-24af1d99ee5f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cf75f346-932c-531b-85b2-24af1d99ee5f/attachment.md","path":"references/agent-examples.md","size":11828,"sha256":"88b740c058df9e955fee6ea964ced2c801d07e3c89ca7826ca4589a2622b97e6","contentType":"text/markdown; charset=utf-8"},{"id":"788b6561-76bf-5ff3-a3fc-21fd23414b7b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/788b6561-76bf-5ff3-a3fc-21fd23414b7b/attachment.md","path":"references/agent-update-patterns.md","size":12947,"sha256":"1fe665f4d337d42e95e58d45a24e405ec288f39152aaa1142fe41fbb57b7c17d","contentType":"text/markdown; charset=utf-8"},{"id":"5dc742d7-8eda-57ec-92b3-68e12f414370","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5dc742d7-8eda-57ec-92b3-68e12f414370/attachment.md","path":"references/color-palette.md","size":7794,"sha256":"21669e81d41e75baed7f06438dabed8fb3e77027f16d97888c76635da97887e0","contentType":"text/markdown; charset=utf-8"},{"id":"9066fbfc-352a-515c-a42d-c495982332e6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9066fbfc-352a-515c-a42d-c495982332e6/attachment.md","path":"references/migration-guide.md","size":12469,"sha256":"bc0c3683c458a42bfc7b2b488ed46a9e66dead54dea5e089177219a845e02cf2","contentType":"text/markdown; charset=utf-8"},{"id":"8173af7a-ab9a-5ca3-a577-e04ebe35e79a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8173af7a-ab9a-5ca3-a577-e04ebe35e79a/attachment.py","path":"scripts/validate-agent.py","size":7374,"sha256":"48338c94becec6883b81b0b5b81477596d7c3c691f016074d51fcccdb1d083c2","contentType":"text/x-python; charset=utf-8"},{"id":"40d44416-811a-5268-b601-84ac0a95f34d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/40d44416-811a-5268-b601-84ac0a95f34d/attachment.json","path":"skill-report.json","size":11429,"sha256":"de15d92b44dfb1a554a2392d3b71bb63c72f03112a50508d2b4e550f751071e4","contentType":"application/json; charset=utf-8"},{"id":"16800590-fb9c-5111-a223-825c36013bd4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/16800590-fb9c-5111-a223-825c36013bd4/attachment.md","path":"templates/agent-checklist.md","size":9234,"sha256":"4fe33ac16f5adad0300a0852871290bb413a7126203f1771b86fbd58d7e3875e","contentType":"text/markdown; charset=utf-8"},{"id":"a8dc9b09-af85-5337-a82e-7e1a3b582fc7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a8dc9b09-af85-5337-a82e-7e1a3b582fc7/attachment.md","path":"templates/agent-template.md","size":4410,"sha256":"78bdc2a5a51d58d1e7f15caa5d8d5688ea32350049be8640bb61a3bb48682a8e","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"2c25fbf6006c9440c043b1628966790b94274f7179f0f3379a48a662d9c2b35a","attachment_count":8,"text_attachments":8,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/c0ntr0lledcha0s/building-agents/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"web-development","category_label":"Web"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"web-development","import_tag":"clean-skills-v1","description":"Expert at creating and modifying Claude Code agents (subagents). Auto-invokes when the user wants to create, update, modify, enhance, validate, or standardize agents, or when modifying agent YAML frontmatter fields (especially 'model', 'tools', 'description'), needs help designing agent architecture, or wants to understand agent capabilities. Also auto-invokes proactively when Claude is about to write agent files (*/agents/*.md), create modular agent architectures, or implement tasks that involve creating agent components.","allowed-tools":"Read, Write, Edit, Grep, Glob, Bash"}},"renderedAt":1782980402958}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.