diff --git a/.changeset/great-queens-raise.md b/.changeset/great-queens-raise.md new file mode 100644 index 0000000..b694ed3 --- /dev/null +++ b/.changeset/great-queens-raise.md @@ -0,0 +1,5 @@ +--- +"restman": refactor +--- + +Refactored the app to use OpenTUI instead of Ink for better performance diff --git a/.opencode/agents/tui-dev.md b/.opencode/agents/tui-dev.md new file mode 100644 index 0000000..b8a315d --- /dev/null +++ b/.opencode/agents/tui-dev.md @@ -0,0 +1,312 @@ +--- +description: Build and modify terminal user interfaces using OpenTUI with React or Core API. Use when implementing terminal UIs, TUIs, CLI applications, interactive terminal components, keyboard navigation, terminal styling, or working on RestMan UI features. +mode: subagent +--- + +You are an expert OpenTUI developer specializing in building terminal user interfaces using OpenTUI with React or the Core API. + +## Your Expertise + +You specialize in: +- Building terminal UI applications with OpenTUI (React and Core API) +- Implementing interactive terminal components (boxes, inputs, selects, tabs) +- Adding keyboard navigation and input handling +- Styling terminal interfaces with colors and borders +- Debugging rendering and layout issues +- Working on RestMan UI features +- Creating TUI/CLI applications + +## OpenTUI Quick Reference + +### Installation & Setup + +```bash +# Core only +bun install @opentui/core + +# With React (recommended for RestMan) +bun install @opentui/react @opentui/core react +``` + +**TypeScript Config:** +```json +{ + "compilerOptions": { + "jsx": "react-jsx", + "jsxImportSource": "@opentui/react" + } +} +``` + +### Basic React App Structure + +```tsx +import { createCliRenderer } from '@opentui/core' +import { createRoot } from '@opentui/react' + +function App() { + return Hello, world! +} + +const renderer = await createCliRenderer({ exitOnCtrlC: false }) +const root = createRoot(renderer) +root.render() +``` + +## Key Concepts + +### Interactive Components MUST Be Focused + +Components like ``, ` + +// Core +input.focus() +``` + +### RestMan Color Scheme + +Always use these colors for consistency: +- **Primary (focus):** `#CC8844` +- **Secondary (edit mode):** `#BB7733` +- **Borders:** `#555555` +- **Muted text:** `#999999` +- **Background:** `#1a1a1a` + +## Common Components + +### Text +```tsx +Important Message +``` + +### Box (Container) +```tsx + + {children} + +``` + +### Input (Text Field) +```tsx + setValue(value)} + onSubmit={(value) => handleSubmit(value)} + focused={isFocused} +/> +``` + +### Select (List) +```tsx + + +``` + +### Dynamic Border Colors +```tsx +const getBorderColor = (focused: boolean, editMode: boolean): string => { + if (focused) return '#CC8844' + if (editMode) return '#BB7733' + return '#555555' +} +``` + +### Keyboard Navigation +```tsx +useKeyboard((key) => { + if (key.name === 'tab') { + // Cycle through fields + setFocused(fields[(fields.indexOf(focused) + 1) % fields.length]) + } + if (key.name === 'up') setSelectedIndex(Math.max(0, selectedIndex - 1)) + if (key.name === 'down') setSelectedIndex(Math.min(max, selectedIndex + 1)) +}) +``` + +## React Hooks + +- **useKeyboard(callback, options?)** - Handle keyboard input +- **useTerminalDimensions()** - Get terminal size +- **useRenderer()** - Access renderer instance +- **useOnResize(callback)** - Handle terminal resize + +## Best Practices + +1. **Choose the right approach:** Use React for RestMan UI (stateful, complex). Use Core for simple utilities. +2. **Always ensure focus:** Interactive components MUST be focused to work. +3. **Use RestMan colors:** Stick to the standard color scheme for consistency. +4. **Implement proper keyboard navigation:** Use `useKeyboard` hook in React. +5. **Style consistently:** Use kebab-case in style objects, direct props when possible. +6. **Use useCallback for handlers:** Prevents unnecessary re-renders in React. +7. **Fire-and-forget async:** Use `void asyncFunction()` to avoid lint warnings. +8. **Test in terminal:** Always test keyboard navigation flow. +9. **Handle modal keys separately:** Prevent conflicts with underlying UI. +10. **Exit edit mode with ESC:** Standard pattern for RestMan. + +## Styling + +### Direct Props (Recommended) +```tsx + +``` + +### Style Object +```tsx + +``` + +## Border Styles + +Available border styles: +- `'single'` - Single line border (─│┌┐└┘) +- `'double'` - Double line border (═║╔╗╚╝) +- `'rounded'` - Rounded corners (─│╭╮╰╯) +- `'bold'` - Bold line border (━┃┏┓┗┛) +- `'none'` - No border + +## Development Workflow + +When implementing TUI features: + +1. **Understand requirements** - Ask clarifying questions about: + - What components are needed? + - What keyboard shortcuts should work? + - What visual styling is expected? + - What state management is required? + +2. **Plan component structure** - Consider: + - Layout hierarchy (boxes, containers) + - Focus management strategy + - State flow and updates + - Keyboard navigation paths + +3. **Implement incrementally** - Start with: + - Basic layout and containers + - Static content and styling + - Interactive components + - Keyboard handlers + - State management + +4. **Test thoroughly** - Verify: + - All keyboard shortcuts work + - Focus management is correct + - Visual styling matches RestMan standards + - Edge cases are handled + +5. **Follow RestMan conventions** - Ensure: + - Color scheme consistency + - Keyboard patterns match existing UI + - Component structure follows project patterns + - Code style matches AGENTS.md guidelines + +## RestMan Integration Notes + +When working on RestMan: +1. Follow the component structure in `src/components/` +2. Use established patterns from `RequestEditor.tsx`, `HistoryView.tsx`, etc. +3. Maintain consistent focus management across views +4. Use the standard color scheme defined above +5. Test all keyboard shortcuts thoroughly +6. Ensure proper state management with React hooks + +## Common Gotchas + +1. **Interactive components need focus** - Always ensure input/select/tab-select are focused +2. **Key names vs sequences** - Use `key.name` for special keys, `key.sequence` for characters +3. **Yoga layout quirks** - Flexbox in terminals has edge cases +4. **Color formats** - Use hex strings or RGBA objects, not CSS rgb() +5. **Position absolute** - Requires explicit left/top values +6. **zIndex** - Higher values render on top + +## Your Approach + +When asked to help with OpenTUI development: +1. **Analyze the request** - Understand what UI elements are needed +2. **Check existing code** - Look at current RestMan components for patterns +3. **Design the solution** - Plan component structure and interactions +4. **Implement carefully** - Follow RestMan conventions and OpenTUI best practices +5. **Test the implementation** - Ensure keyboard navigation and styling work correctly +6. **Explain your choices** - Help the user understand the approach + +Remember: You have access to comprehensive OpenTUI documentation and RestMan codebase patterns. Use them to create high-quality terminal UI implementations. diff --git a/.opencode/commands/dev.md b/.opencode/commands/dev.md new file mode 100644 index 0000000..963bd1e --- /dev/null +++ b/.opencode/commands/dev.md @@ -0,0 +1,6 @@ +--- +description: TUI Development +agent: build +--- + +Use the opentui-react skill. diff --git a/.opencode/skills/opencode-agents/README.md b/.opencode/skills/opencode-agents/README.md new file mode 100644 index 0000000..cc8db66 --- /dev/null +++ b/.opencode/skills/opencode-agents/README.md @@ -0,0 +1,148 @@ +# OpenCode Agents Skill + +A comprehensive skill for creating and configuring custom OpenCode agents with specialized prompts, tools, permissions, and models. + +## What this skill provides + +This skill helps you: +- Create new OpenCode agents (primary and subagents) +- Configure agent tools, permissions, and models +- Understand agent modes and use cases +- Design specialized agents for specific workflows +- Manage agent configurations in JSON or Markdown format + +## Skill structure + +``` +opencode-agents/ +├── SKILL.md # Main skill instructions +├── references/ +│ └── REFERENCE.md # Comprehensive configuration reference +└── assets/ + └── templates/ + ├── read-only-reviewer.md # Code reviewer without write access + ├── security-auditor.json # Security-focused agent + ├── docs-writer.md # Documentation agent + ├── careful-dev.json # Development agent with approvals + └── prompts/ + └── security-auditor.txt # Security auditor custom prompt +``` + +## When to use + +This skill activates when you: +- Ask to create a new agent +- Want to modify agent configurations +- Mention agent modes, permissions, or tools +- Need specialized agents for code review, security, documentation, etc. +- Ask about agent switching or task delegation + +## Example templates + +### Read-only Code Reviewer +A subagent that reviews code using git commands without making any modifications. Perfect for getting feedback before implementing changes. + +**File**: `assets/templates/read-only-reviewer.md` + +### Security Auditor +A security-focused subagent with access to grep and git commands, plus web fetching for CVE lookups. Includes comprehensive security audit instructions. + +**Files**: +- `assets/templates/security-auditor.json` +- `assets/templates/prompts/security-auditor.txt` + +### Documentation Writer +A subagent specialized in writing clear, comprehensive documentation without bash access. + +**File**: `assets/templates/docs-writer.md` + +### Careful Developer +A primary agent that asks for approval before making file changes or running risky commands. Safe mode for development. + +**File**: `assets/templates/careful-dev.json` + +## Quick start + +### Creating an agent with the CLI + +```bash +opencode agent create +``` + +This interactive command will guide you through creating a new agent. + +### Creating an agent manually + +1. Choose configuration format (JSON or Markdown) +2. For Markdown, create a file in `.opencode/agents/` or `~/.config/opencode/agents/` +3. Add frontmatter with configuration +4. Write agent instructions in Markdown body + +Example: + +```markdown +--- +description: Reviews code for quality +mode: subagent +tools: + write: false + edit: false +--- + +You are a code reviewer. Focus on quality and best practices. +``` + +### Using a template + +Copy one of the templates from `assets/templates/` to your agents directory: + +```bash +# Global +cp .opencode/skills/opencode-agents/assets/templates/read-only-reviewer.md \ + ~/.config/opencode/agents/ + +# Project-specific +cp .opencode/skills/opencode-agents/assets/templates/read-only-reviewer.md \ + .opencode/agents/ +``` + +## Key concepts + +### Agent types +- **Primary agents**: Main assistants (switch with Tab key) +- **Subagents**: Specialized helpers (invoked via @ mention or automatically) + +### Configuration locations +- Global: `~/.config/opencode/opencode.json` or `~/.config/opencode/agents/*.md` +- Project: `.opencode/config.json` or `.opencode/agents/*.md` + +### Permissions +- `allow`: No approval needed +- `ask`: Prompt before execution +- `deny`: Completely disable + +### Common patterns +- **Read-only**: Disable write, edit, and bash tools +- **Git-only**: Allow only git commands in bash +- **Careful**: Set permissions to "ask" for dangerous operations +- **Specialized**: Custom prompts with focused tool access + +## Resources + +- **Main instructions**: `SKILL.md` +- **Complete reference**: `references/REFERENCE.md` +- **Example templates**: `assets/templates/` +- **OpenCode docs**: https://opencode.ai/docs/agents/ + +## Contributing + +Have a useful agent configuration? Consider adding it as a template to help others! + +1. Create your agent configuration +2. Test it thoroughly +3. Add it to `assets/templates/` +4. Update this README with a description + +## License + +MIT diff --git a/.opencode/skills/opencode-agents/SKILL.md b/.opencode/skills/opencode-agents/SKILL.md new file mode 100644 index 0000000..c2b2c07 --- /dev/null +++ b/.opencode/skills/opencode-agents/SKILL.md @@ -0,0 +1,686 @@ +--- +name: opencode-agents +description: Create and configure custom OpenCode agents (primary and subagents) with specialized prompts, tools, permissions, and models. Use when the user wants to create, modify, or configure OpenCode agents, or mentions agent modes, tool permissions, or task delegation. +license: MIT +metadata: + author: opencode-community + version: "1.0" + category: configuration +--- + +## When to use this skill + +Use this skill when: +- User asks to create a new OpenCode agent +- User wants to modify or configure an existing agent +- User mentions agent modes (primary, subagent) +- User wants to control tool permissions or access +- User needs specialized agents for specific tasks (review, security, docs, etc.) +- User mentions agent switching, task delegation, or @ mentions +- User wants to customize prompts or models for different workflows + +## What OpenCode agents are + +OpenCode agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access. + +### Agent types + +**Primary agents**: Main assistants you interact with directly. Switch between them using **Tab** key or configured keybind. +- Examples: Build (default with all tools), Plan (restricted for analysis) + +**Subagents**: Specialized assistants invoked by primary agents or via **@ mention**. +- Examples: General (multi-step tasks), Explore (read-only codebase exploration) + +### Built-in agents + +1. **Build** (primary): Default agent with all tools enabled for full development work +2. **Plan** (primary): Restricted agent for planning/analysis without making changes +3. **General** (subagent): General-purpose for complex questions and multi-step tasks +4. **Explore** (subagent): Fast, read-only agent for exploring codebases + +## Configuration methods + +Agents can be configured in two ways: + +### 1. JSON configuration + +Add agents to `opencode.json` config file: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "agent": { + "agent-name": { + "description": "What the agent does and when to use it", + "mode": "primary", + "model": "anthropic/claude-sonnet-4-20250514", + "temperature": 0.3, + "prompt": "{file:./prompts/agent-name.txt}", + "tools": { + "write": true, + "edit": true, + "bash": true + }, + "permission": { + "edit": "ask", + "bash": { + "*": "ask", + "git status *": "allow" + } + } + } + } +} +``` + +### 2. Markdown files + +Place markdown files in: +- Global: `~/.config/opencode/agents/` +- Per-project: `.opencode/agents/` + +The filename becomes the agent name (e.g., `review.md` creates `review` agent). + +```markdown +--- +description: Reviews code for quality and best practices +mode: subagent +model: anthropic/claude-sonnet-4-20250514 +temperature: 0.1 +tools: + write: false + edit: false + bash: false +permission: + edit: deny + bash: + "*": ask + "git diff": allow + "git log*": allow + webfetch: deny +--- + +You are in code review mode. Focus on: +- Code quality and best practices +- Potential bugs and edge cases +- Performance implications +- Security considerations + +Provide constructive feedback without making direct changes. +``` + +## Configuration options + +### Required fields + +#### description +Brief description of what the agent does and when to use it. +- **Required**: Yes (for custom agents) +- **Constraints**: Clear, actionable description with keywords + +```json +{ + "agent": { + "review": { + "description": "Reviews code for best practices and potential issues" + } + } +} +``` + +### Optional fields + +#### mode +Determines how the agent can be used. +- **Values**: `"primary"`, `"subagent"`, `"all"` (default if not specified) +- **Primary**: Main assistants you interact with directly (switchable via Tab) +- **Subagent**: Specialized assistants invoked by other agents or @ mention + +```json +{ + "agent": { + "review": { + "mode": "subagent" + } + } +} +``` + +#### model +Override the model for this agent. +- **Format**: `provider/model-id` +- **Examples**: `anthropic/claude-sonnet-4-20250514`, `openai/gpt-5`, `opencode/gpt-5.1-codex` +- Primary agents use globally configured model if not specified +- Subagents use the invoking primary agent's model if not specified + +```json +{ + "agent": { + "plan": { + "model": "anthropic/claude-haiku-4-20250514" + } + } +} +``` + +#### temperature +Control randomness and creativity of responses. +- **Range**: 0.0 to 1.0 +- **0.0-0.2**: Very focused and deterministic (code analysis, planning) +- **0.3-0.5**: Balanced with some creativity (general development) +- **0.6-1.0**: More creative and varied (brainstorming, exploration) +- **Default**: 0 for most models, 0.55 for Qwen models + +```json +{ + "agent": { + "analyze": { + "temperature": 0.1 + }, + "brainstorm": { + "temperature": 0.7 + } + } +} +``` + +#### prompt +Custom system prompt file for this agent. +- **Format**: `{file:./path/to/prompt.txt}` +- **Path**: Relative to config file location +- Works for both global and project-specific configs + +```json +{ + "agent": { + "review": { + "prompt": "{file:./prompts/code-review.txt}" + } + } +} +``` + +#### tools +Control which tools are available to this agent. +- **Values**: `true` (enable), `false` (disable) +- Can use wildcards: `"mymcp_*": false` +- Agent-specific config overrides global config + +```json +{ + "agent": { + "plan": { + "tools": { + "write": false, + "edit": false, + "bash": false, + "mymcp_*": false + } + } + } +} +``` + +#### permission +Manage what actions an agent can take. +- **Values**: `"ask"` (prompt for approval), `"allow"` (no approval needed), `"deny"` (disable) +- **Supported tools**: `edit`, `bash`, `webfetch` +- Can set permissions for specific bash commands with glob patterns +- Last matching rule takes precedence + +```json +{ + "agent": { + "build": { + "permission": { + "edit": "ask", + "bash": { + "*": "ask", + "git status *": "allow", + "git diff *": "allow", + "git push": "ask" + }, + "webfetch": "allow" + } + } + } +} +``` + +##### Task permissions +Control which subagents an agent can invoke via the Task tool. +- Uses glob patterns for flexible matching +- `"deny"` removes subagent from Task tool description +- Last matching rule wins +- Users can always invoke any subagent directly via @ mention + +```json +{ + "agent": { + "orchestrator": { + "permission": { + "task": { + "*": "deny", + "orchestrator-*": "allow", + "code-reviewer": "ask" + } + } + } + } +} +``` + +#### maxSteps +Maximum number of agentic iterations before text-only response. +- **Type**: Number +- Controls cost by limiting iterations +- Agent receives summary prompt when limit reached +- If not set, agent continues until model stops or user interrupts + +```json +{ + "agent": { + "quick-thinker": { + "maxSteps": 5 + } + } +} +``` + +#### disable +Disable the agent. +- **Values**: `true` (disable), `false` (enable) + +```json +{ + "agent": { + "review": { + "disable": true + } + } +} +``` + +#### hidden +Hide subagent from @ autocomplete menu. +- **Values**: `true` (hidden), `false` (visible) +- Only applies to `mode: subagent` +- Can still be invoked programmatically via Task tool + +```json +{ + "agent": { + "internal-helper": { + "mode": "subagent", + "hidden": true + } + } +} +``` + +#### Additional provider-specific options +Any other options are passed directly to the provider. +- Example: OpenAI reasoning models support `reasoningEffort`, `textVerbosity` + +```json +{ + "agent": { + "deep-thinker": { + "model": "openai/gpt-5", + "reasoningEffort": "high", + "textVerbosity": "low" + } + } +} +``` + +## Creating agents step-by-step + +### Using the CLI command + +The fastest way to create an agent: + +```bash +opencode agent create +``` + +This interactive command will: +1. Ask where to save (global or project-specific) +2. Prompt for description +3. Generate appropriate system prompt and identifier +4. Let you select which tools can be accessed +5. Create a markdown file with the configuration + +### Manual creation process + +#### 1. Gather requirements +Ask the user: +- What should the agent do? +- When should it be used? +- Should it be a primary agent or subagent? +- What tools does it need access to? +- Should any operations require approval? +- What model is best suited for the task? +- Should it have a custom prompt? + +#### 2. Choose agent name +- Use lowercase with hyphens (for markdown files) +- Keep it short and descriptive +- Examples: `review`, `security-audit`, `docs-writer` + +#### 3. Write clear description +Include: +- What the agent does +- When to use it +- Keywords for agent matching + +Good: "Reviews code for best practices and potential issues" +Poor: "Helps with code" + +#### 4. Select mode +- **Primary**: User switches to it directly (Tab key) +- **Subagent**: Invoked by other agents or @ mention +- **All**: Can be used both ways (default) + +#### 5. Configure tools and permissions +Decide which tools to enable/disable: +- Write operations (`write`, `edit`) +- Shell commands (`bash`) +- Web fetching (`webfetch`) +- MCP tools (wildcards like `mymcp_*`) + +Set permissions: +- `allow`: No approval needed +- `ask`: Prompt before execution +- `deny`: Completely disable + +#### 6. Choose model and temperature +- Fast models for planning: `anthropic/claude-haiku-4-20250514` +- Capable models for implementation: `anthropic/claude-sonnet-4-20250514` +- Temperature: lower (0.1) for focused work, higher (0.7) for creative tasks + +#### 7. Write custom prompt (optional) +If the agent needs specialized instructions: +1. Create a prompts directory (e.g., `./prompts/`) +2. Write a `.txt` or `.md` file with instructions +3. Reference it: `{file:./prompts/agent-name.txt}` + +#### 8. Decide on configuration format +- **JSON**: Better for complex configs, good for global agents +- **Markdown**: Better for prompt-heavy agents, good for project-specific + +#### 9. Create the configuration + +For Markdown (recommended for most use cases): + +```bash +# Global +mkdir -p ~/.config/opencode/agents +touch ~/.config/opencode/agents/agent-name.md + +# Project-specific +mkdir -p .opencode/agents +touch .opencode/agents/agent-name.md +``` + +For JSON: + +```bash +# Edit opencode.json (global or project .opencode/config.json) +``` + +#### 10. Validate configuration +Check that: +- Description is clear and keyword-rich +- Mode is appropriate for use case +- Tools match agent's purpose +- Permissions prevent unwanted actions +- Model is appropriate for task complexity +- Temperature matches desired creativity level +- Custom prompt (if any) is well-structured + +## Common agent patterns + +### Read-only analysis agent + +```json +{ + "agent": { + "analyzer": { + "description": "Analyzes code for patterns and insights without making changes", + "mode": "subagent", + "temperature": 0.1, + "tools": { + "write": false, + "edit": false, + "bash": false + } + } + } +} +``` + +### Security auditor + +```markdown +--- +description: Performs security audits and identifies vulnerabilities +mode: subagent +tools: + write: false + edit: false +permission: + bash: + "*": deny + "grep *": allow + "git log*": allow +--- + +You are a security expert. Focus on identifying potential security issues. + +Look for: +- Input validation vulnerabilities +- Authentication and authorization flaws +- Data exposure risks +- Dependency vulnerabilities +- Configuration security issues +``` + +### Documentation writer + +```json +{ + "agent": { + "docs-writer": { + "description": "Writes and maintains project documentation", + "mode": "subagent", + "model": "anthropic/claude-sonnet-4-20250514", + "tools": { + "bash": false + }, + "prompt": "{file:./prompts/docs-writer.txt}" + } + } +} +``` + +### Careful build agent with approvals + +```json +{ + "agent": { + "careful-build": { + "description": "Development agent that asks before making changes", + "mode": "primary", + "permission": { + "edit": "ask", + "bash": { + "*": "ask", + "git status": "allow", + "git diff": "allow" + } + } + } + } +} +``` + +### Specialized reviewer with git access + +```markdown +--- +description: Reviews code changes using git history and diffs +mode: subagent +temperature: 0.1 +tools: + write: false + edit: false +permission: + bash: + "*": deny + "git diff*": allow + "git log*": allow + "git show*": allow +--- + +You are a code reviewer with access to git history. + +Review process: +1. Use `git diff` to see changes +2. Use `git log` for context +3. Analyze for quality, security, performance +4. Provide constructive feedback +``` + +### Orchestrator with limited subagent access + +```json +{ + "agent": { + "orchestrator": { + "description": "Coordinates multiple specialized agents for complex tasks", + "mode": "primary", + "permission": { + "task": { + "*": "deny", + "explore": "allow", + "docs-writer": "allow", + "security-audit": "ask" + } + } + } + } +} +``` + +## Agent usage guide + +### Switching primary agents +- Use **Tab** key to cycle through primary agents +- Or use configured `switch_agent` keybind + +### Invoking subagents +- **Automatic**: Primary agents invoke based on descriptions +- **Manual**: @ mention in message (e.g., `@review please check this code`) + +### Navigating between sessions +When subagents create child sessions: +- **+Right**: Cycle forward (parent → child1 → child2 → parent) +- **+Left**: Cycle backward (parent ← child1 ← child2 ← parent) + +## Use cases by agent type + +### Primary agents +- **Build**: Full development work with all tools +- **Plan**: Analysis and planning without changes +- **Careful-build**: Development with approval prompts +- **Fast-build**: Quick iterations with faster model + +### Subagents +- **Review**: Code review with read-only access +- **Debug**: Investigation with bash and read tools +- **Docs**: Documentation writing without system commands +- **Security**: Security audits with limited tool access +- **Explore**: Fast codebase exploration (built-in) +- **General**: Multi-step complex tasks (built-in) + +## Best practices + +### Agent design +1. **Single responsibility**: Each agent should have a clear, focused purpose +2. **Descriptive names**: Use names that clearly indicate the agent's role +3. **Rich descriptions**: Include what the agent does AND when to use it +4. **Appropriate permissions**: Grant only the tools needed for the task +5. **Temperature matching**: Lower for deterministic tasks, higher for creative work + +### Tool configuration +1. **Principle of least privilege**: Disable tools not needed for the agent's purpose +2. **Use permissions wisely**: `ask` for dangerous operations, `allow` for safe ones +3. **Bash command granularity**: Allow specific safe commands, ask for risky ones +4. **Test thoroughly**: Ensure the agent can complete its tasks with given tools + +### Prompt engineering +1. **Clear instructions**: Be specific about what the agent should do +2. **Include examples**: Show expected behavior and output format +3. **Edge case handling**: Document how to handle unusual situations +4. **Consistent style**: Match the project's coding standards and conventions + +### Organization +1. **Global vs project**: Global for general-purpose, project for specific needs +2. **Markdown for prompts**: Use markdown format when custom prompts are primary +3. **JSON for config**: Use JSON when managing multiple related agents +4. **Version control**: Commit project-specific agents to git + +### Performance +1. **Use fast models for planning**: Haiku for analysis, Sonnet for implementation +2. **Set maxSteps**: Limit iterations for cost control +3. **Progressive disclosure**: Keep agents focused, use task delegation +4. **Cache-friendly prompts**: Shorter, stable prompts cache better + +## Troubleshooting + +### Agent not appearing +- Check `disable: false` is set (or option not present) +- For subagents, verify not `hidden: true` +- Ensure config file is in correct location +- Validate JSON syntax (if using JSON config) + +### Agent can't perform needed actions +- Check `tools` configuration includes needed tools +- Verify `permission` settings allow the operations +- For subagents, check parent's `permission.task` settings +- Ensure model has capability for the task + +### Agent asks for approval too often +- Change permission from `ask` to `allow` for safe operations +- Use glob patterns to allow specific bash commands +- Consider creating a separate agent without restrictions + +### Agent makes unwanted changes +- Set `permission.edit` to `ask` or `deny` +- Disable `write` tool if not needed +- Review custom prompt for overly aggressive instructions + +### Agent not invoking subagents +- Check subagent's `description` is clear and keyword-rich +- Verify parent's `permission.task` allows the subagent +- Ensure subagent is not `hidden: true` +- Consider manual invocation with @ mention + +## Example configurations + +See [assets/templates/](assets/templates/) for complete example configurations: +- `read-only-reviewer.md` - Code reviewer without write access +- `security-auditor.json` - Security-focused agent with limited bash +- `docs-writer.md` - Documentation agent with file access only +- `careful-dev.json` - Development agent with approval prompts + +## Resources + +- [OpenCode Agents Documentation](https://opencode.ai/docs/agents/) +- [OpenCode Configuration](https://opencode.ai/docs/config/) +- [OpenCode Permissions](https://opencode.ai/docs/permissions/) +- [OpenCode Tools](https://opencode.ai/docs/tools/) +- [OpenCode Models](https://opencode.ai/docs/models/) + +Run `opencode models` to see available models for your configured providers. diff --git a/.opencode/skills/opencode-agents/assets/templates/careful-dev.json b/.opencode/skills/opencode-agents/assets/templates/careful-dev.json new file mode 100644 index 0000000..681ba87 --- /dev/null +++ b/.opencode/skills/opencode-agents/assets/templates/careful-dev.json @@ -0,0 +1,32 @@ +{ + "agent": { + "careful-dev": { + "description": "Development agent that asks for approval before making file changes or running potentially risky commands", + "mode": "primary", + "model": "anthropic/claude-sonnet-4-20250514", + "temperature": 0.3, + "permission": { + "edit": "ask", + "bash": { + "*": "ask", + "git status": "allow", + "git diff": "allow", + "git log*": "allow", + "git show*": "allow", + "ls *": "allow", + "cat *": "allow", + "grep *": "allow" + }, + "webfetch": "allow" + }, + "tools": { + "write": true, + "edit": true, + "read": true, + "bash": true, + "glob": true, + "grep": true + } + } + } +} diff --git a/.opencode/skills/opencode-agents/assets/templates/docs-writer.md b/.opencode/skills/opencode-agents/assets/templates/docs-writer.md new file mode 100644 index 0000000..82e908b --- /dev/null +++ b/.opencode/skills/opencode-agents/assets/templates/docs-writer.md @@ -0,0 +1,97 @@ +--- +description: Writes and maintains technical documentation including README files, API docs, and user guides +mode: subagent +model: anthropic/claude-sonnet-4-20250514 +temperature: 0.3 +tools: + bash: false +--- + +You are a technical writer specializing in clear, comprehensive documentation. + +## Documentation principles + +1. **Clarity first** + - Use simple, direct language + - Avoid jargon unless necessary + - Define technical terms on first use + - Write for your target audience + +2. **Structure and organization** + - Use clear headings and hierarchy + - Logical flow from basic to advanced + - Table of contents for long documents + - Cross-reference related sections + +3. **Completeness** + - Cover all major features + - Include setup/installation instructions + - Document edge cases and limitations + - Provide troubleshooting guidance + +4. **Examples and code snippets** + - Show don't just tell + - Use realistic, practical examples + - Include expected output + - Comment code when helpful + +## Document types + +### README files +- Project overview and purpose +- Quick start guide +- Installation instructions +- Basic usage examples +- Link to full documentation +- Contributing guidelines +- License information + +### API documentation +- Endpoint descriptions +- Request/response formats +- Authentication requirements +- Error codes and handling +- Rate limiting information +- Code examples in multiple languages + +### User guides +- Step-by-step tutorials +- Feature explanations +- Screenshots or diagrams (when helpful) +- Common workflows +- Best practices +- FAQ section + +### Developer documentation +- Architecture overview +- Setup for development +- Code structure and conventions +- Testing guidelines +- Deployment process +- Contribution workflow + +## Formatting guidelines + +- Use Markdown for most documentation +- Code blocks with language specification +- Tables for structured data +- Lists (bulleted/numbered) for steps +- Bold for **emphasis**, italic for *terms* +- Links to related resources + +## Before writing + +1. Understand the code/feature thoroughly +2. Identify the target audience +3. Determine documentation type needed +4. Review existing documentation for style consistency + +## After writing + +1. Check for clarity and completeness +2. Verify all code examples work +3. Ensure proper formatting +4. Link related documentation +5. Update table of contents if needed + +Remember: Good documentation reduces support burden and improves user experience. diff --git a/.opencode/skills/opencode-agents/assets/templates/prompts/security-auditor.txt b/.opencode/skills/opencode-agents/assets/templates/prompts/security-auditor.txt new file mode 100644 index 0000000..ae8eb41 --- /dev/null +++ b/.opencode/skills/opencode-agents/assets/templates/prompts/security-auditor.txt @@ -0,0 +1,132 @@ +You are a security expert performing comprehensive security audits. + +## Your mission + +Identify security vulnerabilities, insecure patterns, and compliance issues in codebases. Focus on preventing security incidents before they occur. + +## Analysis areas + +### 1. Input Validation +- Validate all user inputs +- Sanitize data before use +- Check for injection attacks (SQL, NoSQL, command injection) +- Validate file uploads (type, size, content) +- Check for path traversal vulnerabilities + +### 2. Authentication & Authorization +- Strong password policies +- Secure session management +- Proper token handling (JWT, OAuth) +- Multi-factor authentication +- Role-based access control (RBAC) +- Privilege escalation risks + +### 3. Data Protection +- Sensitive data encryption (at rest and in transit) +- Secure credential storage +- PII (Personally Identifiable Information) handling +- Data exposure in logs or error messages +- Secure API key management + +### 4. Injection Vulnerabilities +- SQL injection +- NoSQL injection +- Command injection +- LDAP injection +- XPath injection +- Template injection + +### 5. Cross-Site Attacks +- XSS (Cross-Site Scripting) - stored, reflected, DOM-based +- CSRF (Cross-Site Request Forgery) +- Clickjacking +- Content Security Policy (CSP) implementation + +### 6. Cryptography +- Use of strong algorithms +- Proper key management +- Avoid deprecated crypto functions +- Secure random number generation +- Certificate validation + +### 7. Dependencies & Supply Chain +- Outdated dependencies with known vulnerabilities +- Unverified package sources +- Dependency confusion attacks +- License compliance + +### 8. Configuration & Deployment +- Exposed secrets in code or config +- Debug mode in production +- Verbose error messages +- Insecure default configurations +- Missing security headers + +### 9. API Security +- Rate limiting +- Input validation +- Authentication on all endpoints +- Proper HTTP methods +- CORS configuration + +### 10. Business Logic +- Race conditions +- Insufficient anti-automation +- Price manipulation +- Workflow bypass +- Insufficient logging and monitoring + +## Audit process + +1. **Reconnaissance** + - Understand application architecture + - Identify attack surface + - Map data flows + +2. **Static Analysis** + - Review code for patterns + - Check dependency versions + - Analyze configuration files + +3. **Threat Modeling** + - Identify assets and threats + - Determine impact and likelihood + - Prioritize risks + +4. **Reporting** + - Categorize by severity (Critical, High, Medium, Low) + - Provide clear descriptions + - Include remediation steps + - Reference security standards (OWASP, CWE) + +## Severity levels + +- **Critical**: Immediate exploitation, severe impact (RCE, data breach) +- **High**: Likely exploitation, significant impact (auth bypass, privilege escalation) +- **Medium**: Moderate impact or difficult exploitation (info disclosure, CSRF) +- **Low**: Minor impact or theoretical (verbose errors, missing security headers) + +## Output format + +### Critical Vulnerabilities +[List with CVE references if applicable] + +### High Severity Issues +[List with exploitation scenarios] + +### Medium Severity Issues +[List with recommended fixes] + +### Low Severity Issues +[List with best practice improvements] + +### Recommendations +[General security improvements] + +## Tools you can use + +- `grep` for pattern searching +- `git log` and `git diff` for change analysis +- `webfetch` to check for CVEs or security advisories + +Remember: Be thorough but prioritize actionable findings. Every finding should have a clear remediation path. diff --git a/.opencode/skills/opencode-agents/assets/templates/read-only-reviewer.md b/.opencode/skills/opencode-agents/assets/templates/read-only-reviewer.md new file mode 100644 index 0000000..af248fb --- /dev/null +++ b/.opencode/skills/opencode-agents/assets/templates/read-only-reviewer.md @@ -0,0 +1,89 @@ +--- +description: Reviews code for quality, security, and best practices without making any modifications +mode: subagent +model: anthropic/claude-sonnet-4-20250514 +temperature: 0.1 +tools: + write: false + edit: false +permission: + bash: + "*": deny + "git diff*": allow + "git log*": allow + "git show*": allow + "grep *": allow + webfetch: deny +--- + +You are an expert code reviewer focused on quality, security, and maintainability. + +## Review process + +1. **Understand the changes** + - Use `git diff` to see what changed + - Use `git log` to understand commit history and context + - Use `grep` to search for related code patterns + +2. **Analyze the code** + - Code quality and best practices + - Potential bugs and edge cases + - Performance implications + - Security vulnerabilities + - Test coverage + - Documentation completeness + +3. **Provide feedback** + - Be constructive and specific + - Explain the "why" behind suggestions + - Prioritize issues (critical, important, nice-to-have) + - Provide code examples when helpful + - Acknowledge good practices + +## Areas to focus on + +### Security +- Input validation +- Authentication and authorization +- Sensitive data handling +- SQL injection, XSS, CSRF vulnerabilities +- Dependency vulnerabilities + +### Performance +- Algorithm complexity +- Resource usage (memory, CPU) +- Database query efficiency +- Caching opportunities +- Async/await patterns + +### Maintainability +- Code clarity and readability +- Consistent naming conventions +- Proper error handling +- Documentation and comments +- Test coverage + +### Best practices +- DRY (Don't Repeat Yourself) +- SOLID principles +- Separation of concerns +- Type safety +- Error boundaries + +## Feedback format + +Structure your feedback as: + +### Critical Issues +Issues that must be fixed (security, bugs, breaking changes) + +### Important Suggestions +Improvements that significantly impact quality + +### Minor Suggestions +Nice-to-have improvements and style preferences + +### Positive Observations +What was done well + +Remember: You cannot make changes. Provide clear, actionable suggestions for the developer to implement. diff --git a/.opencode/skills/opencode-agents/assets/templates/security-auditor.json b/.opencode/skills/opencode-agents/assets/templates/security-auditor.json new file mode 100644 index 0000000..3324bf6 --- /dev/null +++ b/.opencode/skills/opencode-agents/assets/templates/security-auditor.json @@ -0,0 +1,24 @@ +{ + "agent": { + "security-auditor": { + "description": "Performs comprehensive security audits to identify vulnerabilities, insecure patterns, and compliance issues", + "mode": "subagent", + "model": "anthropic/claude-sonnet-4-20250514", + "temperature": 0.1, + "tools": { + "write": false, + "edit": false + }, + "permission": { + "bash": { + "*": "deny", + "grep *": "allow", + "git log*": "allow", + "git diff*": "allow" + }, + "webfetch": "allow" + }, + "prompt": "{file:./prompts/security-auditor.txt}" + } + } +} diff --git a/.opencode/skills/opencode-agents/references/REFERENCE.md b/.opencode/skills/opencode-agents/references/REFERENCE.md new file mode 100644 index 0000000..6bd0da7 --- /dev/null +++ b/.opencode/skills/opencode-agents/references/REFERENCE.md @@ -0,0 +1,390 @@ +# OpenCode Agent Configuration Reference + +This document provides comprehensive reference information for configuring OpenCode agents. + +## Configuration file locations + +### Global configuration +- **macOS/Linux**: `~/.config/opencode/opencode.json` +- **Windows**: `%APPDATA%\opencode\opencode.json` + +### Project-specific configuration +- `.opencode/config.json` (in project root) +- `.opencode/agents/*.md` (markdown agent files) + +### Agent markdown files +- **Global**: `~/.config/opencode/agents/*.md` +- **Project**: `.opencode/agents/*.md` + +## Complete configuration schema + +```json +{ + "$schema": "https://opencode.ai/config.json", + "agent": { + "agent-name": { + "description": "string (required)", + "mode": "primary | subagent | all", + "model": "provider/model-id", + "temperature": 0.0, + "maxSteps": 0, + "disable": false, + "hidden": false, + "prompt": "{file:./path/to/prompt.txt}", + "tools": { + "write": true, + "edit": true, + "read": true, + "bash": true, + "glob": true, + "grep": true, + "webfetch": true, + "task": true, + "todowrite": true, + "todoread": true, + "skill": true, + "question": true, + "mcp-tool-name": true, + "prefix_*": true + }, + "permission": { + "edit": "ask | allow | deny", + "bash": { + "*": "ask | allow | deny", + "specific-command *": "ask | allow | deny" + }, + "webfetch": "ask | allow | deny", + "task": { + "*": "ask | allow | deny", + "subagent-name": "ask | allow | deny" + } + } + } + } +} +``` + +## Markdown agent schema + +```yaml +--- +description: string (required) +mode: primary | subagent | all +model: provider/model-id +temperature: 0.0 +maxSteps: 0 +disable: false +hidden: false +tools: + write: true + edit: true + bash: true +permission: + edit: ask | allow | deny + bash: + "*": ask + "git diff": allow + webfetch: ask | allow | deny + task: + "*": deny + "allowed-subagent": allow +--- + +Agent instructions go here in Markdown format. +``` + +## Field reference + +### description +- **Type**: String +- **Required**: Yes (for custom agents) +- **Constraints**: 1-1024 characters, non-empty +- **Purpose**: Describes what the agent does and when to use it +- **Best practices**: + - Include both capabilities and use cases + - Add keywords for agent matching + - Be specific and actionable + +### mode +- **Type**: String +- **Required**: No +- **Default**: `"all"` +- **Values**: `"primary"`, `"subagent"`, `"all"` +- **Purpose**: Determines how agent can be invoked + - `primary`: Switchable via Tab key, main conversation + - `subagent`: Invoked by other agents or @ mention + - `all`: Can be used as either primary or subagent + +### model +- **Type**: String +- **Required**: No +- **Format**: `provider/model-id` +- **Default**: + - Primary agents: Global model config + - Subagents: Invoking agent's model +- **Examples**: + - `anthropic/claude-sonnet-4-20250514` + - `anthropic/claude-haiku-4-20250514` + - `openai/gpt-5` + - `opencode/gpt-5.1-codex` + +### temperature +- **Type**: Number +- **Required**: No +- **Range**: 0.0 to 1.0 +- **Default**: 0 (most models), 0.55 (Qwen models) +- **Purpose**: Controls response randomness/creativity +- **Guidelines**: + - 0.0-0.2: Deterministic, focused (analysis, planning) + - 0.3-0.5: Balanced (general development) + - 0.6-1.0: Creative (brainstorming, exploration) + +### maxSteps +- **Type**: Number +- **Required**: No +- **Default**: Unlimited +- **Purpose**: Limits agentic iterations for cost control +- **Behavior**: Agent receives summary prompt when limit reached + +### disable +- **Type**: Boolean +- **Required**: No +- **Default**: `false` +- **Purpose**: Disable agent without removing configuration + +### hidden +- **Type**: Boolean +- **Required**: No +- **Default**: `false` +- **Applies to**: `mode: subagent` only +- **Purpose**: Hide from @ autocomplete menu +- **Note**: Can still be invoked programmatically + +### prompt +- **Type**: String +- **Required**: No +- **Format**: `{file:./path/to/prompt.txt}` +- **Purpose**: Custom system prompt file +- **Path**: Relative to config file location +- **Supported formats**: `.txt`, `.md` + +### tools +- **Type**: Object +- **Required**: No +- **Purpose**: Control tool availability +- **Values**: `true` (enable), `false` (disable) +- **Wildcards**: Use `*` for pattern matching (e.g., `"mcp_*": false`) +- **Inheritance**: Agent config overrides global config +- **Available tools**: + - `write`: Create new files + - `edit`: Modify existing files + - `read`: Read file contents + - `bash`: Execute shell commands + - `glob`: Find files by pattern + - `grep`: Search file contents + - `webfetch`: Fetch web content + - `task`: Invoke subagents + - `todowrite`: Manage todo list + - `todoread`: Read todo list + - `skill`: Load agent skills + - `question`: Ask user questions + - MCP tools: Named by MCP server + +### permission +- **Type**: Object +- **Required**: No +- **Purpose**: Control what actions require approval +- **Values**: + - `"ask"`: Prompt for approval + - `"allow"`: No approval needed + - `"deny"`: Completely disable +- **Inheritance**: Agent config overrides global config + +#### permission.edit +- **Type**: String +- **Values**: `"ask"`, `"allow"`, `"deny"` +- **Purpose**: Control file editing operations + +#### permission.bash +- **Type**: String or Object +- **Simple format**: `"ask" | "allow" | "deny"` (applies to all commands) +- **Complex format**: Object with glob patterns + ```json + { + "bash": { + "*": "ask", + "git status": "allow", + "git diff*": "allow", + "git push*": "ask", + "rm *": "deny" + } + } + ``` +- **Pattern matching**: Last matching rule wins +- **Order matters**: Put `*` first, specific rules after + +#### permission.webfetch +- **Type**: String +- **Values**: `"ask"`, `"allow"`, `"deny"` +- **Purpose**: Control web content fetching + +#### permission.task +- **Type**: Object +- **Purpose**: Control subagent invocation +- **Format**: Map of subagent names to permission levels + ```json + { + "task": { + "*": "deny", + "allowed-*": "allow", + "maybe-subagent": "ask" + } + } + ``` +- **Behavior**: `"deny"` removes subagent from Task tool description +- **User override**: Users can always @ mention any subagent +- **Pattern matching**: Glob patterns supported, last match wins + +## Provider-specific options + +Any additional fields in agent config are passed to the provider. + +### OpenAI reasoning models +```json +{ + "agent": { + "deep-thinker": { + "model": "openai/gpt-5", + "reasoningEffort": "low | medium | high", + "textVerbosity": "low | medium | high" + } + } +} +``` + +### Other providers +Check your provider's documentation for available parameters. + +## Agent naming conventions + +### JSON config +- Use lowercase with hyphens +- Examples: `review`, `security-audit`, `docs-writer` + +### Markdown files +- Filename becomes agent name +- Use lowercase with hyphens +- Examples: `review.md`, `security-audit.md`, `docs-writer.md` + +## Configuration precedence + +1. **Agent-specific config** (highest priority) +2. **Project-specific global config** +3. **User global config** (lowest priority) + +For tools and permissions: +- Agent config overrides global config +- Within agent bash permissions, last matching glob pattern wins + +## Validation checklist + +- [ ] Description is clear and includes when to use +- [ ] Mode is appropriate (primary/subagent/all) +- [ ] Model is suitable for task complexity +- [ ] Temperature matches desired creativity +- [ ] Tools include everything needed +- [ ] Permissions prevent unwanted actions +- [ ] Bash glob patterns are ordered correctly (*first, specific last) +- [ ] Task permissions don't accidentally block needed subagents +- [ ] Custom prompt file exists at specified path +- [ ] JSON syntax is valid (if using JSON) +- [ ] YAML frontmatter is valid (if using markdown) + +## Common patterns + +### Read-only agent +```json +{ + "tools": { + "write": false, + "edit": false, + "bash": false + } +} +``` + +### Git-only agent +```json +{ + "permission": { + "bash": { + "*": "deny", + "git *": "allow" + } + }, + "tools": { + "write": false, + "edit": false + } +} +``` + +### Careful agent (asks for approval) +```json +{ + "permission": { + "edit": "ask", + "bash": { + "*": "ask", + "git status": "allow", + "git diff": "allow" + } + } +} +``` + +### Orchestrator (limited subagent access) +```json +{ + "permission": { + "task": { + "*": "deny", + "explore": "allow", + "review": "allow" + } + } +} +``` + +## Troubleshooting + +### Agent not showing up +- Check `disable: false` or option not set +- Verify mode is correct (primary vs subagent) +- Check `hidden: false` for subagents +- Validate file location (global vs project) +- Check JSON/YAML syntax + +### Can't perform needed actions +- Verify tool is enabled in `tools` section +- Check `permission` settings +- For subagents, check parent's `permission.task` +- Ensure model has required capabilities + +### Too many approval prompts +- Change `permission` from `ask` to `allow` +- Add specific bash commands with `allow` +- Consider separate unrestricted agent + +### Making unwanted changes +- Set `permission.edit` to `ask` or `deny` +- Disable `write` tool +- Review and tighten custom prompt +- Lower temperature for more focused behavior + +## See also + +- [OpenCode Agents Documentation](https://opencode.ai/docs/agents/) +- [OpenCode Permissions](https://opencode.ai/docs/permissions/) +- [OpenCode Tools](https://opencode.ai/docs/tools/) +- [OpenCode Models](https://opencode.ai/docs/models/) diff --git a/.opencode/skills/skills-creator/SKILL.md b/.opencode/skills/skills-creator/SKILL.md new file mode 100644 index 0000000..36c8559 --- /dev/null +++ b/.opencode/skills/skills-creator/SKILL.md @@ -0,0 +1,446 @@ +--- +name: skills-creator +description: Create and manage Agent Skills following the agentskills.io specification. Use when users want to create, validate, or modify skills for AI agents. +license: MIT +metadata: + author: restman + version: "1.0" +--- + +# Skills Creator + +A comprehensive skill for creating, validating, and managing Agent Skills that follow the agentskills.io specification. + +## When to use this skill + +Use this skill when: +- User asks to create a new agent skill +- User wants to modify or improve an existing skill +- User needs to validate a skill's structure or frontmatter +- User mentions "skill", "agent skill", or agentskills.io +- User wants to understand the Agent Skills format + +## What Agent Skills are + +Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. At its core, a skill is a folder containing a `SKILL.md` file with metadata and instructions. + +### Progressive disclosure principle + +Skills use progressive disclosure to manage context efficiently: +1. **Discovery**: At startup, agents load only name and description +2. **Activation**: When relevant, agents read the full SKILL.md instructions +3. **Execution**: Agents load referenced files or execute code as needed + +This keeps agents fast while providing access to more context on demand. + +## Directory structure + +``` +skill-name/ +├── SKILL.md # Required: instructions + metadata +├── scripts/ # Optional: executable code +├── references/ # Optional: documentation +└── assets/ # Optional: templates, resources +``` + +## SKILL.md format + +Every skill starts with YAML frontmatter followed by Markdown instructions. + +### Required frontmatter + +```yaml +--- +name: skill-name +description: A description of what this skill does and when to use it. +--- +``` + +### Optional frontmatter fields + +```yaml +--- +name: skill-name +description: What this skill does and when to use it. +license: MIT +compatibility: Requires git, docker, jq, and internet access +metadata: + author: example-org + version: "1.0" +allowed-tools: Bash(git:*) Bash(jq:*) Read +--- +``` + +## Field specifications + +### name field +- **Required**: Yes +- **Constraints**: 1-64 characters, lowercase letters/numbers/hyphens only +- Must not start or end with hyphen +- Must not contain consecutive hyphens (`--`) +- Must match the parent directory name + +**Valid examples:** +- `pdf-processing` +- `data-analysis` +- `code-review` + +**Invalid examples:** +- `PDF-Processing` (uppercase) +- `-pdf` (starts with hyphen) +- `pdf--processing` (consecutive hyphens) + +### description field +- **Required**: Yes +- **Constraints**: 1-1024 characters, non-empty +- Should describe both what the skill does AND when to use it +- Include specific keywords that help agents identify relevant tasks + +**Good example:** +```yaml +description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. +``` + +**Poor example:** +```yaml +description: Helps with PDFs. +``` + +### license field +- **Required**: No +- Keep it short (license name or reference to bundled file) + +Example: +```yaml +license: Apache-2.0 +``` + +### compatibility field +- **Required**: No +- **Constraints**: 1-500 characters if provided +- Only include if skill has specific environment requirements +- Can indicate intended product, required packages, network access, etc. + +Examples: +```yaml +compatibility: Designed for Claude Code (or similar products) +``` +```yaml +compatibility: Requires git, docker, jq, and access to the internet +``` + +### metadata field +- **Required**: No +- Map from string keys to string values +- Use for additional properties not defined by spec +- Make key names reasonably unique to avoid conflicts + +Example: +```yaml +metadata: + author: example-org + version: "1.0" + category: development +``` + +### allowed-tools field +- **Required**: No +- Space-delimited list of pre-approved tools +- Experimental feature, support varies + +Example: +```yaml +allowed-tools: Bash(git:*) Bash(jq:*) Read +``` + +## Body content guidelines + +The Markdown body after frontmatter contains the skill instructions. No format restrictions, but follow these best practices: + +### Recommended sections + +1. **When to use this skill** - Clear triggers for when agents should activate this skill +2. **What this skill does** - Brief overview of capabilities +3. **Step-by-step instructions** - Detailed procedures +4. **Examples** - Sample inputs and expected outputs +5. **Common patterns** - Reusable approaches +6. **Best practices** - Tips and recommendations +7. **Edge cases** - How to handle unusual situations + +### Content best practices + +- Keep main SKILL.md under 500 lines (< 5000 tokens recommended) +- Move detailed reference material to separate files in `references/` +- Use clear, actionable language +- Include code examples where helpful +- Focus on the "why" and "how", not just "what" +- Consider the agent's perspective when writing instructions + +## Optional directories + +### scripts/ +Contains executable code that agents can run. + +**Best practices:** +- Make scripts self-contained or clearly document dependencies +- Include helpful error messages +- Handle edge cases gracefully +- Use common languages (Python, Bash, JavaScript) + +Example structure: +``` +scripts/ +├── validate.py +├── generate.sh +└── utils/ + └── helpers.py +``` + +### references/ +Contains additional documentation loaded on demand. + +**Best practices:** +- Keep files focused on single topics +- Use descriptive filenames +- Recommended files: + - `REFERENCE.md` - Detailed technical reference + - `FORMS.md` - Form templates or structured data formats + - Domain-specific files (`finance.md`, `legal.md`, etc.) + +Example structure: +``` +references/ +├── REFERENCE.md +├── API.md +└── TROUBLESHOOTING.md +``` + +### assets/ +Contains static resources like templates, images, and data files. + +Example structure: +``` +assets/ +├── templates/ +│ └── config.yaml +├── diagrams/ +│ └── workflow.png +└── data/ + └── schema.json +``` + +## File references + +When referencing other files in your skill, use relative paths from the skill root: + +```markdown +See [the reference guide](references/REFERENCE.md) for details. + +Run the extraction script: +```bash +scripts/extract.py +``` +``` + +Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains. + +## Creating a new skill step-by-step + +When a user asks you to create a skill, follow these steps: + +### 1. Gather requirements +Ask the user: +- What should the skill do? +- When should it be activated? +- What tools or resources are needed? +- Are there specific examples or use cases? + +### 2. Choose a name +- Use lowercase with hyphens +- Keep it short and descriptive +- Ensure it matches the directory name + +### 3. Write a clear description +- Include what the skill does +- Include when to use it +- Add keywords for agent matching + +### 4. Create directory structure +```bash +mkdir -p skill-name/scripts +mkdir -p skill-name/references +mkdir -p skill-name/assets +``` + +### 5. Write SKILL.md +Start with frontmatter, then add body with: +- When to use section +- What it does +- Step-by-step instructions +- Examples +- Best practices + +### 6. Add supporting files (if needed) +- Scripts in `scripts/` +- Reference docs in `references/` +- Templates/assets in `assets/` + +### 7. Validate +Check that: +- Name follows constraints (lowercase, no consecutive hyphens, etc.) +- Description is clear and keyword-rich (1-1024 chars) +- Frontmatter is valid YAML +- Directory name matches skill name +- Instructions are clear and actionable + +## Common patterns + +### Basic skill (instructions only) +``` +basic-skill/ +└── SKILL.md +``` + +### Skill with scripts +``` +automation-skill/ +├── SKILL.md +└── scripts/ + └── automate.py +``` + +### Complex skill with references +``` +complex-skill/ +├── SKILL.md +├── scripts/ +│ └── process.py +├── references/ +│ ├── REFERENCE.md +│ └── API.md +└── assets/ + └── templates/ + └── config.yaml +``` + +## Validation checklist + +Before finalizing a skill, verify: + +- [ ] Directory name matches `name` in frontmatter +- [ ] `name` is 1-64 chars, lowercase alphanumeric + hyphens only +- [ ] `name` doesn't start/end with hyphen or have consecutive hyphens +- [ ] `description` is 1-1024 chars and includes when to use +- [ ] YAML frontmatter is valid +- [ ] Main SKILL.md is under 500 lines +- [ ] File references use relative paths +- [ ] Scripts have clear error handling (if present) +- [ ] No deeply nested reference chains + +## Example skill templates + +### Minimal skill +```markdown +--- +name: example-skill +description: Brief description of what this does and when to use it. +--- + +## When to use this skill +Use when... + +## Instructions +1. Step one +2. Step two +3. Step three +``` + +### Full-featured skill +```markdown +--- +name: advanced-skill +description: Comprehensive description with keywords for activation. +license: MIT +compatibility: Requires specific tools or environment +metadata: + author: your-name + version: "1.0" +--- + +## When to use this skill +Use when... + +## What this skill does +Overview... + +## Instructions +Detailed steps... + +## Examples +Sample code and outputs... + +## Best practices +Tips and recommendations... + +## Common patterns +Reusable approaches... + +## Troubleshooting +See [troubleshooting guide](references/TROUBLESHOOTING.md) +``` + +## Integration notes + +Skills are designed to work with filesystem-based agents (preferred) or tool-based agents: + +### Filesystem-based agents +- Skills activated via shell commands like `cat /path/to/skill/SKILL.md` +- Bundled resources accessed through shell commands + +### Tool-based agents +- Implement tools for triggering skills and accessing assets +- Tool implementation is up to the developer + +## Resources + +For more information: +- [agentskills.io specification](https://agentskills.io/specification) +- [Integration guide](https://agentskills.io/integrate-skills) +- [Example skills on GitHub](https://github.com/anthropics/skills) +- [Authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) +- [Reference library (skills-ref)](https://github.com/agentskills/agentskills/tree/main/skills-ref) + +## Validation commands + +If the user has the `skills-ref` library installed: + +```bash +# Validate a skill directory +skills-ref validate ./skill-name + +# Generate XML for agent prompts +skills-ref to-prompt ./skill-name +``` + +## Best practices for writing skills + +1. **Keep it focused**: One skill should do one thing well +2. **Be specific in descriptions**: Include activation keywords +3. **Use progressive disclosure**: Keep SKILL.md concise, move details to references +4. **Provide examples**: Show don't just tell +5. **Handle errors gracefully**: Anticipate edge cases +6. **Test thoroughly**: Ensure instructions are clear and complete +7. **Version your skills**: Use metadata to track changes +8. **Document dependencies**: Use compatibility field when needed +9. **Make it portable**: Skills should work across environments when possible +10. **Think like an agent**: Write instructions from the agent's perspective + +## Security considerations + +When creating skills with scripts: +- Warn about potentially dangerous operations +- Document all external dependencies +- Consider sandboxing requirements +- Use allowlisting for trusted scripts +- Log script executions for auditing +- Avoid hardcoded credentials or secrets diff --git a/.opencode/skills/skills-creator/assets/TEMPLATES.md b/.opencode/skills/skills-creator/assets/TEMPLATES.md new file mode 100644 index 0000000..33ded18 --- /dev/null +++ b/.opencode/skills/skills-creator/assets/TEMPLATES.md @@ -0,0 +1,528 @@ +# Skill Templates + +Quick-start templates for creating Agent Skills. + +## Template 1: Minimal Skill + +Use for simple, instruction-only skills. + +```markdown +--- +name: skill-name +description: Brief description of what this skill does and when to use it (include keywords). +--- + +## When to use this skill +Use when... + +## Instructions +1. First step +2. Second step +3. Third step + +## Examples +Example input: +\`\`\` +Sample input +\`\`\` + +Expected output: +\`\`\` +Sample output +\`\`\` +``` + +## Template 2: Skill with Scripts + +Use for skills that include executable code. + +```markdown +--- +name: automation-skill +description: Describe what this automates and when to use it. +license: MIT +compatibility: List required tools or packages +--- + +## When to use this skill +Use when user needs to... + +## What this skill does +Brief overview of capabilities. + +## Installation +\`\`\`bash +# Install dependencies +pip install required-package +\`\`\` + +## Instructions + +### Basic usage +1. Run the script: \`python scripts/main.py --input file.txt\` +2. Review output in \`output/\` directory +3. Handle any errors by checking logs + +### Advanced options +See \`python scripts/main.py --help\` for all options. + +## Script reference +- \`scripts/main.py\` - Primary entry point +- \`scripts/validate.py\` - Input validation +- \`scripts/utils.py\` - Helper functions + +## Examples +\`\`\`bash +# Example 1: Basic processing +python scripts/main.py --input data.csv + +# Example 2: With options +python scripts/main.py --input data.csv --format json --output results/ +\`\`\` + +## Troubleshooting +Common issues: +- **Error**: "Module not found" → Install dependencies +- **Error**: "Permission denied" → Check file permissions +``` + +## Template 3: Comprehensive Skill + +Use for complex skills with references and assets. + +```markdown +--- +name: advanced-skill +description: Comprehensive description with specific keywords for agent activation. +license: MIT +compatibility: Required environment and tools +metadata: + author: your-name + version: "1.0" + category: category-name + tags: tag1, tag2, tag3 +--- + +# Skill Name + +Brief introduction and purpose. + +## When to use this skill +Use when user: +- Needs to do X +- Wants to achieve Y +- Mentions keywords: A, B, C + +## What this skill does +High-level overview of capabilities. + +## Prerequisites +- Tool A (install: \`command\`) +- Tool B (install: \`command\`) +- Environment requirements + +## Quick start +\`\`\`bash +# 1. Setup +./scripts/setup.sh + +# 2. Basic usage +python scripts/main.py --input sample.txt + +# 3. Verify output +ls output/ +\`\`\` + +## Detailed instructions + +### Task 1: Description +1. Step-by-step instructions +2. Include code examples +3. Reference assets: \`assets/templates/config.yaml\` + +### Task 2: Description +1. More instructions +2. Reference documentation: [API Reference](references/API.md) + +## Examples + +### Example 1: Basic scenario +\`\`\`python +# Sample code +import module +result = module.process(data) +\`\`\` + +### Example 2: Advanced scenario +See [references/EXAMPLES.md](references/EXAMPLES.md) for detailed examples. + +## Common patterns +- Pattern 1: When to use and how +- Pattern 2: Best practices +- Pattern 3: Optimization tips + +## Configuration +Default config in \`assets/config.yaml\`: +\`\`\`yaml +setting1: value1 +setting2: value2 +\`\`\` + +Customize by copying to \`~/.skill-name/config.yaml\` + +## Reference documentation +- [API Reference](references/API.md) - Complete API documentation +- [Configuration Guide](references/CONFIG.md) - All configuration options +- [Troubleshooting](references/TROUBLESHOOTING.md) - Common issues and solutions +- [Examples](references/EXAMPLES.md) - Real-world use cases + +## Best practices +1. Best practice one with explanation +2. Best practice two with explanation +3. Best practice three with explanation + +## Troubleshooting +See [references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) for detailed solutions. + +Quick fixes: +- Issue 1: Solution +- Issue 2: Solution + +## Version history +See metadata.version for current version. Full changelog available in repository. +``` + +## Template 4: Tool Integration Skill + +Use for skills that integrate with specific tools. + +```markdown +--- +name: tool-integration +description: Integrate with [Tool Name] to perform specific tasks. Use when user needs to work with [Tool Name] or mentions [keywords]. +license: MIT +compatibility: Requires [Tool Name] version X.Y or higher +metadata: + author: integration-team + version: "1.0" + tool-version: "2.5+" +allowed-tools: Bash(tool-name:*) +--- + +# Tool Name Integration + +Automate and enhance [Tool Name] workflows. + +## When to use this skill +Use when: +- User mentions [Tool Name] +- User needs to perform tasks with [Tool Name] +- Keywords: tool-name, feature1, feature2 + +## What this skill does +- Integration capability 1 +- Integration capability 2 +- Integration capability 3 + +## Setup + +### Installation +\`\`\`bash +# Install the tool +brew install tool-name # or equivalent + +# Verify installation +tool-name --version +\`\`\` + +### Configuration +\`\`\`bash +# Initialize configuration +tool-name init + +# Set required options +tool-name config set option1 value1 +\`\`\` + +## Common workflows + +### Workflow 1: Task name +\`\`\`bash +tool-name command --option value +\`\`\` + +### Workflow 2: Task name +\`\`\`bash +tool-name command2 --flag +\`\`\` + +## Integration with scripts +The skill includes helper scripts: +- \`scripts/wrapper.sh\` - Enhanced tool wrapper +- \`scripts/batch.sh\` - Batch processing + +Example: +\`\`\`bash +./scripts/wrapper.sh --input data/ --output results/ +\`\`\` + +## Best practices +- Practice 1: When to use this approach +- Practice 2: How to optimize +- Practice 3: Common pitfalls to avoid + +## Tool-specific tips +- Tip 1: Specific to [Tool Name] +- Tip 2: Integration advice +``` + +## Template 5: Domain-Specific Skill + +Use for specialized domain knowledge (finance, legal, science, etc.). + +```markdown +--- +name: domain-skill +description: Domain-specific expertise for [specific tasks]. Use when user needs help with [domain] tasks or mentions [domain keywords]. +metadata: + author: domain-experts + version: "1.0" + domain: domain-name + expertise-level: intermediate +--- + +# Domain Skill Name + +Expert guidance for [domain] tasks. + +## When to use this skill +Use when user: +- Needs domain-specific knowledge +- Asks about domain concepts +- Mentions: keyword1, keyword2, keyword3 + +## Domain overview +Brief explanation of the domain and what this skill covers. + +## Key concepts +- Concept 1: Explanation +- Concept 2: Explanation +- Concept 3: Explanation + +## Common tasks + +### Task 1: Description +1. Domain-specific steps +2. Include formulas or calculations if relevant +3. Reference standards or regulations + +### Task 2: Description +1. More domain-specific guidance +2. Include examples from the domain +3. Reference best practices + +## Terminology +See [references/GLOSSARY.md](references/GLOSSARY.md) for domain terms. + +Quick reference: +- Term 1: Definition +- Term 2: Definition + +## Standards and regulations +- Standard 1: When it applies +- Regulation 1: Compliance requirements + +See [references/COMPLIANCE.md](references/COMPLIANCE.md) for details. + +## Examples + +### Real-world scenario 1 +Problem: Description +Solution: Step-by-step approach +Result: Expected outcome + +### Real-world scenario 2 +See [references/CASE_STUDIES.md](references/CASE_STUDIES.md) for more examples. + +## Best practices in [domain] +1. Practice specific to domain +2. Industry standards +3. Common patterns + +## Resources +- [Domain Reference](references/DOMAIN_REF.md) - Comprehensive domain knowledge +- [Calculations Guide](references/CALCULATIONS.md) - Formulas and methods +- External resources: Links to authoritative sources +``` + +## Template 6: Diagnostic/Troubleshooting Skill + +Use for skills focused on debugging and problem-solving. + +```markdown +--- +name: diagnostic-skill +description: Diagnose and fix issues with [system/tool]. Use when user reports errors, bugs, or problems with [specific system]. +metadata: + author: support-team + version: "1.0" + category: troubleshooting +--- + +# System Diagnostic Skill + +Identify and resolve issues with [System Name]. + +## When to use this skill +Use when: +- User reports an error or issue +- System is not working as expected +- Keywords: error, bug, not working, issue, problem + +## Diagnostic process + +### Step 1: Gather information +Run diagnostics: +\`\`\`bash +python scripts/diagnose.py +\`\`\` + +### Step 2: Identify the issue +Check common patterns: +1. Error type A → Solution path 1 +2. Error type B → Solution path 2 +3. Error type C → Solution path 3 + +### Step 3: Apply solution +Follow the appropriate solution guide below. + +## Common issues and solutions + +### Issue 1: Error message or symptom +**Symptoms:** What the user experiences +**Cause:** Why it happens +**Solution:** +\`\`\`bash +# Commands to fix +fix-command --option +\`\`\` + +### Issue 2: Error message or symptom +**Symptoms:** Description +**Cause:** Root cause +**Solution:** See [references/SOLUTIONS.md](references/SOLUTIONS.md#issue-2) + +## Diagnostic tools +- \`scripts/diagnose.py\` - System health check +- \`scripts/logs.py\` - Log analyzer +- \`scripts/test.py\` - Component testing + +## Decision tree +\`\`\` +Is service running? +├─ No → Start service: systemctl start service-name +└─ Yes + └─ Is service responding? + ├─ No → Check logs: journalctl -u service-name + └─ Yes → Check configuration +\`\`\` + +## Prevention +Best practices to avoid issues: +1. Preventive measure 1 +2. Preventive measure 2 +3. Regular maintenance tasks +``` + +## Directory structure templates + +### Minimal (instructions only) +``` +skill-name/ +└── SKILL.md +``` + +### With scripts +``` +skill-name/ +├── SKILL.md +└── scripts/ + ├── main.py + └── utils.py +``` + +### With references +``` +skill-name/ +├── SKILL.md +└── references/ + ├── REFERENCE.md + └── EXAMPLES.md +``` + +### Full structure +``` +skill-name/ +├── SKILL.md +├── scripts/ +│ ├── main.py +│ ├── validate.py +│ └── lib/ +│ └── helpers.py +├── references/ +│ ├── API.md +│ ├── EXAMPLES.md +│ └── TROUBLESHOOTING.md +└── assets/ + ├── templates/ + │ └── config.yaml + └── data/ + └── schema.json +``` + +## Quick reference: Required vs optional + +### Required +- ✅ Directory with skill name +- ✅ SKILL.md file +- ✅ Frontmatter with `name` and `description` +- ✅ Name matches directory name +- ✅ Valid YAML frontmatter + +### Optional but recommended +- 📝 License field +- 📝 Metadata for version and author +- 📝 Scripts directory for executable code +- 📝 References directory for detailed docs +- 📝 Assets directory for templates +- 📝 Examples section in SKILL.md +- 📝 Troubleshooting guidance + +### Optional (use when needed) +- ⚙️ Compatibility field (only if specific requirements) +- ⚙️ Allowed-tools field (experimental) +- ⚙️ Multiple reference files (if skill is complex) +- ⚙️ Assets for templates or data + +## Naming conventions + +### Skill names (lowercase with hyphens) +- ✅ `pdf-processing` +- ✅ `git-workflow` +- ✅ `data-analysis` +- ❌ `PDF-Processing` (no uppercase) +- ❌ `pdf_processing` (use hyphens, not underscores) +- ❌ `pdf--processing` (no consecutive hyphens) + +### Script names (descriptive, extension indicates language) +- ✅ `process.py` +- ✅ `validate.sh` +- ✅ `analyze.js` +- ✅ `batch_process.py` (underscores OK in scripts) + +### Reference names (UPPERCASE for visibility) +- ✅ `REFERENCE.md` +- ✅ `API.md` +- ✅ `EXAMPLES.md` +- ✅ `TROUBLESHOOTING.md` +- ✅ `glossary.md` (lowercase also acceptable) diff --git a/.opencode/skills/skills-creator/references/REFERENCE.md b/.opencode/skills/skills-creator/references/REFERENCE.md new file mode 100644 index 0000000..ca7a0a3 --- /dev/null +++ b/.opencode/skills/skills-creator/references/REFERENCE.md @@ -0,0 +1,437 @@ +# Skills Creator Reference + +This reference provides detailed examples and edge cases for creating Agent Skills. + +## Complete skill examples + +### Example 1: PDF Processing Skill + +```markdown +--- +name: pdf-processing +description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. +license: Apache-2.0 +compatibility: Requires pdfplumber, PyPDF2 Python packages +metadata: + author: example-org + version: "1.2" + category: document-processing +--- + +# PDF Processing + +## When to use this skill +Use this skill when the user needs to: +- Extract text or tables from PDF files +- Fill PDF forms programmatically +- Merge multiple PDF documents +- Split PDF files +- Add watermarks or annotations + +## Instructions + +### Extracting text from PDFs +1. Use the pdfplumber library for text extraction +2. Handle multi-page documents by iterating through pages +3. Preserve formatting when possible + +Example: +```python +import pdfplumber + +with pdfplumber.open('document.pdf') as pdf: + for page in pdf.pages: + text = page.extract_text() + print(text) +``` + +### Filling PDF forms +1. Use PyPDF2 for form filling +2. Get field names first using scripts/get_form_fields.py +3. Update fields with new values + +See [FORMS.md](references/FORMS.md) for field specifications. + +### Merging PDFs +1. Use PyPDF2.PdfMerger +2. Add files in desired order +3. Write to output file + +Run: `python scripts/merge.py input1.pdf input2.pdf -o output.pdf` + +## Best practices +- Always validate PDF files before processing +- Handle encrypted PDFs appropriately +- Check file permissions before writing +- Use try-catch for better error handling +``` + +### Example 2: Git Workflow Skill + +```markdown +--- +name: git-workflow +description: Automate common git operations including branch management, commit conventions, and pull request creation. Use when user needs help with git commands, branching strategies, or version control workflows. +license: MIT +compatibility: Requires git CLI and gh (GitHub CLI) for PR operations +metadata: + author: devtools-team + version: "2.0" +allowed-tools: Bash(git:*) Bash(gh:*) +--- + +# Git Workflow + +## When to use this skill +Use when the user: +- Needs to create branches following naming conventions +- Wants to commit with conventional commit messages +- Needs to create or manage pull requests +- Asks about git workflows or branching strategies +- Mentions git, commits, branches, or PRs + +## Branch naming conventions + +Follow this pattern: `/` + +Types: +- `feature/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation updates +- `refactor/` - Code refactoring +- `test/` - Test additions or changes + +Example: `feature/add-user-authentication` + +## Commit message format + +Use conventional commits: +``` +(): + + + +