AGENTS/AGENTS.md

Agent Instructions - Opencode Skills Repository

This repository contains Opencode Agent Skills, context files, and agent configurations for personal productivity and AI-assisted workflows. Files are deployed to ~/.config/opencode/ via Nix flake + home-manager.

Project Overview

Type: Configuration-only repository (no build/compile step) Purpose: Central repository for Opencode Agent Skills, AI agent configurations, custom commands, and workflows. Extensible framework for productivity, automation, knowledge management, and AI-assisted development. Primary User: Sascha Koenig (@m3tam3re) Deployment: Nix flake → home-manager → ~/.config/opencode/

Current Focus Areas

• Productivity & Task Management - PARA methodology, Anytype integration, reviews
• Knowledge Management - Note capture, organization, research workflows
• Communications - Email drafts, follow-ups, calendar scheduling
• AI Development - Skill creation, agent configurations, custom commands
• Memory & Context - Persistent memory with Mem0, conversation analysis

Extensibility

This repository serves as a foundation for any Opencode-compatible skill or agent configuration. Add new skills for:

• Domain-specific workflows (finance, legal, engineering, etc.)
• Tool integrations (APIs, databases, cloud platforms)
• Custom automation and productivity systems
• Specialized AI agents for different contexts

Directory Structure

.
├── agent/           # AI agent configurations (chiron.md)
├── context/         # User profiles and preferences
├── command/         # Custom command definitions
├── skill/           # Opencode Agent Skills (8 skills)
│   ├── task-management/
│   ├── skill-creator/
│   ├── reflection/
│   ├── communications/
│   ├── calendar-scheduling/
│   ├── mem0-memory/
│   ├── research/
│   └── knowledge-management/
├── .beads/          # Issue tracking database
└── AGENTS.md        # This file

Issue Tracking with Beads

This project uses bd (beads) for AI-native issue tracking.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --status in_progress  # Claim work
bd close <id>         # Complete work
bd sync               # Sync with git
bd list               # View all issues
bd create "title"     # Create new issue

Beads Workflow Integration

• Issues live in .beads/ directory (git-tracked)
• Auto-syncs with commits
• CLI-first design for AI agents
• No web UI needed

Skill Development

Creating a New Skill

Use the skill initialization script:

python3 skill/skill-creator/scripts/init_skill.py <skill-name> --path skill/

This creates:

• skill/<skill-name>/SKILL.md with proper frontmatter template
• skill/<skill-name>/scripts/ - For executable code
• skill/<skill-name>/references/ - For documentation
• skill/<skill-name>/assets/ - For templates/files

Validating Skills

Run validation before committing:

python3 skill/skill-creator/scripts/quick_validate.py skill/<skill-name>

Validation checks:

• YAML frontmatter structure
• Required fields: name, description
• Name format: hyphen-case, max 64 chars
• Description: max 1024 chars, no angle brackets
• Allowed frontmatter properties: name, description, compatibility, license, allowed-tools, metadata

Skill Structure Requirements

SKILL.md Frontmatter (required):

---
name: skill-name
description: What it does and when to use it. Include trigger words.
compatibility: opencode
---

Resource Directories (optional):

• scripts/ - Executable Python/Bash code for deterministic operations
• references/ - Documentation loaded into context as needed
• assets/ - Files used in output (templates, images, fonts)

Skill Design Principles

1. Concise is key - Context window is shared resource
2. Progressive disclosure - Metadata → SKILL.md body → bundled resources
3. Appropriate freedom - Match specificity to task fragility
4. No extraneous files - No README.md, CHANGELOG.md, etc. in skills
5. Reference patterns - See skill/skill-creator/references/workflows.md and output-patterns.md

Code Style Guidelines

File Naming

Skills: Hyphen-case (e.g., task-management, skill-creator) Python scripts: Snake_case (e.g., init_skill.py, quick_validate.py) Markdown files: UPPERCASE or sentence-case (e.g., SKILL.md, profile.md) Configuration: Standard conventions (e.g., config.yaml, metadata.json)

Markdown Style

Frontmatter:

• Always use YAML format between --- delimiters
• Required fields for skills: name, description
• Optional: compatibility: opencode, mode: primary

Headers:

• Use ATX-style (#, ##, ###)
• One H1 per file (skill title)
• Clear hierarchy

Lists:

• Use - for unordered lists (not *)
• Use numbered lists for sequential steps
• Indent nested lists with 2 spaces

Code blocks:

• Always specify language for syntax highlighting
• Use bash for shell commands
• Use yaml, nix, python as appropriate

Tables:

• Use for structured comparisons and reference data
• Keep aligned for readability in source
• Example:

  | Header 1 | Header 2 |
  |----------|----------|
  | Value    | Value    |
  

Python Style

Shebang: Always use #!/usr/bin/env python3

Docstrings:

"""
Brief description of module/script

Usage:
    script_name.py <arg1> --flag <arg2>

Examples:
    script_name.py my-skill --path ~/.config/opencode/skill
"""

Imports:

# Standard library
import sys
import os
from pathlib import Path

# Third-party (if any)
import yaml

# Local (if any)
from . import utilities

Naming:

• Functions: snake_case
• Classes: PascalCase
• Constants: UPPER_SNAKE_CASE
• Private: _leading_underscore

Error handling:

try:
    # operation
except SpecificException as e:
    print(f"❌ Error: {e}")
    return None

User feedback:

• Use ✅ for success messages
• Use ❌ for error messages
• Print progress for multi-step operations

YAML Style

# Use lowercase keys with hyphens
skill-name: value

# Quotes for strings with special chars
description: "PARA-based task management. Use when: (1) item, (2) item."

# No quotes for simple strings
compatibility: opencode

# Lists with hyphens
items:
  - first
  - second

Nix Flake Integration

This repository is designed to be consumed by a Nix flake via home-manager.

Expected Deployment Pattern

# In your flake.nix or home.nix
xdg.configFile."opencode" = {
  source = /path/to/AGENTS;
  recursive = true;
};

This deploys:

• agent/ → ~/.config/opencode/agent/
• skill/ → ~/.config/opencode/skill/
• context/ → ~/.config/opencode/context/
• command/ → ~/.config/opencode/command/

Best Practices for Nix

1. Keep original structure - Don't rename directories; Opencode expects this layout
2. Use recursive = true - Required for directory deployment
3. Exclude .git and .beads - These are development artifacts:

   xdg.configFile."opencode" = {
     source = /path/to/AGENTS;
     recursive = true;
     # Or filter with lib.cleanSource
   };
   

4. No absolute paths in configs - All references should be relative

Quality Gates

Before committing changes, verify:

1. Skill validation - Run quick_validate.py on modified skills
2. File structure - Ensure no extraneous files (README in skills, etc.)
3. Frontmatter - Check YAML syntax and required fields
4. Scripts executable - Python scripts should have proper shebang
5. Markdown formatting - Check headers, lists, code blocks
6. Git status - No uncommitted or untracked files that should be tracked

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW

1. File issues for remaining work - Create beads issues for anything that needs follow-up
2. Run quality gates - Validate modified skills, check file structure
3. Update issue status - Close finished work, update in-progress items
4. PUSH TO REMOTE - This is MANDATORY:

   git pull --rebase
   bd sync
   git push
   git status  # MUST show "up to date with origin"
   

5. Clean up - Clear stashes, prune remote branches
6. Verify - All changes committed AND pushed
7. Hand off - Provide context for next session

CRITICAL RULES

• Work is NOT complete until git push succeeds
• NEVER stop before pushing - that leaves work stranded locally
• NEVER say "ready to push when you are" - YOU must push
• If push fails, resolve and retry until it succeeds

Common Operations

Test a Skill Locally

# Validate structure
python3 skill/skill-creator/scripts/quick_validate.py skill/<skill-name>

# Check skill triggers by reading SKILL.md frontmatter
grep -A5 "^description:" skill/<skill-name>/SKILL.md

Create New Skill

# Initialize
python3 skill/skill-creator/scripts/init_skill.py my-new-skill --path skill/

# Edit SKILL.md and implement resources
# Delete unneeded example files from scripts/, references/, assets/

# Validate
python3 skill/skill-creator/scripts/quick_validate.py skill/my-new-skill

Update User Context

Edit context/profile.md to update:

• Work style preferences
• PARA areas
• Communication preferences
• Integration status

Modify Agent Behavior

Edit agent/chiron.md to adjust:

• Skill routing logic
• Communication protocols
• Daily rhythm support
• Operating principles

Reference Documentation

Skill creation guide: skill/skill-creator/SKILL.md Workflow patterns: skill/skill-creator/references/workflows.md Output patterns: skill/skill-creator/references/output-patterns.md User profile: context/profile.md Agent config: agent/chiron.md Beads docs: .beads/README.md

Notes for AI Agents

1. This is a config repo - No compilation, no tests, no runtime
2. Validation is manual - Run scripts explicitly before committing
3. Skills are documentation - Write for AI consumption, not humans
4. Context window matters - Keep skills concise, use progressive disclosure
5. Nix deployment - Maintain structure expected by home-manager
6. Always push - Follow session completion workflow religiously