AGENTS/README.md

# 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**