Tools

Skill Tool

Tool that exposes the live Skill catalog, activates allowed Skills, and reads their UTF-8 package files. skill is directly configurable through Tool Access Policy and seeded default-on in the Project Tool Whitelist (PROJECT_DEFAULT_ALLOWED_TOOLS).

Interfaces

• Tool name: skill.
• Registration: register_skill_tool(registry, resolve_registry, refresh_skills) registers the Tool. resolve_registry maps (skill_project_id, agent_id) to the live registry a call uses; refresh_skills rescans Skills from disk (wired to Runtime.reload_skills_async, invoked once on a named Skill miss). Registry resolution, package reads, resource scans, and catalog projection use the Tool worker boundary; the async Runtime refresh builds its replacement registry in a worker and applies registry/cache/System Prompt mutations back on the Event Loop.
• Schema: one flat model-facing object with optional non-blank name and optional file_path; no arguments list the live catalog, name alone activates, and name plus file_path reads. file_path accepts SKILL.md or a relative path below scripts/, references/, or assets/ and is handler-required whenever provided. The schema omits additionalProperties; the handler remains authoritative for unknown arguments and field dependencies.
• Display: named calls use name or the support-file path as their primary; a successful no-argument catalog call derives an exact presentation-only results count from its count; failures publish no count.
• ToolContext.activate_skill(name, content) -> bool | None - dedup-only session hook (ChatSession.register_skill_activation): True fresh, False already active, None no hook (treated as fresh). Nothing is persisted through the hook - the tool result itself is the durable carrier.

Conventions

• skill is governed by Tool Access Policy plus the scoped registry's Skill policy: the Tool policy decides whether the capability is offered, while the Agent's allowed_skills filters listing, activation, and reads from the ordinary shared pool. Agent-private Skills and the effective Skills granted by an active Project Context are always allowed inside that Identity-scoped registry; Project disables and shared-Skill opt-ins decide the Project grant. The no-argument result groups the current live catalog by origin.
• The activation Result IS the durable carrier. A fresh skill(name) activation returns data: {name, status: "loaded", content, resource_files?, environment_access?}. content is only the SKILL.md instruction body after complete YAML frontmatter removal; it contains no <skill_content> wrapper, directory preamble, resource block, or environment notice. resource_files, when present, is {guidance, files} and tells the Model these are additional Skill files to read only when the SKILL.md instructs it; scripts are absolute paths for direct bash execution, while references/assets stay relative for this Tool. A {baseDir} marker in the body is still substituted with the absolute Skill directory (see skills.md). Sessions reconstruct the internal wrapped activation context from the structured Result for same-epoch dedup. At a committed Compaction boundary the checkpoint retains an instruction-free digest at the same Tool Result id, while the original durable carrier remains retrievable through history.
• When the activated Skill declares one or more vBot env requirements, environment_access carries the Bash guidance as a sibling of content. It lists the newly usable names and explains that each Bash call must request them through env_keys; the internal trigger/Compaction context wraps the same text before the instructions. The field is included even when permanent Agent grants already caused the System Prompt's tool:bash block to explain the general mechanism. Project Context grants only Skill visibility; requirement checks and Bash environment grants remain unchanged. File reads remain non-activating and do not receive this field.
• File reads are relative and non-activating. skill(name, file_path) confines the path to the resolved Skill directory and supported package shape, rejects missing or non-UTF-8 files, and returns data: {name, status: "file_loaded", file_path, content}. Reading file_path: "SKILL.md" returns the complete document including frontmatter and is the required source for a complete skill_manage edit; activation by name returns only the instruction body. The result contains no absolute path and does not call the Session activation hook, so support-file reads remain separately trackable without affecting activation dedup.
• An already-active Skill returns a short stub (status: "already_active", message, no content) only within the current Compaction epoch. A committed checkpoint resets dedup, so the next skill(name) call returns a fresh loaded carrier; aborted Compaction does not.
• Rescan on name miss. When a requested name is absent from the resolved registry, skill calls refresh_skills once and re-resolves before giving up, so a Skill hand-dropped after the Session registry was cached can activate or serve a file without a restart. A genuinely unknown name still returns skill_not_found after that single rescan. The current Prompt-Epoch Catalog is deliberately left untouched - only the live lookup is refreshed, with no availability note; successful Compaction later performs the catalog refresh. A no-argument catalog call reads the resolved live registry without an additional rescan.

Constraints & Gotchas

• The loaded envelope shape (data.name / data.status == "loaded" / data.content, plus optional data.resource_files / data.environment_access) is a persisted read contract: core/sessions/ parses it (skill_tool_activation) for same-epoch dedup, Compaction names/digest projection, environment grants, and usage statistics. Renaming those fields breaks activation scanning over current-format Sessions.
• When skill is excluded or denied by Tool Access Policy, listing, activation, and file reads are all unavailable; when it is available, an empty allowed_skills yields an empty catalog and blocks activation/read access.
• Keep all three modes in this one flat optional-field contract: {} lists, {name} activates, and {name, file_path} reads. Do not add an action discriminator or split catalog listing into a companion Tool.