[DOCS] Clarification needed: What defines the "active" boundary for a skill's scoped configuration?

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/skills#frontmatter-reference

Section/Topic

Skills Front matter reference

Current Documentation

_No response_

What's Wrong or Missing?

he custom slash commands documentation describes skill-level configuration options like allowed_tools and model that
apply while a skill is active. However, the documentation does not clearly define what "active" means, particularly for
skills that describe multi-turn workflows.

The question

For a single-turn skill (e.g., /commit), the boundary is intuitive — the skill is active from invocation until Claude
produces a final response with no pending tool calls. The allowed_tools and model constraints apply for that entire
agentic loop, and then control returns to the user.

But skills can also describe multi-turn workflows that require user input at intermediate steps. For example:

  # .claude/commands/refactor.md
  ---
  allowed_tools:
    - Read
    - Grep
    - Glob
    - Edit
    - Bash
  model: claude-sonnet-4-6
  ---

  1. Analyze the target module and identify refactoring opportunities
  2. Present a refactoring plan to the user for approval
  3. After user approves, implement the changes
  4. Run the test suite
  5. Present a summary and ask the user to review

Steps 2 and 5 require user responses, making this a multi-turn conversation. In this case:

• When does the skill stop being "active"?
• Do allowed_tools and model constraints persist across all turns until the workflow is "done"?
• If so, how is "done" determined — is there an implicit or explicit signal?
• Or do the constraints only apply to the first turn (the initial invocation), while the prompt text persists in context

for subsequent turns without the scoped configuration?

Why this matters

1. Security/safety: If allowed_tools is being used to restrict a skill (e.g., a read-only review skill that only allows

Read, Grep, Glob), it's important to know whether that restriction holds across the full workflow or only the first turn.
A user authoring a skill for their team might assume the restriction applies throughout, when it may not.

1. Model override behavior: If a skill specifies model: claude-sonnet-4-6 for cost/speed reasons, does that override

persist for all turns the skill is "driving", or only the first?

1. Skill authoring guidance: Skill authors need to understand the execution model to design skills correctly. Should

multi-turn workflows be broken into separate single-turn skill invocations? Or can they rely on scoped configuration
persisting?

Suggested Improvement

It would be helpful to have documentation clarify:

• The precise definition of a skill's "active" lifecycle
• Whether scoped configuration (allowed_tools, model) applies per-turn or across the full multi-turn workflow
• If multi-turn, what determines the boundary (heuristic, explicit signal, end of conversation, etc.)
• Best practices for authoring multi-turn skills with scoped configuration

Impact

High - Prevents users from using a feature

Additional Context

_No response_