AGENTS/README.md

Opencode Agent Skills & Configurations

Central repository for Opencode 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)
• 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:

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

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:

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

# 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

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:

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

python3 skills/skill-creator/scripts/quick_validate.py skills/my-skill-name

4. Test the Skill

Test your skill without deploying via home-manager:

# 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 - AI coding assistant
• PARA Method - Productivity methodology
• Obsidian - 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