claude-code - 💡(How to fix) Fix [DOCS] Skills docs missing `${CLAUDE_EFFORT}` string substitution [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

Available string substitutions under Configure skills

Current Documentation

The skills docs currently list the supported string substitutions:

Skills support string substitution for dynamic values in the skill content:

| $ARGUMENTS | All arguments passed when invoking the skill. If $ARGUMENTS is not present in the content, arguments are appended as ARGUMENTS: <value>. | | $ARGUMENTS[N] | Access a specific argument by 0-based index, such as $ARGUMENTS[0] for the first argument. | | $N | Shorthand for $ARGUMENTS[N], such as $0 for the first argument or $1 for the second. | | $name | Named argument declared in the arguments frontmatter list. | | ${CLAUDE_SESSION_ID} | The current session ID. | | ${CLAUDE_SKILL_DIR} | The directory containing the skill's SKILL.md file. |

The same page documents effort frontmatter:

effort | Effort level when this skill is active. Overrides the session effort level. Default: inherits from session. Options: low, medium, high, xhigh, max; available levels depend on the model.

What's Wrong or Missing?

Changelog v2.1.120 added that "Skills can now reference the current effort level with ${CLAUDE_EFFORT} in their content", but the Available string substitutions table does not include ${CLAUDE_EFFORT}.

Skill authors can see that skills have an effort frontmatter field, and they can see other dynamic placeholders such as ${CLAUDE_SESSION_ID} and ${CLAUDE_SKILL_DIR}, but there is no documentation explaining:

• that ${CLAUDE_EFFORT} exists,
• what value it expands to,
• whether it reflects the inherited session effort or the skill's own effort override while the skill is active, and
• which effort values users should expect (low, medium, high, xhigh, max, or model-dependent values).

Suggested Improvement

Add ${CLAUDE_EFFORT} to the Available string substitutions table on the skills page, near the other ${CLAUDE_*} placeholders.

Suggested row:

If the value instead reflects only the session effort before applying skill frontmatter, document that explicitly so skill authors can reason about it.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.120

Exact changelog entry:

Skills can now reference the current effort level with ${CLAUDE_EFFORT} in their content