[napetrov]

Summary

New warn, one per skill: bundle-file-unreferenced. It counts bundled scripts and documents (.py .sh .js .ts .md .txt …) that neither SKILL.md nor a document it names mentions, by path, file name or folder alone, with case ignored. The message gives the count and three example paths. Data, images, licence and readme files, AGENTS.md, _-prefixed helpers, tests, vendored folders and nested skills are not counted, and a skill at the checkout root is not checked. A document in a test or hidden folder that SKILL.md names is still read. A changelog, contributing or notice file supplies no references. A named document the search cannot read (over 256 KiB, not UTF-8, a symlink or a FIFO) gives no claim.

Evidence

• GitSkills corpus: of 5.9M files bundled next to a SKILL.md, 63% of .py, 45% of .sh and 47% of .md files are never named in it.
• 24 upstream repos: 120 of 2,372 skills flagged (596 of 2,391 counted files). These numbers are from before the round of review fixes on named documents and unreadable documents, so they are stale: a rerun is needed before quoting them again. The main false-positive class left is package modules imported by a script that is named.
• tests/test_catalog_bundle_unreferenced.py: 73 pass; the 360-file timing case runs under its 30 s CPU bound. Self-review of the latest round: no blocking finding, nits recorded in the review.

Merge danger

Conflicts with the other PRs in this series on FINDING_CODES and the docs.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Named FIFO references can hang reviews, while substring matching misidentifies overlapping filenames, suppressing warnings and reading unintended documents.

2 open issues

• Reject named pipes before reading referenced files · New
• Use exact link matching to avoid filename substring collisions · New

What changed in this PR

2 new findings.

Adds bundle-file-unreferenced to catalog validation, warning when bundled scripts or documents are not named by SKILL.md or a document it references.

Changes:

• Implements case-insensitive reference matching, document traversal, and bundle exclusions.
• Integrates one warning per skill, with counts and example paths.
• Adds regression coverage and documents the new warning.

File	Description
dokimi/​tests/​test_content_checks.py	Updates expected standalone-review findings.
dokimi/​tests/​test_catalog_bundle_unreferenced.py	Tests references, exclusions, document traversal, and review scope.
dokimi/​dokimi/​external/​validate.py	Registers and emits the new warning.
dokimi/​dokimi/​external/​bundle_refs.py	Implements bundle scanning and reference detection.
dokimi/​docs/​external-content.md	Documents warning behavior and exclusions.
dokimi/​changelog.d/​20261109_160000_napetrov_bundle-file-unreferenced.md	Announces the warning and its ignore option.

_{Review effort: Balanced}

[exai-bot]

OpenCodeReview: Commit 00ae79b was not reviewed. This PR has reached its review limit (6 reviews).

CI at `00ae79b`: 11 still running, 5 passing, 1 skipped

Check	Status
Build docs (strict)	still running
CodeQL (actions)	still running
CodeQL (python)	still running
External catalog smoke test (uxlfoundation/skills)	still running
Linux Python 3.11	still running
Linux Python 3.14	still running
Linux Wheels Python 3.11	still running
Linux Wheels Python 3.14	still running
Static checks (ruff, schema, zizmor, licenses, pre-commit, bandit, secrets, changelog, schema com...	still running
benchmark	still running

1 more not listed.

To review this commit: re-request review from exai-bot in the Reviewers list.

<details><summary>Last review (cd26489): no findings</summary>

Open threads from the bot: 0

</details>

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 98.74214% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.74%. Comparing base (7137604) to head (00ae79b).

Files with missing lines	Patch %	Lines
dokimi/dokimi/external/bundle_refs.py	98.50%	2 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #559      +/-   ##
==========================================
+ Coverage   95.72%   95.74%   +0.01%     
==========================================
  Files         415      416       +1     
  Lines       55363    55522     +159     
  Branches     9516     9547      +31     
==========================================
+ Hits        52994    53157     +163     
+ Misses       1466     1464       -2     
+ Partials      903      901       -2     

Files with missing lines	Coverage Δ
dokimi/dokimi/external/validate.py	98.81% <100.00%> (+0.73%)	⬆️
dokimi/dokimi/external/bundle_refs.py	98.50% <98.50%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[vlad-perevezentsev]

Review at c72c3d3. The check works and the five earlier bot findings are fixed, but folder references are still matched too narrowly: a folder written with ./ or ${CLAUDE_SKILL_DIR}/ gives false warns. It also needs a rebase: it conflicts with current main in validate.py.

Agreed with @exai-bot: build.py.bak counts as naming build.py; a folder link in a nested document does not cover its files.

What I ran, at c72c3d3:

• make ci-local --offline: 17,916 passed, 0 failed, 72 skipped. One FAIL, schema_compat on arms.v1.json, comes from main moving since the base, not from this PR (it touches no schema).
• Repros of _named and unreferenced_message for folder prefixes, dotted suffixes, nested folder links and ${CLAUDE_SKILL_DIR} links in nested documents.

Checked, no issues

• Earlier fixes: the FIFO, whole-name, test-name, skipped-README and encoded-link fixes hold, each with a test.
• Docs and changelog: the new code is in FINDING_CODES, the docs and the module docstring; the fragment is under Added and says how to turn it off.

[napetrov]

Re: review by vlad-perevezentsev

folder references are matched too narrowly
Fixed in 4f58c73: ./, ../ and skill-dir folder forms name their files.

Fixed in 93200bc and cc078d5: ./, ../, skill-dir folder forms count.

[exai-bot]

placeholder

[napetrov]

This comment has only the word "placeholder", so there is no finding to act on. Please repost the finding if one was meant.

[napetrov]

Re: review by vchamarthi

6 new findings: 4 must-fix, 2 nits
Each has its own commit, named in its thread. Last one: a62b2ef.

[vlad-perevezentsev]

Review at e993313. My last point is settled: a9f441c lists the skip conditions in the docs, and I agree with keeping the read cap (replied in its thread). @vchamarthi's six line comments are fixed too.

Agreed with @vchamarthi on the search time: 1900 unnamed .py files and 50 named documents of 200 KB take 24.7 s CPU here. On a bare folder word (the scripts folder) I disagree: the docs define a folder mention with its slash, and the word alone is too common in prose to count. Counting .txt is the author's choice and the docs say so: many skills keep reference text in .txt.

What I ran, at e993313:

• make ci-local --offline: 19,004 passed, 0 failed, 72 skipped; every step passes.
• Repros of @vchamarthi's cases: a backslash folder, a folder link with a title and as a reference definition in a nested document, a hidden named document, and a nested document in a folder with capitals. Each gives the expected result, and a plain unnamed script still warns.
• The search time above, with a skill of 1900 scripts and 50 named 200 KB documents.

Checked, no issues

• Fixes: bb11659, 9e535a8, 446e43c, 5c5e3ae, 195fbf1 and e993313 each come with a test for its case.
• Backslash as a separator: links are decoded from the raw text, so a Markdown escape such as guide\_notes.md in a link still names its file.
• Merge: it merges cleanly into current main; once it is in, #454 conflicts with it in validate.py.

[vchamarthi]

Pushed 1 commit to feat/bundle-file-unreferenced (e993313..e002876).

• A folder os.walk cannot list withholds the claim.
• A folder written with a backslash in brackets ([helpers](scripts\)) is text, so it names its folder.
• A nested folder link with # or ? is dropped from the text like scripts/.
• A link to the skill root names every file.
  Run: the full suite with main merged in, 19221 passed.

[antonwolfy]

Review at 9bc964f. The earlier threads hold and the unreadable-document handling is sound, but the two newest rounds (the backslash separator and the root link) each open a false result. Two bugs inline, plus two nits.

What I ran, on a Linux review host at 9bc964f:

• make ci-local: 29 passed, 3 failed, 13 skipped; 19,064 tests; the changed-line coverage step passes. The three FAILs are not from the PR: Install gitleaks and Scan commits (a download that returned HTTP 504), and Run tests, where two tests in test_audit_test_quality.py, a file the PR does not touch, hit the 60 s timeout under load and pass alone (172 passed in 8.9 s).
• Reproductions for the code findings, with no model or network calls.
• A mutation run on bundle_refs.py: 112 mutants, 37 pass the full suite; most are equivalent or change only a message.

Test gaps (nit). These mutants pass all of test_catalog_bundle_unreferenced.py and test_catalog_validate_scripts.py, and each flips a warn on a realistic SKILL.md: _mentions checking only the first occurrence (i = -1 at bundle_refs.py:116; "Run rebuild.py and then build.py" with both bundled), the .- preceding set at :141 emptied (my-build.py names build.py), after == "-" removed at :113 (build.py-old), UnicodeDecodeError dropped from the except at :190 (a named non-UTF-8 document then ends in an unreadable row), the SKIPPED_DIRS clause at :75 (a non-test_* file in tests/ or Tests/), the suffix guard in _read_doc at :184 (a named .py is read as a document), and suffix.lower() at :83 (A.PY). One test case each would pin them.

Checked, no issues

• Unreadable documents: an oversize, non-UTF-8, symlinked or FIFO named document gives no claim, each guard killed by a test.
• Exclusions and registry: data, images, readme, AGENTS.md, _ helpers, tests, evals/, hidden and vendored folders and nested skills are left out as documented; bundle-file-unreferenced is in FINDING_CODES and --ignore bundle-file-unreferenced removes it; the changelog fragment is under Added.
• Repo rules: every non-merge commit has a Signed-off-by; the growth ratchet and docs tests pass; no schema or generated files in the diff.

Bot points I checked that no longer apply at this head (1)

• exai-bot's point on bundle_refs.py:49 does not apply: the comment holds only the word "placeholder", so it names no defect.

[antonwolfy]

A [back](../) link in a nested document names every bundled file. _target("references", "../") normalizes to ".", and this line reads "." in links as "the skill root is linked", which was meant for SKILL.md linking its own root.

Repro (SKILL.md: see references/g.md; references/g.md: [back](../); bundled scripts/run.py, named nowhere): unreferenced_message returns None. With [up](../) removed from the guide it returns 1 of 2 ... never named. A back-link at the end of a reference page is common, so it hides the warn for the whole skill.

Suggestion: treat "." as the root only for links from SKILL.md (pass linked for the root separately from the links of read documents), or only when the document's folder is ".". Add a test with a back-link in a nested document.

[napetrov]

Waiting on a decision before I change this: should a [back](../) link in a nested document name every bundled file? It does today, since ../ from references/ is the skill root. Options: (a) only a root link in SKILL.md names every file; (b) keep it, and the pinned test test_a_nested_link_to_the_skill_root_names_the_files_under_it stays. My recommendation: (a).

[antonwolfy]

Thanks for asking. Option (a): only a root link in SKILL.md names every bundled file; a root link in a nested document does not. Please change the pinned test test_a_nested_link_to_the_skill_root_names_the_files_under_it to match, and say in the docs and the changelog fragment that a root link in SKILL.md silences the check.

[napetrov]

Re: review by antonwolfy

Test gaps (nit): six mutants pass the suite
Fixed in 13f8a60: each has a test that fails on it.

[napetrov]

Re: comment by vchamarthi

Pushed 1 commit (e993313..e002876)
e002876 is not in this branch's history, and the PR head at setup was 9bc964f. The four items it lists are already on the head, so nothing to change.

[napetrov]

Re: review by vlad-perevezentsev

My last point is settled
No change: a bare folder word stays unnamed, as the docs say. The review has no open item.

[napetrov]

Round on 0d83bf9 (intel/main merged in de4a9b4):

• Fixed: FFOJ and FFOO, and the test-gap nit, in 13f8a60; self-review fixes in e92451c and 0d83bf9; path-missing test update in 3341461.
• Open, waiting on a decision: the nested ../ root link (FFOD). The question is in its thread.

[antonwolfy]

Review at 0d83bf9. The escape fix and the ${CLAUDE_SKILL_DIR}/ root-link fix both work, but my earlier point on the ../ back-link is still open, so I am not approving yet. Two nits inline.

What I ran, on a Linux review host at 0d83bf9:

• make ci-local: 32 passed, 1 failed, 14 skipped; 20,534 tests; changed-line coverage 98%. The one FAIL, the fidelity golden, ran every test to completion and then died in pytest's own temp-dir cleanup (ResourceWarning: unclosed scandir iterator); the installed Claude Code is also not the pinned one. The PR does not touch either.
• Reproductions for the escape reading (my\_script.py, a\*b.py, x\~y.py, Windows scripts\_helper.py, nested documents with .\ and ..\ prefixes) and for the root links, with no model or network calls.
• A mutation run on the two changed pieces: 22 mutants, 12 pass both changed test files; 6 of those are real gaps and the two inline nits cover them.

Still open from my earlier review:

• dokimi/dokimi/external/bundle_refs.py:141: a [back](../) link in a nested document still names every bundled file. At this head, SKILL.md = see references/g.md, references/g.md = [back](../), bundled scripts/run.py named nowhere: unreferenced_message returns None; with [back](./) in the guide it warns 1 of 2. Take option (a) from the thread: only a root link in SKILL.md names every file, and change the pinned test test_a_nested_link_to_the_skill_root_names_the_files_under_it. Whichever way it goes, the docs and the changelog fragment should say that a link to the skill root silences the check; neither does now.

Checked, no issues

• Escapes: my\_script.py, a\*b.py and x\~y.py name their files; scripts\_helper.py still names scripts/_helper.py; the joined two-reading text makes no match across the join and the control cases still warn.
• Root link: [home](${CLAUDE_SKILL_DIR}/) and the form without the slash now name the root like ./; the new tests fail against the previous head's validate.py.
• Repo rules: every non-merge commit has a Signed-off-by; bundle-file-unreferenced is in FINDING_CODES; the changelog fragment is under Added; validate.py is 786 of 800 lines in the growth ratchet; no generated files.

Bot points I checked that no longer apply at this head (1)

• exai-bot's point on bundle_refs.py:49 does not apply: the comment holds only the word "placeholder", so it names no defect.

[antonwolfy]

I pushed a commit per nit, up to 00ae79b, which fix the two nits from my review:

• a96b4d0: dokimi/tests/test_catalog_bundle_unreferenced.py:547: added the my\*script.py case to the escape parametrize list.
• 00ae79b: dokimi/tests/test_catalog_bundle_unreferenced.py:554: added the five root-link destinations (angle brackets, percent-encoding, backslash escape, #top, ?a=1) to the dest parametrize list.

make ci-local at 00ae79b: 33 passed, 0 failed, 14 skipped.

Not approving yet. Still open: the earlier thread of mine above nit level.