Sync Project Knowledge

2.5 Discover Agent Skills and optional MCPs for newly added tools

Run only when dependency manifests changed or the diff clearly adds a significant external tool. Skip ordinary utility libraries unless they define a durable workflow or integration.

• Identify newly added significant packages/tools from the manifest diff, not the full lockfile: framework, router, styling/UI kit, database, ORM/query layer, auth/session, payments, email/notifications, storage/uploads, search, queue/background jobs, AI provider/vector DB, browser/runtime testing, observability, hosting/deploy. Include package names and common aliases from manifests. Do not stop after the first technology.

• Filter out anything already covered by installed skills, connected MCPs, or AGENTS.md declined entries.

• Ask before you search.

  <!-- TOOL-CONSENT:START (identical in /architect, /audit and /sync; edit all or none) -->

  Asking is mandatory. Searching is not. Nothing is searched, fetched, installed, or spawned for Agent Skill and MCP discovery until the engineer has picked. Offer four choices: find them for me, I will name the ones I want, no and record the decline, or not now. Only the first may run a search command. Never silently skip the offer, and never run a search before the engineer agrees to one.

  <!-- TOOL-CONSENT:END -->

  Name the tools this change added, say in one line that an Agent Skill gives the agent that tool's real conventions and an MCP server gives it live access to the real system, then ask: "Want me to find Agent Skills and MCP servers for the tools this change added?" (header Agent skills), with Yes, find them for me (recommended) · I'll name the ones I want · No, skip it · Not now, later. On Yes continue below. On I'll name the ones I want, take the list and go straight to the install step, searching for nothing. On No, skip it run nothing and record the decline. On Not now, later run nothing and note the candidate tools in the report.

• Isolate the searches in a read only subagent (capability first, only after Yes). Hand the remaining set to a discovery subagent rather than searching on the main thread: spawn it in the background (it does not block) if your agent supports that, else blocking; set its model explicitly to a fast, low cost tier (do not inherit the session model; on Claude Code spawn it as the researcher subagent type, which pins the model); it returns only the compact candidate list. This keeps the search output out of /sync's bounded context. No subagent → search inline; no search capability → skip and note it. The offer panel stays on the main thread.

• For each remaining item, run npx skills find <tool-or-package>; if weak, retry aliases from package/org names. Collect every credible Agent Skill candidate and confirm with npx skills add <owner>/<repo> --list when practical. If the CLI is interactive/unavailable, search "<tool>" "agent skill" and confirm before offering.

• MCP search is optional: connector list first, else "<tool>" "MCP server" per item. MCP is recommended upside, not required.

• Keep discovery capped and cacheable: max 5 web searches and 8 fetched pages total, official registry/docs first. Reuse docs/.agent-cache/tool-discovery/<slug>.md when under 30 days old, after filtering installed/declined items.

• Offer all Agent Skill matches in one multi select panel, grouped by technology: "Install relevant Agent Skills for newly added tools?" plus skip/decline. Then offer MCPs separately: "Optional MCP servers that could help these tools" plus skip/decline. Never install or connect automatically.

• Install selected skills with npx skills add <owner>/<repo> -y. For MCPs, point to the user's connector/MCP settings; once connected the tools are used automatically.

• Carry the result as INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE, and DECLINED_TOOLS_OR_NONE and record durable lines in the right AGENTS.md file when you write. If nothing was found or no capability exists, treat as none.

3. Do the maintenance (main thread)

The main thread does the maintenance itself; it never hands the AGENTS.md / scope / spec status edits to a subagent. Read agent-prompt.md now (only now, at write time) and follow it exactly; it is authoritative for the maintenance rules. The diff reading is the one thing you may offload, and only for a large change set, to a read only scout subagent on the cheapest model (Claude Code: haiku) that returns a compact map. Stay within the same boundaries the old tool grant expressed: Edit existing docs, scope, and spec **Status**: lines; Write strictly for a net new area nested AGENTS.md; no root creation, no spec content edits (Status line only), no shallow nested docs for established areas (these are rules in agent-prompt.md).

The inputs to apply:

1. MODE, BASE, MERGE_BASE, CHANGED_FILES (name status changed source list), DIFF_COMMAND (exact git diff command)
2. DELETED_PATHS (deleted paths, for orphan cleanup)
3. ROOT_AGENTS_MD (root AGENTS.md contents), NESTED_PATHS (nested AGENTS.md paths)
4. SPEC_PATHS (all spec paths, for Status line reconciliation and staleness flagging)
5. FILE_TO_CONTEXT_MAP (changed file → nearest context file)
6. SCOPE_PATH_OR_NONE (relevant workspace scope path(s), not all of docs/scope/; also the source of each linked feature's status for spec Status line reconciliation)
7. INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE, DECLINED_TOOLS_OR_NONE from Step 2.5

4. Relay the result

If the maintenance failed or produced no parseable summary, report that and do it again, don't fabricate a result (a genuine NOTHING_TO_SYNC is a valid success; a crash or empty output is not). Otherwise relay the compact summary:

Lead with what it reconciled in one line; then list only what needs the engineer (per docs/conventions.md). The edits themselves are in the files. Template:

## /sync complete · reconciled <N> changed files

**Updated <AGENTS.md files · scope features · spec statuses> to match the diff.**   (or "everything already current, nothing to sync")
Heads up (need you):
- Stale spec → /architect: `<file>` (<why, or a status mismatch /sync couldn't safely resolve>)
- Assumed, not ratified → /architect: `<file>` (<feature>; owes ratification, doesn't block `done`)
- Context gap → /audit: `<area>` (established area /sync can't document from the diff alone)
- Conflict, decide manually: `<path>` (<curated content that would need rewriting>)

Drop any Heads up bullet with no items, and drop the whole Heads up block if there are none. What /sync did (AGENTS.md lines, scope ticks, orphan cleanup, status reconciliation) is in the files; don't list it. /sync does not run /architect or /audit for you; it points, you decide.

Subagent prompt template

See agent-prompt.md.