docs: recommend find-skills + add agent-side routing protocol#22
Merged
Conversation
The skills.sh CLI prompts users to install the optional 'find-skills' helper during 'npx skills add'. Tell users to say yes — without it, agents have to route across 17 DocumentDB skills using AGENTS.md alone, which is unreliable at this catalog size. find-skills gives agents an on-demand router so questions like 'how do I create a BM25 index?' auto-load the right skill (documentdb-full-text-search) instead of requiring users to invoke skills by name. Also adds a recovery hint for users who skipped the prompt: npx skills add find-skills Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The kit ships 17+ skills, which is too many for agents to reliably pick from a flat table. Add an explicit routing protocol to AGENTS.md so every agent that loads this kit follows the same flow: 1. If find-skills is installed -> call it for routing (don't scan the table). 2. If find-skills is NOT installed -> ask the user once whether to install it (npx skills add find-skills) before falling back. 3. If the user declines -> fall back to the manual table-driven routing that this section used to describe. Pairs with the README change in this PR that tells users to accept the find-skills install prompt: README explains it to humans, AGENTS.md explains it to the agent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
khelanmodi
changed the title
xgerman
approved these changes
May 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR ensures users and agents both get the benefit of the optional
find-skillshelper thatskills.shalready prompts for duringnpx skills add Azure/documentdb-agent-kit.Why this matters
The kit ships 17+ skills. From a flat
AGENTS.mdtable that's too many for an agent to reliably route across.find-skillsis an on-demand router that closes this gap — but only if (a) users accept the install prompt and (b) the agent actually knows to use it.This PR addresses both halves.
Changes
1.
README.md— tell users which way to answer the install prompt (1st commit)> 💡callout under the universal one-liner explaining whatfind-skillsis and why to accept it, with a recovery line (npx skills add find-skills) for users who already declined.2.
AGENTS.md— tell the agent how to route (2nd commit)find-skillsis installed → call it; don't scan the table.SKILL.md+ table flow.What this PR does NOT do
find-skillsinto this kit. It's owned by skills-sh/find-skills and bundling would create version-collision risk for users with multiple kits.mcp.json, or per-tool plugin configs. Docs-only.Diff
README.md+2 linesAGENTS.md+10 / −3 lines