@open-agent-toolkit/cli 0.2.66 → 0.2.68

package/assets/skills/create-agnostic-skill/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: 1.4.3
+  version: 1.5.0
 ---
 
 # Create Skill
@@ -69,7 +69,7 @@ If not provided in arguments, ask for:
 **The context window is a shared resource.** Skills share context with everything else the agent needs. Structure information in three levels:
 
 1. **Metadata** (~100 words): Name + description in frontmatter, always loaded
-2. **SKILL.md body** (<5k words): Loads when skill triggers
+2. **SKILL.md body** (~5,000 tokens): Loads when skill triggers
 3. **Bundled resources**: Files in `references/`, `scripts/`, `assets/` loaded as-needed
 
 **Writing principles:**
@@ -172,11 +172,12 @@ Natural language request that triggers this skill
 **Frontmatter notes:**
 
 - `argument-hint`, `allowed-tools`, `user-invocable`, `context`, `hooks` are Claude Code specific
-- Other agents ignore unknown frontmatter fields, so it's safe to include Claude-specific fields everywhere
+- `allowed-tools`: write the value as a **comma-separated** list. The spec's own example is space-delimited and OAT never parses the separator — `validateOatSkills` in `packages/cli/src/validation/skills.ts` only checks that the key is present, and `getToolDetail` in `packages/cli/src/commands/tools/info/index.ts` reads the raw scalar — so this is OAT's authoring convention rather than a runtime contract. Backstop: `it('declares allowed-tools as a comma-separated list in every canonical skill')` in `packages/cli/src/validation/skills.test.ts`
+- The spec defines a fixed field set, and providers differ in which extension fields they read. An unread field is inert rather than guaranteed harmless, so check the dated compatibility section of `references/docs/skills-guide.md` for the per-provider picture before depending on one
 - `name`: max 64 chars for cross-provider portability (Codex allows 100, but 64 is the spec limit)
 - `metadata.version`: include valid semver and start new skills at `1.0.0`. The Agent Skills specification puts the version under `metadata`, and OAT resolves `metadata.version` first and the top-level `version` second — `resolveSkillVersion` in `packages/cli/src/commands/shared/frontmatter.ts` owns that order, backstopped by `packages/cli/src/commands/shared/frontmatter.test.ts`
-- `version` (top-level): the deprecated alias, still read when `metadata.version` is absent. Do not set both to different values: OAT reports the conflict, skill validation fails on it, and canonical role identity rejects it
-- `description`: **single line, ≤ 500 chars** (Codex enforces single-line ≤ 500 chars; spec allows 1024)
+- `version` (top-level): the deprecated alias, still read when `metadata.version` is absent — but a skill whose only version is that alias no longer validates. `validateOatSkills` in `packages/cli/src/validation/skills.ts` reports it as `skill-version-alias` at `severity: 'error'`, so `pnpm oat:validate-skills` fails the skill outright; the pass runs over every skill directory, not just `oat-*`, so an agnostic skill is covered too. Backstop: `it('reports exactly once for a non-oat-* alias-only skill')` in `packages/cli/src/validation/skills.test.ts`. Setting both to different values is the separate `skill-version-conflict` error: OAT reports the conflict, skill validation fails on it, and canonical role identity rejects it. Declare `metadata.version` and leave the alias out
+- `description`: **single line, ≤ 500 chars**. This is OAT's house rule, not a provider requirement: `validateOatSkills` in `packages/cli/src/validation/skills.ts` enforces it only for skills whose directory name starts with `oat-`. For every other skill it is an unenforced authoring convention this repository follows for portability. Backstops in `packages/cli/src/validation/skills.test.ts`: `it('reports description longer than 500 characters')` and `it('does not report a description longer than 500 characters for a non-oat-* skill')`. The spec allows 1024
 - Bump `metadata.version` on future edits: patch for fixes/clarifications, minor for backward-compatible behavior additions, major for breaking workflow/interface changes
 
 **Writing the `description` field:**
@@ -194,7 +195,7 @@ Examples:
 - Bad: "Reviews code by checking spec compliance, then code quality, then creates PR"
 - Good: "Use when reviewing code or checking PRs. Systematic quality and security analysis."
 
-Present the plan and wait for user approval before creating files.
+Present the plan and ask once for approval, stating the approval scope: it covers the skill directory, its `SKILL.md`, and the supporting files this plan named, for the rest of this run. Re-ask only if the file set changes. If the user declines, stop before creating any file and report the plan instead.
 
 ### Step 4: Create Skill File
 
@@ -231,18 +232,21 @@ Skills can include supporting files in subdirectories:
 
 ### Step 5: Sync and Verify
 
-After creating the skill, run OAT sync to update provider views:
+If the repository uses OAT sync, refresh the provider views for this repository only:
 
 ```bash
-oat sync
+oat sync --scope project
 ```
 
+A bare `oat sync` defaults to `--scope all`, which also rewrites the invoking user's home-scope provider
+directories. `withScopeOption` in `packages/cli/src/commands/shared/scope-option.ts` owns that default, and `it('sync --help matches snapshot')` in `packages/cli/src/commands/help-snapshots.test.ts` is its backstop.
+
 Verify:
 
 - File created at `.agents/skills/{skill-name}/SKILL.md`
 - Frontmatter syntax is valid
 - Frontmatter includes valid semver `metadata.version:` (new skills start at `1.0.0`)
-- Skill appears in `AGENTS.md`
+- Skill resolves through the provider views after a scoped sync — check with `oat tools info {skill-name}` or the provider's own skill list
 - Examples include both invocation styles
 - If the skill name starts with `oat-`, run `pnpm oat:validate-skills` and fix any findings
 
@@ -268,7 +272,7 @@ Provide:
 - **Context window is a public good**—keep skills lean, challenge every paragraph
 - Description is the trigger—include "when to use" in frontmatter, not just body
 - Bump `metadata.version` for edits: patch = fixes/clarifications, minor = backward-compatible additions, major = breaking changes
-- Keep SKILL.md **under 500 lines / ~5,000 tokens** (spec constraint)
+- Keep SKILL.md **under 500 lines / ~5,000 tokens** — OAT's authoring budget, not a specification limit; see the dated provider-compatibility section of `references/docs/skills-guide.md` for what each provider documents
 - Use clear, task-based headings
 - Include working examples for both invocation styles
 - Document all arguments with defaults
@@ -289,7 +293,7 @@ Skills that need user decisions (parameter choices, confirmations, disambiguatio
 
 Do **not** hard-code a specific Codex question tool name in skill prose unless the runtime contract is guaranteed. Prefer capability-based wording ("structured user-input tooling when available") so the skill remains portable across Codex hosts.
 
-**Claude Code enhancement:** Add `AskUserQuestion` to `allowed-tools` in frontmatter. Claude Code renders these as structured UI prompts with selectable options, headers, and multi-select support. Other providers ignore the field and handle the same instructions as conversational questions.
+**Claude Code enhancement:** Add `AskUserQuestion` to `allowed-tools` in frontmatter. Claude Code renders these as structured UI prompts with selectable options, headers, and multi-select support. Providers that do not read `allowed-tools` handle the same instructions as conversational questions; treat the field as having no effect there rather than as universally supported, and check the dated compatibility matrix in `references/docs/skills-guide.md`.
 
 **When to include interactive input:**
 
@@ -374,32 +378,11 @@ For multi-step skills, print brief progress updates so the user knows what's hap
 
 ### Frontmatter Reference
 
-Legend: ✅ supported | ⚠️ provider-specific | 💤 ignored | ❓ unknown
-
-| Field                      | Spec            | Claude Code | Cursor | Codex CLI   | Gemini CLI |
-| -------------------------- | --------------- | ----------- | ------ | ----------- | ---------- |
-| `name`                     | ✅ required     | ✅          | ✅     | ✅ required | ✅         |
-| `description`              | ✅ required     | ✅          | ✅     | ✅ required | ✅         |
-| `license`                  | ✅ optional     | ❓          | ✅     | 💤          | ❓         |
-| `compatibility`            | ✅ optional     | ❓          | ✅     | 💤          | ❓         |
-| `metadata`                 | ✅ optional     | ❓          | ✅     | 💤          | ❓         |
-| `allowed-tools`            | ⚠️ experimental | ✅          | ❓     | 💤          | ❓         |
-| `disable-model-invocation` | ❌              | ✅          | ✅     | 💤          | ❓         |
-| `user-invocable`           | ❌              | ✅          | ❓     | 💤          | ❓         |
-| `argument-hint`            | ❌              | ✅          | ❓     | 💤          | ❓         |
-| `context` / `agent`        | ❌              | ✅          | ❌     | 💤          | ❓         |
-| `hooks`                    | ❌              | ✅          | ❌     | 💤          | ❓         |
-
-**Key takeaway:** `name` + `description` are the only truly portable interface. Codex ignores unknown keys (safe to include Claude fields), so layer tool-specific fields on top of a portable baseline. For the full matrix, see `references/docs/skills-guide.md` (bundled with this skill).
+**Key takeaway:** `name` + `description` are the only truly portable interface. Layer tool-specific fields on top of that baseline, but treat an unread field as inert rather than guaranteed harmless — providers differ in which extension fields they read, and not every provider documents what it does with the rest. The single canonical, dated compatibility matrix lives in `references/docs/skills-guide.md` (bundled with this skill); consult it rather than a copy.
 
 ### Detail Level
 
-| Skill Type            | Detail Level | Examples                       |
-| --------------------- | ------------ | ------------------------------ |
-| Complex workflows     | Detailed     | docs-new, docs-review          |
-| Simple command-like   | Concise      | update-doc-refs, create-ticket |
-| Reference/standards   | Detailed     | repo-documentation             |
-| Helper (auto-invoked) | Moderate     | read-relevant-docs             |
+For the detail level each skill type warrants, see `references/skill-template.md`.
 
 ## Examples
 
@@ -428,7 +411,7 @@ I need a skill for running database migrations
 - [Agent Skills Open Standard](https://agentskills.io) — the spec
 - [Claude Code Skills](https://code.claude.com/docs/en/skills) — Claude-specific features
 - [Cursor Skills](https://cursor.com/docs/context/skills) — Cursor-specific features
-- [Codex CLI Skills](https://developers.openai.com/codex/skills) — Codex-specific features
+- [Codex CLI Skills](https://learn.chatgpt.com/docs/build-skills) — Codex-specific features
 - [Gemini CLI Skills](https://geminicli.com/docs/cli/skills/) — Gemini-specific features
 - [npx skills CLI](https://github.com/vercel-labs/skills) — installing remote/community skills
 - [Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — authoring guidance
@@ -439,7 +422,7 @@ I need a skill for running database migrations
 
 **Skill not appearing in menu:**
 
-- Run `oat sync` to regenerate provider views
+- Run `oat sync --scope project` to regenerate this repository's provider views
 - Verify YAML frontmatter syntax is valid
 - Check that skill name matches directory name
 - Ensure `user-invocable` is not set to `false` (Claude Code)
@@ -461,7 +444,6 @@ I need a skill for running database migrations
 Successful skill creation:
 
 - ✅ Skill created at `.agents/skills/{name}/SKILL.md`
-- ✅ `oat sync` run successfully
 - ✅ For `oat-*` skills, `pnpm oat:validate-skills` passes
 - ✅ Frontmatter valid
 - ✅ Workflow uses "Step" naming

package/assets/skills/create-agnostic-skill/references/docs/skills-guide.md

@@ -2,7 +2,7 @@
 
 Agent Skills ecosystem research and notes across providers.
 
-_Last updated: July 2026_
+_Last updated: September 2026_
 
 ---
 
@@ -55,7 +55,7 @@ license: MIT # License name or reference to bundled file
 compatibility:
   | # Max 500 chars — intended product, system packages, network needs
   Requires Node.js 18+
-allowed-tools: Read Grep Glob # Space-delimited tool list (experimental)
+allowed-tools: Read Grep Glob # Spec example: space-delimited. OAT writes commas and never parses the separator — see the separator note below
 metadata: # Arbitrary key-value pairs
   author: my-org
   version: '1.0'
@@ -64,7 +64,20 @@ metadata: # Arbitrary key-value pairs
 
 ### Spec Constraints
 
-- SKILL.md should be **under 500 lines / ~5,000 tokens**
+The size budget in the first bullet is **OAT's authoring guidance**, not a published
+specification limit — no spec text in this document's sources imposes either number
+(checked against https://agentskills.io/specification on 2026-09-09).
+The remaining bullets restate the spec's own file-layout guidance.
+
+**Separator note:** the spec's `allowed-tools` example is space-delimited. OAT writes
+the value comma-separated, and OAT never parses the separator — `validateOatSkills` in
+`packages/cli/src/validation/skills.ts` only checks that the key is present, and `getToolDetail` in
+`packages/cli/src/commands/tools/info/index.ts` reads the raw scalar. The comma form is therefore an
+authoring convention, not a runtime contract. Backstop:
+`it('declares allowed-tools as a comma-separated list in every canonical skill')` in
+`packages/cli/src/validation/skills.test.ts`.
+
+- SKILL.md should be **under 500 lines / ~5,000 tokens** (OAT authoring budget)
 - Use **relative paths** from skill root: `See [guide](references/REFERENCE.md)`
 - Keep file references **one level deep** from SKILL.md
 - Scripts should be **self-contained** or clearly document dependencies
@@ -79,12 +92,13 @@ If you want a skill to work across Claude Code, Cursor, Codex CLI, and Gemini CL
 1. Follow the Agent Skills spec folder layout and constraints
 2. Keep frontmatter minimal and conservative:
    - `name`: lowercase letters + numbers + hyphens, max 64 chars, must match folder name, no leading/trailing hyphen
-   - `description`: **single line**, ≤ 500 chars (Codex enforces this), describes _when to use_ + _what_
+   - `description`: **single line**, ≤ 500 chars, describes _when to use_ + _what_. This is OAT's house rule, not a provider requirement: `validateOatSkills` in `packages/cli/src/validation/skills.ts` enforces it only for skills whose directory name starts with `oat-`; elsewhere it is an unenforced authoring convention for portability. Backstops in `packages/cli/src/validation/skills.test.ts`: `it('reports description longer than 500 characters')` and `it('does not report a description longer than 500 characters for a non-oat-* skill')`. The spec allows 1024
 3. Put detailed instructions in the Markdown body (and/or `references/`), not in `description`
 4. Treat extra frontmatter keys as **best-effort extensions**:
    - Claude Code supports many optional frontmatter keys
-   - Codex CLI explicitly **ignores unknown keys** (safe to include, won't break, won't be used)
    - Cursor + Gemini support a subset; some keys are undocumented
+   - An unread key is inert rather than guaranteed harmless. See the Frontmatter Compatibility Matrix
+     below for the per-provider picture and for which entries are verified rather than inherited
 
 ### Cross-Provider Safe Template
 
@@ -129,6 +143,10 @@ Provider-specific fields can be layered on top but should be treated as non-port
 
 ## Frontmatter Compatibility Matrix
 
+This is the **single canonical frontmatter matrix** for this repository, verified against
+provider documentation on **2026-09-08** (re-verified 2026-09-09). Where any other table —
+including the third-party `npx skills` matrix below — disagrees with it, this table governs.
+
 Legend: ✅ documented support | ⚠️ provider-specific semantics | 💤 ignored (documented) | ❓ not documented / unknown
 
 | Field                          | Agent Skills Spec | Cursor      | Claude Code     | Codex CLI       | Copilot             | Gemini CLI    |
@@ -151,7 +169,22 @@ Legend: ✅ documented support | ⚠️ provider-specific semantics | 💤 ignor
 ² Claude Code uses first paragraph of body if `description` omitted
 ³ Copilot may require `license` in practice (see https://github.com/github/copilot-cli/issues/894)
 
-**Key takeaway:** Codex's "ignores extra keys" means you can include Claude/Cursor-only fields without breaking Codex, but you cannot depend on them affecting Codex behavior. `name` + `description` are the only truly portable interface.
+**Consolidation note (2026-09-08).** This table absorbed the shorter 5-column matrix that
+`create-agnostic-skill/SKILL.md` used to carry. Every field row from that table survives here. Two cells
+were deliberately changed rather than dropped silently: the old table asserted Cursor `❌` for
+`context` / `agent` and for `hooks`, and no current Cursor documentation substantiates a positive claim of
+non-support, so both are recorded here as `❓ not documented` instead. The old table carried no footnote or
+caveat that is missing above.
+
+**Key takeaway:** `name` + `description` are the only truly portable interface. Layer provider-specific
+fields on top of that baseline, but treat an unread key as inert rather than guaranteed harmless.
+
+**Codex and unknown keys — unverified as of 2026-09-08.** This document previously stated that Codex CLI
+explicitly ignores unknown frontmatter keys. That statement is retained here as an inherited claim, not a
+checked one: the current Codex skills documentation at https://learn.chatgpt.com/docs/build-skills carries no
+statement about unknown or extra frontmatter keys (checked 2026-09-08, re-checked 2026-09-09). The `💤 ignored`
+Codex cells above rest on that earlier, no-longer-restated documentation. Do not depend on a Claude-only or
+Cursor-only field having any effect under Codex, and do not treat its inertness there as documented.
 
 ---
 
@@ -222,7 +255,7 @@ supported home for Cursor-only skills. Cursor also reads `.claude/skills/` and
 
 ### Codex CLI (OpenAI)
 
-**Docs:** https://developers.openai.com/codex/skills
+**Docs:** https://learn.chatgpt.com/docs/build-skills
 
 **Skill locations (by precedence, high → low):**
 
@@ -238,10 +271,10 @@ supported home for Cursor-only skills. Cursor also reads `.claude/skills/` and
 **Codex-specific behaviors:**
 
 - **Uses `.agents/skills/` natively at all scopes** — Codex scans `.agents/skills/` from CWD up to repo root, plus `$HOME/.agents/skills` for user-level
-- **Ignores unknown frontmatter keys** — you can include Claude/Cursor-specific fields without breaking Codex, but they won't affect behavior
 - **Does NOT deduplicate** same-named skills — multiple can appear in selectors
 - `name`: ≤ 100 chars, **single line** (spec says 64; use 64 for max portability)
-- `description`: ≤ 500 chars, **single line** (spec says 1024; use 500 for max portability)
+- **Skill-list context budget (verified 2026-09-08 against https://learn.chatgpt.com/docs/build-skills, re-verified 2026-09-09):** the initial skills list — each skill's name, description, and file path — uses at most 2% of the model's context window, or 8,000 characters when the context window is unknown. If many skills are installed, Codex shortens skill descriptions first, and for large skill sets it may omit skills from the list and show a warning. The budget applies only to the initial list; the full `SKILL.md` is read once a skill is selected. The page states **no** single-line requirement and **no** character limit for `description`
+- `description`: OAT's own house rule — not a Codex rule — is a single-line scalar of at most 500 characters. `validateOatSkills` in `packages/cli/src/validation/skills.ts` enforces it **only for skills whose directory name starts with `oat-`**; for every other skill it is an unenforced repository authoring convention. Backstops in `packages/cli/src/validation/skills.test.ts`: `it('reports description longer than 500 characters')` and `it('does not report a description longer than 500 characters for a non-oat-* skill')`. Because implicit matching depends on `description`, front-load trigger keywords so the skill still matches when a host shortens it
 - Markdown body stays on disk and **is not injected unless explicitly invoked**
 - Built-in `$skill-creator` and `$skill-installer` skills
 - `/skills` slash command or `$` prefix for explicit invocation
@@ -368,6 +401,12 @@ For automated distribution, use **OAT sync** (for local/internal skills) or **`n
 
 ```bash
 # OAT sync — manages local canonical → provider distribution with manifest tracking
+# --scope all is correct here: this section is about user-level distribution.
+# --scope project writes only this repository's provider views; --scope user writes only
+# the invoking user's home-scope views; --scope all writes both and is the default when
+# the flag is omitted. Inside a repository, prefer --scope project. Owner: computePlans in
+# packages/cli/src/commands/sync/index.ts (the project/user mapping split); backstop:
+# packages/cli/src/commands/sync/index.test.ts.
 oat sync --scope all
 
 # npx skills — installs remote skills from GitHub or skills.sh
@@ -385,7 +424,11 @@ and `~/.copilot/skills/` as legacy Copilot adoption inputs, not mirrors.
 
 ## Cross-Tool Compatibility (npx skills Matrix)
 
-From the `npx skills` CLI compatibility matrix:
+This is a **third-party, vendor-published claim** from the `npx skills` CLI compatibility matrix,
+reproduced as published (retrieved 2026-09-08, re-checked 2026-09-09), not independently verified here.
+Where it disagrees with the canonical Frontmatter Compatibility Matrix above — notably on `allowed-tools`,
+which it marks supported everywhere while the canonical matrix records `💤 ignored` for Codex and `❓` for
+Cursor — **the canonical matrix governs**.
 
 | Feature         | Claude Code | Codex | Cursor | Copilot | Gemini CLI | Amp | Roo | OpenCode | Cline |
 | --------------- | ----------- | ----- | ------ | ------- | ---------- | --- | --- | -------- | ----- |
@@ -420,7 +463,7 @@ At startup, agents load _only_ `name` + `description` across potentially 100+ sk
 
 1. **Lead with triggering conditions**: "Use when…" / "Run this when…" / "Triggers when…"
 2. **Include keywords for disambiguation**: nouns + verbs that differentiate from similar skills
-3. **Keep it single-line**: Codex enforces single-line ≤ 500 chars
+3. **Keep it single-line**: OAT's house rule is a single-line scalar of at most 500 characters — `validateOatSkills` in `packages/cli/src/validation/skills.ts` enforces it only for skills whose directory name starts with `oat-`, backstopped by `it('reports description longer than 500 characters')` and `it('does not report a description longer than 500 characters for a non-oat-* skill')` in `packages/cli/src/validation/skills.test.ts`. No provider is documented as requiring it; the spec allows 1024
 4. **Don't summarize the workflow**: providers route on description without reading the body
 
 Examples:
@@ -481,7 +524,7 @@ Examples:
 
 Same-named skills at a more specific scope overwrite those from a less specific scope. This mirrors the AGENTS.md "nearest file wins" pattern and is well-suited for monorepos where packages need different conventions.
 
-**Source:** https://developers.openai.com/codex/skills, https://developers.openai.com/codex/config-advanced/, https://github.com/vercel-labs/skills
+**Source:** https://learn.chatgpt.com/docs/build-skills, https://developers.openai.com/codex/config-advanced/, https://github.com/vercel-labs/skills
 
 ### Q: What's the practical token cost of skills via progressive disclosure vs. same content in AGENTS.md?
 
@@ -563,7 +606,7 @@ ln -s ../../.agents/skills/my-skill .claude/skills/my-skill    # Claude Code + C
 `.agents/skills/` natively at project and user scope. No skill symlinks are
 needed for those providers.
 
-**Source:** https://cursor.com/docs/context/skills, https://code.visualstudio.com/docs/copilot/customization/agent-skills, https://developers.openai.com/codex/skills, https://github.com/vercel-labs/skills
+**Source:** https://cursor.com/docs/context/skills, https://code.visualstudio.com/docs/copilot/customization/agent-skills, https://learn.chatgpt.com/docs/build-skills, https://github.com/vercel-labs/skills
 
 ### Q: How does Claude Code's skill description character budget interact with many installed skills?
 
@@ -589,7 +632,7 @@ needed for those providers.
 
 **Answer:** Uncertain. The `npx skills` compatibility matrix marks `allowed-tools` as ✅ for Cursor, but Cursor's own documentation does not explicitly document the field. Their docs only list `name`, `description`, `license`, `compatibility`, `metadata`, and `disable-model-invocation` as supported frontmatter.
 
-The safe assumption: Cursor likely doesn't error on `allowed-tools` (similar to Codex's "ignore unknown keys" behavior), but whether it actually restricts tool access based on the field is unconfirmed. Treat `allowed-tools` as **Claude Code-specific for enforcement** and include it as a documentation signal for other tools.
+The safe assumption: Cursor likely doesn't error on `allowed-tools`, but whether it actually restricts tool access based on the field is unconfirmed. (The comparable Codex "ignores unknown keys" behavior is itself an inherited, unverified claim — see the note under the Frontmatter Compatibility Matrix.) Treat `allowed-tools` as **Claude Code-specific for enforcement** and include it as a documentation signal for other tools.
 
 **Source:** https://cursor.com/docs/context/skills, https://github.com/vercel-labs/skills#compatibility
 
@@ -597,7 +640,7 @@ The safe assumption: Cursor likely doesn't error on `allowed-tools` (similar to
 
 **Answer:** Treat this as a two-layer pattern: frontmatter hinting for discovery, then provider-native interaction at runtime.
 
-- **Layer 1 (discovery UX):** Use `argument-hint` when a provider supports it (for slash/autocomplete discoverability), but do not treat it as input collection. Codex ignores unknown frontmatter keys, so `argument-hint` is non-functional there.
+- **Layer 1 (discovery UX):** Use `argument-hint` when a provider supports it (for slash/autocomplete discoverability), but do not treat it as input collection. `argument-hint` is not documented as functional under Codex; see the unknown-key note under the Frontmatter Compatibility Matrix for how far that claim is verified.
 - **Layer 2 (runtime clarification):** Use the provider's native user-question mechanism when available:
   - **Claude Agent SDK:** Handle `AskUserQuestion` in `canUseTool`. If you restrict tools with a `tools` array, include `AskUserQuestion` explicitly. Parse `questions[]` (`question`, `header`, `options`, `multiSelect`) and return `answers` mapped by question text.
   - **Codex:** Use `request_user_input` when the runtime exposes it. As of PR #12735 (Feb 25, 2026), Codex app-server behavior was expanded so Default mode can use `request_user_input`, with guidance to prefer assumptions first and ask only when unavoidable; rollout can still be mode/config dependent in host environments.

package/assets/skills/create-agnostic-skill/references/skill-template.md

@@ -43,7 +43,7 @@ metadata:
   # only when `metadata.version` is absent.
   # author: my-org
 
-# === Claude Code / Cursor extension fields (ignored by Codex, safe to include) ===
+# === Claude Code / Cursor extension fields (not read by every provider) ===
 argument-hint: '[required-arg] [--optional-flag]'
 # Claude Code only: Shows in autocomplete after /skill-name
 
@@ -52,6 +52,10 @@ disable-model-invocation: true
 
 allowed-tools: Read, Write, Glob, Grep
 # Claude Code only: Tools agent can use without permission prompts
+# Write the list comma-separated: the spec's example is space-delimited, but OAT
+# writes commas and never parses the separator. Backstop:
+# it('declares allowed-tools as a comma-separated list in every canonical skill')
+# in packages/cli/src/validation/skills.test.ts
 
 user-invocable: true
 # Claude Code only: Set false for helper skills that shouldn't appear in / menu
@@ -116,7 +120,6 @@ Include code blocks for commands:
 ```bash
 example command
 ```
-````
 
 ### Step 2: Second Step Title
 
@@ -174,17 +177,16 @@ Successful completion means:
 - ✅ Second condition is met
 - ✅ Artifacts created or modified as expected
 - ✅ Skill can be invoked with /skill-name
-
-```
+````
 
 ## Detail Level Guidelines
 
-| Skill Type | Detail Level | Examples |
-|------------|--------------|----------|
-| Complex workflows | Detailed | docs-new, docs-review |
-| Simple command-like | Concise | update-doc-refs, create-ticket |
-| Reference/standards | Detailed | repo-documentation |
-| Helper (auto-invoked) | Moderate | read-relevant-docs |
+| Skill Type            | Detail Level | Examples                       |
+| --------------------- | ------------ | ------------------------------ |
+| Complex workflows     | Detailed     | docs-new, docs-review          |
+| Simple command-like   | Concise      | update-doc-refs, create-ticket |
+| Reference/standards   | Detailed     | repo-documentation             |
+| Helper (auto-invoked) | Moderate     | read-relevant-docs             |
 
 ## Versioning Guidance
 
@@ -197,15 +199,16 @@ Successful completion means:
 
 **Portable baseline:** `name` + `description` are the only fields that work identically across all providers. Everything else is either spec-optional or provider-specific.
 
-**Safe layering strategy:** Start with the portable fields, then layer provider-specific fields on top. Codex explicitly ignores unknown keys, so including Claude-specific fields (like `allowed-tools`, `user-invocable`) won't break Codex — they just won't have effect there.
+**Safe layering strategy:** Start with the portable fields, then layer provider-specific fields on top. Providers differ in which extension fields they read, and an unread field is inert rather than guaranteed harmless, so treat a Claude-specific field as having no effect elsewhere rather than as universally safe. The dated per-provider picture lives in one place: see `references/docs/skills-guide.md`.
 
-**Description constraints for max portability:**
-- Single line (Codex enforces this)
-- ≤ 500 chars (Codex limit; spec allows 1024)
+**Description constraints:**
+
+- Single line, ≤ 500 chars — OAT's house rule, not a provider requirement. `validateOatSkills` in `packages/cli/src/validation/skills.ts` enforces it only for skills whose directory name starts with `oat-`; for every other skill it is an unenforced convention this repository follows for portability. Backstops in `packages/cli/src/validation/skills.test.ts`: `it('reports description longer than 500 characters')` and `it('does not report a description longer than 500 characters for a non-oat-* skill')`. The spec allows 1024
 - Lead with "Use when..." or "Run this when..."
 - Front-load trigger keywords in first 50 chars (may be truncated at scale)
 
 **Skill budget awareness (Claude Code):**
+
 - Claude Code has a ~16,000 character budget for skill descriptions at startup
 - At 60+ skills, descriptions may be silently truncated
 - Keep descriptions concise; the body handles detail
@@ -213,4 +216,3 @@ Successful completion means:
 **Shared references:** Keep a shared doc's canonical copy in `.agents/docs/` (edit it in one place). If a distributed skill needs it at invocation time, vendor it into `references/docs/` as a symlink to the canonical file (`ln -s ../../../../docs/my-guide.md references/docs/my-guide.md`); the build materializes the symlink so the doc travels with the skill. Reference the bundled `references/docs/...` path — a bare `.agents/docs/...` reference dangles once the skill is installed in another repo.
 
 For the full compatibility matrix and resolved research questions, see `references/docs/skills-guide.md`.
-```

package/assets/skills/oat-agent-instructions-apply/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.7.1
+  version: 1.7.2
 ---
 
 # Agent Instructions Apply

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/glob-scoped-rule.md

@@ -37,15 +37,13 @@ See `frontmatter/` for provider-specific frontmatter examples.
 ```{lang}
 {example}
 ```
-````
 
 ### Incorrect
 
 ```{lang}
 {counter-example}
 ```
-
-```
+````
 
 ## Guidance
 
@@ -56,4 +54,3 @@ See `frontmatter/` for provider-specific frontmatter examples.
 - Only the frontmatter wrapper changes per provider (see `frontmatter/` directory)
 - Use progressive disclosure: keep the rule short and link to deeper docs/examples when needed
 - Do not encode style trivia unless it is backed by repo evidence and genuinely helps the matching files
-```

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read
 metadata:
-  version: 1.2.7
+  version: 1.2.8
 ---
 
 # Dispatching OAT Subagents
@@ -175,7 +175,9 @@ terminal outcome, not a pre-start rejection, and must be recorded through
 `child_outcome`. If you cannot prove the child never existed, you cannot set
 `provesNoChildStarted: true`, and no fallback is authorized.
 
-Project-aware callers pass the validated record and event on standard input:
+The calling workflow records each launch in its own run record (request ID,
+`Dispatch:` stamp, launch status, terminal outcome). Writing a per-dispatch file with `oat project dispatch record` is optional and off by default: no lifecycle skill or command consumes those files, so do not write them unless the host has explicitly opted in. A host that has opted
+in passes the validated record and event on standard input:
 
 ```bash
 oat project dispatch record \

package/assets/skills/oat-doctor/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.2.3
+  version: 1.2.4
 ---
 
 # OAT Doctor
@@ -238,11 +238,8 @@ OAT ▸ DOCTOR SUMMARY
 | Pack      | Scope   | Skills | Status   |
 | --------- | ------- | ------ | -------- |
 | core      | user    | 2/2    | current  |
-| docs      | project | 7/7    | current  |
 | workflows | project | 40/40  | current  |
 | ideas     | user    | 4/4    | current  |
-| project-management | project | 5/5 | current |
-| research  | project | 6/6    | current  |
 | utility   | project | 10/10  | outdated |
 
 ## Outdated Skills

package/assets/skills/oat-project-autonomous/references/gate-inventory.md

@@ -82,7 +82,8 @@ artifact already owned by the calling workflow:
 
 - planning and artifact decisions: the relevant artifact plus its review row;
 - implementation and boundary decisions: `implementation.md`;
-- review and dispatch decisions: the dispatch record schema and the referenced
+- review and dispatch decisions: the run record in `implementation.md` (request
+  ID, `Dispatch:` stamp, launch status, terminal outcome) and the referenced
   review artifact;
 - gate execution: structured gate result, attempt count, and disposition;
 - documentation and completion decisions: `state.md` and the normal summary or
@@ -276,7 +277,7 @@ remains immutable baseline evidence for the original p01-t01 verification.
 | `oat-dispatch-subagents/references/record-schema.md`           | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`; `2a63da6e3a96 -> NG`; `30762d53b043 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `oat-project-dispatch-subagents/SKILL.md`                      | `eca03ad1ca12 -> PDISPATCH-01`; `59fbcdc79cea -> PDISPATCH-01`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `oat-project-plan/SKILL.md`                                    | `f99e44b39932 -> PLAN-12`; `7e6a9854504b -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `oat-project-complete/SKILL.md`                                | `0177956707aa -> NG`; `8305b5bb65ef -> NG`; `2cd0503c0ef5 -> NG`; `44f54ef110a5 -> NG`; `fbf1ff53808a -> NG`; `6b774ee567b4 -> NG`; `8cc1fa5aab1e -> COMPLETE-01`; `4c209fbb4716 -> COMPLETE-01`; `02e4175e1171 -> COMPLETE-01`; `d698d4f98e76 -> COMPLETE-01`; `9f86a7218d93 -> COMPLETE-01`; `024713698d9a -> COMPLETE-01`; `c327995053fa -> COMPLETE-01`; `61f81d4ec7c1 -> COMPLETE-01`; `14fb2e56809f -> COMPLETE-01`; `7d4ff668744d -> COMPLETE-01`; `502a6c141784 -> COMPLETE-01`; `fb7e2db356af -> COMPLETE-01`; `f73f8476360a -> NG`; `1e15f420039f -> NG`; `cc234032ddd7 -> NG`; `c3d25f1398bb -> NG`; `ca13a6645df2 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `oat-project-complete/SKILL.md`                                | `0177956707aa -> NG`; `8305b5bb65ef -> NG`; `2cd0503c0ef5 -> NG`; `44f54ef110a5 -> NG`; `fbf1ff53808a -> NG`; `6b774ee567b4 -> NG`; `8cc1fa5aab1e -> COMPLETE-01`; `4c209fbb4716 -> COMPLETE-01`; `02e4175e1171 -> COMPLETE-01`; `d698d4f98e76 -> COMPLETE-01`; `9f86a7218d93 -> COMPLETE-01`; `024713698d9a -> COMPLETE-01`; `c327995053fa -> COMPLETE-01`; `61f81d4ec7c1 -> COMPLETE-01`; `14fb2e56809f -> COMPLETE-01`; `7d4ff668744d -> COMPLETE-01`; `502a6c141784 -> COMPLETE-01`; `fb7e2db356af -> COMPLETE-01`; `f73f8476360a -> NG`; `1e15f420039f -> NG`; `cc234032ddd7 -> NG`; `1dd54687229b -> NG`; `fc05c8303cd2 -> NG`; `24be721d635e -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `oat-project-lite/references/docs/autonomy-contract.md`        | `* -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `oat-project-implement/references/completion-and-closeout.md`  | `87f1424a8692 -> NG`; `6b1ec05182f0 -> IMPLEMENT-11`; `e6d696a27c91 -> NG`; `c77f8ccb52ad -> NG`; `48de2614c0ba -> IMPLEMENT-11`; `32d53f5212e5 -> IMPLEMENT-11`; `7cdb4a9c57b7 -> IMPLEMENT-11`; `16ffc0aa099b -> IMPLEMENT-11`; `d6868ea10b3f -> IMPLEMENT-11`; `4f05ff5567be -> IMPLEMENT-11`; `c70b47ae7a6d -> IMPLEMENT-11`; `5fafd093b58e -> NG`; `21ceaf7e658a -> NG`; `249427a9f475 -> NG`; `8a7ec13a9b7c -> NG`; `9aeb7fce2012 -> IMPLEMENT-18`; `f11a7cdda220 -> IMPLEMENT-18`; `4523ac029152 -> NG`; `6e87b08c4046 -> NG`; `baa6052c7f0a -> IMPLEMENT-18`; `27d3fad116b1 -> IMPLEMENT-18`; `2cfbeb4388a5 -> IMPLEMENT-18`; `c56ea56a56db -> NG`; `43e2e3c1380d -> IMPLEMENT-17`; `b49690277fb5 -> NG`; `df12304d6a36 -> NG`; `52eacac11fef -> IMPLEMENT-17`; `60092df6b17b -> IMPLEMENT-17`; `361872c6b00e -> IMPLEMENT-17`; `d2bc711a75fb -> IMPLEMENT-17`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `oat-project-quick-start/SKILL.md`                             | `4f393afc3b4d -> QS-13`; `40ddcac880ef -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |