Follow-up from the #298 review (closes the loop on #271).
Why
#298 added a runtime routing directive: the agent checks each installed skill's catalog description for a match before answering from its own defaults. That fix is only as good as the descriptions in the catalog — and the embedded skills (forge-skills/local/embedded/*/SKILL.md) predate the guidance. Their descriptions are exactly the capability-style the new Skill Builder prompt warns "never routes":
| Skill |
Current description (capability-style) |
tavily-search |
Search the web using Tavily AI search API |
tavily-research |
Deep multi-source research using Tavily Research API |
weather |
Get current weather and forecasts |
code-review |
AI-powered code review for diffs and individual files using LLM analysis |
web-browse |
Drive a headless browser … for sites that need JavaScript rendering |
k8s-incident-triage |
Read-only Kubernetes incident triage using kubectl … |
github |
Create issues, PRs, clone repos, and manage git workflows |
linear |
Read Linear issues, transition state, and post comments … |
| … |
(the rest under forge-skills/local/embedded/) |
These state what the skill does, not when it fires — so the shipped/out-of-box experience stays as prone to the original #271 failure as before (the agent answers from its defaults instead of routing).
Ask
Sweep the description: frontmatter of every forge-skills/local/embedded/*/SKILL.md to be trigger-rich, per the new guidance (see #298 / docs/core-concepts/skill-md-format.md#skill-activation--routing): lead with when the skill fires and name the concrete phrases/intents, then the capability.
Before → after examples:
weather → When the user asks about the weather, forecast, or temperature for a place, fetch current conditions and the forecast.
tavily-search → When the user asks to search the web / look something up / find current information online, run a Tavily web search.
k8s-incident-triage → When the user reports a Kubernetes problem (pods crashing, CrashLoopBackOff, 503s, nodes NotReady, "triage this cluster"), run read-only kubectl triage and produce root-cause hypotheses.
Constraints / notes
- Keep it one line; the parser has no length cap, but overly long descriptions bloat the catalog and the A2A Agent Card (
skills[], FWS-1) where these project verbatim — trigger phrasing is fine there, just keep it tight.
- Preserve the existing capability meaning; don't change tool names or behavior.
- No test needed beyond
forge skills validate staying green; a manual "does a natural query route to each skill now?" spot-check is the real acceptance.
Acceptance
Related: #271 (fixed in #298), #270 (Skill Builder authoring), FWS-1 (Agent Card projection).
Follow-up from the #298 review (closes the loop on #271).
Why
#298 added a runtime routing directive: the agent checks each installed skill's catalog
descriptionfor a match before answering from its own defaults. That fix is only as good as the descriptions in the catalog — and the embedded skills (forge-skills/local/embedded/*/SKILL.md) predate the guidance. Their descriptions are exactly the capability-style the new Skill Builder prompt warns "never routes":tavily-searchtavily-researchweathercode-reviewweb-browsek8s-incident-triagegithublinearforge-skills/local/embedded/)These state what the skill does, not when it fires — so the shipped/out-of-box experience stays as prone to the original #271 failure as before (the agent answers from its defaults instead of routing).
Ask
Sweep the
description:frontmatter of everyforge-skills/local/embedded/*/SKILL.mdto be trigger-rich, per the new guidance (see #298 /docs/core-concepts/skill-md-format.md#skill-activation--routing): lead with when the skill fires and name the concrete phrases/intents, then the capability.Before → after examples:
weather→When the user asks about the weather, forecast, or temperature for a place, fetch current conditions and the forecast.tavily-search→When the user asks to search the web / look something up / find current information online, run a Tavily web search.k8s-incident-triage→When the user reports a Kubernetes problem (pods crashing, CrashLoopBackOff, 503s, nodes NotReady, "triage this cluster"), run read-only kubectl triage and produce root-cause hypotheses.Constraints / notes
skills[], FWS-1) where these project verbatim — trigger phrasing is fine there, just keep it tight.forge skills validatestaying green; a manual "does a natural query route to each skill now?" spot-check is the real acceptance.Acceptance
descriptionleads with its trigger and names concrete phrases.Related: #271 (fixed in #298), #270 (Skill Builder authoring), FWS-1 (Agent Card projection).