{"slug": "attempts-to-improve-skill-discovery-in-claude-code", "title": "Attempts to improve skill discovery in Claude Code", "summary": "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.", "body_md": "*The same text as a page: [ydmitry.github.io/skill-finder](https://ydmitry.github.io/skill-finder/).*\n\nWhen using skills in Claude Code, I was concerned about the following things:\n\n- Mostly I needed to explicitly say which skill to use.\n- If in the middle of a session some skill appears to be useful, will it be auto-invoked?\n- If I need a specific reference, will it be added to the context?\n- Is the description enough for the LLM to decide if a skill needs to be used?\n- Also, what about skills with a badly written description, or skills too broad to describe with only one description?\n\nSo 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.\n\nClaude 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.\n\nThe 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.](#the-instruction-to-put-in-claudemd)\n\n- 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.\n- When a team keeps its conventions in skills, Claude cannot follow a rule it has not read.\n- 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.\n\nPut 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`.\n\n```\n## Skills\nBefore 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:\n  python3 ~/.claude/skills/skill-finder/scripts/find_skills.py --phrase \"<a name>\" --phrase \"<another name>\"\nIt 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.\nThe 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.\n```\n\nThe last paragraph tells Claude to look up again after each file it reads. I call it look-again below.\n\n## The grep version, without the finder\n\nThe same instruction with grep. I tested a close version of it, not this exact text.\n\n```\n## Skills\nBefore 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:\n  grep -Ril --include=SKILL.md -e \"<a name>\" -e \"<another name>\" ~/.claude/skills\nIt 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.\nThe 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.\n```\n\nAdd your other skill folders to the command. On macOS add `-S` if they are symlinks.\n\nI used two suites and three Claude models: Haiku (small), Sonnet (mid-size) and Opus (the largest).\n\nThe 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.\n\nThe 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.\n\nHaiku and Sonnet ran everything. Opus ran ten tasks from each suite, because it costs more.\n\nBefore 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.\n\nEach 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.\n\nThe test harness and the run records are not published: they hold copies of other people's skills and of the benchmark's tasks.\n\nWith 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.\n\nThe 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).\n\nEarlier, 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.\n\nTelling 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.\n\nA 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.\n\nOne 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.\n\nWith 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.\n\nA 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.\n\nThis 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.\n\nWhen 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.\"\n\nHaiku 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.\n\nSo a description that insists works for Sonnet with a short list. You can only write it that way for skills that are yours.\n\nTwo 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.\n\nIt depends on how `SKILL.md` points to the file.\n\nWhen `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).\n\nIn 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.\n\nJudging 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.\n\nI ran the same instruction with `grep` in place of the finder.\n\nNo 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.\n\nI 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.\n\nInstalling the finder as a skill, without the instruction, did nothing. Haiku never called it.\n\nAdd the instruction. If you would rather install nothing, use the grep version.\n\n**Maybe someone in your org already wrote a skill for this.**\n\nYour company keeps Claude Code skills in a few repos or plugin marketplaces, or you added a marketplace once and forgot what\nis 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\nexist. skill-finder searches every skill on your machine (installed, disabled, or never installed but shipped inside a\nmarketplace Claude Code cloned) plus any skill repo you have cloned and listed in `scripts/roots`. It lists the skills that\ncontain the words Claude looks up, in their `SKILL.md` or in their reference files, each with its path and the line that\nmatched. Claude can then read the one that fits, or\nyou can copy it into a folder you start a fresh session in. It never edits `settings.json`; beyond the folder you clone, the\nonly change to your setup is the `CLAUDE.md` lines you add.\n\nWhat the tests show: with the `CLAUDE.md` block, Sonnet runs the finder and opens skills it could not otherwise see (one in 44\nof 50 runs, against none in 30 runs without the block; ten requests, the first turn only); Haiku, on the same requests, mostly\nanswered without running it. What they do not show: that the finished work is better. In my own sessions in the nine days after\nI 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.\nThe tests are under [Does it work?](#does-it-work).\n\n**Why not just enable them?** Enable the plugins you know you need. Claude Code gives its skill list a budget of 1% of the\ncontext window and, past that, drops the descriptions of the skills you invoke least, keeping their names; a 200-skill Haiku\ntest could not measure any harm from that.\nThe finder is for the skills you cannot enable without first finding them: in a marketplace you added but never installed, in\na team or public repo you cloned, or in a plugin you turned off.\n\nThe `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\nlookup lists at most 10 skills whose `SKILL.md` holds the phrase (and up to 5 that hold it only in reference files), each with\nits description and the line that matched: in my tests about 3,800 characters in the median, up to about 8,800. Claude can\nread most skills from their files without enabling them; whether it then follows one as well as an enabled skill is not\nmeasured.\n\nClaude will not reach for the finder by itself, so it comes with a short instruction for your `CLAUDE.md` (below). It pays\noff most for skills Claude cannot see; for skills Claude already lists, the tests found little gain, except for a second\nneed that shows only in the files (the optional `Second lookups` section below).\n\n``` bash\n$ python3 scripts/find_skills.py --phrase \"release notes\" --only tests/fixtures/skills\nphrase 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')\n1 skill(s) contain it. Best first: the phrase in the name, then in the description, then how often it occurs.\n\n1. release-notes  [folder skill]  tests/fixtures/skills/release-notes/SKILL.md\n   Draft release notes and changelog entries from merged pull requests.\n   :6: # release-notes\n\nBest match: release-notes  tests/fixtures/skills/release-notes/SKILL.md\nWhy: \"release notes\" is in its name and its description and 3 times in SKILL.md (line 6: \"# release-notes\")\nDescription: Draft release notes and changelog entries from merged pull requests.\nFirst lines of SKILL.md:\n  # release-notes\n\n  Group by change type.\nRead tests/fixtures/skills/release-notes/SKILL.md to the end, then follow it; search again only if it does not fit.\n```\n\nThat 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\nhere), `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\ninstall records and the settings a session started in the current folder reads: your `settings.json`, then that folder's\n`.claude/settings.json`, then `settings.local.json` there and at its git repo root (for a linked worktree, the main checkout's\nroot, so an entry the `/skills` menu saved there reaches the worktree). A folder whose own settings enable a plugin\ngets it, even one installed only for another project. A user or project skill that `skillOverrides` in those files hides or\nshortens (an entry under its folder name, not its frontmatter `name`) says so: `user skill, off in settings` (hidden from\nClaude and from the `/` menu), `user skill, user-invocable only in settings` (in your\n`/` menu, hidden from Claude) or `user skill, name only in settings` (Claude gets its name without the description), and\n`project skill, ...` alike; plugin skills are not affected. That holds for the config dir a session uses (`$CLAUDE_CONFIG_DIR`, else\n`~/.claude`); when the finder scans both, the other one is labelled by its own `settings.json` (an old version's copy still\nreads `plugin cached, other version`), and where both hold the same skill the copy shown is the one in use. The labels can still\ndisagree 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\n`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\nname, so `skillOverrides` set to `off` or `user-invocable-only` for that folder name in the files a session started in `DIR`\nreads (the ones above) keeps Claude from invoking it, and a user skill in a folder of that name runs instead of it (personal\nbeats 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\nan 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\nanother project's `.claude/settings.local.json`, where the `/skills` menu saves it, does not reach `DIR`.\n\n`--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\nreference files. In a small Haiku test (four tasks over one folder of 927 public skills, run before the finder read\nreference 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\nskill is installed or its name says what it holds: on Sonnet 94 against 98 of 144 team rules followed and 41 against 40 of\n58 skills opened, on Haiku 74 against 76 and 45 against 47. For skills that are not installed the finder was ahead: on Sonnet\nit 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\nbefore the runs), on Haiku 44 against 37 (just short of the rule). One run a task, grep in a first wording.\n\nWhat the finder adds is around the match:\n\n- **Where to look.** It knows where Claude Code keeps skills: user and project folders and every plugin's skills in each\nconfig dir, including disabled plugins and the marketplace folders of plugins you never installed, plus the folders in`scripts/roots` .\n- **What each hit is.** Its state, path, description and the line that matched. Copies of one skill (a plugin's cache and\nits marketplace folder) are shown once.\n- **Order.** The phrase in the name first, then in the description, then by how often it occurs, not by folder order. A\nphrase starts a word and ignores case, and its words match across spaces, hyphens and underscores (\"release notes\" finds`release-notes` ).\n- **Reference files.** Many skills keep most of their text in reference files (`.md` and`.txt` files in the skill's\nfolder,`references/` first; log, test and hidden folders are skipped). A skill that holds the phrase only there is listed\nafter the`SKILL.md` hits, up to five, with the file and line. A listed skill's row also shows, with file and line, each\nlooked-up phrase that only its reference files hold (up to three), and then the names of its reference files (up to\neight: 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\nmost). 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\nskill about another topic), Claude followed the rule in 20 cases with these lines against 8 without them; with the\nreference files renamed`part-1.md` and so on, in 15 against 5. The file-and-line hits did that work: the list of names\nled Claude to the file only when the names said what was inside. A lookup's output grows by about 6 to 20%.\nOn real skills the picture is narrower. With 151 public skills from 16 GitHub repositories installed, Sonnet got tasks\nwritten to fit one reference file each, with either a lookup step in`CLAUDE.md` or a plain \"open the skills that fit\"\nstep. When`SKILL.md` names the file, both opened it equally often (16 of 16 each at a plan; 9 against 8 of 10 at a\nreview). 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\nreview, where the gap was under that test's own bar. Reference files that`SKILL.md` does not name are rare (29 of the 151\nskills have one), and opening a file is not a better answer: Sonnet already writes much of what these files say, and\nwhere 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\nplan better to work from in three tasks of six and the same in three. The order of the eight names was added after those\nruns, because a skill with 85 files rarely named the right one; a rerun of the 32 not-named tasks then reached 26 files\nagainst 24, which is no loss and not a shown gain (the same tasks, a day apart). In all of these the tasks were written\nto fit the files, one run each. In a replay of 894 lookups recorded in four test tasks (no\nmodel), the right skill was in the first ten for 213 of the 294 lookups that no`SKILL.md` matched, against 205 without it\n(first three: 126 against 113). All of the gain at ten came from one task, whose words sit in its reference files; the\nother three neither gained nor lost there.\n- **No match.** It says how many skills hold each word (in`SKILL.md` or reference files) and usually lists the skills\nnearest by words. The same holds for one phrase of several: a phrase that no skill holds is named, with its word counts\nand up to three skills nearest by its words (six a lookup), also when the other phrases matched. A skill counts as near\nonly when it holds two of the phrase's words or has the rarest one in its name or description. Before, such a phrase\ngot nothing unless the whole lookup matched nothing, and that was the largest single cause of a lookup missing the\nskill in the benchmark runs under \"Does it work?\".\n- **Near the whole lookup.** With several phrases, up to two skills that hold no typed phrase but rank in the first\nthree by the words of the whole lookup are listed after the rows, when near by the same rule. A row shows up to 200\ncharacters of the description (110 before, which often cut off the part that says when to use the skill). On the\nlookups that earlier model runs typed, replayed on both versions: the needed skill listed in 3 more benchmark runs of\n155 and 3 more times on a team's tasks, none lost, the best match the same in all 328 lookups, about 19% more\ncharacters a lookup. Not shown with the model: this version was not run with it. A wider version was (53 benchmark\ntasks, one run each: the needed skill opened in 40 against 37, not a shown difference); read run by run, one task was\ngained through these rows and one plausibly lost through a part since dropped. Tried in that wider version and\ndropped: moving the first row and the best match to the listed skill the whole lookup's words rank highest (it fired\nin 12 lookups and named the right skill in 4), and retrying a long unmatched phrase by its two-word parts (it never\nlisted a needed skill).\n\n`--task` is a keyword ranking instead (a word in the name counts most, then the description, then the body; rare words\ncount more). It is the part the public benchmark below scores.\n\n1. **Install the skill.**`git clone https://github.com/ydmitry/skill-finder ~/.claude/skills/skill-finder` (or copy the\nfolder to a project's`.claude/skills/` ). Python 3, standard library only; PyYAML is used for the front matter when it is\ninstalled. The`CLAUDE.md` block below calls the script directly; the skill's own`SKILL.md` is for when you or Claude\ninvoke`skill-finder` for a fuller search and a report on which skill to use and how.\n2. **Point it at your org's skills.** It already scans user skills, project skills (`.claude/skills` up from the working\nfolder) and every plugin's skills in each config dir (`~/.claude` , and`$CLAUDE_CONFIG_DIR` when set): enabled plugins,\ndisabled ones, installed ones that`settings.json` does not list, and the marketplace folders of plugins you never\ninstalled, under`plugins/marketplaces` . So a marketplace that Claude Code cloned when you added it is searched as it\nis, except plugins it only links to in other repos, which are not on disk until you install them. For a skill repo\nthat is not a marketplace, clone it once and add its folder (for a marketplace added from a local folder, that folder) to`scripts/roots` (copy`scripts/roots.example` ; one folder per line, machine-local, not committed). It cannot see Claude\nCode's bundled skills.\n3. **Add the instruction to your `CLAUDE.md`.** Put this in your global`~/.claude/CLAUDE.md` (or a project's`CLAUDE.md` ),\nand change the path if you installed the skill elsewhere:\n\n```\n## Skills\nBefore 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:\n  python3 ~/.claude/skills/skill-finder/scripts/find_skills.py --phrase \"<a name>\" --phrase \"<another name>\"\nIt 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.\nThe 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.\n```\n\nIf your permission rules allow the finder by its command (for example\n`Bash(python3 ~/.claude/skills/skill-finder/scripts/find_skills.py *)`), Claude Code checks each part of a chained command on\nits own, so a plain finder call with several `--phrase`, alone or chained with `;` or `&&`, passes. A shell loop does not, nor does a `cd`\noutside your working folders: expect a prompt, or a refusal in unattended runs. In a test, Opus put its phrases in a loop in\nall 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,\nthe line \"Run one phrase per command, with no cd and no loop\" kept every Opus subagent to plain calls; the block with that line\nadded is untested.\n\n**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\na marketplace or repo you never installed and may never have read, and a `SKILL.md` can tell Claude to run its scripts.\nWhat 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`\nin a searched source can put common phrases there.\nSearch only sources you would install from: the marketplaces you added are searched as they are, and `scripts/roots` holds\nthe rest. A plain read does not run a skill's `` !` command` `` lines, fill in `${CLAUDE_SKILL_DIR}` or `${CLAUDE_PLUGIN_ROOT}`,\nor apply its frontmatter (`allowed-tools`, `context: fork`, `hooks`, `model`); such a skill works only when Claude Code loads\nit: its plugin enabled, or a copy made with `--enable`, which runs `` !` command` `` lines and fills `${CLAUDE_SKILL_DIR}` but\nnot `${CLAUDE_PLUGIN_ROOT}`.\n\n**This block replaced an earlier one on 2026-11-14.** The earlier block (\"Before the first edit of a task ... look the\nskills up by phrase\", one phrase a command, \"open the best match\"; its text is in this file's history) is the one every test\nunder \"Does it work?\" ran with, except where a test names its own wording. On 24 plan and review tasks about a team's own\nskills among 897 public ones, the earlier block followed 46 of 144 of the team's rules and this one 84 of 144; the earlier\nblock 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\ngain (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).\nThe plan and review tasks are the ones the new wording was written from, and the earlier block's runs were made the evening\nbefore; \"Does it work?\" has the test and its limits. Not rerun with this block: the ten requests for skills that are\nnot 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\nlast paragraph (\"The lookup is not one step\") can be left out if your skills do not point to each other and the extra\nlookups are not worth it to you; it was tested in a differently worded step (144 against 182 of 216 rules, 19% more cost a\nrun) and in the earlier block (16 against 46 of 144). In a Haiku test on unattended runs (such as `claude -p` with a task),\na longer version of the earlier text, not published here, got the skill opened in 15 of 15 runs when added to the task and\nin 9 of 15 when left in `CLAUDE.md`; this block has not been tried in a task. To see whether it works for\nyou, count the transcripts in which Claude ran the finder:\n\n```\ngrep -rl --include='*.jsonl' '\"name\":\"Bash\".*find_skills\\.py' \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects\" | wc -l\n```\n\nand look at whether a skill it listed is invoked afterwards.\n\n**Optional: a second lookup mid-task.** The block already says to look again after each skill or reference file for what\nthat 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\ninside the files: a GPL-licensed file in a pull request under review, answers from under-16s in a survey, money stored as\nfloats in a bug fix. The `Second lookups` section below, pasted into the same `CLAUDE.md` right under the block (the tested\ntext and placement, word for word), asks for a lookup for each technology or kind of data the files show. Add it if your org\nkeeps 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\nadds 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\nwork?\".\n\n```\n## Second lookups\nThe 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.\nBefore 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\".\n\n| Thought | Reality |\n|---|---|\n| \"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. |\n| \"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. |\n| \"The match is the same as last time, so I'll follow it\" | Same phrases, same match. Search with the names the files show. |\n| \"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. |\n| \"This is a review, not an edit, so no skill is needed\" | A review is where the team's rules matter most. |\n| \"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. |\n\nRed 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.\nTeams keep their rules for a technology or a kind of data in a skill. Work that skips them comes back incomplete, every time.\n```\n\nThe tests in this section ran with the earlier block (see the note under the block), except the last part of the\nteam-skills paragraph. In short: it helps Claude find and open skills it could not otherwise see, and adds little for skills Claude already lists,\nexcept a second skill whose need shows only in the files (the optional `Second lookups` section).\nMost tests measure whether Claude ran the finder and opened the skill, not whether the work came out better; the tests of the\n`Second lookups` section check whether a skill's rules reached Claude before a check on the output asked for them. They were\nrun 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,\nsome of them private; the others on a local copy of 927 public skills that is not redistributed), and they are small: read\nthem as directions, not rates. The model tests ran when a `--phrase` lookup listed up to 40 skills, except the subagent tests, which\nran 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\nbefore `--phrase` also read reference files. Two tests need no model: the\nreference-file replay above, which replays the unpublished runs' lookups, and the benchmark in the last paragraph of this\nsection, whose scripts are published in `bench/skillret/`.\n\n**Skills you have not installed** are the finder's main job. Ten skills from public repos that were not installed, and\nrequests written without any word of the skill's name or description (rejected by a check, then confirmed blind by a second\nmodel that picked the right skill first for 8 of 10). Without the instruction, Sonnet ran the finder in none of 30 runs and\nopened 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\nexact 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\nfive runs; two of the misses were requests that fit another unseen skill as well, one was a short skill whose words the\nrequest did not share. Ten skills, one model, the first turn only (nothing is written, so whether the skill was followed is\nnot measured), and requests written by a model that had read each skill: a direction, not a rate. A later Sonnet rerun at\ntoday's default of 10 hits, counted more strictly (only skills opened before the reply reached 1,000 characters), opened an\nunseen skill in 14 of 20 runs and the exact one in 11 of 20.\n\n**The same question on a public benchmark's tasks.** The ten skills above were picked and their requests written for\nthis test. Skill-Use-Bench ([arXiv 2608.04828](https://arxiv.org/abs/2608.04828)) has tasks and skills written by\nothers: each task has input files and one skill it needs, an edited copy of a public skill. I took one task for each\nskill that fits an unattended run (the skill in English, no word of its name in the prompt or the inputs, inputs present\nand not an archive), put the skill among 889 public skills, and counted whether Sonnet opened it: its `SKILL.md` read,\nor 20 of its lines shown. One run a task; the benchmark's files are not redistributed here and the harness is not\npublished.\nWith the skills installed, so that their names are in Claude's skill list (58 tasks): no instruction opened the right\nskill 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\ntask's own words. With the skills only on disk, where a lookup is the one way to them (53 tasks): the block opened the\nright skill in 30. The earlier block gave 36 of 58 and 28 of 53; no difference between the two blocks is shown here, in\na test that could only see one of about 20 points. Of the 23 misses when not installed, 15 were lookups that did not\nlist 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\nlookup of one of the phrases alone would have named it among the nearest by words. The finder now prints those rows\n(see \"No match\" above). Replayed on the new runs' own lookups, that lists the right skill in 7 tasks where the old\noutput 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\nthis test does not show (10 tasks ahead, 4 behind): 6 of the 36 came only through the new rows, and no wrong skill was\nopened from them. On the 24 plan and review tasks of the team-skills test below, the rules followed went from 84 to 91\nof 144 with the change, inside a no-loss margin set before the runs. Limits: \"opened\" is often the first 60 to 150\nlines; asking for half the skill's text gives 26 opens for 30 and 29 for 36. Whether the skill was then followed is not\nmeasured: the benchmark's own file checks failed in 24 of 55 cases even with the skill handed over. One model, one run a\ntask, and prompts written by the benchmark's authors with the skill in view.\n\n**Why the instruction is needed.** None of the `SKILL.md` descriptions tried, one of them saying \"use at the start of EVERY\ntask\", 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\njob is to look for skills. On a machine with many skills Claude Code also drops the description of the ones you never\ninvoke, so the skill is often listed by name alone. What works better is a standing instruction in the system\ninstructions, next to the work.\n\n**What the instruction does.** With it in the global `CLAUDE.md`, Sonnet ran the finder before its first edit in 8 of 8 test\nruns (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\nthose 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\ntheme) 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\nabout three lookups each before their first edit; a coordinator that only handed the task over looked nothing up (0 of 8),\nso a coordinator's main conversation does not see those lookups. In placement tests with Haiku on unattended runs, a longer version of\nthis 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\nsame text got it opened in 15 of 15. The line \"open the best match's SKILL.md before writing anything\" has not been measured.\nOn Haiku the block rarely fired on the ten unseen-skill requests, nine of which ask for a written answer rather than an edit:\nin 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\nfile. Sonnet ran the finder first in all 20 runs on the same requests. In these runs the block came as an addition to the\nsystem prompt, not from `CLAUDE.md`.\n\n**The lookup in a subagent.** A variant of the block that hands the lookup to a subagent, tested against the block on Haiku,\nSonnet and Opus with a bar set before the runs, did not pass on any model. On Sonnet, the only model where both versions ran\ntheir search, in the 7 pairs where both found the skill the main conversation still received 84% as much text: the finder's\noutput (about 30% of what the block put there) stayed out, but the subagent's report and the skill and its references, read\nin 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\nblock's runs mostly made no tool call, and on Opus the allow rule refused the block's searches (above), so there was little to\ncompare. The block stays as it is.\n\n**A second skill the files reveal mid-task** (the optional `Second lookups` section). Each test task asked for one thing\n(review a pull request, summarise a survey, fix a bug) and hid a second need in its files. A scripted check passed the work\nonly once it applied that second skill's rules, and when it failed it said only that the work was incomplete, never which\nneed. The measure: did Claude read the second skill's rules before the check first said so (\"reached it\" below)? The second\nskills were written for these tests (not published) and sat among 200 public skills, listed in the session by name only:\nunlike the uninstalled skills above, Claude could see their names, and part of the gain came through those names. On four such tasks, 6\nHaiku 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\n24. The first count is exploratory, because that round's control task failed; the rerun passed a bar set before it, with one\nrun to spare.\n\nOver 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.\n\n**What the `Second lookups` section costs.** Four ordinary tasks (a styled page, a project plan, search ads, and an incident\nwrite-up whose notes do hold a second need, a PostgreSQL index built without CONCURRENTLY), Haiku, eight runs each with and\nwithout 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\nrose 3% overall, held down by runs without it that needed a second try; among runs that passed at the first try it cost more\non every task, from 2% (the plan) to 29% (the styled page). Lookups rose by about half. On the first three tasks it opened a\nskill 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\nthe 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,\nwithout it in none. The \"Technologies and kinds of data\" line it asks for showed in the reply in 10 of 32 Haiku runs and\nnever in a deliverable, but Sonnet wrote it into the review file itself in 2 of its 4 licence reviews. The margins set before\nthe runs were wide, so this shows no large harm, not no cost. Not tested: harm on Sonnet, and one-line questions or small\nedits with the section. The tasks, the second skills and the section were written for these tests by the same author, with\nmodel help; the section's table grew from one task's failed runs; and each comparison had 4 to 8 runs a task.\n\n**A team's own skills among many public ones.** Twelve skills written for the test as one team's house rules (each rule\nwith an ID, some of them in reference files) sat among 151 and among 897 public skills. Each of 24 tasks, plans and reviews,\nneeded three of the rules from two or three of the skills; the count is rules cited in the answer, 144 for each setup, on\nSonnet. With no step in `CLAUDE.md`, Claude Code followed 32 rules at 151 skills and none at 897, where it called no skill in\n48 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\nlookup 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\none difference these runs show. Between the plain sentence and the lookup step they show none (the team's skills had names\nthat 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\nrule fitted to a gap of that size and so chosen after seeing it: the same 24 tasks at 897 skills, three runs each, the\nlookup step against the same step plus the paragraph that now ends the block above. Rules followed: 144 against 182 of 216;\nlook 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\nfound either way (61 against 63 of 72); the gain was the second skill (40 against 54) and the rules one skill points to in\nanother (43 against 65). In 26 of 72 runs the lookup step alone looked a second time too.\n**The lookup step in these runs is not the block above.** It is the test's own wording, written for plans and reviews:\n\"Before you write a plan or a review. First read the request and every file it names. List the things, activities, materials\nand technologies that appear in them. Look all of them up in one plain command, one --phrase for each. Open every listed\nreference file that fits; open every listed skill that fits, and read the reference files in its folder that fit.\" The block\nabove, put on the same 24 tasks at 897 skills the same evening (two runs each), followed 46 of 144 rules, 32%, where that\nstep with the same last paragraph followed 84%; without its last paragraph, 16 of 144 against the step's 67%. The loss is\nbefore 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\n(21 of 48 without the last paragraph), and 15 of the 27 runs that did look without it typed only \"code review\" or\n\"step-by-step plan\", the kind of document, which is what the block's \"what the finished thing is called\" asks for. Once a\nneeded skill was listed, the block's runs followed it about as often as the step's. That block was written for tasks that\nedit, and these make no edit.\n**Two sentences of the block changed on 2026-11-14.** \"Run it as a command of its own, not joined to other commands\" was\nadded, and \"Open every listed skill that fits\" became \"Read every listed skill that fits to the end\". Without the first\nsentence Claude mostly put the lookup in one command with other things (a `cd`, a `cat` of the task's files, a `| head`),\nand a harness that refuses part of such a command refuses the lookup with it. On 27 of the public benchmark's tasks\nbelow, skills not installed, one run each, with the rule fixed before the runs: a lookup joined to other commands in 25\ntasks without the sentence and in 0 with it; the needed skill opened in 20 and 18 tasks (the rule allowed 3 fewer; 38\nand 36 over this round and an earlier one on the same tasks); opens that showed at least half of the skill 14 and 17.\nOn the 24 plan and review tasks it followed 99 of 144 rules (the block before the change 84 with the earlier finder and\n91 with this one), reviews 46 against 32. What this does not show: the measure was chosen after the earlier round on\nthe same tasks had shown the difference, so this is a repeat, not a new finding. The cost of a joined lookup was small\nin these runs: every refusal was for the command joined to the lookup, 4 of the 5 refused tasks retried and opened the\nskill, and with the sentence Claude ran the same file reads as a call of its own, so no calls were saved. Two runs\nwith the sentence made no lookup at all, none without it, and skills other than the needed one were opened in 7 runs\nagainst 4. The runs used a short command name in place of the `python3` path above. The two sentences were not tested\napart.\n\n**The block reworded.** The block above borrows the step's wording: read the files first, list what is in them, look it all\nup in one command, open every listed skill and reference file that fits. One wording was tried, with rules fixed before the\nruns. 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\nbehind 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\n$0.15. On the 12 review files given as tasks that edit (\"fix what is wrong in this file\"), both blocks looked skills up\nbefore 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\nallowed 6 needs, and no gain. Neither looked anything up for four one-line questions (0 of 8 runs each). It is still below\nthe test's own step (84 against 119 of 144 on the same two repeats). Nearly all of that gap is needed skills never listed:\nits runs type about half as many phrases, mostly two words long where the step's runs often type one; 9 of 24 review runs\nlooked up before reading the file, typing \"code review\"; and 7 review runs stopped after a first lookup that listed no team\nskill. Limits: the wording was written after reading these tasks' runs, so this is not a test on new tasks; the earlier\nblock's plan and review runs were made the evening before, not side by side; its answers cite nearly twice as many rule IDs\n(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\nrules allow, where the earlier block lost a few runs to refused loops.\nAt 897 skills the first lookup, typed as about seven phrases in one command, listed the needed skill for fewer than half the\nneeds: skills that hold many common phrases took the ten rows. Since then each phrase takes a row in turn. Replayed on the\nrecorded first lookups, that lists the needed skill for 236 of 384 needs against 166, in output of the same size. In new runs\nat 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\nskills it was 125 against 131 of 144, the size of the difference between two days of the same setup. Once a skill was listed,\nits rule was followed in about 96% of cases under either order. Showing more rows, more rows for each phrase, or more of the\nreference-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\nnot listed, no typed phrase matches the skill for 54, and for 33 the phrase is only in a reference file; those take other\nphrases or a second lookup, not another order. One invented team, one model, tasks written to fit these rules.\n\n**Skills the session already lists** gain little. Three skills the session lists by name alone, five Sonnet runs each, with\nand without the instruction: the model opened the right skill in all fifteen runs either way, because the names say what\nthe skill does and it calls the skill by its name. So that test shows no gain from the finder for readable names, and no\nharm. Name-only skills whose names say nothing are untested. For skills that keep their description, the runs without and\nwith 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\nskills are on disk (a marketplace or a cloned repo) but not installed.\n\n**On a public benchmark, with no model.** This benchmark scores the `--task` ranker, not the `--phrase` lookups the\n`CLAUDE.md` block uses. SkillRet ([arXiv 2605.05726](https://arxiv.org/abs/2605.05726)) asks a ranker to\nfind the skills each of 4,392 requests needs among 6,006 public SKILL.md files. The finder's `--task` ranker scores NDCG@10\n58.78 (how high the needed skills sit in the first ten, out of 100), against 51.69 for the benchmark's own BM25 keyword\nbaseline, whose rerun here gives the paper's numbers exactly; off-the-shelf embedding models in the paper reach 70.26, but\nneed a model, and the finder uses none. The lead\nover BM25 comes from requests that need two or three skills; on the 2,143 that need one, there is no measurable difference.\nThe requests were written from each skill's name and description, which suits the weight the finder puts on the description.\nIt does not test whether Claude runs the finder or opens what it finds. [`bench/skillret/`](https://github.com/ydmitry/skill-finder/blob/main/bench/skillret) reruns it on a\nlaptop in about a quarter of an hour, with no API key.\n\n```\npython3 scripts/find_skills.py --phrase \"implementation plan\"           # exact phrase in every SKILL.md, then its reference files\npython3 scripts/find_skills.py --task \"heap snapshot memory leak\"        # keyword ranking\npython3 scripts/find_skills.py --list                                   # the whole inventory\npython3 scripts/find_skills.py --toc [FOLDER|SKILL] [--kind names|sentence|description|headers|files]   # tables of contents\npython3 scripts/find_skills.py --phrase \"...\" --toc   # the hits as sections (SKILL.md only)\npython3 scripts/find_skills.py --enable NAME --into DIR                 # copy a skill into DIR/.claude/skills for one run\npython3 scripts/find_skills.py --phrase \"...\" --only DIR                # search only the skills in DIR, as in the example\n```\n\n`--phrase` is the recommended lookup and the one the `CLAUDE.md` block uses. It lists the best 10 skills; when more hold the\nphrase, it says how many and that `--limit 40` lists more. Quotes are optional for the words that follow it after a space\n(`--phrase release notes` is one phrase; another `--phrase` adds a second). `--phrase` and `--task` leave out the finder\nitself, 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\nits name with `scripts/find_skills.py` beside it); `--list` and `--toc` without `--phrase` still show it. `--toc` (every skill on one line,\ngrouped by folder) is an optional way to browse. In an unpublished pick-only test (48 requests over one machine's 264 skills;\nSonnet read a whole table and named up to three skills),\nno table put the right skill among its picks more often than `--phrase` output did (43 of 48). The table with whole\ndescriptions matched it, 43, at about seven times the cost; the tables with names, first sentences (the default) or headers\nhad 33, 34 and 40.\n\n`SKILL.md` is the skill: it tells Claude how to search, read the best matches and their reference files, and report which\nskill to use and how. `scripts/find_skills.py` is the finder.\n\n```\npython3 -m unittest discover -s tests\n```\n\n`tests/test_ranking.py` holds the golden queries; `tests/fixtures/skills` is the small skill set they run against.\n\nExperimental. The finder lists candidates by keywords or by an exact phrase; it does not decide. Experiments on whether a worker\nopens the right skill (not part of this repository) found that where the instruction to search sits matters, and that the\n\"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\nagainst 9) but did not get more tasks done (8 against 9). `TODO.md` lists what is open.\n\nMIT", "url": "https://wpnews.pro/news/attempts-to-improve-skill-discovery-in-claude-code", "canonical_source": "https://github.com/ydmitry/skill-finder", "published_at": "2026-11-18 13:33:05+00:00", "updated_at": "2026-11-18 13:45:56.224912+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "large-language-models"], "entities": ["Claude Code", "Anthropic", "skill-finder", "ydmitry", "Haiku", "Sonnet", "Opus"], "also_reported_by": [], "takeaway": "Adding a CLAUDE.md paragraph that tells Claude Code to grep ~/.claude/skills for two-to-three-word phrases before writing, and to re-run the lookup after each file it reads, lifted correct skill opening from 2/58 to 47/58 tasks on Haiku and 7/58 to 40/58 on Sonnet.", "recommendation": {"advice": "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.", "playbook": "agent-architecture", "playbook_url": "https://wpnews.pro/playbooks/agent-architecture"}, "alternates": {"html": "https://wpnews.pro/news/attempts-to-improve-skill-discovery-in-claude-code", "markdown": "https://wpnews.pro/news/attempts-to-improve-skill-discovery-in-claude-code.md", "text": "https://wpnews.pro/news/attempts-to-improve-skill-discovery-in-claude-code.txt", "jsonld": "https://wpnews.pro/news/attempts-to-improve-skill-discovery-in-claude-code.jsonld"}}