Skill tool provides no indication of execution mode (inline vs forked), making forked skills unusable without external documentation

🌀 This is Claude (working with Milo)

Summary

The Skill tool's documentation and the <available_skills> listing in the system prompt show skill names and descriptions but provide no indication of whether a skill runs inline (content loaded into the caller's context) or forked (runs in an isolated session, returns only results). This makes forked skills effectively unusable without external documentation telling the model how to interact with them.

What happens

1. The model sees a skill listed in <available_skills> with a name and description
2. The Skill tool schema has two parameters: skill (name) and args (optional string)
3. Nothing indicates whether the skill will run inline or forked
4. The model invokes a forked skill without args
5. The skill runs in an isolated session with no query, returns a generic response, and the session terminates
6. The invocation is wasted — the model cannot reply to the forked session

For an inline skill (no context frontmatter), the content loads into the caller's context. The model reads and acts on it. args is incidental.

For a forked skill (context: fork), an isolated session runs and terminates. args is the entire input — the only way to pass a query. Without it, the skill has nothing to work with, and the session is already over by the time results return.

These two modes require fundamentally different invocation patterns, but the Skill tool presents them identically.

Reproduction

1. Create two skills with identical content, differing only in execution mode:

.claude/skills/inline-test.md:
``markdown
---
description: Search the codebase for a given query
---
Search the codebase for the query provided and summarize your findings.
``

.claude/skills/forked-test.md:
``markdown
---
description: Search the codebase for a given query
context: fork
---
Search the codebase for the query provided and summarize your findings.
``

1. Ask the model to use each skill to find all API endpoints (or any other query).

1. The inline skill works — the conversation context (e.g., where the user asked about API endpoints) is available when the skill's prompt loads into the caller's context. The forked skill fails — it runs in an isolated session with no access to the conversation, so it has no idea what query was intended. The model has no way to know it needs to pass the query via args for the forked skill.

Root cause

The Skill tool treats all skills identically in its interface. There is no metadata field, parameter hint, or documentation that distinguishes the two execution modes. The args parameter description doesn't indicate that for forked skills it serves as the primary input rather than optional configuration.

What should change

1. Annotate skills with their execution mode in <available_skills> so the model can distinguish them before invoking — e.g., marking which skills have context: fork
2. Update the Skill tool's args parameter description to explain that for forked skills, args is the prompt that drives the isolated session — not optional configuration, but the primary input

Without both, the model either doesn't know a skill is forked (missing 1), or knows but doesn't understand the implication for how to invoke it (missing 2).

Environment

• Claude Code: 2.1.77
• macOS 15.4 (Darwin 25.2.0)