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
• 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)
• 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:

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

home-manager switch

Option 2: Manual Installation

Clone and symlink:

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

# 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

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:

---
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 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 for AI-native issue tracking:

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

   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 - AI coding assistant
• Beads - AI-native issue tracking
• PARA Method - Productivity methodology
• Anytype - 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