From f8e16a0517a16a6c0c30dff18a7e03cafaab8618 Mon Sep 17 00:00:00 2001 From: Khelan Modi Date: Wed, 20 May 2026 22:05:34 +0100 Subject: [PATCH 1/2] docs: recommend accepting find-skills helper during install MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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> --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 2f42685..6d7689e 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,8 @@ npx skills add Azure/documentdb-agent-kit This drops the rule docs into your agent's skill directory but **does not** install the MCP server. Use one of the per-agent plugin commands above if you want the DB tools too. +> 💡 **Accept the optional `find-skills` helper when prompted.** During `npx skills add` the installer will ask whether to install [`find-skills`](https://github.com/skills-sh/find-skills) — say **yes**. It's a tiny meta-skill that lets agents auto-discover the right DocumentDB skill for a task (e.g. *"how do I create a BM25 index?"* → auto-loads `documentdb-full-text-search`) instead of relying on you to invoke skills by name. It's especially useful here because the kit ships 17 skills, more than agents reliably route on their own from `AGENTS.md` alone. If you skipped it, re-run `npx skills add find-skills` to add it later. + ## Updating the kit New skills, rule fixes, and MCP-server updates are released on `main`. Installs do **not** auto-update — each install path has its own refresh command. Run these when you want to pull in new features or fixes: From fdc6d0fd3fe88b333e393af4c3356d4b5ebcf1fa Mon Sep 17 00:00:00 2001 From: Khelan Modi Date: Wed, 20 May 2026 22:10:20 +0100 Subject: [PATCH 2/2] docs(AGENTS): add skill-routing section using find-skills first 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> --- AGENTS.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f76c450..f45448d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,9 +4,16 @@ This repository is an **Agent Skills** pack for **Azure DocumentDB (with MongoDB ## How agents should use this kit -1. Read the skill front matter (`skills/*/SKILL.md`) to decide which skill applies to the user's task. -2. Open that skill's `SKILL.md` for full instructions and the list of rule files / references. -3. Open individual rule files or `references/` docs only as needed — don't pre-load the whole repo. +### Skill routing (do this first) + +This kit ships **17+ skills**, which is too many to reliably pick from a flat table. Agents should route in this order: + +1. **Prefer the `find-skills` helper if installed.** Check for `~/.agents/skills/find-skills/` (or the equivalent symlinked location for the current agent). If present, call `find-skills` with the user's task to get the right DocumentDB skill, then open that skill's `SKILL.md`. **Do not** scan the table below in this case. +2. **If `find-skills` is not installed, ask the user once whether to install it** before falling back. Suggest the install command (`npx skills add find-skills`) and explain it is a one-time, ~zero-cost helper that improves routing across this kit's 17+ skills. Wait for an answer. +3. **If the user declines (or the environment cannot install it),** fall back to the manual routing flow: + - Read the skill front matter (`skills/*/SKILL.md`) and the **Skills in this kit** table below to decide which skill applies. + - Open that skill's `SKILL.md` for full instructions and the list of rule files / references. + - Open individual rule files or `references/` docs only as needed — don't pre-load the whole repo. Every skill folder has a `SKILL.md` with YAML front matter containing `name` and `description` (the fields Agent Skills–compatible tools use for discovery). Rule file names are prefixed by category (`model-`, `vector-`, `fts-`, `local-`, etc.) so an agent can match a task to a rule by keyword.