AGENTS/AGENTS.md

Agent Skills Repository

Configuration repository for AI Agent Skills, canonical agent definitions, context files, and agent configurations. Deployed via Nix home-manager to ~/.config/opencode/ (or equivalent paths for other tools).

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/

# Verify agent TOML parses
for f in agents/*/agent.toml; do nix eval --impure --expr "builtins.fromTOML (builtins.readFile ./$f)" --json > /dev/null && echo "OK: $f"; done

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/          # Canonical agent definitions (harness-agnostic)
│   ├── SCHEMA.md            # Canonical agent.toml schema definition
│   └── <name>/
│       ├── agent.toml       # Agent metadata, permissions, references
│       └── system-prompt.md # Agent system prompt (markdown)
├── 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/

Canonical Agent Format

Agent definitions live in agents/<name>/agent.toml + agents/<name>/system-prompt.md. This is a harness-agnostic format — renderers in m3ta-nixpkgs generate tool-specific configs.

See agents/SCHEMA.md for the full schema definition.

Adding a new agent

1. Create agents/<name>/agent.toml with required fields (name, description) and optional fields (mode, permissions, etc.)
2. Create agents/<name>/system-prompt.md with the agent's system prompt
3. Verify: nix eval --impure --expr 'builtins.fromTOML (builtins.readFile ./agents/<name>/agent.toml)' --json
4. Add the agent to renderers by updating the consuming flake inputs

How renderers work

Renderers live in m3ta-nixpkgs (not this repo). They consume lib.loadAgents and produce:

Tool	Output	Path
OpenCode	.opencode/agents/*.md	~/.config/opencode/agents/
Claude Code	.claude/agents/*.md + settings.json	~/.claude/
Pi	AGENTS.md + SYSTEM.md	~/.pi/agent/

Project-level usage

# In project flake.nix
m3taLib.agents.shellHookForTool {
  inherit pkgs;
  agentsInput = inputs.agents;
  tool = "opencode";
  modelOverrides = { chiron = "anthropic/claude-sonnet-4"; };
};

Deployment

Nix flake pattern:

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

Exports:

• lib.loadAgents — loads all canonical agents/*/agent.toml + system-prompt.md into an attrset
• lib.mkOpencodeSkills — compose custom + external skills.sh skills into one directory
• lib.agentsJson — backward-compat bridge producing legacy agents.json shape (temporary, will be removed)
• packages.skills-runtime — composable runtime with all skill dependencies
• devShells.default — dev environment for working with skills

Mapping (via home-manager + m3ta-nixpkgs renderers):

• agents/ → rendered per-tool via lib.agents.renderForTool in m3ta-nixpkgs
• skills/ → composed via mkOpencodeSkills (custom + external merged)
• context/, commands/ → symlinks
• Agent changes via file-based agents: visible on next tool restart (no home-manager switch needed for prompt changes)

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" ]; }
    ];
  };

Migration Guide (for the repo owner)

This section documents how to complete the migration from the legacy agents.json + prompts/*.txt format to the canonical agent.toml + system-prompt.md format. The canonical files already exist; what remains is updating the consumer configs and removing legacy files.

Current state

• ✅ All 6 agents exist in canonical format: agents/{name}/agent.toml + agents/{name}/system-prompt.md
• ✅ lib.loadAgents loads canonical agents from TOML
• ✅ lib.agentsJson backward-compat bridge produces the old JSON shape from TOML
• ⏳ Legacy files still present: agents/agents.json, prompts/*.txt
• ⏳ Consumer (home-manager) still reads agents.json directly via the old coding.opencode module

Step 1: Update home-manager config in your NixOS/HM flake

Change from the old coding.opencode agent options to the new coding.agents.opencode module:

# BEFORE (legacy — agents embedded in config.json):
coding.opencode = {
  enable = true;
  agentsInput = inputs.agents;
  externalSkills = [ ... ];
  ohMyOpencodeSettings = { ... };
  extraSettings = { ... };
};

# AFTER (new — file-based agents from canonical TOML):
coding.opencode = {
  enable = true;  # handles theme, plugins, formatter, oh-my-opencode
  ohMyOpencodeSettings = { ... };
  extraSettings = { ... };
};

coding.agents.opencode = {
  enable = true;
  agentsInput = inputs.agents;
  externalSkills = [ ... ];
  modelOverrides = {
    chiron = "zai-coding-plan/glm-5";
    "chiron-forge" = "zai-coding-plan/glm-5";
  };
};

Key changes:

• agentsInput and externalSkills move from coding.opencode to coding.agents.opencode
• modelOverrides is new — per-agent model selection (previously hardcoded in agents.json)
• Skills, context, commands are now handled by the agents module
• Agents are deployed as file-based ~/.config/opencode/agents/*.md instead of embedded in config.json

Step 2: Run home-manager switch

home-manager switch --flake .

Verify that ~/.config/opencode/agents/ contains 6 .md files with the correct frontmatter.

Step 3: Remove legacy files from AGENTS repo

After confirming everything works with the new setup:

cd /home/m3tam3re/p/AI/AGENTS

# Remove legacy agent definition
rm agents/agents.json

# Remove legacy prompt files (now in agents/*/system-prompt.md)
rm prompts/chiron.txt prompts/chiron-forge.txt prompts/hermes.txt \
   prompts/athena.txt prompts/apollo.txt prompts/calliope.txt
rmdir prompts/  # if empty

# Remove backward-compat bridge from flake.nix
# Delete the lib.agentsJson section from flake.nix

After removing lib.agentsJson, update flake.nix to remove the bridge function. The lib.loadAgents and lib.mkOpencodeSkills exports remain.

Step 4: Verify

# AGENTS repo: all TOML files parse
cd /home/m3tam3re/p/AI/AGENTS
for f in agents/*/agent.toml; do
  nix eval --impure --expr "builtins.fromTOML (builtins.readFile ./$f)" --json > /dev/null && echo "OK: $f"
done
nix flake check

# nixpkgs: flake check passes
cd /home/m3tam3re/p/NIX/nixpkgs
nix flake check

# Home-manager: agents deployed correctly
ls ~/.config/opencode/agents/

Optional: Enable other tool renderers

To also deploy agents for Claude Code or Pi, add to your home-manager config:

# Claude Code agents
coding.agents.claude-code = {
  enable = true;
  agentsInput = inputs.agents;
  modelOverrides = { };
};

# Pi agents
coding.agents.pi = {
  enable = true;
  agentsInput = inputs.agents;
};

Rules System

Centralized AI coding rules consumed via mkCodingRules from m3ta-nixpkgs (mkOpencodeRules still works as backward-compat alias):

# In project flake.nix
m3taLib.coding-rules.mkCodingRules {
  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