docs: clarify commands and skills use same Skill tool mechanism (#201)

## 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

- [x] Documentation update (improvements to README, CLAUDE.md, or
component docs)

## Component(s) Affected

- [x] Skills (methodology and best practices)
- [x] 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

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

### Documentation

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

### Markdown

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

### Version Management (if applicable)

- [x] 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](https://claude.ai/code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: sjnims

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Update documentation for commands/skills merge** - Clarified that commands and skills use the same Skill tool mechanism but differ in complexity (fixes #198)
+
+### Added
+
+- **New reference: commands-vs-skills.md** - Explains when to use commands vs skills and migration path
+
 ## [0.3.2] - 2026-01-24
 
 ### Fixed

plugins/plugin-dev/skills/command-development/SKILL.md

@@ -55,6 +55,24 @@ You'll receive a report with vulnerability details.
 
 The first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.
 
+### Commands and Skills: Same Mechanism, Different Complexity
+
+Commands and skills are both invoked via the same **Skill tool**. The difference is organizational complexity:
+
+| Aspect    | Commands                        | Skills                            |
+| --------- | ------------------------------- | --------------------------------- |
+| Location  | `commands/`                     | `skills/name/`                    |
+| Format    | Single `.md` file               | `SKILL.md` + optional resources   |
+| Resources | None                            | scripts/, references/, examples/  |
+| Best for  | Quick prompts, simple workflows | Complex knowledge, bundled assets |
+
+**Invocation control** (works for both):
+
+- `disable-model-invocation: true` → User-only (for side effects: deploy, commit)
+- Default → Both Claude and user can invoke
+
+**When to graduate a command to a skill**: If you need scripts, reference files, or progressive disclosure, convert the command to a skill. See the `skill-development` skill for guidance.
+
 ### Command Locations
 
 **Project commands** (shared with team):

plugins/plugin-dev/skills/command-development/references/skill-tool.md

@@ -6,6 +6,8 @@ How Claude programmatically invokes slash commands and skills during conversatio
 
 The Skill tool enables Claude to programmatically execute both slash commands and Agent Skills without user typing. This allows Claude to autonomously invoke these capabilities as part of complex workflows, chain them together, or use them in response to user requests.
 
+> **Key Insight:** Commands and skills are the same mechanism. Both are invoked via the Skill tool. Commands are simple (single `.md` file); skills are complex (directory with bundled resources).
+>
 > **Note:** In earlier versions of Claude Code, slash command invocation was provided by a separate `SlashCommand` tool. This has been merged into the `Skill` tool.
 
 **Key concepts:**

plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md

@@ -16,9 +16,9 @@ The plugin-dev toolkit provides 9 specialized skills for building Claude Code pl
 | Skill                     | Purpose                                            |
 | ------------------------- | -------------------------------------------------- |
 | **plugin-structure**      | Directory layout, manifest, component organization |
-| **command-development**   | Slash commands with frontmatter                    |
+| **command-development**   | Simple prompts (single .md files in commands/)     |
 | **agent-development**     | Autonomous subagents                               |
-| **skill-development**     | Creating skills with progressive disclosure        |
+| **skill-development**     | Complex prompts with bundled resources (skills/)   |
 | **hook-development**      | Event-driven automation                            |
 | **mcp-integration**       | Model Context Protocol servers                     |
 | **lsp-integration**       | Language Server Protocol for code intelligence     |
@@ -140,9 +140,9 @@ Use when the user needs to:
 ```
 User wants to...
 ├── Create/organize a plugin structure? → plugin-structure
-├── Add a slash command? → command-development
+├── Add a simple slash command (no bundled resources)? → command-development
 ├── Create an autonomous agent? → agent-development
-├── Add domain expertise/knowledge? → skill-development
+├── Add a complex skill with scripts/references? → skill-development
 ├── React to Claude Code events? → hook-development
 ├── Integrate external service/API? → mcp-integration
 ├── Add code intelligence/LSP? → lsp-integration

plugins/plugin-dev/skills/plugin-structure/SKILL.md

@@ -115,6 +115,8 @@ Specify custom paths for components (supplements default directories):
 **Format**: Markdown files with YAML frontmatter
 **Auto-discovery**: All `.md` files in `commands/` load automatically
 
+Simple, user-invocable prompts stored as single `.md` files. Use when you don't need bundled resources. Both commands and skills are invoked via the Skill tool—commands are essentially simple skills.
+
 **Example structure**:
 
 ```
@@ -173,6 +175,8 @@ Detailed agent instructions and knowledge...
 **Format**: Each skill in its own directory with `SKILL.md` file
 **Auto-discovery**: All `SKILL.md` files in skill subdirectories load automatically
 
+Complex prompts with bundled resources (scripts, references, examples). Use when you need progressive disclosure or supporting files. Both skills and commands are invoked via the Skill tool.
+
 **Example structure**:
 
 ```

plugins/plugin-dev/skills/skill-development/SKILL.md

@@ -14,6 +14,15 @@ specialized knowledge, workflows, and tools. Think of them as "onboarding guides
 domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
 equipped with procedural knowledge that no model can fully possess.
 
+### Skills and Commands: Unified Mechanism
+
+Skills and commands share the same underlying mechanism (Skill tool). The choice depends on complexity needs:
+
+- **Use commands** (`commands/foo.md`): Simple prompts without bundled resources
+- **Use skills** (`skills/foo/SKILL.md`): Complex workflows needing scripts, references, or examples
+
+Both support `$ARGUMENTS`, `[BANG]` bash execution, and frontmatter fields. Skills add bundled resources and progressive disclosure.
+
 ### What Skills Provide
 
 1. Specialized workflows - Multi-step procedures for specific domains

plugins/plugin-dev/skills/skill-development/references/commands-vs-skills.md

@@ -0,0 +1,39 @@
+# Commands vs Skills: When to Use Each
+
+## Same Mechanism, Different Complexity
+
+Both commands and skills:
+
+- Are invoked via the Skill tool
+- Support $ARGUMENTS and `[BANG]` bash execution
+- Support frontmatter (description, allowed-tools, model)
+- Can control invocability (disable-model-invocation)
+
+## Decision Matrix
+
+| Need                    | Use     | Location               |
+| ----------------------- | ------- | ---------------------- |
+| Simple reusable prompt  | Command | commands/foo.md        |
+| Dynamic arguments only  | Command | commands/foo.md        |
+| Scripts for validation  | Skill   | skills/foo/            |
+| Reference documentation | Skill   | skills/foo/references/ |
+| Working examples        | Skill   | skills/foo/examples/   |
+| Progressive disclosure  | Skill   | skills/foo/            |
+
+## Invocation Control
+
+| Setting                             | User (/) | Claude (Skill tool) |
+| ----------------------------------- | -------- | ------------------- |
+| Default                             | Yes      | Yes                 |
+| disable-model-invocation: true      | Yes      | No                  |
+| user-invocable: false (skills only) | No       | Yes                 |
+
+## Migration: Command to Skill
+
+When a command grows complex:
+
+1. Create `skills/name/SKILL.md`
+2. Move command content to SKILL.md body (frontmatter fields like `description`, `allowed-tools`, `model` work identically)
+3. Add `references/` for detailed docs
+4. Add `scripts/` for utilities
+5. Delete original command file