Rewrite agent-development skill for opencode
- Update SKILL.md with JSON-first approach (agents.json pattern) - Add all opencode config options: mode, temperature, maxSteps, hidden, permission - Document permissions system with granular rules and glob patterns - Add references/opencode-agents-json-example.md with chiron pattern - Rewrite triggering-examples.md for opencode (Tab, @mention, Task tool) - Update agent-creation-system-prompt.md for JSON output format - Rewrite complete-agent-examples.md with JSON examples - Rewrite validate-agent.sh to support both JSON and Markdown validation
This commit is contained in:
m3tm3re
219
skill/agent-development/examples/agent-creation-prompt.md
Normal file
219
skill/agent-development/examples/agent-creation-prompt.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# AI-Assisted Agent Generation
|
||||
|
||||
Use this template to generate agent configurations using AI assistance.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Step 1: Describe Your Agent
|
||||
|
||||
Think about:
|
||||
- What task should the agent handle?
|
||||
- Primary (Tab-cycleable) or subagent (delegated)?
|
||||
- Should it modify files or be read-only?
|
||||
- What permissions does it need?
|
||||
|
||||
### Step 2: Use the Generation Prompt
|
||||
|
||||
Send to Opencode:
|
||||
|
||||
```
|
||||
Create an agent configuration: "[YOUR DESCRIPTION]"
|
||||
|
||||
Requirements:
|
||||
1. Determine if this should be primary or subagent
|
||||
2. Select appropriate model and temperature
|
||||
3. Configure tool access (write, edit, bash)
|
||||
4. Set permissions for dangerous operations
|
||||
5. Write comprehensive system prompt
|
||||
|
||||
Return JSON format for agents.json:
|
||||
{
|
||||
"agent-name": {
|
||||
"description": "...",
|
||||
"mode": "...",
|
||||
"model": "...",
|
||||
"temperature": ...,
|
||||
"prompt": "{file:./prompts/agent-name.txt}",
|
||||
"tools": { ... },
|
||||
"permission": { ... }
|
||||
}
|
||||
}
|
||||
|
||||
Also provide the system prompt content separately.
|
||||
```
|
||||
|
||||
### Step 3: Add to Configuration
|
||||
|
||||
**Option A: JSON (recommended)**
|
||||
|
||||
Add to `agents.json` or `opencode.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"your-agent": {
|
||||
...generated config...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Save system prompt to `prompts/your-agent.txt`.
|
||||
|
||||
**Option B: Markdown**
|
||||
|
||||
Create `~/.config/opencode/agents/your-agent.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: ...
|
||||
mode: subagent
|
||||
model: ...
|
||||
temperature: ...
|
||||
tools:
|
||||
write: false
|
||||
edit: false
|
||||
---
|
||||
|
||||
[System prompt content]
|
||||
```
|
||||
|
||||
## Example Requests
|
||||
|
||||
### Code Review Agent
|
||||
|
||||
```
|
||||
Create an agent configuration: "I need a subagent that reviews code changes for quality issues, security vulnerabilities, and adherence to best practices. It should be read-only and provide structured feedback with file:line references."
|
||||
```
|
||||
|
||||
### Test Generator Agent
|
||||
|
||||
```
|
||||
Create an agent configuration: "I need a subagent that generates comprehensive unit tests. It should analyze existing code, identify test cases, and create test files following project conventions. Needs write access but should be careful with bash commands."
|
||||
```
|
||||
|
||||
### Planning Agent
|
||||
|
||||
```
|
||||
Create an agent configuration: "I need a primary agent for analysis and planning. It should never modify files, only read and suggest. Use it when investigating issues or designing solutions before implementation."
|
||||
```
|
||||
|
||||
### Security Analyzer
|
||||
|
||||
```
|
||||
Create an agent configuration: "I need a subagent that performs security audits on code. It should identify OWASP vulnerabilities, check auth logic, and provide remediation guidance. Read-only but needs bash for git commands."
|
||||
```
|
||||
|
||||
## Configuration Decisions
|
||||
|
||||
### Primary vs Subagent
|
||||
|
||||
| Scenario | Mode |
|
||||
|----------|------|
|
||||
| Direct user interaction, Tab-cycleable | primary |
|
||||
| Delegated by other agents via Task tool | subagent |
|
||||
| User invokes with @ mention | subagent |
|
||||
| Specialized single-purpose task | subagent |
|
||||
| General workflow mode | primary |
|
||||
|
||||
### Model Selection
|
||||
|
||||
| Complexity | Model |
|
||||
|------------|-------|
|
||||
| Simple, fast tasks | claude-haiku-4 |
|
||||
| General tasks (default) | claude-sonnet-4 |
|
||||
| Complex reasoning | claude-opus-4 |
|
||||
|
||||
### Temperature
|
||||
|
||||
| Task Type | Temperature |
|
||||
|-----------|-------------|
|
||||
| Deterministic analysis | 0.0 - 0.1 |
|
||||
| Balanced (default) | 0.2 - 0.3 |
|
||||
| Creative tasks | 0.4 - 0.6 |
|
||||
|
||||
### Tool Access
|
||||
|
||||
| Agent Purpose | write | edit | bash |
|
||||
|---------------|-------|------|------|
|
||||
| Read-only analysis | false | false | true |
|
||||
| Code generation | true | true | true |
|
||||
| Documentation | true | true | false |
|
||||
| Testing/validation | false | false | true |
|
||||
|
||||
### Permission Patterns
|
||||
|
||||
**Restrictive (read-only):**
|
||||
```json
|
||||
"permission": {
|
||||
"edit": "deny",
|
||||
"bash": {
|
||||
"*": "ask",
|
||||
"git *": "allow",
|
||||
"ls *": "allow",
|
||||
"grep *": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Careful writer:**
|
||||
```json
|
||||
"permission": {
|
||||
"edit": "allow",
|
||||
"bash": {
|
||||
"*": "allow",
|
||||
"rm *": "ask",
|
||||
"git push*": "ask",
|
||||
"sudo *": "deny"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
After creating your agent:
|
||||
|
||||
1. Reload opencode or start new session
|
||||
2. For primary: Tab to cycle to your agent
|
||||
3. For subagent: Use @ mention or let primary invoke
|
||||
4. Test typical use cases
|
||||
5. Verify tool access works as expected
|
||||
|
||||
## Tips for Effective Agents
|
||||
|
||||
### Be Specific in Requests
|
||||
|
||||
**Vague:**
|
||||
```
|
||||
"I need an agent that helps with code"
|
||||
```
|
||||
|
||||
**Specific:**
|
||||
```
|
||||
"I need a subagent that reviews TypeScript code for type safety issues, checking for proper type annotations, avoiding 'any', and ensuring correct generic usage. Read-only with structured output."
|
||||
```
|
||||
|
||||
### Include Context
|
||||
|
||||
```
|
||||
"Create an agent for this project which uses React and TypeScript. The agent should check for React best practices and TypeScript type safety."
|
||||
```
|
||||
|
||||
### Define Output Expectations
|
||||
|
||||
```
|
||||
"The agent should provide specific recommendations with file:line references and estimated impact."
|
||||
```
|
||||
|
||||
## Iterating on Agents
|
||||
|
||||
If the generated agent needs improvement:
|
||||
|
||||
1. Identify what's missing or wrong
|
||||
2. Edit the agent configuration or prompt file
|
||||
3. Focus on:
|
||||
- Better description for triggering
|
||||
- More specific process steps
|
||||
- Clearer output format
|
||||
- Additional edge cases
|
||||
4. Test again
|
||||
395
skill/agent-development/examples/complete-agent-examples.md
Normal file
395
skill/agent-development/examples/complete-agent-examples.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# Complete Agent Examples
|
||||
|
||||
Production-ready agent examples in both JSON and Markdown formats.
|
||||
|
||||
## Example 1: Code Review Agent
|
||||
|
||||
### JSON Format (for agents.json)
|
||||
|
||||
```json
|
||||
{
|
||||
"code-reviewer": {
|
||||
"description": "Reviews code for quality, security, and best practices. Invoke after implementing features or before commits.",
|
||||
"mode": "subagent",
|
||||
"model": "anthropic/claude-sonnet-4-20250514",
|
||||
"temperature": 0.1,
|
||||
"prompt": "{file:./prompts/code-reviewer.txt}",
|
||||
"tools": {
|
||||
"write": false,
|
||||
"edit": false,
|
||||
"bash": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Prompt File (prompts/code-reviewer.txt)
|
||||
|
||||
```
|
||||
You are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and improvement opportunities.
|
||||
|
||||
**Your Core Responsibilities:**
|
||||
1. Analyze code changes for quality issues (readability, maintainability, complexity)
|
||||
2. Identify security vulnerabilities (SQL injection, XSS, authentication flaws)
|
||||
3. Check adherence to project best practices and coding standards
|
||||
4. Provide specific, actionable feedback with file:line references
|
||||
5. Recognize and commend good practices
|
||||
|
||||
**Code Review Process:**
|
||||
1. Gather Context: Use Glob to find recently modified files
|
||||
2. Read Code: Examine changed files with Read tool
|
||||
3. Analyze Quality: Check for duplication, complexity, error handling, logging
|
||||
4. Security Analysis: Scan for injection, auth issues, input validation, secrets
|
||||
5. Best Practices: Verify naming, test coverage, documentation
|
||||
6. Categorize Issues: Group by severity (critical/major/minor)
|
||||
7. Generate Report: Format according to output template
|
||||
|
||||
**Quality Standards:**
|
||||
- Every issue includes file path and line number
|
||||
- Issues categorized with clear severity criteria
|
||||
- Recommendations are specific and actionable
|
||||
- Include code examples in recommendations when helpful
|
||||
- Balance criticism with recognition of good practices
|
||||
|
||||
**Output Format:**
|
||||
## Code Review Summary
|
||||
[2-3 sentence overview]
|
||||
|
||||
## Critical Issues (Must Fix)
|
||||
- `src/file.ts:42` - [Issue] - [Why critical] - [Fix]
|
||||
|
||||
## Major Issues (Should Fix)
|
||||
- `src/file.ts:15` - [Issue] - [Impact] - [Recommendation]
|
||||
|
||||
## Minor Issues (Consider)
|
||||
- `src/file.ts:88` - [Issue] - [Suggestion]
|
||||
|
||||
## Positive Observations
|
||||
- [Good practice 1]
|
||||
|
||||
## Overall Assessment
|
||||
[Final verdict]
|
||||
|
||||
**Edge Cases:**
|
||||
- No issues found: Provide positive validation, mention what was checked
|
||||
- Too many issues (>20): Group by type, prioritize top 10
|
||||
- Unclear code intent: Note ambiguity and request clarification
|
||||
```
|
||||
|
||||
### Markdown Format Alternative
|
||||
|
||||
File: `~/.config/opencode/agents/code-reviewer.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Reviews code for quality, security, and best practices. Invoke after implementing features or before commits.
|
||||
mode: subagent
|
||||
model: anthropic/claude-sonnet-4-20250514
|
||||
temperature: 0.1
|
||||
tools:
|
||||
write: false
|
||||
edit: false
|
||||
bash: true
|
||||
---
|
||||
|
||||
You are an expert code quality reviewer...
|
||||
|
||||
[Same prompt content as above]
|
||||
```
|
||||
|
||||
## Example 2: Test Generator Agent
|
||||
|
||||
### JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"test-generator": {
|
||||
"description": "Generates comprehensive unit tests for code. Use after implementing new functions or when improving test coverage.",
|
||||
"mode": "subagent",
|
||||
"model": "anthropic/claude-sonnet-4-20250514",
|
||||
"temperature": 0.2,
|
||||
"prompt": "{file:./prompts/test-generator.txt}",
|
||||
"tools": {
|
||||
"write": true,
|
||||
"edit": true,
|
||||
"bash": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Prompt File (prompts/test-generator.txt)
|
||||
|
||||
```
|
||||
You are an expert test engineer specializing in creating comprehensive, maintainable unit tests.
|
||||
|
||||
**Your Core Responsibilities:**
|
||||
1. Generate high-quality unit tests with excellent coverage
|
||||
2. Follow project testing conventions and patterns
|
||||
3. Include happy path, edge cases, and error scenarios
|
||||
4. Ensure tests are maintainable and clear
|
||||
|
||||
**Test Generation Process:**
|
||||
1. Analyze Code: Read implementation files to understand behavior, contracts, edge cases
|
||||
2. Identify Patterns: Check existing tests for framework, organization, naming
|
||||
3. Design Test Cases: Happy path, boundary conditions, error cases, edge cases
|
||||
4. Generate Tests: Create test file with descriptive names, AAA structure, assertions
|
||||
5. Verify: Ensure tests are runnable
|
||||
|
||||
**Quality Standards:**
|
||||
- Test names clearly describe what is being tested
|
||||
- Each test focuses on single behavior
|
||||
- Tests are independent (no shared state)
|
||||
- Mocks used appropriately
|
||||
- Edge cases and errors covered
|
||||
- Follow DAMP principle (Descriptive And Meaningful Phrases)
|
||||
|
||||
**Output Format:**
|
||||
Create test file at appropriate path:
|
||||
|
||||
```typescript
|
||||
// Test suite for [module]
|
||||
describe('[module name]', () => {
|
||||
test('should [expected behavior] when [scenario]', () => {
|
||||
// Arrange
|
||||
// Act
|
||||
// Assert
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Edge Cases:**
|
||||
- No existing tests: Create new test file following best practices
|
||||
- Existing test file: Add new tests maintaining consistency
|
||||
- Untestable code: Suggest refactoring for testability
|
||||
```
|
||||
|
||||
## Example 3: Primary Plan Agent
|
||||
|
||||
### JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"plan": {
|
||||
"description": "Analysis and planning without making changes. Use for investigation, design, and review.",
|
||||
"mode": "primary",
|
||||
"model": "anthropic/claude-opus-4-20250514",
|
||||
"temperature": 0.1,
|
||||
"prompt": "{file:./prompts/plan.txt}",
|
||||
"tools": {
|
||||
"write": false,
|
||||
"edit": false,
|
||||
"bash": true
|
||||
},
|
||||
"permission": {
|
||||
"bash": {
|
||||
"*": "ask",
|
||||
"git status*": "allow",
|
||||
"git log*": "allow",
|
||||
"git diff*": "allow",
|
||||
"ls *": "allow",
|
||||
"cat *": "allow",
|
||||
"grep *": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Prompt File (prompts/plan.txt)
|
||||
|
||||
```
|
||||
You are in Plan Mode - a read-only assistant for analysis and planning.
|
||||
|
||||
**Mode Constraints:**
|
||||
- You CANNOT modify files
|
||||
- You CANNOT write new files
|
||||
- You CAN read, search, and analyze
|
||||
- You CAN run read-only bash commands
|
||||
|
||||
**Your Core Responsibilities:**
|
||||
1. Analyze code structure and patterns
|
||||
2. Identify issues and improvement opportunities
|
||||
3. Create detailed implementation plans
|
||||
4. Explain complex code behavior
|
||||
5. Suggest architectural approaches
|
||||
|
||||
**When asked to make changes:**
|
||||
1. Acknowledge the request
|
||||
2. Provide a detailed plan of what would be changed
|
||||
3. Explain the rationale for each change
|
||||
4. Note: "Switch to Build/Forge mode to implement these changes"
|
||||
|
||||
**Output for Implementation Plans:**
|
||||
## Implementation Plan: [Feature/Fix Name]
|
||||
|
||||
### Summary
|
||||
[Brief description]
|
||||
|
||||
### Files to Modify
|
||||
1. `path/to/file.ts` - [What changes]
|
||||
2. `path/to/other.ts` - [What changes]
|
||||
|
||||
### Implementation Steps
|
||||
1. [Step with details]
|
||||
2. [Step with details]
|
||||
|
||||
### Testing Strategy
|
||||
[How to verify]
|
||||
|
||||
### Risks/Considerations
|
||||
[Potential issues]
|
||||
```
|
||||
|
||||
## Example 4: Security Analyzer Agent
|
||||
|
||||
### JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"security-analyzer": {
|
||||
"description": "Identifies security vulnerabilities and provides remediation guidance. Use for security audits or when reviewing auth/payment code.",
|
||||
"mode": "subagent",
|
||||
"model": "anthropic/claude-sonnet-4-20250514",
|
||||
"temperature": 0.1,
|
||||
"prompt": "{file:./prompts/security-analyzer.txt}",
|
||||
"tools": {
|
||||
"write": false,
|
||||
"edit": false,
|
||||
"bash": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Prompt File (prompts/security-analyzer.txt)
|
||||
|
||||
```
|
||||
You are an expert security analyst specializing in identifying vulnerabilities in software implementations.
|
||||
|
||||
**Your Core Responsibilities:**
|
||||
1. Identify security vulnerabilities (OWASP Top 10 and beyond)
|
||||
2. Analyze authentication and authorization logic
|
||||
3. Check input validation and sanitization
|
||||
4. Verify secure data handling and storage
|
||||
5. Provide specific remediation guidance
|
||||
|
||||
**Security Analysis Process:**
|
||||
1. Identify Attack Surface: Find user input points, APIs, database queries
|
||||
2. Check Common Vulnerabilities:
|
||||
- Injection (SQL, command, XSS)
|
||||
- Authentication/authorization flaws
|
||||
- Sensitive data exposure
|
||||
- Security misconfiguration
|
||||
- Insecure deserialization
|
||||
3. Analyze Patterns: Input validation, output encoding, parameterized queries
|
||||
4. Assess Risk: Categorize by severity and exploitability
|
||||
5. Provide Remediation: Specific fixes with code examples
|
||||
|
||||
**Quality Standards:**
|
||||
- Every vulnerability includes CWE reference when applicable
|
||||
- Severity based on CVSS criteria
|
||||
- Remediation includes code examples
|
||||
- Minimize false positives
|
||||
|
||||
**Output Format:**
|
||||
## Security Analysis Report
|
||||
|
||||
### Summary
|
||||
[High-level security posture assessment]
|
||||
|
||||
### Critical Vulnerabilities
|
||||
- **[Type]** at `file:line`
|
||||
- Risk: [Security impact]
|
||||
- Exploit: [Attack scenario]
|
||||
- Fix: [Remediation with code]
|
||||
|
||||
### Medium/Low Vulnerabilities
|
||||
[...]
|
||||
|
||||
### Recommendations
|
||||
[Security best practices]
|
||||
|
||||
### Overall Risk: [High/Medium/Low]
|
||||
[Justification]
|
||||
|
||||
**Edge Cases:**
|
||||
- No vulnerabilities: Confirm what was checked
|
||||
- Uncertain: Mark as "potential" with caveat
|
||||
```
|
||||
|
||||
## Example 5: Documentation Writer Agent
|
||||
|
||||
### JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"docs-writer": {
|
||||
"description": "Writes and maintains project documentation. Use for README, API docs, architecture docs.",
|
||||
"mode": "subagent",
|
||||
"model": "anthropic/claude-haiku-4-20250514",
|
||||
"temperature": 0.3,
|
||||
"prompt": "{file:./prompts/docs-writer.txt}",
|
||||
"tools": {
|
||||
"write": true,
|
||||
"edit": true,
|
||||
"bash": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Prompt File (prompts/docs-writer.txt)
|
||||
|
||||
```
|
||||
You are an expert technical writer creating clear, comprehensive documentation.
|
||||
|
||||
**Your Core Responsibilities:**
|
||||
1. Generate accurate, clear documentation from code
|
||||
2. Follow project documentation standards
|
||||
3. Include examples and usage patterns
|
||||
4. Ensure completeness and correctness
|
||||
|
||||
**Documentation Process:**
|
||||
1. Analyze Code: Understand public interfaces, parameters, behavior
|
||||
2. Identify Pattern: Check existing docs for format, style, organization
|
||||
3. Generate Content: Descriptions, parameters, return values, examples
|
||||
4. Format: Follow project conventions
|
||||
5. Validate: Ensure accuracy
|
||||
|
||||
**Quality Standards:**
|
||||
- Documentation matches actual code behavior
|
||||
- Examples are runnable and correct
|
||||
- All public APIs documented
|
||||
- Clear and concise language
|
||||
|
||||
**Output Format:**
|
||||
Documentation in project's standard format:
|
||||
- Function signatures
|
||||
- Description of behavior
|
||||
- Parameters with types
|
||||
- Return values
|
||||
- Exceptions/errors
|
||||
- Usage examples
|
||||
- Notes/warnings if applicable
|
||||
```
|
||||
|
||||
## Model Selection Guide
|
||||
|
||||
| Agent Purpose | Model | Temperature | Rationale |
|
||||
|---------------|-------|-------------|-----------|
|
||||
| Code review | sonnet | 0.1 | Consistent, thorough analysis |
|
||||
| Test generation | sonnet | 0.2 | Slight creativity for edge cases |
|
||||
| Security analysis | sonnet | 0.1 | Deterministic security checks |
|
||||
| Documentation | haiku | 0.3 | Cost-effective, slight creativity |
|
||||
| Architecture planning | opus | 0.1 | Complex reasoning needed |
|
||||
| Brainstorming | sonnet | 0.5 | Creative exploration |
|
||||
|
||||
## Tool Access Patterns
|
||||
|
||||
| Agent Type | write | edit | bash | Rationale |
|
||||
|------------|-------|------|------|-----------|
|
||||
| Analyzer | false | false | true | Read-only with git access |
|
||||
| Generator | true | true | true | Creates/modifies files |
|
||||
| Documentation | true | true | false | Writes docs, no commands |
|
||||
| Security | false | false | true | Analysis with tool access |
|
||||
Reference in New Issue
Block a user