@open-agent-toolkit/cli 0.2.66 → 0.2.67

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/assets/bundle-metadata.json +1 -1
  2. package/assets/docs/cli-utilities/configuration.md +14 -1
  3. package/assets/docs/cli-utilities/project-log.md +63 -4
  4. package/assets/docs/contributing/code.md +8 -4
  5. package/assets/docs/contributing/skills.md +29 -17
  6. package/assets/docs/docs-tooling/commands.md +3 -1
  7. package/assets/docs/provider-sync/manifest-and-drift.md +2 -18
  8. package/assets/docs/workflows/projects/lifecycle.md +17 -0
  9. package/assets/docs/workflows/projects/picking-up-projects.md +18 -0
  10. package/assets/docs/workflows/skills/repo-improve.md +7 -3
  11. package/assets/public-package-versions.json +4 -4
  12. package/assets/skills/create-agnostic-skill/SKILL.md +19 -37
  13. package/assets/skills/create-agnostic-skill/references/docs/skills-guide.md +58 -15
  14. package/assets/skills/create-agnostic-skill/references/skill-template.md +17 -15
  15. package/assets/skills/oat-agent-instructions-apply/SKILL.md +1 -1
  16. package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/glob-scoped-rule.md +1 -4
  17. package/assets/skills/oat-doctor/SKILL.md +1 -4
  18. package/assets/skills/oat-project-autonomous/references/gate-inventory.md +1 -1
  19. package/assets/skills/oat-project-complete/SKILL.md +158 -30
  20. package/assets/skills/oat-project-complete/scripts/finalize-synced-archive.mjs +26 -7
  21. package/assets/skills/oat-project-complete/scripts/validate-durable-archive-receipt.mjs +183 -0
  22. package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +1 -1
  23. package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +1 -1
  24. package/assets/skills/oat-project-lite/references/docs/autonomy-contract.md +1 -1
  25. package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +1 -1
  26. package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +1 -1
  27. package/assets/skills/oat-project-retro/SKILL.md +1 -1
  28. package/assets/skills/oat-project-retro/references/apply-procedure.md +11 -0
  29. package/assets/skills/oat-project-review-provide/SKILL.md +4 -4
  30. package/assets/skills/oat-project-summary/SKILL.md +24 -2
  31. package/assets/skills/oat-repo-improve/SKILL.md +9 -2
  32. package/assets/skills/oat-repo-improve/references/plan-template.md +4 -6
  33. package/assets/skills/oat-repo-knowledge-index/SKILL.md +11 -9
  34. package/assets/skills/oat-wave-execute/SKILL.md +20 -6
  35. package/assets/skills/oat-wave-program/SKILL.md +9 -4
  36. package/dist/commands/config/index.d.ts +2 -1
  37. package/dist/commands/config/index.d.ts.map +1 -1
  38. package/dist/commands/config/index.js +133 -38
  39. package/dist/commands/docs/index-generate/index.d.ts.map +1 -1
  40. package/dist/commands/docs/index-generate/index.js +68 -12
  41. package/dist/commands/docs/init/index.d.ts +11 -0
  42. package/dist/commands/docs/init/index.d.ts.map +1 -1
  43. package/dist/commands/docs/init/index.js +19 -1
  44. package/dist/commands/gate/index.d.ts.map +1 -1
  45. package/dist/commands/gate/index.js +10 -2
  46. package/dist/commands/instructions/instructions.utils.d.ts.map +1 -1
  47. package/dist/commands/instructions/instructions.utils.js +42 -9
  48. package/dist/commands/internal/validate-skill-version-bumps.d.ts.map +1 -1
  49. package/dist/commands/internal/validate-skill-version-bumps.js +5 -5
  50. package/dist/commands/project/dispatch-ceiling/index.d.ts.map +1 -1
  51. package/dist/commands/project/dispatch-ceiling/index.js +32 -18
  52. package/dist/commands/project/log/append.d.ts +48 -0
  53. package/dist/commands/project/log/append.d.ts.map +1 -1
  54. package/dist/commands/project/log/append.js +207 -30
  55. package/dist/commands/project/log/check.d.ts +87 -1
  56. package/dist/commands/project/log/check.d.ts.map +1 -1
  57. package/dist/commands/project/log/check.js +139 -5
  58. package/dist/commands/project/log/grammar.d.ts +165 -0
  59. package/dist/commands/project/log/grammar.d.ts.map +1 -1
  60. package/dist/commands/project/log/grammar.js +219 -1
  61. package/dist/commands/project/log/rollup.d.ts +16 -1
  62. package/dist/commands/project/log/rollup.d.ts.map +1 -1
  63. package/dist/commands/project/log/rollup.js +22 -2
  64. package/dist/commands/project/log/synthesize.d.ts +16 -0
  65. package/dist/commands/project/log/synthesize.d.ts.map +1 -1
  66. package/dist/commands/project/log/synthesize.js +85 -9
  67. package/dist/commands/status/index.d.ts.map +1 -1
  68. package/dist/commands/status/index.js +24 -2
  69. package/dist/commands/sync/apply.d.ts.map +1 -1
  70. package/dist/commands/sync/apply.js +6 -4
  71. package/dist/config/dispatch-matrix.d.ts.map +1 -1
  72. package/dist/config/dispatch-matrix.js +13 -5
  73. package/dist/config/oat-config.d.ts +15 -0
  74. package/dist/config/oat-config.d.ts.map +1 -1
  75. package/dist/config/oat-config.js +61 -7
  76. package/dist/config/own-keys.d.ts +22 -0
  77. package/dist/config/own-keys.d.ts.map +1 -0
  78. package/dist/config/own-keys.js +32 -0
  79. package/dist/config/resolve.d.ts +11 -0
  80. package/dist/config/resolve.d.ts.map +1 -1
  81. package/dist/config/resolve.js +35 -11
  82. package/dist/config/sync-config.d.ts.map +1 -1
  83. package/dist/config/sync-config.js +16 -0
  84. package/dist/drift/detector.d.ts.map +1 -1
  85. package/dist/drift/detector.js +52 -1
  86. package/dist/drift/skill-view-diagnostic.d.ts.map +1 -1
  87. package/dist/drift/skill-view-diagnostic.js +2 -23
  88. package/dist/engine/compute-plan.d.ts.map +1 -1
  89. package/dist/engine/compute-plan.js +22 -72
  90. package/dist/engine/managed-copy-hash.d.ts +69 -0
  91. package/dist/engine/managed-copy-hash.d.ts.map +1 -0
  92. package/dist/engine/managed-copy-hash.js +175 -0
  93. package/dist/fs/assets.d.ts +11 -0
  94. package/dist/fs/assets.d.ts.map +1 -1
  95. package/dist/fs/assets.js +1 -1
  96. package/dist/manifest/hash.d.ts +110 -0
  97. package/dist/manifest/hash.d.ts.map +1 -1
  98. package/dist/manifest/hash.js +111 -13
  99. package/dist/providers/ceiling/registry.d.ts.map +1 -1
  100. package/dist/providers/ceiling/registry.js +6 -1
  101. package/dist/providers/identity/dispatch-report.d.ts.map +1 -1
  102. package/dist/providers/identity/dispatch-report.js +4 -1
  103. package/dist/release/public-package-contract.d.ts.map +1 -1
  104. package/dist/release/public-package-contract.js +21 -0
  105. package/dist/validation/skills.d.ts.map +1 -1
  106. package/dist/validation/skills.js +305 -40
  107. package/package.json +2 -2
@@ -2,7 +2,7 @@
2
2
 
3
3
  Agent Skills ecosystem research and notes across providers.
4
4
 
5
- _Last updated: July 2026_
5
+ _Last updated: September 2026_
6
6
 
7
7
  ---
8
8
 
@@ -55,7 +55,7 @@ license: MIT # License name or reference to bundled file
55
55
  compatibility:
56
56
  | # Max 500 chars — intended product, system packages, network needs
57
57
  Requires Node.js 18+
58
- allowed-tools: Read Grep Glob # Space-delimited tool list (experimental)
58
+ allowed-tools: Read Grep Glob # Spec example: space-delimited. OAT writes commas and never parses the separator — see the separator note below
59
59
  metadata: # Arbitrary key-value pairs
60
60
  author: my-org
61
61
  version: '1.0'
@@ -64,7 +64,20 @@ metadata: # Arbitrary key-value pairs
64
64
 
65
65
  ### Spec Constraints
66
66
 
67
- - SKILL.md should be **under 500 lines / ~5,000 tokens**
67
+ The size budget in the first bullet is **OAT's authoring guidance**, not a published
68
+ specification limit — no spec text in this document's sources imposes either number
69
+ (checked against https://agentskills.io/specification on 2026-09-09).
70
+ The remaining bullets restate the spec's own file-layout guidance.
71
+
72
+ **Separator note:** the spec's `allowed-tools` example is space-delimited. OAT writes
73
+ the value comma-separated, and OAT never parses the separator — `validateOatSkills` in
74
+ `packages/cli/src/validation/skills.ts` only checks that the key is present, and `getToolDetail` in
75
+ `packages/cli/src/commands/tools/info/index.ts` reads the raw scalar. The comma form is therefore an
76
+ authoring convention, not a runtime contract. Backstop:
77
+ `it('declares allowed-tools as a comma-separated list in every canonical skill')` in
78
+ `packages/cli/src/validation/skills.test.ts`.
79
+
80
+ - SKILL.md should be **under 500 lines / ~5,000 tokens** (OAT authoring budget)
68
81
  - Use **relative paths** from skill root: `See [guide](references/REFERENCE.md)`
69
82
  - Keep file references **one level deep** from SKILL.md
70
83
  - 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
79
92
  1. Follow the Agent Skills spec folder layout and constraints
80
93
  2. Keep frontmatter minimal and conservative:
81
94
  - `name`: lowercase letters + numbers + hyphens, max 64 chars, must match folder name, no leading/trailing hyphen
82
- - `description`: **single line**, ≤ 500 chars (Codex enforces this), describes _when to use_ + _what_
95
+ - `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
83
96
  3. Put detailed instructions in the Markdown body (and/or `references/`), not in `description`
84
97
  4. Treat extra frontmatter keys as **best-effort extensions**:
85
98
  - Claude Code supports many optional frontmatter keys
86
- - Codex CLI explicitly **ignores unknown keys** (safe to include, won't break, won't be used)
87
99
  - Cursor + Gemini support a subset; some keys are undocumented
100
+ - An unread key is inert rather than guaranteed harmless. See the Frontmatter Compatibility Matrix
101
+ below for the per-provider picture and for which entries are verified rather than inherited
88
102
 
89
103
  ### Cross-Provider Safe Template
90
104
 
@@ -129,6 +143,10 @@ Provider-specific fields can be layered on top but should be treated as non-port
129
143
 
130
144
  ## Frontmatter Compatibility Matrix
131
145
 
146
+ This is the **single canonical frontmatter matrix** for this repository, verified against
147
+ provider documentation on **2026-09-08** (re-verified 2026-09-09). Where any other table —
148
+ including the third-party `npx skills` matrix below — disagrees with it, this table governs.
149
+
132
150
  Legend: ✅ documented support | ⚠️ provider-specific semantics | 💤 ignored (documented) | ❓ not documented / unknown
133
151
 
134
152
  | Field | Agent Skills Spec | Cursor | Claude Code | Codex CLI | Copilot | Gemini CLI |
@@ -151,7 +169,22 @@ Legend: ✅ documented support | ⚠️ provider-specific semantics | 💤 ignor
151
169
  ² Claude Code uses first paragraph of body if `description` omitted
152
170
  ³ Copilot may require `license` in practice (see https://github.com/github/copilot-cli/issues/894)
153
171
 
154
- **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.
172
+ **Consolidation note (2026-09-08).** This table absorbed the shorter 5-column matrix that
173
+ `create-agnostic-skill/SKILL.md` used to carry. Every field row from that table survives here. Two cells
174
+ were deliberately changed rather than dropped silently: the old table asserted Cursor `❌` for
175
+ `context` / `agent` and for `hooks`, and no current Cursor documentation substantiates a positive claim of
176
+ non-support, so both are recorded here as `❓ not documented` instead. The old table carried no footnote or
177
+ caveat that is missing above.
178
+
179
+ **Key takeaway:** `name` + `description` are the only truly portable interface. Layer provider-specific
180
+ fields on top of that baseline, but treat an unread key as inert rather than guaranteed harmless.
181
+
182
+ **Codex and unknown keys — unverified as of 2026-09-08.** This document previously stated that Codex CLI
183
+ explicitly ignores unknown frontmatter keys. That statement is retained here as an inherited claim, not a
184
+ checked one: the current Codex skills documentation at https://learn.chatgpt.com/docs/build-skills carries no
185
+ statement about unknown or extra frontmatter keys (checked 2026-09-08, re-checked 2026-09-09). The `💤 ignored`
186
+ Codex cells above rest on that earlier, no-longer-restated documentation. Do not depend on a Claude-only or
187
+ Cursor-only field having any effect under Codex, and do not treat its inertness there as documented.
155
188
 
156
189
  ---
157
190
 
@@ -222,7 +255,7 @@ supported home for Cursor-only skills. Cursor also reads `.claude/skills/` and
222
255
 
223
256
  ### Codex CLI (OpenAI)
224
257
 
225
- **Docs:** https://developers.openai.com/codex/skills
258
+ **Docs:** https://learn.chatgpt.com/docs/build-skills
226
259
 
227
260
  **Skill locations (by precedence, high → low):**
228
261
 
@@ -238,10 +271,10 @@ supported home for Cursor-only skills. Cursor also reads `.claude/skills/` and
238
271
  **Codex-specific behaviors:**
239
272
 
240
273
  - **Uses `.agents/skills/` natively at all scopes** — Codex scans `.agents/skills/` from CWD up to repo root, plus `$HOME/.agents/skills` for user-level
241
- - **Ignores unknown frontmatter keys** — you can include Claude/Cursor-specific fields without breaking Codex, but they won't affect behavior
242
274
  - **Does NOT deduplicate** same-named skills — multiple can appear in selectors
243
275
  - `name`: ≤ 100 chars, **single line** (spec says 64; use 64 for max portability)
244
- - `description`: ≤ 500 chars, **single line** (spec says 1024; use 500 for max portability)
276
+ - **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`
277
+ - `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
245
278
  - Markdown body stays on disk and **is not injected unless explicitly invoked**
246
279
  - Built-in `$skill-creator` and `$skill-installer` skills
247
280
  - `/skills` slash command or `$` prefix for explicit invocation
@@ -368,6 +401,12 @@ For automated distribution, use **OAT sync** (for local/internal skills) or **`n
368
401
 
369
402
  ```bash
370
403
  # OAT sync — manages local canonical → provider distribution with manifest tracking
404
+ # --scope all is correct here: this section is about user-level distribution.
405
+ # --scope project writes only this repository's provider views; --scope user writes only
406
+ # the invoking user's home-scope views; --scope all writes both and is the default when
407
+ # the flag is omitted. Inside a repository, prefer --scope project. Owner: computePlans in
408
+ # packages/cli/src/commands/sync/index.ts (the project/user mapping split); backstop:
409
+ # packages/cli/src/commands/sync/index.test.ts.
371
410
  oat sync --scope all
372
411
 
373
412
  # npx skills — installs remote skills from GitHub or skills.sh
@@ -385,7 +424,11 @@ and `~/.copilot/skills/` as legacy Copilot adoption inputs, not mirrors.
385
424
 
386
425
  ## Cross-Tool Compatibility (npx skills Matrix)
387
426
 
388
- From the `npx skills` CLI compatibility matrix:
427
+ This is a **third-party, vendor-published claim** from the `npx skills` CLI compatibility matrix,
428
+ reproduced as published (retrieved 2026-09-08, re-checked 2026-09-09), not independently verified here.
429
+ Where it disagrees with the canonical Frontmatter Compatibility Matrix above — notably on `allowed-tools`,
430
+ which it marks supported everywhere while the canonical matrix records `💤 ignored` for Codex and `❓` for
431
+ Cursor — **the canonical matrix governs**.
389
432
 
390
433
  | Feature | Claude Code | Codex | Cursor | Copilot | Gemini CLI | Amp | Roo | OpenCode | Cline |
391
434
  | --------------- | ----------- | ----- | ------ | ------- | ---------- | --- | --- | -------- | ----- |
@@ -420,7 +463,7 @@ At startup, agents load _only_ `name` + `description` across potentially 100+ sk
420
463
 
421
464
  1. **Lead with triggering conditions**: "Use when…" / "Run this when…" / "Triggers when…"
422
465
  2. **Include keywords for disambiguation**: nouns + verbs that differentiate from similar skills
423
- 3. **Keep it single-line**: Codex enforces single-line ≤ 500 chars
466
+ 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
424
467
  4. **Don't summarize the workflow**: providers route on description without reading the body
425
468
 
426
469
  Examples:
@@ -481,7 +524,7 @@ Examples:
481
524
 
482
525
  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.
483
526
 
484
- **Source:** https://developers.openai.com/codex/skills, https://developers.openai.com/codex/config-advanced/, https://github.com/vercel-labs/skills
527
+ **Source:** https://learn.chatgpt.com/docs/build-skills, https://developers.openai.com/codex/config-advanced/, https://github.com/vercel-labs/skills
485
528
 
486
529
  ### Q: What's the practical token cost of skills via progressive disclosure vs. same content in AGENTS.md?
487
530
 
@@ -563,7 +606,7 @@ ln -s ../../.agents/skills/my-skill .claude/skills/my-skill # Claude Code + C
563
606
  `.agents/skills/` natively at project and user scope. No skill symlinks are
564
607
  needed for those providers.
565
608
 
566
- **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
609
+ **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
567
610
 
568
611
  ### Q: How does Claude Code's skill description character budget interact with many installed skills?
569
612
 
@@ -589,7 +632,7 @@ needed for those providers.
589
632
 
590
633
  **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.
591
634
 
592
- 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.
635
+ 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.
593
636
 
594
637
  **Source:** https://cursor.com/docs/context/skills, https://github.com/vercel-labs/skills#compatibility
595
638
 
@@ -597,7 +640,7 @@ The safe assumption: Cursor likely doesn't error on `allowed-tools` (similar to
597
640
 
598
641
  **Answer:** Treat this as a two-layer pattern: frontmatter hinting for discovery, then provider-native interaction at runtime.
599
642
 
600
- - **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.
643
+ - **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.
601
644
  - **Layer 2 (runtime clarification):** Use the provider's native user-question mechanism when available:
602
645
  - **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.
603
646
  - **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.
@@ -43,7 +43,7 @@ metadata:
43
43
  # only when `metadata.version` is absent.
44
44
  # author: my-org
45
45
 
46
- # === Claude Code / Cursor extension fields (ignored by Codex, safe to include) ===
46
+ # === Claude Code / Cursor extension fields (not read by every provider) ===
47
47
  argument-hint: '[required-arg] [--optional-flag]'
48
48
  # Claude Code only: Shows in autocomplete after /skill-name
49
49
 
@@ -52,6 +52,10 @@ disable-model-invocation: true
52
52
 
53
53
  allowed-tools: Read, Write, Glob, Grep
54
54
  # Claude Code only: Tools agent can use without permission prompts
55
+ # Write the list comma-separated: the spec's example is space-delimited, but OAT
56
+ # writes commas and never parses the separator. Backstop:
57
+ # it('declares allowed-tools as a comma-separated list in every canonical skill')
58
+ # in packages/cli/src/validation/skills.test.ts
55
59
 
56
60
  user-invocable: true
57
61
  # Claude Code only: Set false for helper skills that shouldn't appear in / menu
@@ -116,7 +120,6 @@ Include code blocks for commands:
116
120
  ```bash
117
121
  example command
118
122
  ```
119
- ````
120
123
 
121
124
  ### Step 2: Second Step Title
122
125
 
@@ -174,17 +177,16 @@ Successful completion means:
174
177
  - ✅ Second condition is met
175
178
  - ✅ Artifacts created or modified as expected
176
179
  - ✅ Skill can be invoked with /skill-name
177
-
178
- ```
180
+ ````
179
181
 
180
182
  ## Detail Level Guidelines
181
183
 
182
- | Skill Type | Detail Level | Examples |
183
- |------------|--------------|----------|
184
- | Complex workflows | Detailed | docs-new, docs-review |
185
- | Simple command-like | Concise | update-doc-refs, create-ticket |
186
- | Reference/standards | Detailed | repo-documentation |
187
- | Helper (auto-invoked) | Moderate | read-relevant-docs |
184
+ | Skill Type | Detail Level | Examples |
185
+ | --------------------- | ------------ | ------------------------------ |
186
+ | Complex workflows | Detailed | docs-new, docs-review |
187
+ | Simple command-like | Concise | update-doc-refs, create-ticket |
188
+ | Reference/standards | Detailed | repo-documentation |
189
+ | Helper (auto-invoked) | Moderate | read-relevant-docs |
188
190
 
189
191
  ## Versioning Guidance
190
192
 
@@ -197,15 +199,16 @@ Successful completion means:
197
199
 
198
200
  **Portable baseline:** `name` + `description` are the only fields that work identically across all providers. Everything else is either spec-optional or provider-specific.
199
201
 
200
- **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.
202
+ **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`.
201
203
 
202
- **Description constraints for max portability:**
203
- - Single line (Codex enforces this)
204
- - ≤ 500 chars (Codex limit; spec allows 1024)
204
+ **Description constraints:**
205
+
206
+ - 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
205
207
  - Lead with "Use when..." or "Run this when..."
206
208
  - Front-load trigger keywords in first 50 chars (may be truncated at scale)
207
209
 
208
210
  **Skill budget awareness (Claude Code):**
211
+
209
212
  - Claude Code has a ~16,000 character budget for skill descriptions at startup
210
213
  - At 60+ skills, descriptions may be silently truncated
211
214
  - Keep descriptions concise; the body handles detail
@@ -213,4 +216,3 @@ Successful completion means:
213
216
  **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.
214
217
 
215
218
  For the full compatibility matrix and resolved research questions, see `references/docs/skills-guide.md`.
216
- ```
@@ -5,7 +5,7 @@ disable-model-invocation: true
5
5
  user-invocable: true
6
6
  allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
7
7
  metadata:
8
- version: 1.7.1
8
+ version: 1.7.2
9
9
  ---
10
10
 
11
11
  # Agent Instructions Apply
@@ -37,15 +37,13 @@ See `frontmatter/` for provider-specific frontmatter examples.
37
37
  ```{lang}
38
38
  {example}
39
39
  ```
40
- ````
41
40
 
42
41
  ### Incorrect
43
42
 
44
43
  ```{lang}
45
44
  {counter-example}
46
45
  ```
47
-
48
- ```
46
+ ````
49
47
 
50
48
  ## Guidance
51
49
 
@@ -56,4 +54,3 @@ See `frontmatter/` for provider-specific frontmatter examples.
56
54
  - Only the frontmatter wrapper changes per provider (see `frontmatter/` directory)
57
55
  - Use progressive disclosure: keep the rule short and link to deeper docs/examples when needed
58
56
  - Do not encode style trivia unless it is backed by repo evidence and genuinely helps the matching files
59
- ```
@@ -6,7 +6,7 @@ disable-model-invocation: true
6
6
  user-invocable: true
7
7
  allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
8
8
  metadata:
9
- version: 1.2.3
9
+ version: 1.2.4
10
10
  ---
11
11
 
12
12
  # OAT Doctor
@@ -238,11 +238,8 @@ OAT ▸ DOCTOR SUMMARY
238
238
  | Pack | Scope | Skills | Status |
239
239
  | --------- | ------- | ------ | -------- |
240
240
  | core | user | 2/2 | current |
241
- | docs | project | 7/7 | current |
242
241
  | workflows | project | 40/40 | current |
243
242
  | ideas | user | 4/4 | current |
244
- | project-management | project | 5/5 | current |
245
- | research | project | 6/6 | current |
246
243
  | utility | project | 10/10 | outdated |
247
244
 
248
245
  ## Outdated Skills
@@ -276,7 +276,7 @@ remains immutable baseline evidence for the original p01-t01 verification.
276
276
  | `oat-dispatch-subagents/references/record-schema.md` | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`; `2a63da6e3a96 -> NG`; `30762d53b043 -> NG` |
277
277
  | `oat-project-dispatch-subagents/SKILL.md` | `eca03ad1ca12 -> PDISPATCH-01`; `59fbcdc79cea -> PDISPATCH-01` |
278
278
  | `oat-project-plan/SKILL.md` | `f99e44b39932 -> PLAN-12`; `7e6a9854504b -> NG` |
279
- | `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` |
279
+ | `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` |
280
280
  | `oat-project-lite/references/docs/autonomy-contract.md` | `* -> NG` |
281
281
  | `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` |
282
282
  | `oat-project-quick-start/SKILL.md` | `4f393afc3b4d -> QS-13`; `40ddcac880ef -> NG` |