Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
62 commits
Select commit Hold shift + click to select a range
0afe66d
feat(catalog): bundle-file-unreferenced, one warn per skill for bundl…
napetrov Nov 9, 2026
61e3a52
fix(catalog): bundle-file-unreferenced does not open a named pipe
napetrov Nov 10, 2026
fbbda30
fix(catalog): a file name inside a longer name does not name the shor…
napetrov Nov 10, 2026
b21da2d
fix(catalog): test files outside a tests folder are not counted
napetrov Nov 10, 2026
c0c1d26
fix(catalog): a skipped document that SKILL.md names is still read
napetrov Nov 10, 2026
c72c3d3
fix(catalog): decode the links of a read document as SKILL.md's are
napetrov Nov 10, 2026
3e67f8f
Merge main into the PR branch, resolving validate.py
napetrov Nov 10, 2026
f81f2ed
Address review: a name followed by a dotted suffix does not name the …
napetrov Nov 10, 2026
93200bc
Address review: a folder written from the skill root names its files
napetrov Nov 10, 2026
4f010b9
Address review: a folder linked from a nested document names only its…
napetrov Nov 10, 2026
cc078d5
Address review: a skill-dir link in a nested document resolves from t…
napetrov Nov 10, 2026
9c7434d
Address review: a bundle over the file cap is a checkout and is not c…
napetrov Nov 10, 2026
7a803a0
bundle-file-unreferenced: a folder at the end of a sentence names its…
napetrov Nov 10, 2026
4f58c73
Thread: PRR_kwDOVBg7g88AAAABXBtM2g: already fixed in 93200bc35 and cc…
napetrov Nov 10, 2026
ada9d8b
Merge branch 'main' of https://github.com/intel/dokimi into HEAD
napetrov Nov 11, 2026
d10c819
bundle-file-unreferenced: a truncated walk or a named document past t…
napetrov Nov 11, 2026
ea94ed7
bundle-file-unreferenced: a plain folder mention in a nested document…
napetrov Nov 11, 2026
c3be91e
bundle-file-unreferenced: the document search is its own function
napetrov Nov 11, 2026
bcf6e35
Move the path prefix comment above _PATH_PREFIX
antonwolfy Nov 11, 2026
cd26489
List every bundle-file-unreferenced exclusion in the docs
antonwolfy Nov 11, 2026
e6ab3e8
Merge branch 'main' of https://github.com/intel/dokimi into pr-addres…
napetrov Nov 11, 2026
a41af7c
Count named documents in test folders; no claim on unreadable ones
napetrov Nov 11, 2026
2d1777b
Time only the bundle search in the timing test, in CPU time
napetrov Nov 11, 2026
72b0970
Merge branch 'main' of https://github.com/intel/dokimi into pr-addres…
napetrov Nov 12, 2026
a9f441c
Address review: list the skip conditions of the bundle check
napetrov Nov 12, 2026
d51328d
Name the bundled files in the script tests' SKILL.md
napetrov Nov 12, 2026
d174325
Thread: PRR_kwDOVBg7g88AAAABXhnXZg: already fixed in a9f441ceb1
napetrov Nov 12, 2026
86a92f3
Merge branch 'main' of https://github.com/intel/dokimi into pr-addres…
napetrov Nov 13, 2026
446e43c
Address review: a document named by a hidden file name is read
napetrov Nov 13, 2026
5c5e3ae
Address review: pin the read-cap guard on named documents
napetrov Nov 13, 2026
0eb6759
Address review: a folder written with a backslash names its files
napetrov Nov 13, 2026
503c9e4
Address review: a folder link with a title or brackets names its folder
napetrov Nov 13, 2026
195fbf1
Address review: the bundle walk lists its files in path order
napetrov Nov 13, 2026
a62b2ef
Address review: drop the scratch corpus figures from the module docst…
napetrov Nov 13, 2026
5228ca2
Thread: PRRT_kwDOVBg7g862mN3b: already fixed in a9f441ceb1
napetrov Nov 13, 2026
bb11659
Address review: a backslash folder in a nested document names its own…
napetrov Nov 13, 2026
9e535a8
Address review: a reference definition with a title names its folder
napetrov Nov 13, 2026
8bc0f18
Merge branch 'main' of https://github.com/intel/dokimi into pr-addres…
napetrov Nov 13, 2026
e993313
Address self-review: a nested document in a folder with capitals name…
napetrov Nov 13, 2026
9bc964f
fix(catalog): bundle-file-unreferenced reads backslash and fragment f…
vchamarthi Nov 13, 2026
de4a9b4
Merge branch 'main' of https://github.com/intel/dokimi into feat/bund…
napetrov Nov 14, 2026
13f8a60
Address review: escapes, a skill-dir root link, and edge pins
napetrov Nov 14, 2026
e92451c
Address self-review: pin the separator reading with a name that can c…
napetrov Nov 14, 2026
3341461
Address test run: path-missing spans also get the unreferenced warning
napetrov Nov 14, 2026
0d83bf9
Address self-review: name the Windows-path test for the tilde it pins
napetrov Nov 14, 2026
a96b4d0
Pin the escaped asterisk in the bundle-file-unreferenced test
antonwolfy Nov 14, 2026
00ae79b
Pin the decoding of a skill-root link in the unreferenced test
antonwolfy Nov 14, 2026
2250924
Merge branch 'main' of https://github.com/intel/dokimi into feat/bund…
napetrov Nov 15, 2026
7994848
Address review: only a root link in SKILL.md names every bundled file
napetrov Nov 15, 2026
5f8e805
Address review: record the test nits the reviewer pushed
napetrov Nov 15, 2026
f8b3f62
Test the variable back link in a nested document; reword the comment
napetrov Nov 15, 2026
c228b31
Test a root link from a document beside SKILL.md; match the docs to it
napetrov Nov 15, 2026
2ffea56
Merge branch 'main' of https://github.com/intel/dokimi into HEAD
napetrov Nov 16, 2026
bb0a616
Address review: ../ above the skill root names nothing; names looked …
napetrov Nov 16, 2026
d573ad3
Say when the bundled-file check does not count
napetrov Nov 16, 2026
f406fa9
Read a backslash before a space or ';' as an escape too
napetrov Nov 16, 2026
67db2f6
Merge intel/main into feat/bundle-file-unreferenced
napetrov Nov 16, 2026
298dd14
Address review: a named document is read up to 1 MiB, and a truncated…
napetrov Nov 16, 2026
e3f793e
Keep validate.py under the file-length cap: move the link-file helpers
napetrov Nov 16, 2026
436f90f
Merge intel/main into feat/bundle-file-unreferenced
napetrov Nov 16, 2026
92af3d7
Thread: PRRT_kwDOVBg7g864HSqA: already fixed in e3f793ea8
napetrov Nov 16, 2026
696225a
Say in the changelog that a skill-root link silences the check
antonwolfy Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
### Added

- **`catalog check` counts bundled files the skill never names.** A script or document next to `SKILL.md` that neither `SKILL.md` nor a document it names mentions (by path, file name or folder, case ignored) is counted in one new `warn` per skill, `bundle-file-unreferenced`, with the count and the first three paths. Data, images, licence and readme files, `_`-prefixed helpers, tests and vendored folders are not counted. A link to the skill root in `SKILL.md` (`./` or `${CLAUDE_SKILL_DIR}/`) names every file, so it silences the check. Leave the code out with `--ignore bundle-file-unreferenced`.
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
### Added

- **`catalog check` says when it does not count bundled files.** When the search cannot see every name (over 2000 files, more than 50 named documents, a named document over 1 MiB (the note names it as truncated), not UTF-8, a symlink or a FIFO, or a folder that cannot be listed), `bundle-file-unreferenced` gives no count, as before, and a new `note`, `bundle-file-unchecked`, gives the reason. Leave the note out with `--ignore bundle-file-unchecked`.
9 changes: 8 additions & 1 deletion dokimi/docs/external-content.md
Original file line number Diff line number Diff line change
Expand Up @@ -269,7 +269,14 @@ Spanish, French, German, Portuguese, Russian, Chinese, Japanese and Korean, and
of them covers (Arabic, Thai, Hebrew, …) is not checked: it gets a `note` (`description-when-not-checked`), so not checked does not read as a pass: its row says `note:` instead of `ok`, and the counts line `1 ok (1 not checked)`. A Latin-script language without a list of its own
(Polish, Dutch, Turkish, Vietnamese) is checked against these cues. Two skills in different paths with the same
directory name and description but different `SKILL.md` text are a `warn` on both
(`mirror-drift`), naming the other copies. Skills with
(`mirror-drift`), naming the other copies. A bundled script or document (`.py`, `.sh`, `.js`,
`.ts`, `.md`, `.txt` and similar) that neither `SKILL.md` nor a document it names ever names, by
path, file name or folder, is counted in one `warn` per skill (`bundle-file-unreferenced`): the agent
finds it only by browsing. Only a link to the skill root in `SKILL.md` (`./`, or `${CLAUDE_SKILL_DIR}/`) names every file; a link to the root from any other document names only its target. Data, images, licence, readme, changelog and `AGENTS.md`-style files,
`_`-prefixed helpers, tests and `evals/` folders, hidden and vendored folders, and nested skills are
not counted, nor is a skill at the root of the scanned checkout. The check then gives no count and no `warn`; it gives a
`note` (`bundle-file-unchecked`) that says why, when the search cannot see every name: a bundle over 2000 files, more than 50 named
documents to read, a named document over 1 MiB (truncated: the note names the file, and its names are not read), not UTF-8, a symlink or a FIFO, a folder that cannot be listed. Skills with
`disable-model-invocation: true` are exempt from the description checks.

The scan also reads the scripts a skill bundles: each `.sh`, `.bash` and `.py` file, and each file that
Expand Down
368 changes: 368 additions & 0 deletions dokimi/dokimi/external/bundle_refs.py

Large diffs are not rendered by default.

94 changes: 94 additions & 0 deletions dokimi/dokimi/external/link_files.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# Copyright (C) 2026 Intel Corporation
# SPDX-License-Identifier: Apache-2.0

"""The file a Markdown link or code span names inside a skill: :func:`_file_ref`, :func:`_link_files`.

Kept apart from :mod:`dokimi.external.validate`, which these were moved out of to stay under the
file-length cap (``scripts/growth_baseline.json``).
"""

from __future__ import annotations

import re
from typing import Optional
from urllib.parse import unquote

from .bundle_paths import LOCATION_SUFFIX_RE, SKILL_DIR_VAR
from .skill_markdown import link_pieces, outside_fences


# A backslash before ASCII punctuation is an escape in a link destination (``guide\_notes.md``).
_ESCAPE_RE = re.compile(r"\\([!-/:-@\[-`{-~])")
# RFC 3986 scheme, dots included; a dotted one with a line or symbol after it is a file (_file_ref).
URI_SCHEME_RE = re.compile(r"[A-Za-z][A-Za-z0-9+\-.]*:")
# After a file, a line or a symbol (``run.py:42``, ``run.py:10-20``, ``run.py:main``): read as the file's name.
FILE_SUFFIX_RE = re.compile(r"\d+(?:[-:]\d+)?|[A-Za-z_]\w*")


def _link_files(markdown: str) -> list[Optional[str]]:
"""The file each Markdown link of ``markdown`` names (see :func:`_file_ref`), None for a link that names none.

A link through ``${CLAUDE_SKILL_DIR}/`` keeps that prefix: it is from the skill root, not from the
folder of the document it is in (:func:`bundle_refs._target` resolves it).
"""
files: list[Optional[str]] = []
for raw in link_pieces(outside_fences(markdown))[0]:
ref = _file_ref(raw, link=True)
if ref is not None and _through_skill_dir(raw):
ref = SKILL_DIR_VAR + ref
elif _is_skill_dir_root(raw): # ``${CLAUDE_SKILL_DIR}/`` alone names the skill root, as ``./`` does
ref = SKILL_DIR_VAR
files.append(ref)
return files


def _is_skill_dir_root(raw: str) -> bool:
"""Whether a link destination is the skill root through the variable, with or without its slash."""
text = raw.strip()
if text.startswith("<") and text.endswith(">"):
text = text[1:-1].strip()
text = unquote(_ESCAPE_RE.sub(r"\1", text)).split("#", 1)[0].split("?", 1)[0].strip()
return text in (SKILL_DIR_VAR, SKILL_DIR_VAR.rstrip("/"))


def _through_skill_dir(raw: str) -> bool:
"""Whether a link destination starts with ``${CLAUDE_SKILL_DIR}/`` (decoded as :func:`_file_ref` decodes it)."""
text = raw.strip()
if text.startswith("<") and text.endswith(">"):
text = text[1:-1].strip()
return unquote(_ESCAPE_RE.sub(r"\1", text)).startswith(SKILL_DIR_VAR)


def _file_ref(raw: str, link: bool = False) -> Optional[str]:
"""The skill-relative file a reference names, or None if it names no file to check.

None for a URL or any other URI (``tel:``, ``urn:``, ``MAILTO:``), a bare anchor, an
absolute path, a placeholder (``URL``, ``TBD``, ``...``), or a template variable (not ``${CLAUDE_SKILL_DIR}``). A
``<...>`` destination (CommonMark) is read as the path inside the brackets. A link
destination (``link``) is a URL: its ``#fragment`` and ``?query`` are not part of the path,
its backslash escapes of ASCII punctuation (``guide\\_notes.md``) are decoded, and its
percent-encoded bytes name the file (``guide%20notes.md``). A code span is literal: a ``#``
or a ``%`` in it is in the file's name.
"""
text = raw.strip()
if text.startswith("<") and text.endswith(">"):
text = text[1:-1].strip()
if link:
text = _ESCAPE_RE.sub(r"\1", text)
text = text.split("#", 1)[0].split("?", 1)[0].strip()
text = unquote(text)
if not text or "://" in text or text.startswith("/"):
return None
scheme = URI_SCHEME_RE.match(text)
if scheme and not ("." in scheme.group() and FILE_SUFFIX_RE.fullmatch(text[scheme.end() :])):
return None
text = LOCATION_SUFFIX_RE.sub("", text) # the file is named before its line or symbol suffix
if not text or text.lower() in {"url", "link", "path", "uri", "href", "todo", "tbd", "..."}: # a stand-in
return None
if text.startswith(SKILL_DIR_VAR):
text = text[len(SKILL_DIR_VAR) :]
if not text:
return None
if any(c in text for c in "${}<>*"):
return None
return text
58 changes: 15 additions & 43 deletions dokimi/dokimi/external/validate.py
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,9 @@
not have is ``path-missing`` (see :mod:`dokimi.external.bundle_paths`). Other code spans, and code
fences, are not checked: those are usually examples or paths in the user's own project.

Bundled scripts and documents that ``SKILL.md`` never names are one ``warn`` per skill
(``bundle-file-unreferenced``, see :mod:`dokimi.external.bundle_refs`).

Descriptions: one with no "when" clause is a ``warn`` (``description-no-when``); the cues are
English, Spanish, French, German, Portuguese, Russian, Chinese, Japanese and Korean (``when_cues.WHEN_CUES``),
and a description in a script none covers is not checked: it gets a ``note`` (``description-when-not-checked``). One whose tokens overlap another skill's at a
Expand All @@ -81,15 +84,16 @@
from dataclasses import dataclass, field
from pathlib import Path, PurePosixPath
from typing import Iterable, Optional, Sequence
from urllib.parse import unquote

import yaml

from dokimi.skills import Skill
from dokimi.utils import describe_yaml_error, parse_frontmatter_strict

from .bundle_paths import LOCATION_SUFFIX_RE, SKILL_DIR_VAR, path_missing
from .bundle_paths import path_missing
from .link_files import _file_ref, _link_files
from .catalog import SkillCatalogEntry, _within
from .bundle_refs import unreferenced_check
from .command_checks import command_findings
from .allowed_tools import RISKY_COMMAND_CODES, tool_names, grants_unrestricted_bash, unrestricted_bash_message
from .content_checks import content_findings
Expand Down Expand Up @@ -138,19 +142,15 @@
should must may might if else only other such via per about over under more most very
just""".split()
)
# A backslash before ASCII punctuation is an escape in a link destination (``guide\_notes.md``).
_ESCAPE_RE = re.compile(r"\\([!-/:-@\[-`{-~])")
# RFC 3986 scheme, dots included; a dotted one with a line or symbol after it is a file (_file_ref).
URI_SCHEME_RE = re.compile(r"[A-Za-z][A-Za-z0-9+\-.]*:")
# After a file, a line or a symbol (``run.py:42``, ``run.py:10-20``, ``run.py:main``): read as the file's name.
FILE_SUFFIX_RE = re.compile(r"\d+(?:[-:]\d+)?|[A-Za-z_]\w*")

# Every code a review can report: ``catalog check --ignore`` accepts these and no others.
# tests/test_catalog_ignore.py reads the emitted codes from the source and fails on any missing here.
FINDING_CODES = (
"allowed-tools-unknown",
"allowed-tools-unrestricted-bash",
"body-too-large",
"bundle-file-unchecked",
"bundle-file-unreferenced",
"description-near-duplicate",
"description-no-when",
"description-too-long",
Expand Down Expand Up @@ -453,41 +453,6 @@ def _counterpart(other: tuple[SkillCatalogEntry, Skill, SkillReview], entry: Ski
return f"{where} in {o_entry.source_root.as_posix()}"


def _file_ref(raw: str, link: bool = False) -> Optional[str]:
"""The skill-relative file a reference names, or None if it names no file to check.

None for a URL or any other URI (``tel:``, ``urn:``, ``MAILTO:``), a bare anchor, an
absolute path, a placeholder (``URL``, ``TBD``, ``...``), or a template variable (not ``${CLAUDE_SKILL_DIR}``). A
``<...>`` destination (CommonMark) is read as the path inside the brackets. A link
destination (``link``) is a URL: its ``#fragment`` and ``?query`` are not part of the path,
its backslash escapes of ASCII punctuation (``guide\\_notes.md``) are decoded, and its
percent-encoded bytes name the file (``guide%20notes.md``). A code span is literal: a ``#``
or a ``%`` in it is in the file's name.
"""
text = raw.strip()
if text.startswith("<") and text.endswith(">"):
text = text[1:-1].strip()
if link:
text = _ESCAPE_RE.sub(r"\1", text)
text = text.split("#", 1)[0].split("?", 1)[0].strip()
text = unquote(text)
if not text or "://" in text or text.startswith("/"):
return None
scheme = URI_SCHEME_RE.match(text)
if scheme and not ("." in scheme.group() and FILE_SUFFIX_RE.fullmatch(text[scheme.end() :])):
return None
text = LOCATION_SUFFIX_RE.sub("", text) # the file is named before its line or symbol suffix
if not text or text.lower() in {"url", "link", "path", "uri", "href", "todo", "tbd", "..."}: # a stand-in
return None
if text.startswith(SKILL_DIR_VAR):
text = text[len(SKILL_DIR_VAR) :]
if not text:
return None
if any(c in text for c in "${}<>*"):
return None
return text


def _link_finding(raw: str, skill_dir: Path, source_root: Path, real_dir: Path) -> Optional[Finding]:
"""The finding for one link destination (inline or reference), or None when it is fine."""
text = _file_ref(raw, link=True)
Expand Down Expand Up @@ -738,6 +703,13 @@ def review_skills(
Finding("warn", code, message)
for code, message in content_findings(skill, at_root=at_root and not standalone)
]
unreferenced, unchecked = unreferenced_check(
skill.path, _link_files(skill.body), at_root=at_root and not standalone, doc_links=_link_files
)
if unreferenced is not None:
review.findings.append(Finding("warn", "bundle-file-unreferenced", unreferenced))
if unchecked is not None:
review.findings.append(Finding("note", "bundle-file-unchecked", unchecked))
review.findings += [Finding(*item) for item in script_findings(
skill.path.parent, checkout=None if standalone else entry.source_root)]
if not hidden:
Expand Down
Loading
Loading