docs: clarify commands and skills use same Skill tool mechanism

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