Skip to content

Skill Tool as Enforcement: Loading Command Prompts at Runtime

Use the Skill tool to load command prompts at invocation time rather than telling agents to "read the file" -- this eliminates stale instructions, truncation, and path drift by using the canonical invocation path.

Also known as

Runtime skill loading, canonical invocation path. For the skill format itself, see Agent Skills: Cross-Tool Task Knowledge Standard. For authoring guidance, see Skill Authoring Patterns.

The Problem: Three Failure Modes of "Read the File"

Telling an agent to "read commands/deploy.md for instructions" can fail three ways:

Failure mode What happens Why it happens
Stale content Agent acts on an outdated version File read earlier; cached content reused
Truncation / paraphrase Agent follows a partial or reworded version Long files get summarized; details dropped
Path drift Agent reads the wrong file or fails to find it Working directory changed, file moved, or wrong path constructed

These failures are silent: output looks reasonable but diverges from canonical instructions, and drift compounds at scale.

How the Skill Tool Eliminates All Three

When an agent calls the Skill tool, the runtime:

  1. Resolves the canonical SKILL.md from the registered skill path -- no path construction by the agent
  2. Injects the full body into context via a controlled two-message pattern sent directly to the API (Chung, 2025)
  3. Modifies the execution context -- updates tool permissions and may switch the model

A Read call does none of these.

flowchart LR
    subgraph read ["Read-based loading"]
        A1[Agent told:<br/>'read deploy.md'] --> A2[Agent constructs path]
        A2 --> A3[Read tool returns text]
        A3 --> A4[Agent interprets text<br/>as it sees fit]
    end

    subgraph skill ["Skill tool loading"]
        B1[Agent invokes<br/>Skill tool] --> B2[Runtime resolves<br/>canonical SKILL.md]
        B2 --> B3[Full body injected<br/>into context]
        B3 --> B4[Execution context<br/>updated]
    end

    style read fill:#1a1a2e,stroke:#e74c3c,color:#fff
    style skill fill:#1a1a2e,stroke:#2ecc71,color:#fff

Why This Works: The Canonical Invocation Path

The Skill tool uses the same mechanism as human /command invocation: change a command's definition and every agent picks up the new version on the next call — no propagation, no cache invalidation. This is JIT context loading applied to agent instructions.

Progressive Disclosure Budget

Skill descriptions are capped at ~15,000 characters / 2% of the context window (Chung, 2025), creating a three-layer progressive disclosure stack:

Layer When loaded Token cost
Frontmatter description Always in system prompt ~100 tokens
Full SKILL.md body On Skill tool invocation <5000 tokens recommended
Referenced files On demand within skill execution Variable

This layering prevents the Mega-Prompt anti-pattern: instructions stay out of the system prompt until invoked.

Dynamic Context with Shell Interpolation

Skills support !`command` syntax: output replaces the placeholder before content reaches the agent, injecting live data on every invocation:

## Current deployment targets
!`kubectl get deployments -o name`

## Active feature flags
!`cat config/flags.json | jq '.enabled[]'`

Shell interpolation extends enforcement beyond static instructions: the agent receives live system state at invocation, not stale file contents from an earlier read.

When Read-Based Loading Is Appropriate

Use direct file reading when:

  • The file is data, not instructions -- configs, schemas, codebases to analyze
  • The content is one-shot -- read once at session start and won't change
  • No execution context change is needed -- reference material, not a command

Use Read to inform; use Skill tool to direct.

When This Backfires

Skill invocation eliminates path drift and per-call caching, but four failure modes take over as the skill count grows:

  • Description-match failures under load. Descriptions sit in context so the model can decide what to invoke; each is capped at 1,536 characters and the listing budget is roughly 1% of the context window. Over budget, descriptions are truncated, stripping "the keywords Claude needs to match your request" (Claude Code Skills docs). A 650-trial experiment found the recommended passive phrasing (Use when...) activates ~77% of the time, versus 100% for a directive ALWAYS invoke... (Seleznov, 2026).
  • Post-compaction drop-out. Invoked skills share a 25k-token re-attach budget after auto-compaction, filled most-recent-first; "older skills can be dropped entirely after compaction if you have invoked many in one session" (Claude Code Skills docs).
  • Opaque injection. The runtime splices the body in without surfacing it in the transcript the way a Read call does, so debugging "did the agent see the new version?" is harder.
  • Harness dependency. Skill invocation only works where the tool is exposed; Read-based instructions run anywhere.

When a playbook must never drop mid-session, prefer Read or a hook over description-based invocation.

Example

A team has a review-pr command that agents execute as part of a CI pipeline. The command definition lives in .claude/commands/review-pr.md.

Fragile approach -- instruction in the agent's system prompt:

When asked to review a PR, read .claude/commands/review-pr.md and follow its instructions.

The agent must construct the path, read the file, and decide to treat the contents as instructions. If review-pr.md is updated, agents mid-session continue using the version they already read.

Robust approach -- Skill tool invocation:

When asked to review a PR, invoke the review-pr skill using the Skill tool.

The Skill tool resolves the canonical path, injects the current version into context, and updates execution permissions. The agent cannot use a stale version because it never caches the instructions -- each invocation loads fresh.

Key Takeaways

  • "Read the file" introduces silent failures: stale content, truncation, and path drift
  • The Skill tool eliminates all three via a controlled injection path that bypasses agent-side file resolution
  • Skills modify the execution context (tool permissions, model selection) -- Read cannot
  • Progressive disclosure keeps instructions out of the system prompt until needed
  • Shell interpolation (!`command`) injects live system state at invocation time
  • Use Skill tool for directing agents; use Read for reference data
Established — multiple independent sources Last reviewed: 2026-05-27
Feedback