# Tools > Skill Tool - Skill: `vironnimo/tools` (Agent Skill, multi-file: 28 files) - Install (CLI): `npx skillmds@latest add vironnimo/tools` - Raw SKILL.md: https://api.skillmd.com/api/skills/vironnimo/tools/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Vironnimo (https://skillmd.com/u/vironnimo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/vironnimo/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 `` 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.