AGENTS/AGENTS.md

Agent Instructions - Opencode Skills Repository

Configuration repository for Opencode Agent Skills, context files, and agent configurations. Files deploy to ~/.config/opencode/ via Nix flake + home-manager.

Quick Commands

Testing Skills

# List or validate all skills
./scripts/test-skill.sh              # List all development skills
./scripts/test-skill.sh --validate   # Validate all skills
./scripts/test-skill.sh <skill-name>  # Validate specific skill

# Test in Opencode (interactive)
./scripts/test-skill.sh --run        # Launch session with dev skills

Creating Skills

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

Running Tests

# Run single test file
python3 -m unittest skills/pdf/scripts/check_bounding_boxes_test.py

# Run all tests in a module
python3 -m unittest discover -s skills/pdf/scripts -p "*_test.py"

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

Code Style Guidelines

File Naming

• Skills: hyphen-case (e.g., task-management, skill-creator)
• Python: snake_case (e.g., init_skill.py, quick_validate.py)
• Markdown: UPPERCASE or sentence-case (e.g., SKILL.md, profile.md)
• Config: Standard conventions (e.g., config.yaml, metadata.json)

Python Style

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

Docstrings:

"""
Brief description

Usage:
    script.py <args>

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

Imports (standard → third-party → local):

import sys
import os
from pathlib import Path
import yaml
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:

print(f"✅ Success: {result}")
print(f"❌ Error: {error}")

Bash Style

Shebang: Always #!/usr/bin/env bash Strict mode: set -euo pipefail Functions: snake_case, descriptive names

Markdown Style

• YAML frontmatter between --- delimiters
• ATX headers (#, ##, ###)
• Use - for unordered lists
• Specify language in code blocks (python, bash, etc.)

YAML Style

name: skill-name
description: "Text with special chars in quotes"
compatibility: opencode
items:
  - first
  - second

Directory Structure

.
├── agents/          # Agent definitions (agents.json)
├── prompts/         # Agent system prompts
├── context/         # User profiles and preferences
├── commands/        # Custom command definitions
├── skills/          # Opencode Agent Skills
│   ├── skill-name/
│   │   ├── SKILL.md
│   │   ├── scripts/     # Executable code (optional)
│   │   ├── references/   # Documentation (optional)
│   │   └── assets/      # Templates/files (optional)
├── scripts/         # Repository utilities
└── AGENTS.md        # This file

Nix Deployment

Flake input (non-flake):

agents = {
  url = "git+https://code.m3ta.dev/m3tam3re/AGENTS";
  flake = false;
};

Deployment mapping:

• skills/ → ~/.config/opencode/skill/ (symlink)
• context/ → ~/.config/opencode/context/ (symlink)
• commands/ → ~/.config/opencode/command/ (symlink)
• prompts/ → ~/.config/opencode/prompts/ (symlink)
• agents/agents.json → Embedded into opencode config.json (not symlinked)

Note: Agent changes require home-manager switch; other changes visible after rebuild.

Quality Gates

Before committing:

1. Validate skills: ./scripts/test-skill.sh --validate
2. Validate YAML frontmatter: python3 skills/skill-creator/scripts/quick_validate.py skills/<name>
3. Check Python scripts have proper shebang and docstrings
4. Ensure no extraneous files (README.md, CHANGELOG.md in skills)
5. Git status clean

Notes for AI Agents

1. Config-only repo - No compilation, no build, minimal test infrastructure
2. Validation is manual - Run scripts explicitly before committing
3. Skills are documentation - Write for AI consumption, not humans
4. Directory naming - Use skills/ (plural), not skill/; agents/ (plural), not agent/
5. Commands naming - Use commands/ (plural), not command/
6. Nix deployment - Maintain structure expected by home-manager
7. Always push - Follow session completion workflow

Optimization Opportunities

1. Add Python linting - Configure ruff or black for consistent formatting
2. Add pre-commit hooks - Auto-validate skills and run linters before commit
3. Test coverage - Add pytest for skill scripts beyond PDF skill
4. CI/CD - Add GitHub Actions to validate skills on PR
5. Documentation - Consolidate README.md and AGENTS.md to reduce duplication