Summary
Follow-up to d266380d (infer skills search plus bounding the AVAILABLE SKILLS block). Two gaps in docs/skills.md that the change surfaced.
1. Trust model for on-demand catalog downloads. The doc explains that catalog skills are fetched on activation, but not who may trigger that or what gates it. The actual behaviour (buildActiveSkillInfo, internal/agent/agent_utils.go):
- A catalog skill downloads the moment a prompt explicitly names it (
/rust, or "use the rust skill"). The model cannot trigger this on its own, since catalog entries are listed to it without a path.
- In chat the install is confirmed by the user first (
ChatMessageProcessor.confirmCatalogInstall).
- Headless (
infer agent, piped infer chat, channels, heartbeat) downloads immediately with no prompt, by design: there is nobody to ask.
- The download is not a
domain.Tool, so tools.safety.require_approval and approval_behaviour do not apply. Notably approval_behaviour: block does not prevent it.
- Under channels the "user" doing the triggering is a remote sender.
2. The catalog.json schema. agent.skills.repository now lets anyone serve skills from their own fork, but the registry contract is written down nowhere: top-level version / release / updated / skills, per-entry name / description / source / vendor / license / tags / categories / homepage, and which of those the CLI actually reads.
Acceptance Criteria
Out of scope
Whether the headless path should route through config.ResolveApprovalDelivery (IPC-approved under the channel manager, blocked in CI) is a behaviour change, not a documentation one. File separately if wanted.
Note
agent.skills.discovery.registry_url was removed in bb3d0be4 before it ever shipped on main, so agent.skills.repository is the only knob to document. It only ever redirected the index while the bodies still resolved against repository.
Summary
Follow-up to d266380d (
infer skills searchplus bounding the AVAILABLE SKILLS block). Two gaps indocs/skills.mdthat the change surfaced.1. Trust model for on-demand catalog downloads. The doc explains that catalog skills are fetched on activation, but not who may trigger that or what gates it. The actual behaviour (
buildActiveSkillInfo,internal/agent/agent_utils.go):/rust, or "use the rust skill"). The model cannot trigger this on its own, since catalog entries are listed to it without a path.ChatMessageProcessor.confirmCatalogInstall).infer agent, pipedinfer chat, channels, heartbeat) downloads immediately with no prompt, by design: there is nobody to ask.domain.Tool, sotools.safety.require_approvalandapproval_behaviourdo not apply. Notablyapproval_behaviour: blockdoes not prevent it.2. The
catalog.jsonschema.agent.skills.repositorynow lets anyone serve skills from their own fork, but the registry contract is written down nowhere: top-levelversion/release/updated/skills, per-entryname/description/source/vendor/license/tags/categories/homepage, and which of those the CLI actually reads.Acceptance Criteria
docs/skills.mdstates the five trust-model points above, so anyone running a CI or Telegram profile knows what a prompt containing/some-skillcan cause.docs/skills.mddocuments thecatalog.jsonschema, marking which fields the CLI reads today (nameanddescriptionper entry,releaseandupdatedfor the search header) and which are ignored.https://raw.githubusercontent.com/<repository>/main/catalog.jsonis documented as the single source for both the index and the skill bodies.Out of scope
Whether the headless path should route through
config.ResolveApprovalDelivery(IPC-approved under the channel manager, blocked in CI) is a behaviour change, not a documentation one. File separately if wanted.Note
agent.skills.discovery.registry_urlwas removed in bb3d0be4 before it ever shipped onmain, soagent.skills.repositoryis the only knob to document. It only ever redirected the index while the bodies still resolved againstrepository.