cd /news/ai-agents/attempts-to-improve-skill-discovery-… · home › topics › ai-agents › article
[ARTICLE · art-171805] src=github.com ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

Attempts to improve skill discovery in Claude Code

A single paragraph added to Claude Code's CLAUDE.md standing-instructions file raised the rate at which Claude opened the skill a task needed from 2 of 58 tasks to 47 of 58 on Haiku and from 7 of 58 to 40 of 58 on Sonnet, according to tests by developer ydmitry published on ydmitry.github.io. The paragraph instructs Claude to search its skills before writing code, a plan or a review, using either the author's skill-finder script or a plain grep over ~/.claude/skills, and to repeat the lookup after each file it reads; the two methods performed about equally well in the 897-skill test setup. The author notes the results come from test tasks rather than real work, and that a ten-task sample on Opus followed the same pattern.

recommendation

Add a CLAUDE.md instruction telling the agent to grep skill files for two-to-three-word phrases before starting work and to re-run the lookup after each file it reads; this raised skill discovery from 2/58 to 47/58 tasks on Haiku.

more in playbook: Designing agent systems
read51 min views6 publishedNov 18, 2026
Attempts to improve skill discovery in Claude Code
Image: Michielbdejong (auto-discovered)

The same text as a page: ydmitry.github.io/skill-finder.

When using skills in Claude Code, I was concerned about the following things:

  • Mostly I needed to explicitly say which skill to use.
  • If in the middle of a session some skill appears to be useful, will it be auto-invoked?
  • If I need a specific reference, will it be added to the context?
  • Is the description enough for the LLM to decide if a skill needs to be used?
  • Also, what about skills with a badly written description, or skills too broad to describe with only one description?

So that's why I decided to write a skill which helps with finding the needed skills: skill-finder. It appeared that the secret is in the CLAUDE.md instruction, and skill-finder itself can be replaced with grep.

Claude Code rarely reads the skill a task needs unless it is told to look. In my tests it opened the needed skill in 2 of 58 tasks on Haiku and 7 of 58 on Sonnet. One paragraph in CLAUDE.md, the file of standing instructions Claude Code reads in every session, changed that to 47 and 40. A ten-task sample on Opus went the same way.

The paragraph tells Claude to search its skills first, with my script skill-finder ("the finder") or with a plain grep. Both did about equally well. These are test tasks, not real work. Jump to the instruction.

  • With many skills, Claude gets only their names and short descriptions, and rarely opens the right one. I tested with 897 skills, not with a few dozen.
  • When a team keeps its conventions in skills, Claude cannot follow a rule it has not read.
  • When a task needs a second skill that nobody could name at the start. For example, a review opens a file, and the file touches something that has its own rules.

Put this in ~/.claude/CLAUDE.md or in a project's CLAUDE.md. Get the script first: git clone https://github.com/ydmitry/skill-finder ~/.claude/skills/skill-finder.

## Skills
Before you write code, a plan, a review or any other piece of work, look the skills up. First read the request and every file it names. List what appears in them: the things, activities, materials and technologies, and what the finished thing is called. Look all of them up in one plain command (no loop, no variable), one --phrase for each, two or three words in order. Run it as a command of its own, not joined to other commands:
  python3 ~/.claude/skills/skill-finder/scripts/find_skills.py --phrase "<a name>" --phrase "<another name>"
It lists the skills and the reference files that hold a phrase. Read every listed skill that fits to the end, and every listed reference file that fits, and the reference files in a skill's folder that fit, before writing anything. Follow what they say. Nothing listed that fits means proceed without a skill. Skip for one-line answers and when the task names its skills.
The lookup is not one step. After you read a skill or a reference file, look up, the same way, every thing, area or kind of data it mentions that your earlier lookups did not cover. Do this before you write, and again after each new file you read. If a lookup lists nothing that fits, try other words.

The last paragraph tells Claude to look up again after each file it reads. I call it look-again below.

The grep version, without the finder #

The same instruction with grep. I tested a close version of it, not this exact text.

## Skills
Before you write code, a plan, a review or any other piece of work, look the skills up. First read the request and every file it names. List what appears in them: the things, activities, materials and technologies, and what the finished thing is called. Look all of them up in one plain command (no loop, no variable), one -e for each, two or three words in order. Run it as a command of its own, not joined to other commands:
  grep -Ril --include=SKILL.md -e "<a name>" -e "<another name>" ~/.claude/skills
It lists the skill files that hold a phrase. Read every listed skill that fits to the end, and the reference files in its folder that fit, before writing anything. Follow what they say. Nothing listed that fits means proceed without a skill. Skip for one-line answers and when the task names its skills.
The lookup is not one step. After you read a skill or a reference file, look up, the same way, every thing, area or kind of data it mentions that your earlier lookups did not cover. Do this before you write, and again after each new file you read. If a lookup lists nothing that fits, try other words.

Add your other skill folders to the command. On macOS add -S if they are symlinks.

I used two suites and three Claude models: Haiku (small), Sonnet (mid-size) and Opus (the largest).

The first suite is about local rules. It has twelve skills written for the test, for an imaginary team, hidden among 897 public skills. Each skill holds made-up rules with an ID, which Claude cannot guess. For example, rule API-14 says the URL of an endpoint for a partner must start with /px/. Each of 24 tasks, a plan or a review, needs three rules from three skills. Each task ran twice, which gives 144 chances to follow a rule. A rule counts as followed when its ID appears in the answer.

The second suite is 58 tasks from Skill-Use-Bench (arXiv 2608.04828), each with a skill its authors say it needs. "Opened" means the skill's text reached Claude. These are not the benchmark's official scores.

Haiku and Sonnet ran everything. Opus ran ten tasks from each suite, because it costs more.

Before each comparison I wrote down a pass rule. Here it was a gap of 15 percentage points, with one setup ahead in clearly more tasks than the other. "Not shown" below means the rule was not met.

Each benchmark task ran once and each local-rules task twice, and two runs of the same setup differed by 2 to 5 tasks, so small gaps mean little. An answer can also cite a rule's ID without applying the rule.

The test harness and the run records are not published: they hold copies of other people's skills and of the benchmark's tasks.

With no instruction Claude almost never found the skill. With the instruction it found most of them. That met the pass rule on both suites, for each of the three models.

The finished work improved a little, though the evidence is thin. 21 of the benchmark tasks come with checks on the finished files, and each ran once. The average task passed 63% of them on Haiku (51% without the instruction) and 64% on Sonnet (49% without).

Earlier, on Sonnet and the local rules, I tested older wordings of the instruction, one of them with no lookup command. Those are separate runs, so do not compare them with the numbers above.

Telling Claude to check its skills, with no command, scored 75 of 144. A lookup step scored 78, and 101 with look-again. None of the gaps among the three met that test's pass rule, which was 30 points.

A later test of look-again alone gave 182 rules followed with it and 144 without, of 216 (three runs a task). I wrote that test's pass rule after I had seen earlier results, so I treat the gain as likely and not as settled.

One of each local-rules task's three rules is "chained". The only pointer to its skill is a sentence inside the first skill Claude reads, so Claude has to look up again in the middle of the task.

With no instruction Claude followed no chained rule, because it never opened the first skill. With it, Claude followed the chained rule in 21 of 48 runs on Haiku, 35 of 48 on Sonnet and 8 of 10 on Opus.

A second lookup does not always find the skill. Haiku looked up again most often and followed the fewest chained rules. Every run also had the look-again paragraph, so this does not show that the look-again paragraph is the cause.

This is a separate small test of plain Claude Code, with no instruction and no finder. Eight made-up skills sat in a list of 20. Each had an obvious trigger, for example a colour being mentioned. I changed only the wording of the description.

When the request itself named the trigger, Sonnet used the skill in 8 of 8 runs with every wording. When the trigger showed up only during the work, the wording decided: 14 of 15 with "Use ALWAYS, every time, when ...", 7 of 15 with "Use when ...", and 3 of 13 with "Rules for X."

Haiku was weaker mid-task with any wording: 8 of 24 with ALWAYS, 0 of 23 with "Rules for X.", and 1 of 24 when the list grew to 200 skills. Over all its mid-task runs with ALWAYS it used the skill in 19 of 47.

So a description that insists works for Sonnet with a short list. You can only write it that way for skills that are yours.

Two of the questions at the top I tested only earlier: on Sonnet and Haiku, with an older wording of the instruction and 20 made-up skills. There were three setups: no instruction ("plain"), an instruction to check the skills with no command ("told"), and the same instruction with the finder. I have not rerun these with the current instruction.

It depends on how SKILL.md points to the file.

When SKILL.md names the file and says when to read it, Claude reads it, even with no instruction. When SKILL.md only says that more files exist, or says nothing, plain Claude stops at SKILL.md: 0 of 18 both times. Told to check the skills, it read a file that nothing mentions in 4 of 18 cases. The finder lists the files that hold the searched words, and reached 18 of 18. Haiku gave the same picture (0, 6 and 15 of 18 for a file that is not mentioned).

In 16 cases the rule sat in a skill about another topic. Neither the skill's name nor its description pointed to it; only the rule's own words matched the task.

Judging by descriptions never reached these rules: no skill was opened. A search by the rule's words did. A harder rerun on Sonnet, with long skills, gave 0 of 20 for the told setup and 20 of 20 for the finder, or 15 of 20 when the reference files had names that say nothing. I did not run grep in these tests.

I ran the same instruction with grep in place of the finder.

No gap came near the pass rule on Haiku or Sonnet. The Opus sample was level too: 24 against 22 of 30 rules, and 9 against 9 of 10 benchmark tasks. Both suites suit grep: the folder held only skills, and their names say what they hold.

I use the finder because one command covers every skill folder and also lists the other files in a skill's folder. These tests do not show it opening more skills than grep.

Installing the finder as a skill, without the instruction, did nothing. Haiku never called it.

Add the instruction. If you would rather install nothing, use the grep version.

Maybe someone in your org already wrote a skill for this.

Your company keeps Claude Code skills in a few repos or plugin marketplaces, or you added a marketplace once and forgot what is in it. You haven't read them all, and you won't install them all. But for the task in front of you, one may already exist. skill-finder searches every skill on your machine (installed, disabled, or never installed but shipped inside a marketplace Claude Code cloned) plus any skill repo you have cloned and listed in scripts/roots. It lists the skills that contain the words Claude looks up, in their SKILL.md or in their reference files, each with its path and the line that matched. Claude can then read the one that fits, or you can copy it into a folder you start a fresh session in. It never edits settings.json; beyond the folder you clone, the only change to your setup is the CLAUDE.md lines you add.

What the tests show: with the CLAUDE.md block, Sonnet runs the finder and opens skills it could not otherwise see (one in 44 of 50 runs, against none in 30 runs without the block; ten requests, the first turn only); Haiku, on the same requests, mostly answered without running it. What they do not show: that the finished work is better. In my own sessions in the nine days after I added the block, the finder ran in 6 of 26, and in 2 of them a skill it listed was invoked or its SKILL.md read afterwards. The tests are under Does it work?.

Why not just enable them? Enable the plugins you know you need. Claude Code gives its skill list a budget of 1% of the context window and, past that, drops the descriptions of the skills you invoke least, keeping their names; a 200-skill Haiku test could not measure any harm from that. The finder is for the skills you cannot enable without first finding them: in a marketplace you added but never installed, in a team or public repo you cloned, or in a plugin you turned off.

The CLAUDE.md block below (about 345 tokens in every session) has Claude look the skills up before it writes code, a plan or a review. A lookup lists at most 10 skills whose SKILL.md holds the phrase (and up to 5 that hold it only in reference files), each with its description and the line that matched: in my tests about 3,800 characters in the median, up to about 8,800. Claude can read most skills from their files without enabling them; whether it then follows one as well as an enabled skill is not measured.

Claude will not reach for the finder by itself, so it comes with a short instruction for your CLAUDE.md (below). It pays off most for skills Claude cannot see; for skills Claude already lists, the tests found little gain, except for a second need that shows only in the files (the optional Second lookups section below).

$ python3 scripts/find_skills.py --phrase "release notes" --only tests/fixtures/skills
phrase search: "release notes" in the SKILL.md and reference files of 18 skills on disk (a phrase starts a word: 'plan' matches 'planning', not 'airplane')
1 skill(s) contain it. Best first: the phrase in the name, then in the description, then how often it occurs.

1. release-notes  [folder skill]  tests/fixtures/skills/release-notes/SKILL.md
   Draft release notes and changelog entries from merged pull requests.
   :6: # release-notes

Best match: release-notes  tests/fixtures/skills/release-notes/SKILL.md
Why: "release notes" is in its name and its description and 3 times in SKILL.md (line 6: "# release-notes")
Description: Draft release notes and changelog entries from merged pull requests.
First lines of SKILL.md:

  Group by change type.
Read tests/fixtures/skills/release-notes/SKILL.md to the end, then follow it; search again only if it does not fit.

That is the repo's test fixtures. On your machine each hit shows its state, such as user skill, project skill, plugin enabled, plugin DISABLED, plugin installed for <project> only (installed for other repos or folders, so it does not load here), plugin cached, other version (another version left in the cache; Claude Code loads the installed one), marketplace only, not installed, or extra root (a folder you added, which Claude Code itself does not load). The states come from the install records and the settings a session started in the current folder reads: your settings.json, then that folder's .claude/settings.json, then settings.local.json there and at its git repo root (for a linked worktree, the main checkout's root, so an entry the /skills menu saved there reaches the worktree). A folder whose own settings enable a plugin gets it, even one installed only for another project. A user or project skill that skillOverrides in those files hides or shortens (an entry under its folder name, not its frontmatter name) says so: user skill, off in settings (hidden from Claude and from the / menu), user skill, user-invocable only in settings (in your / menu, hidden from Claude) or user skill, name only in settings (Claude gets its name without the description), and project skill, ... alike; plugin skills are not affected. That holds for the config dir a session uses ($CLAUDE_CONFIG_DIR, else ~/.claude); when the finder scans both, the other one is labelled by its own settings.json (an old version's copy still reads plugin cached, other version), and where both hold the same skill the copy shown is the one in use. The labels can still disagree with a live session. A skill Claude Code does not load can be read from its path, or copied with --enable NAME --into DIR into DIR/.claude/skills, so a session started in DIR can invoke it (a plugin skill whose scripts use CLAUDE_PLUGIN_ROOT may not work from the copy; the finder warns). The copy is a project skill in a folder of the skill's bare name, so skillOverrides set to off or user-invocable-only for that folder name in the files a session started in DIR reads (the ones above) keeps Claude from invoking it, and a user skill in a folder of that name runs instead of it (personal beats project); the finder warns in both cases. The same entry also hides the original wherever that file is read (always for a user skill, or for an entry in your settings.json); for a plugin skill only the copy is hidden, since skillOverrides does not apply to plugin skills. An entry in another project's .claude/settings.local.json, where the /skills menu saves it, does not reach DIR.

--phrase is close to a grep -ril over every SKILL.md, cut to the best 10 (--limit 40 for more), plus up to five skills that hold the phrase only in their reference files. In a small Haiku test (four tasks over one folder of 927 public skills, run before the finder read reference files), Claude found the right skill about as often with plain grep over SKILL.md files. In the later three-model tests, with grep -ril over a folder holding only the test's skills in place of the finder, the two were level where the skill is installed or its name says what it holds: on Sonnet 94 against 98 of 144 team rules followed and 41 against 40 of 58 skills opened, on Haiku 74 against 76 and 45 against 47. For skills that are not installed the finder was ahead: on Sonnet it opened the needed skill in 36 of 53 tasks and grep in 26 (ahead in 12 tasks, behind in 2, which met the pass rule set before the runs), on Haiku 44 against 37 (just short of the rule). One run a task, grep in a first wording.

What the finder adds is around the match:

  • Where to look. It knows where Claude Code keeps skills: user and project folders and every plugin's skills in each config dir, including disabled plugins and the marketplace folders of plugins you never installed, plus the folders inscripts/roots .
  • What each hit is. Its state, path, description and the line that matched. Copies of one skill (a plugin's cache and its marketplace folder) are shown once.
  • Order. The phrase in the name first, then in the description, then by how often it occurs, not by folder order. A phrase starts a word and ignores case, and its words match across spaces, hyphens and underscores ("release notes" findsrelease-notes ).
  • Reference files. Many skills keep most of their text in reference files (.md and.txt files in the skill's folder,references/ first; log, test and hidden folders are skipped). A skill that holds the phrase only there is listed after theSKILL.md hits, up to five, with the file and line. A listed skill's row also shows, with file and line, each looked-up phrase that only its reference files hold (up to three), and then the names of its reference files (up to eight: those that hold the looked-up phrases in their text or name come first, and a phrase that few of the skill's files hold counts most). In a small Sonnet test on 16 made-up skills with long files (20 cases where the rule sat in a reference file of a skill about another topic), Claude followed the rule in 20 cases with these lines against 8 without them; with the reference files renamedpart-1.md and so on, in 15 against 5. The file-and-line hits did that work: the list of names led Claude to the file only when the names said what was inside. A lookup's output grows by about 6 to 20%. On real skills the picture is narrower. With 151 public skills from 16 GitHub repositories installed, Sonnet got tasks written to fit one reference file each, with either a lookup step inCLAUDE.md or a plain "open the skills that fit" step. WhenSKILL.md names the file, both opened it equally often (16 of 16 each at a plan; 9 against 8 of 10 at a review). When it does not, the lookup step opened it more often: 13 against 6 of 16 at a plan, and 11 against 7 of 16 at a review, where the gap was under that test's own bar. Reference files thatSKILL.md does not name are rare (29 of the 151 skills have one), and opening a file is not a better answer: Sonnet already writes much of what these files say, and where only one side had read the file, a blind count of the file's points in the plan gave 23 against 14 of 25, with the plan better to work from in three tasks of six and the same in three. The order of the eight names was added after those runs, because a skill with 85 files rarely named the right one; a rerun of the 32 not-named tasks then reached 26 files against 24, which is no loss and not a shown gain (the same tasks, a day apart). In all of these the tasks were written to fit the files, one run each. In a replay of 894 lookups recorded in four test tasks (no model), the right skill was in the first ten for 213 of the 294 lookups that noSKILL.md matched, against 205 without it (first three: 126 against 113). All of the gain at ten came from one task, whose words sit in its reference files; the other three neither gained nor lost there.
  • No match. It says how many skills hold each word (inSKILL.md or reference files) and usually lists the skills nearest by words. The same holds for one phrase of several: a phrase that no skill holds is named, with its word counts and up to three skills nearest by its words (six a lookup), also when the other phrases matched. A skill counts as near only when it holds two of the phrase's words or has the rarest one in its name or description. Before, such a phrase got nothing unless the whole lookup matched nothing, and that was the largest single cause of a lookup missing the skill in the benchmark runs under "Does it work?".
  • Near the whole lookup. With several phrases, up to two skills that hold no typed phrase but rank in the first three by the words of the whole lookup are listed after the rows, when near by the same rule. A row shows up to 200 characters of the description (110 before, which often cut off the part that says when to use the skill). On the lookups that earlier model runs typed, replayed on both versions: the needed skill listed in 3 more benchmark runs of 155 and 3 more times on a team's tasks, none lost, the best match the same in all 328 lookups, about 19% more characters a lookup. Not shown with the model: this version was not run with it. A wider version was (53 benchmark tasks, one run each: the needed skill opened in 40 against 37, not a shown difference); read run by run, one task was gained through these rows and one plausibly lost through a part since dropped. Tried in that wider version and dropped: moving the first row and the best match to the listed skill the whole lookup's words rank highest (it fired in 12 lookups and named the right skill in 4), and retrying a long unmatched phrase by its two-word parts (it never listed a needed skill).

--task is a keyword ranking instead (a word in the name counts most, then the description, then the body; rare words count more). It is the part the public benchmark below scores.

  1. Install the skill.git clone https://github.com/ydmitry/skill-finder ~/.claude/skills/skill-finder (or copy the folder to a project's.claude/skills/ ). Python 3, standard library only; PyYAML is used for the front matter when it is installed. TheCLAUDE.md block below calls the script directly; the skill's ownSKILL.md is for when you or Claude invokeskill-finder for a fuller search and a report on which skill to use and how.
  2. Point it at your org's skills. It already scans user skills, project skills (.claude/skills up from the working folder) and every plugin's skills in each config dir (~/.claude , and$CLAUDE_CONFIG_DIR when set): enabled plugins, disabled ones, installed ones thatsettings.json does not list, and the marketplace folders of plugins you never installed, underplugins/marketplaces . So a marketplace that Claude Code cloned when you added it is searched as it is, except plugins it only links to in other repos, which are not on disk until you install them. For a skill repo that is not a marketplace, clone it once and add its folder (for a marketplace added from a local folder, that folder) toscripts/roots (copyscripts/roots.example ; one folder per line, machine-local, not committed). It cannot see Claude Code's bundled skills.
  3. Add the instruction to your CLAUDE.md. Put this in your global~/.claude/CLAUDE.md (or a project'sCLAUDE.md ), and change the path if you installed the skill elsewhere:
## Skills
Before you write code, a plan, a review or any other piece of work, look the skills up. First read the request and every file it names. List what appears in them: the things, activities, materials and technologies, and what the finished thing is called. Look all of them up in one plain command (no loop, no variable), one --phrase for each, two or three words in order. Run it as a command of its own, not joined to other commands:
  python3 ~/.claude/skills/skill-finder/scripts/find_skills.py --phrase "<a name>" --phrase "<another name>"
It lists the skills and the reference files that hold a phrase. Read every listed skill that fits to the end, and every listed reference file that fits, and the reference files in a skill's folder that fit, before writing anything. Follow what they say. Nothing listed that fits means proceed without a skill. Skip for one-line answers and when the task names its skills.
The lookup is not one step. After you read a skill or a reference file, look up, the same way, every thing, area or kind of data it mentions that your earlier lookups did not cover. Do this before you write, and again after each new file you read. If a lookup lists nothing that fits, try other words.

If your permission rules allow the finder by its command (for example Bash(python3 ~/.claude/skills/skill-finder/scripts/find_skills.py *)), Claude Code checks each part of a chained command on its own, so a plain finder call with several --phrase, alone or chained with ; or &&, passes. A shell loop does not, nor does a cd outside your working folders: expect a prompt, or a refusal in unattended runs. In a test, Opus put its phrases in a loop in all 20 runs (14 of them as cd /tmp && for p in ...; do ...; done), and all 20 were refused; that was the earlier block, which showed one phrase a command, and the block now asks for one plain command with no loop (untested on Opus). In the subagent variant below, the line "Run one phrase per command, with no cd and no loop" kept every Opus subagent to plain calls; the block with that line added is untested.

A skill it finds is trusted like one you installed. The block has Claude follow every listed skill that fits, also when it comes from a marketplace or repo you never installed and may never have read, and a SKILL.md can tell Claude to run its scripts. What is listed is picked by keywords, not by you: a phrase in a skill's name or description ranks it first, so any SKILL.md in a searched source can put common phrases there. Search only sources you would install from: the marketplaces you added are searched as they are, and scripts/roots holds the rest. A plain read does not run a skill's !` command` lines, fill in ${CLAUDE_SKILL_DIR} or ${CLAUDE_PLUGIN_ROOT}, or apply its frontmatter (allowed-tools, context: fork, hooks, model); such a skill works only when Claude Code loads it: its plugin enabled, or a copy made with --enable, which runs !` command` lines and fills ${CLAUDE_SKILL_DIR} but not ${CLAUDE_PLUGIN_ROOT}.

This block replaced an earlier one on 2026-11-14. The earlier block ("Before the first edit of a task ... look the skills up by phrase", one phrase a command, "open the best match"; its text is in this file's history) is the one every test under "Does it work?" ran with, except where a test names its own wording. On 24 plan and review tasks about a team's own skills among 897 public ones, the earlier block followed 46 of 144 of the team's rules and this one 84 of 144; the earlier block made no lookup at all in 11 of 48 runs, this one in none. On 12 tasks that edit a file it showed no large loss and no gain (the rule's value applied for 24 of 72 needs against 23), and it looked nothing up for one-line questions (0 of 8 runs). The plan and review tasks are the ones the new wording was written from, and the earlier block's runs were made the evening before; "Does it work?" has the test and its limits. Not rerun with this block: the ten requests for skills that are not installed (a public benchmark's tasks were run with it instead, see "Does it work?"), Haiku and Opus, and the Second lookups section under it. The block costs about 345 tokens in every session. Its last paragraph ("The lookup is not one step") can be left out if your skills do not point to each other and the extra lookups are not worth it to you; it was tested in a differently worded step (144 against 182 of 216 rules, 19% more cost a run) and in the earlier block (16 against 46 of 144). In a Haiku test on unattended runs (such as claude -p with a task), a longer version of the earlier text, not published here, got the skill opened in 15 of 15 runs when added to the task and in 9 of 15 when left in CLAUDE.md; this block has not been tried in a task. To see whether it works for you, count the transcripts in which Claude ran the finder:

grep -rl --include='*.jsonl' '"name":"Bash".*find_skills\.py' "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects" | wc -l

and look at whether a skill it listed is invoked afterwards.

Optional: a second lookup mid-task. The block already says to look again after each skill or reference file for what that file mentions, but in tests of the earlier block Claude mostly looked up the request's words, and rarely a second need that showed only inside the files: a GPL-licensed file in a pull request under review, answers from under-16s in a survey, money stored as floats in a bug fix. The Second lookups section below, pasted into the same CLAUDE.md right under the block (the tested text and placement, word for word), asks for a lookup for each technology or kind of data the files show. Add it if your org keeps skills for such needs. It is about one and a half times as long as the block (roughly 500 tokens in every session), it was tested under the earlier block only, it adds lookups, and in tests it did not reach a business change such as a cut to a pricing plan; the tests are under "Does it work?".

## Second lookups
The lookup is not a one-time step before the first edit. Every time a file you read shows a technology, a kind of data, a format or a service that the skills you opened do not cover, you MUST look the skills up again with its name, before you write about it. No exceptions.
Before you write findings or code, write one line: "Technologies and kinds of data in this work: ..." and, for each, the skill you looked up for it or "no skill found".

| Thought | Reality |
|---|---|
| "I already ran the lookup before the first edit" | That lookup used the request's words. What the files showed since are new facts; look them up. |
| "The skill I found fits the task" | It fits the request. A technology or a kind of data in the files is a second need with its own rules. |
| "The match is the same as last time, so I'll follow it" | Same phrases, same match. Search with the names the files show. |
| "The check failed, so I'll follow the first skill more closely" | Following one skill harder does not add the rules of another. Look up what the files show. |
| "This is a review, not an edit, so no skill is needed" | A review is where the team's rules matter most. |
| "Leave proper nouns out" | That is for phrasing the first search. A technology's name, or the kind of data, is the right phrase for a second one. |

Red flags, stop and look up: you are about to write about a file type, technology or kind of data that no skill you opened mentions; you are rerunning the first lookup's phrases; a check failed and you are only rewording.
Teams keep their rules for a technology or a kind of data in a skill. Work that skips them comes back incomplete, every time.

The tests in this section ran with the earlier block (see the note under the block), except the last part of the team-skills paragraph. In short: it helps Claude find and open skills it could not otherwise see, and adds little for skills Claude already lists, except a second skill whose need shows only in the files (the optional Second lookups section). Most tests measure whether Claude ran the finder and opened the skill, not whether the work came out better; the tests of the Second lookups section check whether a skill's rules reached Claude before a check on the output asked for them. They were run with Claude Haiku and Sonnet (the subagent tests also with Opus), their harness is not published (several tests run on one machine's own config and skills, some of them private; the others on a local copy of 927 public skills that is not redistributed), and they are small: read them as directions, not rates. The model tests ran when a --phrase lookup listed up to 40 skills, except the subagent tests, which ran at today's default of 10. All the model tests except those of the Second lookups section, the subagent tests and the team-skills test ran before --phrase also read reference files. Two tests need no model: the reference-file replay above, which replays the unpublished runs' lookups, and the benchmark in the last paragraph of this section, whose scripts are published in bench/skillret/.

Skills you have not installed are the finder's main job. Ten skills from public repos that were not installed, and requests written without any word of the skill's name or description (rejected by a check, then confirmed blind by a second model that picked the right skill first for 8 of 10). Without the instruction, Sonnet ran the finder in none of 30 runs and opened none of those skills. With it, it ran the finder in all 50 runs, had the target in a list in 78% of them, opened the exact skill in 68%, and in 88% opened at least one skill it could not otherwise see, the right one or not. Seven of the ten skills were opened in four or five of five runs; two of the misses were requests that fit another unseen skill as well, one was a short skill whose words the request did not share. Ten skills, one model, the first turn only (nothing is written, so whether the skill was followed is not measured), and requests written by a model that had read each skill: a direction, not a rate. A later Sonnet rerun at today's default of 10 hits, counted more strictly (only skills opened before the reply reached 1,000 characters), opened an unseen skill in 14 of 20 runs and the exact one in 11 of 20.

The same question on a public benchmark's tasks. The ten skills above were picked and their requests written for this test. Skill-Use-Bench (arXiv 2608.04828) has tasks and skills written by others: each task has input files and one skill it needs, an edited copy of a public skill. I took one task for each skill that fits an unattended run (the skill in English, no word of its name in the prompt or the inputs, inputs present and not an archive), put the skill among 889 public skills, and counted whether Sonnet opened it: its SKILL.md read, or 20 of its lines shown. One run a task; the benchmark's files are not redistributed here and the harness is not published. With the skills installed, so that their names are in Claude's skill list (58 tasks): no instruction opened the right skill in 8 tasks, the block above in 40, ahead in 32 tasks and behind in none. The 8 were skills whose name is nearly the task's own words. With the skills only on disk, where a lookup is the one way to them (53 tasks): the block opened the right skill in 30. The earlier block gave 36 of 58 and 28 of 53; no difference between the two blocks is shown here, in a test that could only see one of about 20 points. Of the 23 misses when not installed, 15 were lookups that did not list the skill, 7 listed it and did not open it, 1 made no lookup. In 8 of the 15 no typed phrase was in the skill, yet a lookup of one of the phrases alone would have named it among the nearest by words. The finder now prints those rows (see "No match" above). Replayed on the new runs' own lookups, that lists the right skill in 7 tasks where the old output did not and loses none; in new runs the block opened the right skill in 36 of 53 against 30 a day earlier, a gain this test does not show (10 tasks ahead, 4 behind): 6 of the 36 came only through the new rows, and no wrong skill was opened from them. On the 24 plan and review tasks of the team-skills test below, the rules followed went from 84 to 91 of 144 with the change, inside a no-loss margin set before the runs. Limits: "opened" is often the first 60 to 150 lines; asking for half the skill's text gives 26 opens for 30 and 29 for 36. Whether the skill was then followed is not measured: the benchmark's own file checks failed in 24 of 55 cases even with the skill handed over. One model, one run a task, and prompts written by the benchmark's authors with the skill in view.

Why the instruction is needed. None of the SKILL.md descriptions tried, one of them saying "use at the start of EVERY task", got the skill called: 0 of 232 runs. The models call the skill whose topic matches the task (a chart skill for a chart) and never a skill whose job is to look for skills. On a machine with many skills Claude Code also drops the description of the ones you never invoke, so the skill is often listed by name alone. What works better is a standing instruction in the system instructions, next to the work.

What the instruction does. With it in the global CLAUDE.md, Sonnet ran the finder before its first edit in 8 of 8 test runs (four tasks, two runs each) and in none of 4 one-line questions. With the lookup allowed it then opened a skill from the list in 6 of 8; in 4 of those it was a skill it opens without the finder, and for the task whose best skill is not in its own skill list (a colour theme) it opened the finder's pick in 2 of 2. Subagents read the same file and did the same in 8 of 8 delegated runs, at about three lookups each before their first edit; a coordinator that only handed the task over looked nothing up (0 of 8), so a coordinator's main conversation does not see those lookups. In placement tests with Haiku on unattended runs, a longer version of this text in CLAUDE.md got the finder run every time, but the skill opened in 9 of 15 runs; added to the task itself, the same text got it opened in 15 of 15. The line "open the best match's SKILL.md before writing anything" has not been measured. On Haiku the block rarely fired on the ten unseen-skill requests, nine of which ask for a written answer rather than an edit: in 18 of 20 runs Haiku answered with no tool call at all, and the 2 runs that ran the finder were both on the one request for a file. Sonnet ran the finder first in all 20 runs on the same requests. In these runs the block came as an addition to the system prompt, not from CLAUDE.md.

The lookup in a subagent. A variant of the block that hands the lookup to a subagent, tested against the block on Haiku, Sonnet and Opus with a bar set before the runs, did not pass on any model. On Sonnet, the only model where both versions ran their search, in the 7 pairs where both found the skill the main conversation still received 84% as much text: the finder's output (about 30% of what the block put there) stayed out, but the subagent's report and the skill and its references, read in the main conversation either way, made up the rest. On Sonnet it also cost about 1.5 times as much in total. On Haiku the block's runs mostly made no tool call, and on Opus the allow rule refused the block's searches (above), so there was little to compare. The block stays as it is.

A second skill the files reveal mid-task (the optional Second lookups section). Each test task asked for one thing (review a pull request, summarise a survey, fix a bug) and hid a second need in its files. A scripted check passed the work only once it applied that second skill's rules, and when it failed it said only that the work was incomplete, never which need. The measure: did Claude read the second skill's rules before the check first said so ("reached it" below)? The second skills were written for these tests (not published) and sat among 200 public skills, listed in the session by name only: unlike the uninstalled skills above, Claude could see their names, and part of the gain came through those names. On four such tasks, 6 Haiku runs each, the block alone reached it in 0 of 24 runs and the section in 15 of 24; in a rerun, 2 of 24 against 13 of 24. The first count is exploratory, because that round's control task failed; the rerun passed a bar set before it, with one run to spare.

Over both rounds (12 runs a task) it worked where the need is a technology or a kind of data, the section's own words: the GPL file 11 of 12, the under-16 answers 9 of 12. For money stored as floats it reached it in 8 of 12 too, but mostly through the skill's name in the session's list (5 of the 8; 2 by searching the need), two of them before any money code had been read. For a cut to a pricing plan in release notes, which is neither, it reached it in 0 of 12. On Sonnet (the licence and survey tasks, 4 runs each) the section reached it in 8 of 8 runs and the block alone in none before the check said the work was incomplete (3 of 8 after); half of the 8, counted by hand, went by the skill's name from the session's list, typed as a search or opened directly, rather than by searching the need. On four tasks whose second need is a rule, a policy or a new fee (gifts to public officials in an expense report, orders to sanctioned places, health claims in product notes, a new card surcharge in a newsletter item), the section reached it in 17 of 24 Haiku runs against 3 of 24: 16 of 18 on the first three, 1 of 6 on the surcharge. These counts are exploratory: the test planned for these tasks was of a different wording, one that also names rules and policies, and it decided nothing, because the block alone reached it in 9 of 30 runs over five such tasks, above the limit set before the runs, 6 of them on a litigation hold. The block alone also found a few needs that were easy to guess (a database migration, a cron parser, the litigation hold). The misses were missing lookups, not failed searches: in the rerun, no run that missed, with the block alone or with the section, had searched for the second need before the check said the work was incomplete.

What the Second lookups section costs. Four ordinary tasks (a styled page, a project plan, search ads, and an incident write-up whose notes do hold a second need, a PostgreSQL index built without CONCURRENTLY), Haiku, eight runs each with and without it. Runs that opened the task's skill and passed its check: 31 of 32 with it, 28 of 32 without. Median tokens a run rose 3% overall, held down by runs without it that needed a second try; among runs that passed at the first try it cost more on every task, from 2% (the plan) to 29% (the styled page). Lookups rose by about half. On the first three tasks it opened a skill besides the task's own in 7 of 24 runs against 4, each one fitting the request (an ad-writing skill for the ads), 4 of the 7 right after a lookup the section asked for. On the incident write-up it looked at the PostgreSQL skill in 2 of 8 runs, without it in none. The "Technologies and kinds of data" line it asks for showed in the reply in 10 of 32 Haiku runs and never in a deliverable, but Sonnet wrote it into the review file itself in 2 of its 4 licence reviews. The margins set before the runs were wide, so this shows no large harm, not no cost. Not tested: harm on Sonnet, and one-line questions or small edits with the section. The tasks, the second skills and the section were written for these tests by the same author, with model help; the section's table grew from one task's failed runs; and each comparison had 4 to 8 runs a task.

A team's own skills among many public ones. Twelve skills written for the test as one team's house rules (each rule with an ID, some of them in reference files) sat among 151 and among 897 public skills. Each of 24 tasks, plans and reviews, needed three of the rules from two or three of the skills; the count is rules cited in the answer, 144 for each setup, on Sonnet. With no step in CLAUDE.md, Claude Code followed 32 rules at 151 skills and none at 897, where it called no skill in 48 runs. A step that tells it to look changed that: a plain "use the team's skills that fit" sentence gave 105 and 75, the lookup step 118 and 78, the lookup step plus "look again after each file you read" 126 and 101. A step against no step is the one difference these runs show. Between the plain sentence and the lookup step they show none (the team's skills had names that say what they hold, which is all a plain sentence needs), and "look again" led only in counts, for 17 to 36% more cost. A confirming test of "look again" alone followed, with a rule fitted to a gap of that size and so chosen after seeing it: the same 24 tasks at 897 skills, three runs each, the lookup step against the same step plus the paragraph that now ends the block above. Rules followed: 144 against 182 of 216; look again was ahead in 18 tasks and behind in 3; cost a run 19% more. That passed the rule. The first rule of a task was found either way (61 against 63 of 72); the gain was the second skill (40 against 54) and the rules one skill points to in another (43 against 65). In 26 of 72 runs the lookup step alone looked a second time too. The lookup step in these runs is not the block above. It is the test's own wording, written for plans and reviews: "Before you write a plan or a review. First read the request and every file it names. List the things, activities, materials and technologies that appear in them. Look all of them up in one plain command, one --phrase for each. Open every listed reference file that fits; open every listed skill that fits, and read the reference files in its folder that fit." The block above, put on the same 24 tasks at 897 skills the same evening (two runs each), followed 46 of 144 rules, 32%, where that step with the same last paragraph followed 84%; without its last paragraph, 16 of 144 against the step's 67%. The loss is before a skill is listed: the block's runs typed about 2 phrases a run against 13, made no lookup at all in 11 of 48 runs (21 of 48 without the last paragraph), and 15 of the 27 runs that did look without it typed only "code review" or "step-by-step plan", the kind of document, which is what the block's "what the finished thing is called" asks for. Once a needed skill was listed, the block's runs followed it about as often as the step's. That block was written for tasks that edit, and these make no edit. Two sentences of the block changed on 2026-11-14. "Run it as a command of its own, not joined to other commands" was added, and "Open every listed skill that fits" became "Read every listed skill that fits to the end". Without the first sentence Claude mostly put the lookup in one command with other things (a cd, a cat of the task's files, a | head), and a harness that refuses part of such a command refuses the lookup with it. On 27 of the public benchmark's tasks below, skills not installed, one run each, with the rule fixed before the runs: a lookup joined to other commands in 25 tasks without the sentence and in 0 with it; the needed skill opened in 20 and 18 tasks (the rule allowed 3 fewer; 38 and 36 over this round and an earlier one on the same tasks); opens that showed at least half of the skill 14 and 17. On the 24 plan and review tasks it followed 99 of 144 rules (the block before the change 84 with the earlier finder and 91 with this one), reviews 46 against 32. What this does not show: the measure was chosen after the earlier round on the same tasks had shown the difference, so this is a repeat, not a new finding. The cost of a joined lookup was small in these runs: every refusal was for the command joined to the lookup, 4 of the 5 refused tasks retried and opened the skill, and with the sentence Claude ran the same file reads as a call of its own, so no calls were saved. Two runs with the sentence made no lookup at all, none without it, and skills other than the needed one were opened in 7 runs against 4. The runs used a short command name in place of the python3 path above. The two sentences were not tested apart.

The block reworded. The block above borrows the step's wording: read the files first, list what is in them, look it all up in one command, open every listed skill and reference file that fits. One wording was tried, with rules fixed before the runs. On the same 24 tasks (two runs each) it followed 84 of 144 rules against the earlier block's 46, ahead in 14 tasks and behind in 2, with a lookup in every run; plans 52 against 25 of 72, reviews 32 against 21. It cost $0.20 a run against $0.15. On the 12 review files given as tasks that edit ("fix what is wrong in this file"), both blocks looked skills up before the first edit in 23 of 24 runs, and the rule's value was applied for 24 of 72 needs against the earlier block's 23: no large loss by a rule that allowed 6 needs, and no gain. Neither looked anything up for four one-line questions (0 of 8 runs each). It is still below the test's own step (84 against 119 of 144 on the same two repeats). Nearly all of that gap is needed skills never listed: its runs type about half as many phrases, mostly two words long where the step's runs often type one; 9 of 24 review runs looked up before reading the file, typing "code review"; and 7 review runs stopped after a first lookup that listed no team skill. Limits: the wording was written after reading these tasks' runs, so this is not a test on new tasks; the earlier block's plan and review runs were made the evening before, not side by side; its answers cite nearly twice as many rule IDs (each one read by hand sat on a step that used the rule); and "no loop" in the block matches what this test's permission rules allow, where the earlier block lost a few runs to refused loops. At 897 skills the first lookup, typed as about seven phrases in one command, listed the needed skill for fewer than half the needs: skills that hold many common phrases took the ten rows. Since then each phrase takes a row in turn. Replayed on the recorded first lookups, that lists the needed skill for 236 of 384 needs against 166, in output of the same size. In new runs at 897 skills, rules followed went from 181 to 208 of 288, under the bar set before the runs, so not a shown gain; at 151 skills it was 125 against 131 of 144, the size of the difference between two days of the same setup. Once a skill was listed, its rule was followed in about 96% of cases under either order. Showing more rows, more rows for each phrase, or more of the reference-file block added 1 to 21 needs of 384 for up to half again the output, and was not adopted. Of the 148 needs still not listed, no typed phrase matches the skill for 54, and for 33 the phrase is only in a reference file; those take other phrases or a second lookup, not another order. One invented team, one model, tasks written to fit these rules.

Skills the session already lists gain little. Three skills the session lists by name alone, five Sonnet runs each, with and without the instruction: the model opened the right skill in all fifteen runs either way, because the names say what the skill does and it calls the skill by its name. So that test shows no gain from the finder for readable names, and no harm. Name-only skills whose names say nothing are untested. For skills that keep their description, the runs without and with the instruction opened the right one in 23 and 25 of 25, a difference of one task (3 of 5 to 5 of 5). So it pays off most when your org's skills are on disk (a marketplace or a cloned repo) but not installed.

On a public benchmark, with no model. This benchmark scores the --task ranker, not the --phrase lookups the CLAUDE.md block uses. SkillRet (arXiv 2605.05726) asks a ranker to find the skills each of 4,392 requests needs among 6,006 public SKILL.md files. The finder's --task ranker scores NDCG@10 58.78 (how high the needed skills sit in the first ten, out of 100), against 51.69 for the benchmark's own BM25 keyword baseline, whose rerun here gives the paper's numbers exactly; off-the-shelf embedding models in the paper reach 70.26, but need a model, and the finder uses none. The lead over BM25 comes from requests that need two or three skills; on the 2,143 that need one, there is no measurable difference. The requests were written from each skill's name and description, which suits the weight the finder puts on the description. It does not test whether Claude runs the finder or opens what it finds. bench/skillret/ reruns it on a laptop in about a quarter of an hour, with no API key.

python3 scripts/find_skills.py --phrase "implementation plan"           # exact phrase in every SKILL.md, then its reference files
python3 scripts/find_skills.py --task "heap snapshot memory leak"        # keyword ranking
python3 scripts/find_skills.py --list                                   # the whole inventory
python3 scripts/find_skills.py --toc [FOLDER|SKILL] [--kind names|sentence|description|headers|files]   # tables of contents
python3 scripts/find_skills.py --phrase "..." --toc   # the hits as sections (SKILL.md only)
python3 scripts/find_skills.py --enable NAME --into DIR                 # copy a skill into DIR/.claude/skills for one run
python3 scripts/find_skills.py --phrase "..." --only DIR                # search only the skills in DIR, as in the example

--phrase is the recommended lookup and the one the CLAUDE.md block uses. It lists the best 10 skills; when more hold the phrase, it says how many and that --limit 40 lists more. Quotes are optional for the words that follow it after a space (--phrase release notes is one phrase; another --phrase adds a second). --phrase and --task leave out the finder itself, whose README and notes hold the example phrases and would match most lookups: its own folder and any copy of it (the same SKILL.md, or a skill of its name with scripts/find_skills.py beside it); --list and --toc without --phrase still show it. --toc (every skill on one line, grouped by folder) is an optional way to browse. In an unpublished pick-only test (48 requests over one machine's 264 skills; Sonnet read a whole table and named up to three skills), no table put the right skill among its picks more often than --phrase output did (43 of 48). The table with whole descriptions matched it, 43, at about seven times the cost; the tables with names, first sentences (the default) or headers had 33, 34 and 40.

SKILL.md is the skill: it tells Claude how to search, read the best matches and their reference files, and report which skill to use and how. scripts/find_skills.py is the finder.

python3 -m unittest discover -s tests

tests/test_ranking.py holds the golden queries; tests/fixtures/skills is the small skill set they run against.

Experimental. The finder lists candidates by keywords or by an exact phrase; it does not decide. Experiments on whether a worker opens the right skill (not part of this repository) found that where the instruction to search sits matters, and that the "Best match:" block a phrase search prints at the end (shown in the example above) got the right skill opened more often in a Haiku test (12 of 15 runs against 9) but did not get more tasks done (8 against 9). TODO.md lists what is open.

MIT

── more in #ai-agents 4 stories · sorted by recency
── more on @claude code 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/attempts-to-improve-…] indexed:0 read:51min 2026-11-18 · —