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
• 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 (15 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
│   ├── obsidian/             # Obsidian vault management
│   ├── outline/              # Outline wiki integration
│   ├── 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/           # AI coding rules
│   ├── languages/   # Python, TypeScript, Nix, Shell
│   ├── concerns/    # Testing, naming, documentation
│   └── frameworks/  # Framework-specific rules (n8n)
├── flake.nix        # Nix flake: dev shell + skills-runtime export
├── .envrc           # direnv config (use flake)
├── AGENTS.md        # Developer documentation
└── README.md        # This file

🚀 Getting Started

Prerequisites

• Nix with flakes enabled — for reproducible dependency management and deployment
• direnv (recommended) — auto-activates the development environment when entering the repo
• Opencode — AI coding assistant (opencode.ai)

Installation

Option 1: Nix Flake (Recommended)

This repository is a Nix flake that exports:

• devShells.default — development environment for working on skills (activated via direnv)
• packages.skills-runtime — composable runtime with all skill script dependencies (Python packages + system tools)

Consume in your system flake:

# flake.nix
inputs.agents = {
  url = "git+https://code.m3ta.dev/m3tam3re/AGENTS";
  inputs.nixpkgs.follows = "nixpkgs";
};

# 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");

Deploy skills via home-manager:

# home-manager module (e.g., opencode.nix)
{ inputs, system, ... }:
{
  # Skill files — symlinked, changes visible immediately
  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 — embedded into config.json (requires home-manager switch)
  programs.opencode.settings.agent = builtins.fromJSON
    (builtins.readFile "${inputs.agents}/agents/agents.json");

  # Skills runtime — ensures opencode always has script dependencies
  home.packages = [ inputs.agents.packages.${system}.skills-runtime ];
}

Compose into project flakes (so opencode has skill deps in any project):

# Any project's flake.nix
{
  inputs.agents.url = "git+https://code.m3ta.dev/m3tam3re/AGENTS";
  inputs.agents.inputs.nixpkgs.follows = "nixpkgs";

  outputs = { self, nixpkgs, agents, ... }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      devShells.${system}.default = pkgs.mkShell {
        packages = [
          # project-specific tools
          pkgs.nodejs
          # skill script dependencies
          agents.packages.${system}.skills-runtime
        ];
      };
    };
}

Rebuild:

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. Register Dependencies

If your skill includes scripts with external dependencies, add them to flake.nix:

# Python packages — add to pythonEnv:
# my-skill: my_script.py
some-python-package

# System tools — add to skills-runtime paths:
# my-skill: needed by my_script.py
pkgs.some-tool

Verify: nix develop --command python3 -c "import some_package"

4. Validate the Skill

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

5. Test the Skill

./scripts/test-skill.sh my-skill-name    # Validate specific skill
./scripts/test-skill.sh --run             # Launch opencode with dev skills

📚 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
obsidian	Obsidian vault management via Local REST API	✅ Active
outline	Outline wiki integration for team documentation	✅ 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

Environment

The repository includes a Nix flake with a development shell. With direnv installed, the environment activates automatically:

cd AGENTS/
# → direnv: loading .envrc
# → 🔧 AGENTS dev shell active — Python 3.13.x, jq-1.x

# All skill script dependencies are now available:
python3 -c "import pypdf, openpyxl, yaml"  # ✔️
pdftoppm -v                                 # ✔️

Without direnv, activate manually: nix develop

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
• rules/USAGE.md - AI coding rules integration guide

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
• excalidraw/ - Diagram generation with JSON templates and Python renderer

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

Add Project Rules

Use the rules system to inject AI coding rules into projects:

# In project flake.nix
m3taLib.opencode-rules.mkOpencodeRules {
  inherit agents;
  languages = [ "python" "typescript" ];
  frameworks = [ "n8n" ];
};

See rules/USAGE.md for full documentation.

🌟 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