docs: expand scope and add comprehensive documentation
Create README.md and enhance AGENTS.md to position this as an extensible framework for any Opencode skills and agents, not just PARA/task management. Includes installation, development workflow, code style guidelines, and Nix flake integration patterns.
This commit is contained in:
m3tm3re
315
README.md
Normal file
315
README.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# Opencode Agent Skills & Configurations
|
||||
|
||||
Central repository for [Opencode](https://opencode.dev) 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
|
||||
- **Custom Workflows** - Domain-specific automation and specialized agents
|
||||
|
||||
## 📂 Repository Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── agent/ # AI agent configurations
|
||||
│ └── chiron.md # Personal assistant agent
|
||||
├── context/ # User profiles and preferences
|
||||
│ └── profile.md # Work style, PARA areas, preferences
|
||||
├── command/ # Custom command definitions
|
||||
│ └── reflection.md
|
||||
├── skill/ # Opencode Agent Skills (8+ skills)
|
||||
│ ├── task-management/ # PARA-based productivity
|
||||
│ ├── skill-creator/ # Meta-skill for creating skills
|
||||
│ ├── reflection/ # Conversation analysis
|
||||
│ ├── communications/ # Email & messaging
|
||||
│ ├── calendar-scheduling/ # Time management
|
||||
│ ├── mem0-memory/ # Persistent memory
|
||||
│ ├── research/ # Investigation workflows
|
||||
│ └── knowledge-management/ # Note capture & organization
|
||||
├── .beads/ # Issue tracking database
|
||||
├── AGENTS.md # Developer documentation
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Opencode** - AI coding assistant ([opencode.dev](https://opencode.dev))
|
||||
- **Nix** (optional) - For declarative deployment via home-manager
|
||||
- **Python 3** - For skill validation and creation scripts
|
||||
- **bd (beads)** (optional) - For issue tracking
|
||||
|
||||
### Installation
|
||||
|
||||
#### Option 1: Nix Flake (Recommended)
|
||||
|
||||
Add to your Nix flake configuration:
|
||||
|
||||
```nix
|
||||
# In your flake.nix or home.nix
|
||||
{
|
||||
inputs.agents = {
|
||||
url = "github:yourusername/AGENTS"; # Update with your repo
|
||||
flake = false;
|
||||
};
|
||||
|
||||
# In your home-manager configuration
|
||||
xdg.configFile."opencode" = {
|
||||
source = inputs.agents;
|
||||
recursive = true;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Rebuild your system:
|
||||
```bash
|
||||
home-manager switch
|
||||
```
|
||||
|
||||
#### Option 2: Manual Installation
|
||||
|
||||
Clone and symlink:
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/yourusername/AGENTS.git ~/AGENTS
|
||||
|
||||
# Create symlink to Opencode config directory
|
||||
ln -s ~/AGENTS ~/.config/opencode
|
||||
```
|
||||
|
||||
### Verify Installation
|
||||
|
||||
Check that Opencode can see your skills:
|
||||
|
||||
```bash
|
||||
# Skills should be available at ~/.config/opencode/skill/
|
||||
ls ~/.config/opencode/skill/
|
||||
```
|
||||
|
||||
## 🎨 Creating Your First Skill
|
||||
|
||||
Skills are modular packages that extend Opencode with specialized knowledge and workflows.
|
||||
|
||||
### 1. Initialize a New Skill
|
||||
|
||||
```bash
|
||||
python3 skill/skill-creator/scripts/init_skill.py my-skill-name --path skill/
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `skill/my-skill-name/SKILL.md` - Main skill documentation
|
||||
- `skill/my-skill-name/scripts/` - Executable code (optional)
|
||||
- `skill/my-skill-name/references/` - Reference documentation (optional)
|
||||
- `skill/my-skill-name/assets/` - Templates and files (optional)
|
||||
|
||||
### 2. Edit the Skill
|
||||
|
||||
Open `skill/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 skill/skill-creator/scripts/quick_validate.py skill/my-skill-name
|
||||
```
|
||||
|
||||
### 4. Test in Opencode
|
||||
|
||||
Open Opencode and trigger your skill naturally in conversation. The skill will load based on the `description` field in the frontmatter.
|
||||
|
||||
## 📚 Available Skills
|
||||
|
||||
| Skill | Purpose | Status |
|
||||
|-------|---------|--------|
|
||||
| **task-management** | PARA-based productivity with Anytype integration | ✅ Active |
|
||||
| **skill-creator** | Guide for creating new Opencode skills | ✅ Active |
|
||||
| **reflection** | Conversation analysis and skill improvement | ✅ Active |
|
||||
| **communications** | Email drafts, follow-ups, message management | ✅ Active |
|
||||
| **calendar-scheduling** | Time blocking, meeting management | ✅ Active |
|
||||
| **mem0-memory** | Persistent memory storage and retrieval | ✅ Active |
|
||||
| **research** | Investigation workflows, source management | 🚧 Stub |
|
||||
| **knowledge-management** | Note capture, knowledge organization | 🚧 Stub |
|
||||
|
||||
## 🤖 AI Agents
|
||||
|
||||
### Chiron - Personal Assistant
|
||||
|
||||
**Location**: `agent/chiron.md`
|
||||
|
||||
Chiron is a personal AI assistant focused on productivity and task management. Named after the wise centaur from Greek mythology, Chiron provides:
|
||||
|
||||
- Task and project management guidance
|
||||
- Daily and weekly review workflows
|
||||
- Skill routing based on user intent
|
||||
- Integration with productivity tools (Anytype, ntfy, n8n)
|
||||
|
||||
**Triggers**: Personal productivity requests, task management, reviews, planning
|
||||
|
||||
## 🛠️ Development Workflow
|
||||
|
||||
### Issue Tracking with Beads
|
||||
|
||||
This project uses [beads](https://github.com/steveyegge/beads) for AI-native issue tracking:
|
||||
|
||||
```bash
|
||||
bd ready # Find available work
|
||||
bd create "title" # Create new issue
|
||||
bd update <id> --status in_progress
|
||||
bd close <id> # Complete work
|
||||
bd sync # Sync with git
|
||||
```
|
||||
|
||||
### Quality Gates
|
||||
|
||||
Before committing:
|
||||
|
||||
1. **Validate skills**: `python3 skill/skill-creator/scripts/quick_validate.py skill/<name>`
|
||||
2. **Check formatting**: Ensure YAML frontmatter is valid
|
||||
3. **Test locally**: Use the skill in Opencode to verify behavior
|
||||
4. **Update docs**: Keep README and AGENTS.md in sync
|
||||
|
||||
### Session Completion
|
||||
|
||||
When ending a work session:
|
||||
|
||||
1. File beads issues for remaining work
|
||||
2. Run quality gates
|
||||
3. Update issue status
|
||||
4. **Push to remote** (mandatory):
|
||||
```bash
|
||||
git pull --rebase
|
||||
bd sync
|
||||
git push
|
||||
```
|
||||
5. Verify changes are pushed
|
||||
|
||||
See `AGENTS.md` for complete developer documentation.
|
||||
|
||||
## 🎓 Learning Resources
|
||||
|
||||
### Essential Documentation
|
||||
|
||||
- **AGENTS.md** - Complete developer guide for AI agents
|
||||
- **skill/skill-creator/SKILL.md** - Comprehensive skill creation guide
|
||||
- **skill/skill-creator/references/workflows.md** - Workflow pattern library
|
||||
- **skill/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
|
||||
|
||||
- **task-management/** - Full implementation with Anytype integration
|
||||
- **skill-creator/** - Meta-skill with bundled resources
|
||||
- **reflection/** - Conversation analysis with rating system
|
||||
|
||||
## 🔧 Customization
|
||||
|
||||
### Modify Agent Behavior
|
||||
|
||||
Edit `agent/chiron.md` to customize:
|
||||
- Skill routing logic
|
||||
- Communication style
|
||||
- Operating principles
|
||||
- Integration awareness
|
||||
|
||||
### 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 `command/` directory following the pattern in `command/reflection.md`.
|
||||
|
||||
## 🌟 Use Cases
|
||||
|
||||
### Personal Productivity
|
||||
|
||||
Use the PARA methodology with Anytype 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
|
||||
- [Beads](https://github.com/steveyegge/beads) - AI-native issue tracking
|
||||
- [PARA Method](https://fortelabs.com/blog/para/) - Productivity methodology
|
||||
- [Anytype](https://anytype.io) - Knowledge management platform
|
||||
|
||||
## 🙋 Questions?
|
||||
|
||||
- Check `AGENTS.md` for detailed developer documentation
|
||||
- Review existing skills in `skill/` for examples
|
||||
- See `skill/skill-creator/SKILL.md` for skill creation guide
|
||||
|
||||
---
|
||||
|
||||
**Built with** ❤️ **for AI-augmented productivity**
|
||||
Reference in New Issue
Block a user