346 lines
13 KiB
Markdown
346 lines
13 KiB
Markdown
# Opencode Agent Skills & Configurations
|
|
|
|
Central repository for [Opencode](https://opencode.ai) Agent Skills, AI agent configurations, custom commands, and AI-assisted workflows. This is an extensible framework for building productivity systems, automations, knowledge management, and specialized AI capabilities.
|
|
|
|
## 🎯 What This Repository Provides
|
|
|
|
This repository serves as a **personal AI operating system** - a collection of skills, agents, and configurations that extend Opencode's capabilities for:
|
|
|
|
- **Productivity & Task Management** - PARA methodology, GTD workflows, project tracking
|
|
- **Knowledge Management** - Note-taking, research workflows, information organization
|
|
- **Communications** - Email management, meeting scheduling, follow-up tracking
|
|
- **AI Development** - Tools for creating new skills and agent configurations
|
|
- **Memory & Context** - Persistent memory systems, conversation analysis
|
|
- **Document Processing** - PDF manipulation, spreadsheet handling, diagram generation
|
|
- **Custom Workflows** - Domain-specific automation and specialized agents
|
|
|
|
## 📂 Repository Structure
|
|
|
|
```
|
|
.
|
|
├── agents/ # Agent definitions (agents.json)
|
|
├── prompts/ # Agent system prompts (chiron.txt, chiron-forge.txt, etc.)
|
|
├── context/ # User profiles and preferences
|
|
│ └── profile.md # Work style, PARA areas, preferences
|
|
├── commands/ # Custom command definitions
|
|
│ └── reflection.md
|
|
├── skills/ # Opencode Agent Skills (18 skills)
|
|
│ ├── agent-development/ # Agent creation and configuration
|
|
│ ├── basecamp/ # Basecamp project management
|
|
│ ├── brainstorming/ # Ideation & strategic thinking
|
|
│ ├── doc-translator/ # Documentation translation
|
|
│ ├── excalidraw/ # Architecture diagrams
|
|
│ ├── frontend-design/ # UI/UX design patterns
|
|
│ ├── memory/ # Persistent memory system
|
|
│ ├── mem0-memory/ # DEPRECATED (use memory)
|
|
│ ├── msteams/ # Microsoft Teams integration
|
|
│ ├── obsidian/ # Obsidian vault management
|
|
│ ├── outline/ # Outline wiki integration
|
|
│ ├── outlook/ # Outlook email & calendar
|
|
│ ├── pdf/ # PDF manipulation toolkit
|
|
│ ├── prompt-engineering-patterns/ # Prompt patterns
|
|
│ ├── reflection/ # Conversation analysis
|
|
│ ├── skill-creator/ # Meta-skill for creating skills
|
|
│ ├── systematic-debugging/ # Debugging methodology
|
|
│ └── xlsx/ # Spreadsheet handling
|
|
├── scripts/ # Repository utility scripts
|
|
│ └── test-skill.sh # Test skills without deploying
|
|
├── rules/ # Development rules and conventions
|
|
├── tools/ # Utility tools
|
|
├── AGENTS.md # Developer documentation
|
|
└── README.md # This file
|
|
```
|
|
|
|
## 🚀 Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- **Opencode** - AI coding assistant ([opencode.dev](https://opencode.ai))
|
|
- **Nix** (optional) - For declarative deployment via home-manager
|
|
- **Python 3** - For skill validation and creation scripts
|
|
|
|
### Installation
|
|
|
|
#### Option 1: Nix Flake (Recommended)
|
|
|
|
This repository is consumed as a **non-flake input** by your NixOS configuration:
|
|
|
|
```nix
|
|
# In your flake.nix
|
|
inputs.agents = {
|
|
url = "git+https://code.m3ta.dev/m3tam3re/AGENTS";
|
|
flake = false; # Pure files, not a Nix flake
|
|
};
|
|
|
|
# In your home-manager module (e.g., opencode.nix)
|
|
xdg.configFile = {
|
|
"opencode/skills".source = "${inputs.agents}/skills";
|
|
"opencode/context".source = "${inputs.agents}/context";
|
|
"opencode/commands".source = "${inputs.agents}/commands";
|
|
"opencode/prompts".source = "${inputs.agents}/prompts";
|
|
};
|
|
|
|
# Agent config is embedded into config.json, not deployed as files
|
|
programs.opencode.settings.agent = builtins.fromJSON
|
|
(builtins.readFile "${inputs.agents}/agents/agents.json");
|
|
```
|
|
|
|
Rebuild your system:
|
|
|
|
```bash
|
|
home-manager switch
|
|
```
|
|
|
|
**Note**: The `agents/` directory is NOT deployed as files. Instead, `agents.json` is read at Nix evaluation time and embedded into the opencode `config.json`.
|
|
|
|
#### Option 2: Manual Installation
|
|
|
|
Clone and symlink:
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://github.com/yourusername/AGENTS.git ~/AGENTS
|
|
|
|
# Create symlinks to Opencode config directory
|
|
ln -s ~/AGENTS/skills ~/.config/opencode/skills
|
|
ln -s ~/AGENTS/context ~/.config/opencode/context
|
|
ln -s ~/AGENTS/commands ~/.config/opencode/commands
|
|
ln -s ~/AGENTS/prompts ~/.config/opencode/prompts
|
|
```
|
|
|
|
### Verify Installation
|
|
|
|
Check that Opencode can see your skills:
|
|
|
|
```bash
|
|
# Skills should be available at ~/.config/opencode/skills/
|
|
ls ~/.config/opencode/skills/
|
|
```
|
|
|
|
## 🎨 Creating Your First Skill
|
|
|
|
Skills are modular packages that extend Opencode with specialized knowledge and workflows.
|
|
|
|
### 1. Initialize a New Skill
|
|
|
|
```bash
|
|
python3 skills/skill-creator/scripts/init_skill.py my-skill-name --path skills/
|
|
```
|
|
|
|
This creates:
|
|
|
|
- `skills/my-skill-name/SKILL.md` - Main skill documentation
|
|
- `skills/my-skill-name/scripts/` - Executable code (optional)
|
|
- `skills/my-skill-name/references/` - Reference documentation (optional)
|
|
- `skills/my-skill-name/assets/` - Templates and files (optional)
|
|
|
|
### 2. Edit the Skill
|
|
|
|
Open `skills/my-skill-name/SKILL.md` and customize:
|
|
|
|
```yaml
|
|
---
|
|
name: my-skill-name
|
|
description: What it does and when to use it. Include trigger keywords.
|
|
compatibility: opencode
|
|
---
|
|
# My Skill Name
|
|
|
|
## Overview
|
|
|
|
[Your skill instructions for Opencode]
|
|
```
|
|
|
|
### 3. Validate the Skill
|
|
|
|
```bash
|
|
python3 skills/skill-creator/scripts/quick_validate.py skills/my-skill-name
|
|
```
|
|
|
|
### 4. Test the Skill
|
|
|
|
Test your skill without deploying via home-manager:
|
|
|
|
```bash
|
|
# Use the test script to validate and list skills
|
|
./scripts/test-skill.sh my-skill-name # Validate specific skill
|
|
./scripts/test-skill.sh --list # List all dev skills
|
|
./scripts/test-skill.sh --run # Launch opencode with dev skills
|
|
```
|
|
|
|
The test script creates a temporary config directory with symlinks to this repo's skills, allowing you to test changes before committing.
|
|
|
|
## 📚 Available Skills
|
|
|
|
| Skill | Purpose | Status |
|
|
| --------------------------- | -------------------------------------------------------------- | ------------ |
|
|
| **agent-development** | Create and configure Opencode agents | ✅ Active |
|
|
| **basecamp** | Basecamp project & todo management via MCP | ✅ Active |
|
|
| **brainstorming** | General-purpose ideation and strategic thinking | ✅ Active |
|
|
| **doc-translator** | Documentation translation to German/Czech with Outline publish | ✅ Active |
|
|
| **excalidraw** | Architecture diagrams from codebase analysis | ✅ Active |
|
|
| **frontend-design** | Production-grade UI/UX with high design quality | ✅ Active |
|
|
| **memory** | SQLite-based persistent memory with hybrid search | ✅ Active |
|
|
| **mem0-memory** | Legacy memory system (deprecated) | ⚠️ Deprecated |
|
|
| **msteams** | Microsoft Teams integration via Graph API | ✅ Active |
|
|
| **obsidian** | Obsidian vault management via Local REST API | ✅ Active |
|
|
| **outline** | Outline wiki integration for team documentation | ✅ Active |
|
|
| **outlook** | Outlook email, calendar, and contact management | ✅ Active |
|
|
| **pdf** | PDF manipulation, extraction, creation, and forms | ✅ Active |
|
|
| **prompt-engineering-patterns** | Advanced prompt engineering techniques | ✅ Active |
|
|
| **reflection** | Conversation analysis and skill improvement | ✅ Active |
|
|
| **skill-creator** | Guide for creating new Opencode skills | ✅ Active |
|
|
| **systematic-debugging** | Debugging methodology for bugs and test failures | ✅ Active |
|
|
| **xlsx** | Spreadsheet creation, editing, and analysis | ✅ Active |
|
|
|
|
## 🤖 AI Agents
|
|
|
|
### Primary Agents
|
|
|
|
| Agent | Mode | Purpose |
|
|
| ------------------- | ------- | ---------------------------------------------------- |
|
|
| **Chiron** | Plan | Read-only analysis, planning, and guidance |
|
|
| **Chiron Forge** | Build | Full execution and task completion with safety |
|
|
|
|
### Subagents (Specialists)
|
|
|
|
| Agent | Domain | Purpose |
|
|
| ------------------- | ---------------- | ------------------------------------------ |
|
|
| **Hermes** | Communication | Basecamp, Outlook, MS Teams |
|
|
| **Athena** | Research | Outline wiki, documentation, knowledge |
|
|
| **Apollo** | Private Knowledge| Obsidian vault, personal notes |
|
|
| **Calliope** | Writing | Documentation, reports, prose |
|
|
|
|
**Configuration**: `agents/agents.json` + `prompts/*.txt`
|
|
|
|
## 🛠️ Development Workflow
|
|
|
|
### Quality Gates
|
|
|
|
Before committing:
|
|
|
|
1. **Validate skills**: `./scripts/test-skill.sh --validate` or `python3 skills/skill-creator/scripts/quick_validate.py skills/<name>`
|
|
2. **Test locally**: `./scripts/test-skill.sh --run` to launch opencode with dev skills
|
|
3. **Check formatting**: Ensure YAML frontmatter is valid
|
|
4. **Update docs**: Keep README and AGENTS.md in sync
|
|
|
|
## 🎓 Learning Resources
|
|
|
|
### Essential Documentation
|
|
|
|
- **AGENTS.md** - Complete developer guide for AI agents
|
|
- **skills/skill-creator/SKILL.md** - Comprehensive skill creation guide
|
|
- **skills/skill-creator/references/workflows.md** - Workflow pattern library
|
|
- **skills/skill-creator/references/output-patterns.md** - Output formatting patterns
|
|
|
|
### Skill Design Principles
|
|
|
|
1. **Concise is key** - Context window is a shared resource
|
|
2. **Progressive disclosure** - Load information as needed
|
|
3. **Appropriate freedom** - Match specificity to task fragility
|
|
4. **No extraneous files** - Keep skills focused and minimal
|
|
|
|
### Example Skills to Study
|
|
|
|
- **skill-creator/** - Meta-skill with bundled resources
|
|
- **reflection/** - Conversation analysis with rating system
|
|
- **basecamp/** - MCP server integration with multiple tool categories
|
|
- **brainstorming/** - Framework-based ideation with Obsidian markdown save
|
|
- **memory/** - SQLite-based hybrid search implementation
|
|
|
|
## 🔧 Customization
|
|
|
|
### Modify Agent Behavior
|
|
|
|
Edit `agents/agents.json` for agent definitions and `prompts/*.txt` for system prompts:
|
|
|
|
- `agents/agents.json` - Agent names, models, permissions
|
|
- `prompts/chiron.txt` - Chiron (Plan Mode) system prompt
|
|
- `prompts/chiron-forge.txt` - Chiron Forge (Build Mode) system prompt
|
|
- `prompts/hermes.txt` - Hermes (Communication) system prompt
|
|
- `prompts/athena.txt` - Athena (Research) system prompt
|
|
- `prompts/apollo.txt` - Apollo (Private Knowledge) system prompt
|
|
- `prompts/calliope.txt` - Calliope (Writing) system prompt
|
|
|
|
**Note**: Agent changes require `home-manager switch` to take effect (config is embedded, not symlinked).
|
|
|
|
### Update User Context
|
|
|
|
Edit `context/profile.md` to configure:
|
|
|
|
- Work style preferences
|
|
- PARA areas and projects
|
|
- Communication preferences
|
|
- Integration status
|
|
|
|
### Add Custom Commands
|
|
|
|
Create new command definitions in `commands/` directory following the pattern in `commands/reflection.md`.
|
|
|
|
## 🌟 Use Cases
|
|
|
|
### Personal Productivity
|
|
|
|
Use the PARA methodology with Obsidian Tasks integration:
|
|
|
|
- Capture tasks and notes quickly
|
|
- Run daily/weekly reviews
|
|
- Prioritize work based on impact
|
|
- Batch similar tasks for efficiency
|
|
|
|
### Knowledge Management
|
|
|
|
Build a personal knowledge base:
|
|
|
|
- Capture research findings
|
|
- Organize notes and references
|
|
- Link related concepts
|
|
- Retrieve information on demand
|
|
|
|
### AI-Assisted Development
|
|
|
|
Extend Opencode for specialized domains:
|
|
|
|
- Create company-specific skills (finance, legal, engineering)
|
|
- Integrate with APIs and databases
|
|
- Build custom automation workflows
|
|
- Deploy via Nix for reproducibility
|
|
|
|
### Team Collaboration
|
|
|
|
Share skills and agents across teams:
|
|
|
|
- Document company processes as skills
|
|
- Create shared knowledge bases
|
|
- Standardize communication templates
|
|
- Build domain expertise libraries
|
|
|
|
## 🤝 Contributing
|
|
|
|
This is a personal repository, but the patterns and structure are designed to be reusable:
|
|
|
|
1. **Fork** this repository
|
|
2. **Customize** for your own use case
|
|
3. **Share** interesting skills and patterns
|
|
4. **Learn** from the skill-creator documentation
|
|
|
|
## 📝 License
|
|
|
|
This repository contains personal configurations and skills. Feel free to use the patterns and structure as inspiration for your own setup.
|
|
|
|
## 🔗 Links
|
|
|
|
- [Opencode](https://opencode.dev) - AI coding assistant
|
|
- [PARA Method](https://fortelabs.com/blog/para/) - Productivity methodology
|
|
- [Obsidian](https://obsidian.md) - Knowledge management platform
|
|
|
|
## 🙋 Questions?
|
|
|
|
- Check `AGENTS.md` for detailed developer documentation
|
|
- Review existing skills in `skills/` for examples
|
|
- See `skills/skill-creator/SKILL.md` for skill creation guide
|
|
|
|
---
|
|
|
|
**Built with** ❤️ **for AI-augmented productivity**
|