cue-ai 0.4.0 → 0.5.0

package/resources/claude-plugins-official/plugins/plugin-dev/skills/agent-development/SKILL.md

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

package/resources/claude-plugins-official/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md

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