Three Fields That Turn a Prompt Into a Safe Workflow

A SKILL.md file supports YAML frontmatter with three configuration fields that commands lack: context: fork, allowed-tools, and argument-hint. Each solves a specific problem. Getting them right — including knowing when NOT to use them — is the difference between a well-configured skill and one that is either dangerous or needlessly slow.

context: fork — Isolation, Not Sandboxing

Fork runs the skill in an isolated sub-agent. The main session receives only a summary when the skill completes. All of the skill’s verbose output — file listings, analysis details, exploration results — stays in the fork and never enters the main conversation context.

This is critical for verbose skills. A codebase analysis skill that produces 20,000+ tokens without fork will fill 40% of the main context. Subsequent commands degrade because the conversation is cluttered with stale analysis data. With fork, the main session stays clean.

What fork isolates: Conversation context. The model’s memory of the skill’s detailed output does not transfer to the main session.

What fork does NOT isolate: The filesystem. A forked skill with Write access creates real files that persist after the fork ends. Fork is about context isolation, not filesystem sandboxing. A skill that generates verbose analysis AND writes result files can fork without losing the file output — the files stay, the verbose reasoning does not.

When Fork Is Wrong

Fork adds overhead and returns only a summary. This makes it wrong for:

• Quick operations — A 2-second lint check does not need fork. The overhead is disproportionate to the work.
• Direct edits the user needs to see — A /quick-fix skill with fork applies the fix in a sub-agent. The main session does not see what changed, forcing the developer to manually verify. If the user needs to see the exact change, keep it in main context.
• Skills that establish session context — If the skill’s output is needed for follow-up questions or subsequent commands, fork discards it. A short skill that sets up important context should not fork even if its output is small.

Data from one team’s audit:

Fork skills consuming 35%+ of context. Remove fork from fast, low-output skills where the overhead is not justified. Leave alone skills at 8% that have minimal impact.

allowed-tools — Deterministic Safety

Without allowed-tools, a skill inherits every tool including Bash. A migration skill with instructions saying “Only generate migration files, do not execute” can still execute a DROP TABLE if the model decides execution would be helpful.

This is not a bug. Prompt instructions are probabilistic. The model balances them against its own judgment. allowed-tools is deterministic — if Bash is not in the list, it does not exist in the skill’s environment. The model cannot call a tool that is not there.

---
allowed-tools:
  - Read
  - Grep
  - Glob
---

This skill physically cannot write files, edit files, or execute commands. No amount of creative reasoning by the model can override it.

Principle of least privilege: List only the tools the skill actually needs. A read-only analysis skill gets Read, Grep, Glob. A file generation skill gets Read, Write. Omitting allowed-tools entirely — even for a skill that “only needs Read” — is an anti-pattern because it gives unrestricted access including Bash.

Stronger prompt wording (“ABSOLUTELY NEVER execute”) does not change the fundamental limitation. It is still a probabilistic instruction competing against model judgment. allowed-tools is the only guarantee.

argument-hint — Prompt for Parameters

When a skill requires input (a file path, module name, directory), developers frequently invoke it without providing the argument. One team found 40% of invocations lacked the required module path, leading to wrong-directory analysis or unclear errors.

---
argument-hint: "Provide the module path (e.g., src/auth or src/payments)"
---

When the developer invokes the skill without arguments, Claude Code displays this hint before the skill starts. It is a UX improvement at the configuration level — no round-trip interaction with the model, no silent defaults that might be wrong.

An alternative — a prompt instruction telling the skill to “ask the user if no path is provided” — works but adds a round trip. The argument hint provides guidance before execution starts.

Combining All Three

A security vulnerability scanner needs: verbose exploration output (fork), read-only access (allowed-tools), and a directory path input (argument-hint).

---
context: fork
allowed-tools:
  - Read
  - Grep
  - Glob
argument-hint: "Provide the directory path to scan (e.g., src/api)"
---

Three requirements, three fields. Each addresses a specific concern deterministically:

1. Fork prevents 20,000+ tokens of scan output from filling the main session.
2. Allowed-tools guarantees no file modifications or command execution.
3. Argument-hint ensures the developer provides the target before the scan begins.

What CLAUDE.md Cannot Do

CLAUDE.md is for always-loaded standards. Skills are for on-demand workflows. Putting a security audit workflow in CLAUDE.md means its instructions load for every interaction — wasting context when the developer is just writing code.

Conversely, putting coding standards in a skill means they only apply when explicitly invoked. Standards must be continuous; workflows must be on-demand. Use the right mechanism for each.

Frontmatter Fields That Do Not Exist

These are frequently proposed but are not valid SKILL.md frontmatter:

• max-tokens — Not a field. Use fork for output isolation.
• safe-mode — Not a field. Use allowed-tools for safety.
• verbose: false — Not a field.
• timeout — Not a field.
• output-limit — Not a field.
• context: main — Not a field. The default (no context field) runs in the main session.

One-liner: context: fork isolates verbose output (not files), allowed-tools provides deterministic safety (not probabilistic instructions), and argument-hint prompts for required input — use each for its specific purpose, not as blanket defaults.