Skip to content

docs(skills): make embedded skill descriptions trigger-rich so the #271 routing directive works out-of-box #299

Description

@initializ-mk

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:

  • weatherWhen the user asks about the weather, forecast, or temperature for a place, fetch current conditions and the forecast.
  • tavily-searchWhen the user asks to search the web / look something up / find current information online, run a Tavily web search.
  • k8s-incident-triageWhen 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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationforge-cliAffects the forge-cli command-line tool (init, run, build, mcp commands)

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions