AGENTS/AGENTS.md

Opencode Skills Repository

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

Quick Commands

# Skill validation
./scripts/test-skill.sh --validate   # Validate all skills
./scripts/test-skill.sh <skill-name>  # Validate specific skill
./scripts/test-skill.sh --run        # Test interactively

# Skill creation
python3 skills/skill-creator/scripts/init_skill.py <name> --path skills/

Directory Structure

.
├── skills/          # Agent skills (15 modules)
│   └── skill-name/
│       ├── SKILL.md         # Required: YAML frontmatter + workflows
│       ├── scripts/         # Executable code (optional)
│       ├── references/      # Domain docs (optional)
│       └── assets/          # Templates/files (optional)
├── rules/           # AI coding rules (languages, concerns, frameworks)
│   ├── languages/   # Python, TypeScript, Nix, Shell
│   ├── concerns/    # Testing, naming, documentation, etc.
│   └── frameworks/  # Framework-specific rules (n8n, etc.)
├── agents/          # Agent definitions (agents.json)
├── prompts/         # System prompts (chiron*.txt)
├── context/         # User profiles
├── commands/        # Custom commands
└── scripts/         # Repo utilities (test-skill.sh, validate-agents.sh)

Code Conventions

File naming: hyphen-case (skills), snake_case (Python), UPPERCASE/sentence-case (MD)

SKILL.md structure:

---
name: skill-name
description: "Use when: (1) X, (2) Y. Triggers: a, b, c."
compatibility: opencode
---

## Overview (1 line)
## Core Workflows (step-by-step)
## Integration with Other Skills

Python: #!/usr/bin/env python3 + docstrings + emoji feedback (✅/❌) Bash: #!/usr/bin/env bash + set -euo pipefail Markdown: YAML frontmatter, ATX headers, - lists, language in code blocks

Anti-Patterns (CRITICAL)

Frontend Design: NEVER use generic AI aesthetics, NEVER converge on common choices Excalidraw: NEVER use label property (use boundElements + text element pairs instead) Debugging: NEVER fix just symptom, ALWAYS find root cause first Excel: ALWAYS respect existing template conventions over guidelines Structure: NEVER place scripts/docs outside scripts/references/ directories

Testing Patterns

Unique conventions (skill-focused, not CI/CD):

• Manual validation via test-skill.sh, no automated CI
• Tests co-located with source (not separate test directories)
• YAML frontmatter validation = primary quality gate
• Mixed formats: Python unittest, markdown pressure tests, A/B prompt testing

Known deviations:

• systematic-debugging/test-*.md - Academic/pressure testing in wrong location
• pdf/forms.md, pdf/reference.md - Docs outside references/

Deployment

Nix flake pattern:

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

Exports:

• lib.mkOpencodeSkills — compose custom + external skills.sh skills into one directory
• packages.skills-runtime — composable runtime with all skill dependencies
• devShells.default — dev environment for working on skills

Mapping (via home-manager):

• skills/ → composed via mkOpencodeSkills (custom + external merged)
• context/, commands/, prompts/ → symlinks
• agents/agents.json → embedded into config.json
• Agent changes: require home-manager switch
• Other changes: visible immediately

External Skills (skills.sh)

This repo supports composing skills from external skills.sh repositories alongside custom skills. External repos follow the Agent Skills standard (same SKILL.md format).

lib.mkOpencodeSkills parameters:

• pkgs (required) — nixpkgs package set
• customSkills (optional) — path to custom skills directory (e.g., "${inputs.agents}/skills")
• externalSkills (optional) — list of external sources, each with:
  • src — flake input or path to repo root
  • skillsDir — subdirectory containing skills (default: "skills")
  • selectSkills — list of skill names to include (default: all)

Collision handling: Custom skills always win. Among externals, earlier entries take priority.

Home-manager example:

inputs = {
  agents.url = "git+https://code.m3ta.dev/m3tam3re/AGENTS";
  skills-anthropic = { url = "github:anthropics/skills"; flake = false; };
};

xdg.configFile."opencode/skills".source =
  inputs.agents.lib.mkOpencodeSkills {
    pkgs = nixpkgs.legacyPackages.${system};
    customSkills = "${inputs.agents}/skills";
    externalSkills = [
      { src = inputs.skills-anthropic; }
    ];
  };

Project flake example (selective):

".agents/skills".source =
  inputs.agents.lib.mkOpencodeSkills {
    pkgs = nixpkgs.legacyPackages.${system};
    externalSkills = [
      { src = inputs.skills-anthropic; selectSkills = [ "mcp-builder" ]; }
    ];
  };

Rules System

Centralized AI coding rules consumed via mkOpencodeRules from m3ta-nixpkgs:

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

See rules/USAGE.md for full documentation.

Notes for AI Agents

1. Config-only repo - No compilation, no build, manual validation only
2. Skills are documentation - Write for AI consumption, progressive disclosure
3. Consistent structure - All skills follow 4-level deep pattern (skills/name/ + optional subdirs)
4. Cross-cutting concerns - Standardized SKILL.md, workflow patterns, delegation rules
5. Always push - Session completion workflow: commit + git push

Quality Gates

Before committing:

1. ./scripts/test-skill.sh --validate
2. Python shebang + docstrings check
3. No extraneous files (README.md, CHANGELOG.md in skills/)
4. If skill has scripts with external dependencies → verify flake.nix is updated (see skill-creator Step 4)
5. Git status clean