Repository navigation
refactor(skills): retire the context-manager scripts and align every Skill name with its directory - #17
Merged
Conversation
…e profile `find_context.py` claimed to rank context documents by relevance but scored only filenames and parent directory names, never document bodies — so a term that appears in the text, which is the normal case, scored zero. `README.md` was pinned to 0.7 and therefore always ranked first, and the 10% recency weight penalised exactly the stable, canonical documents most worth reading. Run against a real `context/` directory with matching keywords, the gap between the correct document and an unrelated one was 0.009. That is noise, not a ranking. `grep -ril` over document bodies is strictly more accurate, so SKILL.md now says to do that and the script is gone. `update_context.py` goes with it: the skill does not write documents on its own initiative, and the script's `mkdir` contradicted the instruction not to create the directory. `references/context_patterns.md` duplicated `static/CONTEXT.md` and cited project layouts that no longer exist. The skill leaves the `core` profile, which is defined in five places that had to agree: profiles.yml, install.sh (array and help text), install.ps1, and both READMEs. It stays installable on request and keeps its `managing-context` frontmatter name, the gerund convention e529d78 applied across the catalog. air-workbench's recognized-shape fixture is unchanged: the rewritten SKILL.md still imports as 4 nodes / 3 edges under `workflow.children`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`e529d78` renamed 22 Skills' `name` frontmatter to gerund phrases — `managing-vault-secrets` on `integrations/vault-secrets`, `auditing-security` on `security/security-auditor` — citing the official guidance on naming a Skill. The guidance is about choosing the Skill's name; it does not ask the declaration to disagree with the directory, and here it does. A host lists a Skill by its directory. `managing-vault-secrets` was therefore a second name nobody could type or invoke. It was not merely cosmetic either: air-workbench's catalog keys items on the frontmatter name, so the catalog and the host disagreed about what a Skill is called, and `catalog.test.mjs` had to assert `analyzing-business-model` for a directory named `bm-analyzer`. Renaming the directories to match the gerund names was the other way to close the gap, and it is worse: every published `--from jiunbae/agent-skills/<group>/<skill>` install path would break, along with the CHANGELOG's own history. The declaration moves instead. `tests/core.test.mjs` gains a guard that fails with the offending path on any future divergence; it was verified to fail by reintroducing one. The frozen `security-auditor` node ids move because a node id hashes the heading's byte offset and the frontmatter line is one byte shorter — titles and shape are unchanged. The playwright-based search fixtures keep testing a divergent name, which a Skill author can still write; their comments no longer claim the repository contains one. 354 → 355 tests pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The pointer added with the demotion omitted `-g`, so following it installs the skill into the current project instead of the user's global skill directory — the opposite of what a workspace-wide opt-in needs. Match the `agt` form the README already documents for `agents/air-workbench`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…inventory The release gate pins a per-file TAP plan so a suite cannot lose a test silently. Adding the Skill-naming guard moved core.test.mjs from 46 to 47, and the gate correctly refused the branch until the inventory agreed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two commits. The first was the original scope; the second closes a naming split
the first one surfaced.
1 —
context-managerloses its scripts and leavescore(e75ecc2)find_context.pypresented itself as a weighted relevance ranker. Measuredagainst a real
context/directory:The correct document beat an unrelated one by 0.009. The causes are structural:
score_keyword_matchlooks at the filename stemand the parent directory name only, so any term that lives in the text —
the normal case — scores zero.
README.mdis hardcoded to 0.7, so it always ranks first.90 days scores zero, penalising the stable, canonical procedures.
score_path_matchcompares code path segments against context categorynames; the vocabularies rarely intersect.
min_score=0.1is met by recency alone.grep -rilover document bodies is strictly more accurate, so SKILL.md nowsays that.
update_context.pygoes too — the skill does not write documents onits own initiative, and its
mkdircontradicted the instruction not to createthe directory.
references/context_patterns.md(524 lines) duplicatedstatic/CONTEXT.mdand cited layouts that no longer exist.The
coreprofile is defined in five places that had to stay in agreement:profiles.yml,install.sh(array + help text),install.ps1,README.md,README_ko.md. The skill stays infulland installable by path.2 — every Skill declares the name a reader types (
30d992a)e529d78renamed 22 Skills'namefrontmatter to gerund phrases. A host listsa Skill by its directory, so
managing-vault-secretsonintegrations/vault-secretswas a second name nobody could type.Not cosmetic: air-workbench's catalog keys items on the frontmatter name, so the
catalog and the host disagreed about what a Skill is called —
catalog.test.mjsasserted
analyzing-business-modelfor a directory namedbm-analyzer.Renaming the directories was the alternative and is worse: it breaks every
published
--from jiunbae/agent-skills/<group>/<skill>path and the CHANGELOG'sown history. So the declaration moved, in 22 one-line edits.
tests/core.test.mjsgains a guard that fails with the offending path on anyfuture divergence — verified by reintroducing a mismatch and watching it fail.
The rule is documented in both READMEs.
Test fallout, explained
security-auditornode ids changed. A node id hashes the heading'sbyte offset; the frontmatter line is one byte shorter. Titles and graph shape
are unchanged — recomputed and updated.
name, which an author can still write. Only their comments changed: they no
longer claim the repository contains such a Skill.
Verification
bash -n install.sh;--helplists the 7 remaining core skills.🤖 Generated with Claude Code