agents: Instructions file for Codex

AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

What This Repo Is

A collection of personal AI agent skills conforming to the AgentSkills open standard. Each skill is a self-contained directory discoverable by any compatible AI agent. Skills are invoked via the agent's native skill mechanism when their description: frontmatter matches the user's intent.

Skill Structure

Every skill lives in its own top-level directory named after the skill:

<skill-name>/
  SKILL.md          # frontmatter (name, description) + full skill instructions
  evals/
    evals.json       # functional test cases: what the skill should do when triggered
    trigger_eval.json # trigger test cases: when the skill should/should not fire

SKILL.md frontmatter

---
name: <skill-name>          # must match the directory name
description: <trigger text> # what the agent reads to decide whether to invoke
---

The description: field is critical — it drives automatic invocation. It should include trigger phrases, use-case scope, and explicit exclusions for common false-positive queries.

evals/evals.json schema

{
  "skill_name": "<name>",
  "evals": [
    {
      "id": 1,
      "prompt": "<user input>",
      "expected_output": "<what the skill should produce>",
      "files": [],
      "assertions": []
    }
  ]
}

evals/trigger_eval.json schema

An array of { "query": "...", "should_trigger": true|false } objects. Include both positive examples (clear matches) and negative examples (common false positives that must NOT fire the skill).

Adding a New Skill

1. Create <skill-name>/SKILL.md with frontmatter and instructions.
2. Create <skill-name>/evals/evals.json with at least 2–3 functional test cases.
3. Create <skill-name>/evals/trigger_eval.json with a mix of positive and negative trigger examples — negative examples are especially important to prevent the skill from firing on superficially similar queries.
4. Create <skill-name>/.claude-plugin/plugin.json with skill metadata.
5. Add @./<skill-name>/SKILL.md to GEMINI.md.
6. Run ln -s ../../<skill-name> .agents/skills/<skill-name> and commit the symlink.
7. Add an entry to .claude-plugin/marketplace.json under plugins[].