[DOCS] Inconsistency regarding "Merged slash commands and skills" in Changelog vs. Documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

• CHANGELOG.md (Section 2.1.3) - docs/en/slash-commands.md (Section: Skills vs slash commands)

Section/Topic

The "Skills vs slash commands" comparison section in the Slash Commands documentation.

Current Documentation

Changelog 2.1.3 states:

"Merged slash commands and skills, simplifying the mental model with no change in behavior"

However, docs/en/slash-commands.md contains a section "Skills vs slash commands" which states:

"Slash commands and Agent Skills serve different purposes in Claude Code... [followed by a 'Key differences' table and an 'Example comparison' table]"

The table explicitly lists differences in:

• Structure: Single .md file vs. Directory with SKILL.md + resources
• Discovery: Explicit invocation vs. Automatic
• Files: One file only vs. Multiple files, scripts, templates

What's Wrong or Missing?

There is a direct contradiction between the latest release notes and the detailed documentation.

If the features have been "merged" to "simplify the mental model," the documentation should reflect a unified system. Instead, the current documentation preserves the old "separate" mental model by providing extensive tables explaining why they are different and when to use one over the other. This leaves the user confused as to whether they are now the same entity or if the "merge" refers only to an internal implementation detail.

Suggested Improvement

1. Unify the Terminology: If they are merged, the documentation should describe them as a single capability (perhaps "Agent Skills") that supports two triggers: explicit (via /) and implicit (via model invocation).
2. Remove/Update Comparison Tables: Delete the "Key differences" table in docs/en/slash-commands.md as it highlights the exact "mental model" complexity the changelog claims to have eliminated.
3. Clarify the Migration: Explicitly state in the docs that a Slash Command is now simply a "lightweight Skill" or that all Skills can be invoked via /.

Suggested New Text for docs/en/slash-commands.md:

"Slash commands and Agent Skills are now part of a unified system. Any Skill you create can be invoked explicitly using a / prefix, and custom prompts created as Markdown files are treated as Skills that Claude can discover when relevant."

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation: docs/en/skills.md
• Related Changelog Entry: 2.1.3 (Merged slash commands and skills).
• Skill Tool Documentation: The section regarding the Skill tool (formerly the SlashCommand tool) correctly notes the merger, but the surrounding descriptive text still treats them as separate concepts.