v0.22.0

Legacy-root compatibility signal

• Flag named candidates found only in the deprecated default ~/.codex/skills root, absent from shared ~/.agents/skills.
• Keep the result strictly static: it can help diagnose installer-root mismatches but does not claim what Codex TUI or Desktop has loaded.

Verified on the exact release target: 76 tests (74 passed; two expected Windows symlink skips), syntax checks, self-scan, and nine-platform CI; code scanning and Pages are green.

v0.21.0

Symlinked Codex skill provenance

instructree skills now reports whether each discovered candidate was reached through a symlink and summarizes the count in human output. The report preserves the logical candidate path and never exposes the symlink target. It is a read-only troubleshooting signal, not a claim about Codex runtime namespace ownership.

This release is grounded in the open Codex report on standalone symlinked skills inheriting plugin namespace metadata from target ancestors: openai/codex#40070.

Verification

• Exact tag target: 28dc12940143e3743a3e416d97713cbbf361cdee
• 76 local tests: 74 passed, 2 expected Windows symlink skips, 0 failed
• Nine CI environments, code scanning, and Pages passed on that exact commit
• Package: 24 files, no tests, zero runtime dependencies
• instructree-0.21.0.tgz SHA-256: 79dbe19fe15831fad96771cc4ea80e4c2c2591f80d293e96596a0088553774c8

Install

npx --yes github:kotobuki09/instructree#v0.21.0 skills . --client codex

v0.20.0

Codex skill-catalog pressure, made actionable

instructree skills now ranks up to five largest enabled contributors to Codex's model-visible skill catalog. The read-only report models the current 1,024-character per-description cap and the 8,000-character unknown-context fallback, while keeping logical paths redacted.

Use the new source-grounded guide, Fix Codex skill overload, to understand the bounded catalog, review duplicates, and keep a focused starter stack. The estimate is a review aid, not a prompt dump: live Codex can use a model-specific token budget and path aliases.

Verification

• Exact tag target: d79e5b65113ecbfa5bf584af56c743871f57907d
• 76 local tests: 74 passed, 2 expected Windows symlink skips, 0 failed
• Nine CI environments, code scanning, and Pages passed on that exact commit
• Package: 24 files, no tests, zero runtime dependencies
• instructree-0.20.0.tgz SHA-256: b72693fd7dca8a209997641bf1b4a49624b869d08a3821470db1afc5ea8871a1

Install

npx --yes github:kotobuki09/instructree#v0.20.0 skills . --client codex

Instructree v0.19.0

What changed

Instructree now audits both Codex user skill roots:

• the shared ~/.agents/skills root recommended by current Codex documentation;
• the deprecated default ~/.codex/skills compatibility root still used by some host-specific installers.

The roots keep distinct provenance, so skills, starter, and doctor can find legacy-root installs and report same-name cross-root duplicates without including hidden .system descendants. The audit remains read-only and explicitly does not resolve a custom CODEX_HOME.

Verification

• 75 tests: 73 passed, 2 expected Windows symlink skips, 0 failed
• 9-job Node 20/22/24 matrix across Ubuntu, Windows, and macOS
• code scanning and GitHub Pages deployment passed on commit 33f3b197700e8c71a1ad0d7385a58412d74f188a
• development gate: 100/100
• fresh packed-install held-out gate: 100/100
• zero runtime dependencies

Artifact

instructree-0.19.0.tgz contains 24 files and no tests. SHA-256:

d9aaed615e19014ec74b08757890ef2a385a91bb56402a926443aecfd4a39d07

Instructree v0.18.0 — audit your Codex starter stack

Highlights

• Add instructree starter [cwd] for a read-only Codex companion-stack audit.
• Check six source-grounded engineering skills across discovery, testing, diagnosis, review, research, and verification.
• Classify local candidates as ready, disabled, invalid, or missing, then print install commands only for missing companions.
• Preserve logical path redaction and make no downloads, configuration edits, or skill changes.

Verification

• 73 tests: 71 passed, 2 expected Windows symlink skips, 0 failed.
• Arbor development gate: 95/95.
• Fresh packed-install held-out gate: 100/100.
• Nine OS/Node CI jobs, code scanning, and Pages deployment passed for f845770139b48008661e0e192f621f0c00ebc530.
• Package contains 24 files and zero runtime dependencies.

Try it

npx --yes github:kotobuki09/instructree#v0.18.0 starter .

SHA-256: 8b525ac63800c32f8303bf78bede7c706af2707656bef304d517cccb2061cccb

Instructree v0.17.0 — find instructions hidden by nested project roots

Find AGENTS.md files hidden by nested project roots

instructree doctor now explains a subtle Codex failure mode: a nearer .git or configured project-root marker can stop discovery before plausible parent instructions are reached.

What's new

• Inspect the boundary above the selected Codex project root without changing the effective instruction chain.
• Report the first-precedence parent instruction candidate from each relevant ancestor up to the nearest outer project marker.
• Preserve AGENTS.override.md, AGENTS.md, then configured-fallback precedence.
• Render only share-safe labels such as <parent>/AGENTS.md; absolute home and repository paths remain redacted.
• Keep clean nested projects quiet when the outer project has no instruction candidate.
• Add a search-focused explanation and current source-pinned research for nested Git repositories, submodules, and worktrees.

The improvement targets the real root-boundary behavior documented in openai/codex#25651, the explicit warning request in openai/codex#30789, and the focused doctor request in openai/codex#30788. The implementation boundary is recorded in the source-pinned research note.

Verification

• 70 tests across Node.js 20, 22, and 24 on Linux, macOS, and Windows.
• All 9 CI jobs, Instructree code scanning, and GitHub Pages passed on commit 2c3649fc5a2c6be657994bbf5e132a5330269cd7.
• Arbor development and fresh packed-install held-out evaluations both scored 100/100.
• The exact 23-file release tarball installed and passed a custom-root, two-level parent-boundary fixture with correct override precedence and zero private-path leaks.
• SHA-256: 94ee3ded21ffa8aa65f38e9c546fd6dfa3742814606e4a311fe3897e661c87be.

Instructree v0.16.0 — one-command Codex setup doctor

One share-safe Codex setup doctor

instructree doctor composes the supported pieces of a Codex setup into one deterministic, pre-session report: project-root discovery, user instructions, the effective project instruction chain, supported user configuration, and skill health.

What's new

• Add instructree doctor [cwd] [--home <home>] [--json] for one-command Codex setup diagnostics.
• Respect supported project_doc_max_bytes, project_doc_fallback_filenames, and project_root_markers settings, including override precedence and the shared project-instruction byte budget.
• Show the selected global instruction file, effective project files, disabled skills, duplicate skill names, metadata failures, scan errors, and approximate skill-list pressure.
• Redact repository and home paths so both text and JSON reports are safe to share.
• Fail closed when relevant TOML syntax is outside the supported parser subset instead of presenting a partial answer.
• Document the boundary clearly: this is a static pre-session preview, not a live or resumed-session inspector.

This addresses the focused diagnostics need described in openai/codex#30788. The behavior is grounded in a source-pinned research note; current Codex source does not yet expose a dedicated debug agents-md subcommand.

Verification

• 68 tests across Node.js 20, 22, and 24 on Linux, macOS, and Windows.
• All 9 CI jobs, Instructree code scanning, and GitHub Pages passed on commit 0fe113f96aa1b67af0bac0109fb2f29b07a79c48.
• Arbor development and fresh packed held-out evaluations both scored 100/100.
• The exact 23-file release tarball installed and passed a marker/fallback/override/byte-budget/duplicate-skill fixture with zero private-path leaks.
• SHA-256: 85ccba4a7d742f27bec54ca297760de201562112bdeff212d9ee365c38b3ec95.

Instructree v0.15.0 — explain Codex skill configuration

Explain why Codex skills are disabled

Codex can discover a skill on disk while user configuration still disables it. Instructree now makes that supported user-level configuration visible in the same read-only skill audit.

What's new

• Read supported [skills], [skills.bundled], and [[skills.config]] settings from user ~/.codex/config.toml.
• Apply exact name/path selectors and later-rule precedence to every discovered candidate.
• Report disabled candidates, unmatched rules, catalog injection, bundled-skill state, and max_context_tokens in JSON and human output.
• Redact absolute path selectors and fail closed when relevant syntax is outside the supported subset; no partial rules are applied.
• Deliberately exclude project skill rules because current Codex main loads these rules from user and session layers, not project configuration.

This targets recurring Codex configuration/discovery confusion documented in #37242, #20210, #24237, and #29846. The implementation is grounded in the pinned Codex configuration source.

Verification

• 63 tests across Node.js 20, 22, and 24 on Linux, macOS, and Windows.
• Hosted CI, code scanning, and GitHub Pages passed on commit 898823b725493a302745148caccbf0487caf8eac.
• Arbor development and fresh packed held-out evaluations both scored 100/100.
• Exact 22-file package installed and passed a configuration fixture with no absolute-path leakage.
• SHA-256: 3d9f75241c21bd07604fd8ebbac1af98e04abea66437d012f3fb70dc4f943a46.

Instructree v0.14.0

Catch Windows skill-loading failures before Codex does

instructree scan . now reports E005 when a SKILL.md starts with a UTF-8 byte-order mark (BOM). Current Codex builds can reject that otherwise valid frontmatter and misleadingly report that YAML frontmatter is missing, as documented in openai/codex#13918.

• Parses the valid metadata behind the BOM, avoiding cascaded missing-field errors.
• Adds the same actionable unsupported-utf8-bom finding to instructree skills.
• Emits the new rule in JSON and SARIF for local checks and GitHub code scanning.
• Does not warn for a BOM character in the skill body or for non-skill frontmatter.

npx --yes github:kotobuki09/instructree#v0.14.0 scan .
npx --yes github:kotobuki09/instructree#v0.14.0 skills . --client codex

The implementation is grounded in the current Codex parser behavior.

Verification

• Arbor development and fresh held-out evaluators: 100/100 each.
• 59 local tests: 57 passed, 2 expected Windows symlink skips, 0 failures.
• All nine OS/Node CI jobs, code scanning, and GitHub Pages passed on the release commit.
• The packed-install smoke test reproduced E005 from the exact attached tarball.
• The package contains 21 files, has zero runtime dependencies, and includes a SHA-256 checksum.

Instructree v0.13.0

Actionable skill audits without the wall of output

instructree skills now keeps its human-readable report concise by default while preserving every actionable finding:

• Each scope reports its candidate count instead of printing every clean skill.
• Duplicate names, metadata failures, metadata warnings, scan errors, prompt-list pressure, and limitations remain visible.
• Add --all to restore the complete human-readable inventory.
• --json remains complete and unchanged for automation.

npx --yes github:kotobuki09/instructree#v0.13.0 skills . --client codex
npx --yes github:kotobuki09/instructree#v0.13.0 skills . --client codex --all

Measured activation improvement

• A synthetic 124-skill catalog with duplicates and metadata problems dropped from 150 lines to 28 while retaining every issue path.
• The held-out real 273-skill catalog dropped from 291 lines to 19; --all still emitted the full 291-line inventory.
• A fresh packed installation reproduced the compact, expanded, and JSON modes with no absolute-path leakage.

Verification

• 56 local tests: 54 passed, 2 expected Windows symlink skips, 0 failures.
• CI, code scanning, and GitHub Pages passed on the tagged commit.
• The attached package contains 21 files, has zero runtime dependencies, and includes a SHA-256 checksum.