Design

Skill Tool — Cross-Language Design Spec

Status: Draft v1 — 2026-04-22 Implementations: TypeScript (@agent-sh/harness-skill, pending), Rust (crates/skill, pending) Scope: Language-neutral contract. Implementation files (packages/skill/ for TS, crates/skill/ for Rust) must conform.

This spec is the source of truth. Implementation-specific ergonomics are allowed; public semantics are not.

Prior art surveyed: Agent Skills open spec (agentskills.io), Claude Code Skill tool, OpenCode skill.ts, Gemini CLI activate-skill, Continue readSkill, Codex CLI core-skills, Anthropic API skill execution, and 35+ adopter harnesses. Research summary in agent-knowledge/skill-tool-design-across-harnesses.md and agent-knowledge/skill-tool-in-autonomous-agents.md.

---

1. Purpose

Expose authored skills to an LLM as a structured tool. A skill is a folder — skill-name/SKILL.md with YAML frontmatter plus optional scripts/, references/, assets/ — that encodes specialized workflows, project conventions, or compressed expertise. The tool's job is to:

1. Enumerate installed skills as a low-cost catalog (≤100 tokens per skill, always available).
2. Expand a skill's full body into the conversation on demand, exactly once per activation.
3. Enforce that skills are authored files, not runtime-generated prompts — you can commit them, diff them, review them.
4. Interoperate with the rest of the tool surface: allowed-tools, scripts invoked via bash, references opened via read.

Scope note: v1 ships the authored-skill pattern only. Runtime-learned skills (Voyager / Letta-style) are out of scope — they belong in a separate @agent-sh/harness-skill-learner adapter package if demand appears.

Enforce at the tool layer every invariant the model cannot be trusted on:

• Name matches directory. name: foo inside skills/bar/SKILL.md is rejected.
• Frontmatter validates. Malformed YAML → structured error, not silently dropped.
• Discovery paths are bounded. Only session-configured roots are scanned; no walking up to /.
• Activation is permission-gated. Every activation passes through the permission hook, carrying the skill's allowed-tools declaration as metadata.
• Trust gating for autonomous mode. Project-root skills from untrusted repos require hook approval or explicit opt-in; unsafeAllowSkillWithoutHook for fixtures.
• Dedupe. Re-activating the same skill in the same session is a no-op (returns a "already loaded" marker), not a context-bloat replay.
• Compaction-safe body wrapping. Skill bodies return wrapped in a stable structural marker so auto-compaction preserves them correctly.

Non-goals for v1:

• Subagent-forked skills (Claude Code's context: fork + agent: ). Requires our own subagent primitive, which we don't ship.
• Dynamic shell injection in skill bodies (Claude Code's ` ! ` backtick blocks). Security surface; needs careful design.
• File-path gating for auto-activation (paths: ["**/*.py"]). Requires file-context awareness we don't have.
• Model/effort overrides (model: opus, effort: high). These are harness concerns, not tool concerns.
• Per-skill hooks (skill-scoped PreToolUse / PostToolUse). Needs design round.
• Live filesystem watching for in-session skill changes. Nice-to-have; not load-bearing.

---

2. Input contract

{
  name:        string                        // required, matches an installed skill
  arguments?:  string | Record   // optional, positional or named
}

Deliberate omissions:

• No path. The tool dispatches on name, not on a filesystem path. The harness owns discovery; the model chooses by name.
• No scope. Skills are session-scoped once loaded; there's no per-turn / per-tool-call scope.
• No reload: true. Session-lifetime contract is simpler; if the skill author edits mid-session, they invalidate by re-running.
• No free-form input map. arguments is the Claude Code $ARGUMENTS / $N / $name conventions; if a skill declares named arguments in its frontmatter, the tool validates against that declaration.

Parameter validation

• name not a string, empty, or > 64 chars → INVALID_PARAM.
• name does not match /^[a-z0-9]+(-[a-z0-9]+)*$/ → INVALID_PARAM: "skill name must be lowercase-kebab-case".
• name not in the session's installed-skill catalog → NOT_FOUND, with siblings listing fuzzy-matched installed names.
• arguments is a string AND the skill declares named arguments in its frontmatter → INVALID_PARAM: "skill {name} expects named arguments: {list}".
• arguments is a map AND the skill declares no arguments frontmatter → INVALID_PARAM: "skill {name} does not accept named arguments".

2.1 Known-alias pushback

Mirrors the pattern from bash / webfetch / grep / glob. Required alias set:

• skill, skill_name, name_of_skill, slug → name
• invoke, activate, run → drop; the tool activates implicitly
• args, args_string, input, params, parameters → arguments
• context, session → drop with note "skill context is session-scoped; no per-call override"
• reload, fresh, force_reload, refresh → drop with note "skills load once per session; edit the skill file and restart the session to refresh"
• fork, subagent, isolated → drop with v1.1 note "subagent-forked skills deferred to v1.1"
• paths, scope_paths → drop with v1.1 note
• model, effort → drop with v1.1 note "model / effort overrides are harness concerns, not tool parameters"
• file, file_path, skill_path, dir → drop with note "skills dispatch by name, not path; the harness owns discovery"

2.2 Description guidance (model-facing)

Tool description must call out:

> Activate an installed skill by name. A skill is a reusable package of instructions, optional scripts, and reference docs, authored as a folder at skill-name/SKILL.md. Activating loads the skill's body into the conversation for the rest of the session. > > When to use. Activate a skill when the user's request matches its description. The catalog of installed skills, each with name and short description, is always visible in your tool-call context. If two skills plausibly apply, pick the one whose description most precisely matches. > > Idempotence. Activating the same skill twice in one session is a no-op — the body is already loaded. The tool returns a already_loaded marker so you know the content is still in context. > > Arguments. Pass arguments as a string for positional skills (those declaring $ARGUMENTS or $1 / $2) or as a JSON object for skills that declare named arguments in frontmatter. Run without arguments if the skill doesn't need them. > > Permission. Activation runs through the session's permission hook. A skill's allowed-tools frontmatter is an advisory declaration of what tools it expects to need — it does not pre-approve anything; downstream tool calls still pass the session's permission hook.

Research backing: Anthropic's Oct 2025 Agent Skills announcement emphasizes progressive disclosure ("load on demand, not always"); Simon Willison documents that skill metadata costs 50-100 tokens vs MCP's 10,000+ for identical capability exposure.

---

3. Output contract

Output is a discriminated union by kind.

3.1 kind: "ok" — skill activated, body loaded

{the parsed frontmatter, re-serialized minus body}

{the SKILL.md body — everything after the closing ---}

{optional; up to 10 sampled file names from scripts/ references/ assets/ — names only, not contents}

(Skill "{name}" activated. Body is {N} bytes. Scripts available via bash(/scripts/). References via read(/references/).)

The `` XML wrapper is load-bearing for auto-compaction: harnesses that summarize history can recognize the marker and preserve the full body verbatim (matching Claude Code's 5000-per-skill / 25000-total compaction carryforward policy).

Structured result shape (what TS/Rust return):

{
  kind: "ok",
  name: string,
  dir: string,                    // absolute path to the skill directory
  body: string,                   // the markdown body, frontmatter-stripped
  frontmatter: Record,  // parsed YAML
  resources: string[],            // up to 10 filenames from scripts/ references/ assets/
  bytes: number,
  output: string                  // the rendered … block above
}

3.2 kind: "already_loaded" — skill is in-context from a prior call

(Skill "{name}" is already active in this session. Body was loaded at turn {turn}. No new content was added.)

Structured: { kind: "already_loaded", name, at_turn }.

This is idempotence. The model may call skill with the same name twice without burning context; the second call is a short no-op hint.

3.3 kind: "not_found"

(No skill matches "{name}". Did you mean: {siblings}? Run with a listed name from the catalog.)

Structured: { kind: "not_found", name, siblings: string[] }.

Siblings are Levenshtein-ranked installed skill names (top 3, similarity threshold 0.6). Mirrors read's NOT_FOUND fuzzy behavior.

3.4 kind: "error"

Structured errors, not thrown. Format: Error [CODE]: message.

| code | When | |---|---| | INVALID_PARAM | Schema error, alias pushback, bad argument shape. | | NOT_FOUND | Skill name does not exist in any configured skill root. | | SENSITIVE | Skill dir matches sensitive-patterns (e.g. **/.env/**) and no hook approved. | | OUTSIDE_WORKSPACE | Skill dir resolved outside all configured workspace roots with no hook approval. | | INVALID_FRONTMATTER | YAML parse error, missing required fields, or constraints violated. | | NAME_MISMATCH | name: foo inside skills/bar/SKILL.md. Rejected with the path + declared name. | | DISABLED | Skill has disable-model-invocation: true and the activation came from the model, not the user. | | NOT_TRUSTED | Project-root skill from an untrusted dir; session required hook approval; hook denied or returned ask. | | PERMISSION_DENIED | Hook explicitly denied activation. | | IO_ERROR | Filesystem read of SKILL.md or resource enumeration failed. |

Error messages echo the requested name:

Error [INVALID_FRONTMATTER]: skill "my-skill" has malformed YAML frontmatter.
Path: /workspace/.skills/my-skill/SKILL.md
Reason: expected colon after 'description' on line 4
Hint: frontmatter must be valid YAML between two `---` lines at the top of the file. See agentskills.io/specification.

---

4. Frontmatter schema

The frontmatter contract is this spec's primary surface. Parity with the agentskills.io open standard plus a minimal set of extensions widely adopted in Claude Code and in the project author's own 66-file skill corpus.

4.1 Required fields

| Field | Constraint | Notes | |---|---|---| | name | 1-64 chars, ^[a-z0-9]+(-[a-z0-9]+)*$, must equal the containing directory's basename | Matches agentskills.io spec verbatim. | | description | 1-1024 chars | Must include what the skill does AND when to use it. The description drives both catalog discovery and model activation choice. |

4.2 Optional fields — standardized

| Field | Shape | Notes | |---|---|---| | version | semver string (1.0.0, 2.1.3-beta) | Not in agentskills.io spec but present in 71% of our corpus; de facto universal. Recommended for any skill shipped publicly. | | argument-hint | string, ≤ 200 chars | Autocomplete hint shown in slash-menus ([path] [--fix]). Present in 42% of our corpus. | | license | SPDX identifier (MIT, Apache-2.0) or bundled filename (LICENSE) | Per spec. | | compatibility | string, 1-500 chars | Free-form environment requirements (node >= 20, requires ripgrep). Per spec. | | metadata | object, string → string | Arbitrary client-extension key/value map. Per spec. Our parser passes through verbatim. |

4.3 Optional fields — behavior hints

| Field | Shape | Semantics | v1? | |---|---|---|---| | allowed-tools | comma- or space-separated string (Read, Grep, Bash(git:*)) | Advisory only in v1 — declares what tools the skill expects to need. See §6 for composition semantics. | yes | | disable-model-invocation | boolean (default false) | When true, only user-initiated /name invocations load the skill. Model calls to skill({ name }) return kind: "disabled". | yes | | user-invocable | boolean (default true) | When false, the skill is hidden from any slash-menu catalog the harness may render. Model-only skills. | yes | | arguments | object, declaring named positional args for $name substitution | Opt-in named-argument contract. If declared, arguments input to the tool must be an object whose keys match this declaration. | optional v1 |

4.4 Optional fields — deferred to v1.1

These are Claude Code extensions we explicitly defer. Parser must ignore unknown fields, not reject, to keep forward-compatibility with skill authors who author for multiple harnesses.

| Field | Why deferred | |---|---| | context: fork | Requires a subagent primitive we don't ship. | | agent: | Same. | | hooks | Skill-scoped hooks need a hook runtime design pass. | | model | Model choice is a harness concern, not a tool concern. | | effort | Same. | | paths | Auto-activation gating on file context; we don't track file context. | | shell | Only meaningful once we add dynamic ` ! injection. | | whentouse | The description` field carries this already. |

4.5 Parser rules

1. Frontmatter is YAML between two --- lines at the top of the file. Missing opening --- → no frontmatter (body is the whole file). Missing closing --- → INVALID_FRONTMATTER.
2. Parse YAML into a Record. Validate required fields first.
3. Validate name matches the containing directory's basename. name: foo inside skills/bar/SKILL.md → NAME_MISMATCH.
4. Normalize allowed-tools from either string or array form into string[].
5. Unknown fields are preserved in the output's frontmatter field; the parser does not reject them.
6. The body (everything after the closing ---) is stored verbatim — no markdown processing. The model sees it raw.

4.6 Canonical SKILL.md

---
# Required
name: api-conventions
description: |
  Use when designing or auditing HTTP APIs in this project. Covers endpoint naming,
  error envelope shape, pagination, and deprecation conventions. Run before drafting
  new routes or when reviewing PRs that add endpoints.

# Strongly recommended
version: 1.2.0
argument-hint: "[--audit path/to/file]"

# Pass-throughs
license: MIT
compatibility: "any node runtime"
metadata:
  short-description: "Project HTTP API style guide"
  owner: platform-team

# Advisory — v1 does not pre-approve tools; see §6
allowed-tools: Read, Grep, Bash(git log:*)

# Visibility
disable-model-invocation: false
user-invocable: true
---

# API Conventions

This project uses RESTful endpoint naming. ...

## When reviewing a new endpoint

1. Does the path use plural nouns? `/users`, not `/user`.
2. Does the response envelope match `references/error-schema.json`?
3. ...

## Scripts

Run `scripts/audit-endpoints.js ` to scan an endpoint file for convention
violations. The script prints a report; no context is consumed by the script's
source.

---

5. Workspace, discovery, and permission model

5.1 Skill roots

A session declares one or more skill roots. Each root is an absolute directory that contains skill subdirectories. Example:

session.skill_roots = [
  "/workspace/.skills",             // project skills, committed with code
  "/home/user/.claude/skills",      // user skills, personal
  "/home/user/.agents/skills"       // shared across harnesses
]

The harness controls which roots are active. The tool scans only these; no walking up to /.

Precedence. Lower-index roots shadow higher-index on

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: avifenesh
• Source: avifenesh/tools
• License: MIT

Install and usage instructions live in the source repository linked above.