--- name: agent-creator description: Guide for creating custom agents. Use when users want to create a new agent that runs in an isolated context with custom system prompts and specific tool access. allowed-tools: Edit, Write --- # Creating Custom Agents for Qoder CLI This skill guides you through creating custom agents. Agents are specialized AI assistants that run in isolated contexts with custom system prompts, specific tool access, and independent permissions. ## When to Use Agents Use agents when you need: - **Context isolation** for long research or exploration tasks - **Parallel execution** of multiple independent workstreams - **Specialized expertise** with custom prompts for specific domains - **Reusable configurations** across projects **When NOT to use agents:** - Simple, single-purpose tasks (use skills instead) - Tasks requiring frequent back-and-forth with the user - Quick, targeted changes ## Agent Locations | Location | Scope | Priority | | -------------------------------- | ----------------- | -------- | | `/${QODER_CONFIG_DIR}/agents/` | Current project | Higher | | `~/${QODER_USER_CONFIG_DIR}/agents/` | All your projects | Lower | **Project agents** (`${QODER_CONFIG_DIR}/agents/`): Ideal for codebase-specific agents. Check into version control to share with your team. **User agents** (`~/${QODER_USER_CONFIG_DIR}/agents/`): Personal agents available across all your projects. ## Agent File Format Each agent is a Markdown file with YAML frontmatter: ```markdown --- name: agent-name description: When to use this agent. Be specific! --- You are a [role]. When invoked: 1. [First step] 2. [Second step] 3. [Output format] ``` ### Required Fields | Field | Description | | ------------- | -------------------------------------------------------------------------- | | `name` | Unique identifier for the agent | | `description` | When to delegate to this agent (be specific). Including trigger scenarios. | ## Writing Effective Descriptions The description is **critical**. Include "use proactively" to encourage automatic delegation - Qoder CLI uses it to decide when to delegate. ```yaml # Bad - Too vague description: Helps with code # Good - Specific and actionable description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. ``` ### Optional Fields | Field | Description | | ---------------- | ----------------------------------------------------------------------------------- | | `tools` | Tools the agent can use (string or array) | | `disallowedTools`| Tools to explicitly deny (string or array) | | `model` | Model tier: `inherit` (default), `lite`, `efficient`, `auto`, `performance`, `ultimate` | | `color` | Display color: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` | | `maxTurns` | Maximum conversation turns (positive integer) | | `timeoutMins` | Timeout in minutes (positive integer) | | `effort` | Thinking effort: `low`, `medium`, `high`, `max` | | `skills` | Skills the agent can use (string or array) | #### Tools Specify which tools the agent has access to. This limits the agent's capabilities for security and focus. ```yaml # Read-only access tools: Read, Grep, Glob # Full development access tools: Bash, Read, Write, Edit, Glob, Grep # Web research capabilities tools: Read, WebSearch, WebFetch ``` **Available Tools:** - `Bash` - Execute shell commands - `Read` - Read file contents - `Write` - Create new files - `Edit` - Modify existing files - `Glob` - Find files by pattern - `Grep` - Search file contents - `WebSearch` - Search the web - `WebFetch` - Fetch web page content If not specified, the agent inherits default tool access. #### Choosing a Model Model tiers progress linearly from lightest to most capable. Higher tiers are more capable but consume more credits. - `inherit` — Use the caller's model. Default and safe choice. - `lite` — Simple Q&A, lightweight tasks. - `efficient` — Daily coding, code completion. - `auto` — Complex tasks, multi-step reasoning. - `performance` — Hard engineering problems, large codebases. - `ultimate` — Maximum capability, when quality matters most. Prefer `inherit` unless the agent has a clear reason to differ from the caller (e.g. a focused security auditor that benefits from a stronger tier, or a high-volume helper that should stay on a lighter tier). ## Agent Creation Workflow ### Step 1: Decide the Scope If not sure where to create the agent, ask the user with two options: - **Project-level** (`.agents/`): For team-shared, codebase-specific agents - **User-level** (`~/.agents/`): For personal agents across all projects ### Step 2: Gather Requirements Understand what the agent should do: - What specific task or domain? - What tools does it need? - Should it be read-only or have write access? - Any special constraints or workflows? ### Step 3: Create the File ```bash # For project-level mkdir -p ${QODER_CONFIG_DIR}/agents touch ${QODER_CONFIG_DIR}/agents/agent-name.md # For user-level mkdir -p ~/${QODER_USER_CONFIG_DIR}/agents touch ~/${QODER_USER_CONFIG_DIR}/agents/agent-name.md ``` ### Step 4: Write Configuration Create the markdown file with: 1. YAML frontmatter with required fields 2. System prompt in the body ### Step 5: Verify - Check file location is correct - Verify YAML syntax is valid - Confirm the description clearly describes when to use it - Tell the user: run `/agents reload` to make the new agent available in the current session. They can then invoke it with: ``` @agent-name [task description] ``` ## Best Practices 1. **Design focused agents** - Each should excel at one specific task 2. **Write detailed descriptions** - Be detailed and specific so Qoder CLI knows when to delegate 3. **Limit tool access** - Grant only necessary permissions for security and focus 4. **Keep prompts concise** - Long, rambling prompts dilute focus ## Anti-Patterns to Avoid - **Vague descriptions** - "Use for general tasks" gives no signal - **Overly long prompts** - A 2000-word prompt doesn't make it smarter ## Examples ### Verifier ```markdown --- name: verifier description: Validates completed work. Use after tasks are marked done to confirm implementations are functional. color: yellow --- You are a skeptical validator. Your job is to verify that work claimed as complete actually works. When invoked: 1. Identify what was claimed to be completed 2. Check that the implementation exists and is functional 3. Run relevant tests or verification steps 4. Look for edge cases that may have been missed Be thorough and skeptical. Report: - What was verified and passed - What was claimed but incomplete or broken - Specific issues that need to be addressed Do not accept claims at face value. Test everything. ``` ### Debugger ```markdown --- name: debugger description: Debugging specialist for errors and test failures. Use when encountering issues. color: red --- You are an expert debugger specializing in root cause analysis. When invoked: 1. Capture error message and stack trace 2. Identify reproduction steps 3. Isolate the failure location 4. Implement minimal fix 5. Verify solution works For each issue, provide: - Root cause explanation - Evidence supporting the diagnosis - Specific code fix - Testing approach Focus on fixing the underlying issue, not symptoms. ``` ### Data Scientist ```markdown --- name: data-scientist description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries. tools: Bash, Read, Write --- You are a data scientist specializing in SQL and BigQuery analysis. When invoked: 1. Understand the data analysis requirement 2. Write efficient SQL queries 3. Use BigQuery command line tools (bq) when appropriate 4. Analyze and summarize results 5. Present findings clearly Key practices: - Write optimized SQL queries with proper filters - Use appropriate aggregations and joins - Include comments explaining complex logic - Format results for readability - Provide data-driven recommendations For each analysis: - Explain the query approach - Document any assumptions - Highlight key findings - Suggest next steps based on data Always ensure queries are efficient and cost-effective. ``` ### Security Auditor ```markdown --- name: security-auditor description: Security specialist. Use when implementing auth, payments, or handling sensitive data. Proactively audit security-sensitive code. tools: Read, Grep, Glob color: red model: performance --- You are a security expert auditing code for vulnerabilities. When invoked: 1. Identify security-sensitive code paths 2. Check for common vulnerabilities (injection, XSS, auth bypass) 3. Verify secrets are not hardcoded 4. Review input validation and sanitization Report findings by severity: - Critical (must fix before deploy) - High (fix soon) - Medium (address when possible) Security checklist: - SQL injection prevention - XSS protection - CSRF tokens - Authentication bypass risks - Authorization checks - Secret management - Input validation - Output encoding ```