docs: clarify commands and skills use same Skill tool mechanism

[sjnims]

Description

Update documentation to reflect Anthropic's conceptual merge of slash commands and skills. Both are now invoked via the same Skill tool but differ in complexity level:

• Commands (commands/): Simple .md files for quick prompts
• Skills (skills/name/): Full directories with bundled resources (scripts, references, examples)

Thanks to @KRRT7 for opening the issue!

Type of Change

• Documentation update (improvements to README, CLAUDE.md, or component docs)

Component(s) Affected

• Skills (methodology and best practices)
• Documentation (README.md, CLAUDE.md, SECURITY.md)

Motivation and Context

Anthropic has merged the concepts of slash commands and skills at the mechanism level—both are now invoked via the Skill tool. This PR updates plugin-dev documentation to clearly explain this relationship while maintaining the organizational distinction (commands = simple, skills = complex with resources).

Fixes #198

How Has This Been Tested?

Test Configuration:

• Claude Code version: Latest
• GitHub CLI version: 2.67.0
• OS: macOS Darwin 25.2.0

Test Steps:

1. Ran markdownlint 'plugins/plugin-dev/**/*.md' --ignore node_modules - passes
2. Ran npx prettier --write on modified files
3. Verified all modified files render correctly

Checklist

General

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My changes generate no new warnings or errors

Documentation

• I have updated the documentation accordingly (README.md, CLAUDE.md, or component docs)
• I have verified all links work correctly

Markdown

• I have run markdownlint and fixed all issues
• My markdown follows the repository style (ATX headers, dash lists, fenced code blocks)

Version Management (if applicable)

• I have updated CHANGELOG.md with relevant changes

Files Changed

File	Change
skills/command-development/SKILL.md	Added "Commands and Skills: Same Mechanism, Different Complexity" section
skills/skill-development/SKILL.md	Added "Skills and Commands: Unified Mechanism" section
skills/plugin-structure/SKILL.md	Updated Commands and Skills component descriptions
skills/plugin-dev-guide/SKILL.md	Updated quick reference table and decision tree
skills/command-development/references/skill-tool.md	Added key insight note
skills/skill-development/references/commands-vs-skills.md	NEW - Decision matrix and migration guide
CHANGELOG.md	Added entries under [Unreleased]

Additional Notes

The approach keeps commands and skills as separate concepts from an organizational standpoint while making clear they share the same invocation mechanism. This aligns with how plugin developers should think about the choice: complexity needs drive whether to use a simple command or a full skill with resources.

🤖 Generated with Claude Code

[claude]

Claude finished @sjnims's task in 55s —— View job

---

PR Review: docs: clarify commands and skills use same Skill tool mechanism

Tasks

• Run quality checks (markdownlint, prettier)
• Review the diff for all changed files
• Check plugin component standards
• Provide feedback with verdict

---

Verdict: ✅ Looks good

This is a well-structured documentation update that clearly explains the conceptual merge of commands and skills while maintaining the practical organizational distinction.

---

Quality Checks

Check	Result
markdownlint	✅ Pass (0 errors)
prettier	✅ Pass (all files formatted)
shellcheck	N/A (no shell scripts changed)

---

What's Good

1. Consistent messaging across files - The "same mechanism, different complexity" concept is reinforced in multiple locations without being redundant

2. Practical decision guidance - The new commands-vs-skills.md reference provides a clear decision matrix and migration path

3. Updated quick reference table - The plugin-dev-guide changes align the skill descriptions with the new conceptual model

4. Progressive disclosure pattern - Information is layered appropriately:

   • Quick mentions in SKILL.md files
   • Detailed reference in commands-vs-skills.md
   • Key insight note in skill-tool.md

5. Invocation control table - Clear documentation of the three invocation settings (default, disable-model-invocation, user-invocable)

---

Suggestions

1. Consider adding a cross-reference - In skills/command-development/SKILL.md:76 where the new section ends with "convert the command to a skill", you might link to skill-development skill for the detailed process

2. Minor: Migration section in commands-vs-skills.md - The migration steps are good but step 2 mentions "Move command content to SKILL.md body" - consider noting that the frontmatter fields (description, allowed-tools, etc.) are preserved since they work identically

These are minor polish suggestions, not blockers.

---

Files Reviewed

File	Status
CHANGELOG.md	✅ Proper changelog format
skills/command-development/SKILL.md	✅ Good comparison table
skills/command-development/references/skill-tool.md	✅ Key insight note well-placed
skills/plugin-dev-guide/SKILL.md	✅ Updated descriptions accurate
skills/plugin-structure/SKILL.md	✅ Brief clarifications appropriate
skills/skill-development/SKILL.md	✅ Unified mechanism explained
skills/skill-development/references/commands-vs-skills.md	✅ Comprehensive new reference

---

[sjnims]

Addressed review suggestions in 547715b:

• Added cross-reference to skill-development skill
• Noted frontmatter field preservation in migration steps

[claude]

Claude finished @sjnims's task in 1m 22s —— View job

---

PR Review: docs: clarify commands and skills use same Skill tool mechanism

Tasks

• Run quality checks (markdownlint, prettier)
• Review the diff for all changed files
• Check for issues addressed in latest commit
• Provide feedback with verdict

---

Verdict: ✅ Looks good

Both suggestions from the previous review have been addressed in commit 547715b:

1. ✅ Cross-reference added - command-development/SKILL.md:74 now links to the skill-development skill for migration guidance
2. ✅ Frontmatter preservation noted - commands-vs-skills.md:36 clarifies that frontmatter fields work identically when migrating

---

Quality Checks

Check	Result
markdownlint	⚠️ Unable to run (tools not available)
prettier	⚠️ Unable to run (tools not available)
shellcheck	N/A (no shell scripts changed)

Note: The linting tools were not pre-installed. The PR description indicates the author ran these checks locally and they passed.

---

What's Good

1. Suggestions implemented cleanly - Both additions integrate naturally into the existing documentation flow

2. Cross-reference placement is ideal - The link to skill-development appears right after the "when to graduate" guidance at line 74, exactly where a reader would want it

3. Migration guidance is actionable - The parenthetical note about frontmatter fields working identically provides helpful reassurance to developers migrating commands to skills

---

Files Reviewed

File	Status	Notes
command-development/SKILL.md	✅ Updated	Added cross-reference to skill-development
commands-vs-skills.md	✅ Updated	Added frontmatter preservation note

---

This PR is ready to merge.