diff --git a/.agents/invocation.md b/.agents/invocation.md index c434516..4ed7701 100644 --- a/.agents/invocation.md +++ b/.agents/invocation.md @@ -2,10 +2,12 @@ Every `SKILL.md` in this repo is a skill. The one axis that splits them is **invocation** — who can reach it: -- **User-invoked** — reachable **only by the human typing its name**. Set `disable-model-invocation: true` in the frontmatter. The `description` is **human-facing**: a one-line summary read by a person browsing slash-commands. Strip trigger lists ("Use when the user says…"). -- **Model-invoked** — reachable by **model or user**. The default: omit `disable-model-invocation`. The `description` is **model-facing** and keeps rich trigger phrasing ("Use when the user wants…, mentions…, asks for…") so auto-invocation fires. The test for whether a skill should stay model-invoked: _could the model usefully reach for this autonomously?_ (Reuse is the reason to extract a skill, not the test.) +- **User-invoked** — reachable **only by the human typing its name**. Set `disable-model-invocation: true` in the frontmatter (Claude Code) and `policy.allow_implicit_invocation: false` in `agents/openai.yaml` (Codex). The `description` is **human-facing**: a one-line summary read by a person browsing slash-commands. Strip trigger lists ("Use when the user says…"). +- **Model-invoked** — reachable by **model or user**. The default: omit `disable-model-invocation` and the `policy` block from `agents/openai.yaml`. The `description` is **model-facing** and keeps rich trigger phrasing ("Use when the user wants…, mentions…, asks for…") so auto-invocation fires. The test for whether a skill should stay model-invoked: _could the model usefully reach for this autonomously?_ (Reuse is the reason to extract a skill, not the test.) -Because a user-invoked skill has no description, nothing but the human can reach it — no other skill can fire it. So a user-invoked skill may invoke model-invoked skills, but it can never reach another user-invoked skill. +Each harness excludes a user-invoked skill from the model's reach in its own way, so nothing but the human can fire it — no other skill can. A user-invoked skill may invoke model-invoked skills, but it can never reach another user-invoked skill. + +Every skill also carries an `agents/openai.yaml` beside its `SKILL.md`. It holds Codex UI metadata — `interface.display_name` and `interface.short_description` for the skill picker — and, for user-invoked skills, the `policy.allow_implicit_invocation: false` that pairs with `disable-model-invocation`. Keep the two in sync: a skill is user-invoked in both harnesses or neither. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. diff --git a/.changeset/codex-skill-metadata.md b/.changeset/codex-skill-metadata.md new file mode 100644 index 0000000..3d90ece --- /dev/null +++ b/.changeset/codex-skill-metadata.md @@ -0,0 +1,10 @@ +--- +"mattpocock-skills": minor +--- + +Add Codex metadata alongside each skill's Claude Code frontmatter so the set works in both harnesses without generated copies. + +- Add an `agents/openai.yaml` beside every `SKILL.md` with Codex UI metadata (`interface.display_name`, `interface.short_description`). +- Mark every user-invoked skill with `policy.allow_implicit_invocation: false`, the Codex analog of `disable-model-invocation: true`, so Codex excludes it from implicit invocation while explicit `$skill` invocation still works. +- Document the dual-harness invocation model in `.agents/invocation.md`, `CLAUDE.md`, and the promoted-bucket READMEs. +- Add `AGENTS.md` as a symlink to `CLAUDE.md` so Codex reads the same repo instructions. diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000..681311e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 20ca92b..294e684 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,7 @@ Each bucket folder has a `README.md` that lists every skill in the bucket with a Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs//.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/` or `productivity/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). Skills in the non-promoted buckets (`misc/`, `personal/`, `in-progress/`, `deprecated/`) get **no** docs page. -Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). See [.agents/invocation.md](./.agents/invocation.md). +Every `SKILL.md` is either user-invoked (`disable-model-invocation: true` plus `policy.allow_implicit_invocation: false` in `agents/openai.yaml`, reachable only by the human) or model-invoked (model- or user-reachable). See [.agents/invocation.md](./.agents/invocation.md). [`ask-matt`](./skills/engineering/ask-matt/SKILL.md) is the router that maps every user-reachable skill and how they relate. The same trigger that re-syncs a docs page applies to it: whenever you add, rename, remove, or change how a user-reachable skill fits the flows, re-read `ask-matt`'s `SKILL.md` and update it so the map stays accurate — a new skill it never mentions, or a stale one it still routes to, is a router that lies. diff --git a/scripts/link-skills.sh b/scripts/link-skills.sh index deb5461..a453287 100755 --- a/scripts/link-skills.sh +++ b/scripts/link-skills.sh @@ -8,7 +8,7 @@ set -euo pipefail # Links all skills in the repository into the local skill directories used by # each agent harness: # - ~/.claude/skills — Claude Code -# - ~/.agents/skills — pi and other Agent-Skills-standard harnesses +# - ~/.agents/skills — Codex and other Agent Skills-compatible harnesses # Each entry is a symlink into this repo, so a `git pull` is all that's needed # to keep installed skills up to date. diff --git a/skills/deprecated/design-an-interface/agents/openai.yaml b/skills/deprecated/design-an-interface/agents/openai.yaml new file mode 100644 index 0000000..c86df18 --- /dev/null +++ b/skills/deprecated/design-an-interface/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Design an Interface" + short_description: "Explore alternative module interfaces" diff --git a/skills/deprecated/qa/agents/openai.yaml b/skills/deprecated/qa/agents/openai.yaml new file mode 100644 index 0000000..a6a5437 --- /dev/null +++ b/skills/deprecated/qa/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "QA" + short_description: "Conversational QA that files issues" diff --git a/skills/deprecated/request-refactor-plan/agents/openai.yaml b/skills/deprecated/request-refactor-plan/agents/openai.yaml new file mode 100644 index 0000000..d7b94d9 --- /dev/null +++ b/skills/deprecated/request-refactor-plan/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Request Refactor Plan" + short_description: "Plan a safe incremental refactor" diff --git a/skills/deprecated/ubiquitous-language/agents/openai.yaml b/skills/deprecated/ubiquitous-language/agents/openai.yaml new file mode 100644 index 0000000..57a0012 --- /dev/null +++ b/skills/deprecated/ubiquitous-language/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Ubiquitous Language" + short_description: "Build a shared domain glossary" +policy: + allow_implicit_invocation: false diff --git a/skills/engineering/README.md b/skills/engineering/README.md index fab47b4..90b9e04 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -4,7 +4,7 @@ Skills I use daily for code work. ## User-invoked -Reachable only when you type them (`disable-model-invocation: true`). +Reachable only when you type them (Claude Code: `disable-model-invocation: true`; Codex: `policy.allow_implicit_invocation: false` in `agents/openai.yaml`). - **[ask-matt](./ask-matt/SKILL.md)** — Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo. - **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. diff --git a/skills/engineering/ask-matt/agents/openai.yaml b/skills/engineering/ask-matt/agents/openai.yaml new file mode 100644 index 0000000..5c60d51 --- /dev/null +++ b/skills/engineering/ask-matt/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Ask Matt" + short_description: "Find the right skill or workflow" +policy: + allow_implicit_invocation: false diff --git a/skills/engineering/code-review/agents/openai.yaml b/skills/engineering/code-review/agents/openai.yaml new file mode 100644 index 0000000..9076774 --- /dev/null +++ b/skills/engineering/code-review/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Code Review" + short_description: "Review a diff on standards and spec" diff --git a/skills/engineering/codebase-design/agents/openai.yaml b/skills/engineering/codebase-design/agents/openai.yaml new file mode 100644 index 0000000..3180715 --- /dev/null +++ b/skills/engineering/codebase-design/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Codebase Design" + short_description: "Vocabulary for deep-module design" diff --git a/skills/engineering/diagnosing-bugs/agents/openai.yaml b/skills/engineering/diagnosing-bugs/agents/openai.yaml new file mode 100644 index 0000000..a13a755 --- /dev/null +++ b/skills/engineering/diagnosing-bugs/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Diagnosing Bugs" + short_description: "Diagnose hard bugs and regressions" diff --git a/skills/engineering/domain-modeling/agents/openai.yaml b/skills/engineering/domain-modeling/agents/openai.yaml new file mode 100644 index 0000000..7f1522d --- /dev/null +++ b/skills/engineering/domain-modeling/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Domain Modeling" + short_description: "Build and sharpen a domain model" diff --git a/skills/engineering/grill-with-docs/agents/openai.yaml b/skills/engineering/grill-with-docs/agents/openai.yaml new file mode 100644 index 0000000..5dbe278 --- /dev/null +++ b/skills/engineering/grill-with-docs/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Grill with Docs" + short_description: "Grill a design and write its docs" +policy: + allow_implicit_invocation: false diff --git a/skills/engineering/implement/agents/openai.yaml b/skills/engineering/implement/agents/openai.yaml new file mode 100644 index 0000000..f8794dc --- /dev/null +++ b/skills/engineering/implement/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Implement" + short_description: "Build work from a spec or tickets" +policy: + allow_implicit_invocation: false diff --git a/skills/engineering/improve-codebase-architecture/agents/openai.yaml b/skills/engineering/improve-codebase-architecture/agents/openai.yaml new file mode 100644 index 0000000..706fdca --- /dev/null +++ b/skills/engineering/improve-codebase-architecture/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Improve Codebase Architecture" + short_description: "Find and grill architecture improvements" +policy: + allow_implicit_invocation: false diff --git a/skills/engineering/prototype/agents/openai.yaml b/skills/engineering/prototype/agents/openai.yaml new file mode 100644 index 0000000..1618b14 --- /dev/null +++ b/skills/engineering/prototype/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Prototype" + short_description: "Prototype to answer a design question" diff --git a/skills/engineering/research/agents/openai.yaml b/skills/engineering/research/agents/openai.yaml new file mode 100644 index 0000000..e18b96c --- /dev/null +++ b/skills/engineering/research/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Research" + short_description: "Research from high-trust sources" diff --git a/skills/engineering/resolving-merge-conflicts/agents/openai.yaml b/skills/engineering/resolving-merge-conflicts/agents/openai.yaml new file mode 100644 index 0000000..331ffb9 --- /dev/null +++ b/skills/engineering/resolving-merge-conflicts/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Resolving Merge Conflicts" + short_description: "Resolve merge and rebase conflicts" diff --git a/skills/engineering/setup-matt-pocock-skills/agents/openai.yaml b/skills/engineering/setup-matt-pocock-skills/agents/openai.yaml new file mode 100644 index 0000000..65a0da8 --- /dev/null +++ b/skills/engineering/setup-matt-pocock-skills/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Setup Matt Pocock Skills" + short_description: "Configure a repo for the skills" +policy: + allow_implicit_invocation: false diff --git a/skills/engineering/tdd/agents/openai.yaml b/skills/engineering/tdd/agents/openai.yaml new file mode 100644 index 0000000..651b838 --- /dev/null +++ b/skills/engineering/tdd/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "TDD" + short_description: "Test-driven red-green-refactor" diff --git a/skills/engineering/to-spec/agents/openai.yaml b/skills/engineering/to-spec/agents/openai.yaml new file mode 100644 index 0000000..549e6f7 --- /dev/null +++ b/skills/engineering/to-spec/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "To Spec" + short_description: "Turn a conversation into a spec" +policy: + allow_implicit_invocation: false diff --git a/skills/engineering/to-tickets/agents/openai.yaml b/skills/engineering/to-tickets/agents/openai.yaml new file mode 100644 index 0000000..24605a5 --- /dev/null +++ b/skills/engineering/to-tickets/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "To Tickets" + short_description: "Split a plan into tracer-bullet tickets" +policy: + allow_implicit_invocation: false diff --git a/skills/engineering/triage/agents/openai.yaml b/skills/engineering/triage/agents/openai.yaml new file mode 100644 index 0000000..acb366c --- /dev/null +++ b/skills/engineering/triage/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Triage" + short_description: "Move issues through triage roles" +policy: + allow_implicit_invocation: false diff --git a/skills/engineering/wayfinder/agents/openai.yaml b/skills/engineering/wayfinder/agents/openai.yaml new file mode 100644 index 0000000..b375447 --- /dev/null +++ b/skills/engineering/wayfinder/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Wayfinder" + short_description: "Map a large effort as decision tickets" +policy: + allow_implicit_invocation: false diff --git a/skills/in-progress/claude-handoff/agents/openai.yaml b/skills/in-progress/claude-handoff/agents/openai.yaml new file mode 100644 index 0000000..0a7aa5d --- /dev/null +++ b/skills/in-progress/claude-handoff/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Claude Handoff" + short_description: "Hand off to a background agent" +policy: + allow_implicit_invocation: false diff --git a/skills/in-progress/loop-me/agents/openai.yaml b/skills/in-progress/loop-me/agents/openai.yaml new file mode 100644 index 0000000..1a4f411 --- /dev/null +++ b/skills/in-progress/loop-me/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Loop Me" + short_description: "Spec the workflows you want to build" +policy: + allow_implicit_invocation: false diff --git a/skills/in-progress/setup-ts-deep-modules/agents/openai.yaml b/skills/in-progress/setup-ts-deep-modules/agents/openai.yaml new file mode 100644 index 0000000..5d0581b --- /dev/null +++ b/skills/in-progress/setup-ts-deep-modules/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Setup TS Deep Modules" + short_description: "Enforce deep TypeScript modules" +policy: + allow_implicit_invocation: false diff --git a/skills/in-progress/wizard/agents/openai.yaml b/skills/in-progress/wizard/agents/openai.yaml new file mode 100644 index 0000000..0a5f4b1 --- /dev/null +++ b/skills/in-progress/wizard/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Wizard" + short_description: "Generate an interactive setup wizard" +policy: + allow_implicit_invocation: false diff --git a/skills/in-progress/writing-beats/agents/openai.yaml b/skills/in-progress/writing-beats/agents/openai.yaml new file mode 100644 index 0000000..e8eaa18 --- /dev/null +++ b/skills/in-progress/writing-beats/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Writing Beats" + short_description: "Assemble raw material into beats" +policy: + allow_implicit_invocation: false diff --git a/skills/in-progress/writing-fragments/agents/openai.yaml b/skills/in-progress/writing-fragments/agents/openai.yaml new file mode 100644 index 0000000..be3713e --- /dev/null +++ b/skills/in-progress/writing-fragments/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Writing Fragments" + short_description: "Mine raw writing fragments" +policy: + allow_implicit_invocation: false diff --git a/skills/in-progress/writing-shape/agents/openai.yaml b/skills/in-progress/writing-shape/agents/openai.yaml new file mode 100644 index 0000000..87e0c73 --- /dev/null +++ b/skills/in-progress/writing-shape/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Writing Shape" + short_description: "Shape raw material into an article" +policy: + allow_implicit_invocation: false diff --git a/skills/misc/git-guardrails-claude-code/agents/openai.yaml b/skills/misc/git-guardrails-claude-code/agents/openai.yaml new file mode 100644 index 0000000..3f5d756 --- /dev/null +++ b/skills/misc/git-guardrails-claude-code/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Git Guardrails for Claude Code" + short_description: "Block dangerous git commands" diff --git a/skills/misc/migrate-to-shoehorn/agents/openai.yaml b/skills/misc/migrate-to-shoehorn/agents/openai.yaml new file mode 100644 index 0000000..3bd79ee --- /dev/null +++ b/skills/misc/migrate-to-shoehorn/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Migrate to Shoehorn" + short_description: "Replace test assertions with shoehorn" diff --git a/skills/misc/scaffold-exercises/agents/openai.yaml b/skills/misc/scaffold-exercises/agents/openai.yaml new file mode 100644 index 0000000..963723a --- /dev/null +++ b/skills/misc/scaffold-exercises/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Scaffold Exercises" + short_description: "Scaffold lint-ready course exercises" diff --git a/skills/misc/setup-pre-commit/agents/openai.yaml b/skills/misc/setup-pre-commit/agents/openai.yaml new file mode 100644 index 0000000..e5a1c63 --- /dev/null +++ b/skills/misc/setup-pre-commit/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Setup Pre-Commit" + short_description: "Add pre-commit quality checks" diff --git a/skills/personal/edit-article/agents/openai.yaml b/skills/personal/edit-article/agents/openai.yaml new file mode 100644 index 0000000..aa6dd40 --- /dev/null +++ b/skills/personal/edit-article/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Edit Article" + short_description: "Restructure and tighten a draft" +policy: + allow_implicit_invocation: false diff --git a/skills/personal/obsidian-vault/agents/openai.yaml b/skills/personal/obsidian-vault/agents/openai.yaml new file mode 100644 index 0000000..cb70f99 --- /dev/null +++ b/skills/personal/obsidian-vault/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Obsidian Vault" + short_description: "Manage linked notes in Obsidian" diff --git a/skills/productivity/README.md b/skills/productivity/README.md index dcc015a..076fc2d 100644 --- a/skills/productivity/README.md +++ b/skills/productivity/README.md @@ -4,7 +4,7 @@ General workflow tools, not code-specific. ## User-invoked -Reachable only when you type them (`disable-model-invocation: true`). +Reachable only when you type them (Claude Code: `disable-model-invocation: true`; Codex: `policy.allow_implicit_invocation: false` in `agents/openai.yaml`). - **[grill-me](./grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. - **[handoff](./handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. diff --git a/skills/productivity/grill-me/agents/openai.yaml b/skills/productivity/grill-me/agents/openai.yaml new file mode 100644 index 0000000..4d6fb0c --- /dev/null +++ b/skills/productivity/grill-me/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Grill Me" + short_description: "Sharpen a plan through interview" +policy: + allow_implicit_invocation: false diff --git a/skills/productivity/grilling/agents/openai.yaml b/skills/productivity/grilling/agents/openai.yaml new file mode 100644 index 0000000..85b1260 --- /dev/null +++ b/skills/productivity/grilling/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Grilling" + short_description: "Stress-test thinking one question at a time" diff --git a/skills/productivity/handoff/agents/openai.yaml b/skills/productivity/handoff/agents/openai.yaml new file mode 100644 index 0000000..6e1d8da --- /dev/null +++ b/skills/productivity/handoff/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Handoff" + short_description: "Compact a conversation into a handoff" +policy: + allow_implicit_invocation: false diff --git a/skills/productivity/teach/agents/openai.yaml b/skills/productivity/teach/agents/openai.yaml new file mode 100644 index 0000000..3452a85 --- /dev/null +++ b/skills/productivity/teach/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Teach" + short_description: "Learn a concept in a guided workspace" +policy: + allow_implicit_invocation: false diff --git a/skills/productivity/writing-great-skills/agents/openai.yaml b/skills/productivity/writing-great-skills/agents/openai.yaml new file mode 100644 index 0000000..d677a13 --- /dev/null +++ b/skills/productivity/writing-great-skills/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Writing Great Skills" + short_description: "Principles for predictable skills" +policy: + allow_implicit_invocation: false