docs(command-development): add SlashCommand tool coverage

[sjnims]

Summary

• Add comprehensive documentation for how Claude programmatically invokes slash commands via the SlashCommand tool
• Create new reference file covering visibility requirements, character budget, permission rules, and best practices
• Update skill description with trigger phrases for discoverability

Problem

Fixes #48

The command-development skill documents the disable-model-invocation frontmatter field but doesn't explain its relationship to the SlashCommand tool. Users need to understand:

• What the SlashCommand tool is and when Claude uses it
• Why commands need description for visibility
• How the character budget (15,000 default) works
• Permission rule patterns for controlling programmatic invocation

Solution

Created references/slashcommand-tool.md with complete coverage:

1. SlashCommand Tool Overview - What it does and when Claude uses it
2. Visibility Requirements - Why description field is required
3. Character Budget - 15,000 default, SLASH_COMMAND_TOOL_CHAR_BUDGET env var
4. Permission Rules - Exact match, prefix match, deny patterns
5. disable-model-invocation Context - When to use vs permission rules
6. Integration Patterns - Commands designed for programmatic vs manual use
7. Troubleshooting - Common issues and solutions
8. Best Practices - For command authors and users

Updated SKILL.md:

• Added trigger phrases: "SlashCommand tool", "programmatic command invocation", "disable-model-invocation", "prevent Claude from running command"
• Added reference to new file in Additional Resources section

Alternatives Considered

• Expand frontmatter-reference.md - Rejected because SlashCommand tool deserves dedicated coverage beyond just frontmatter syntax
• Add to SKILL.md directly - Rejected to follow progressive disclosure pattern (keep SKILL.md lean)

Changes

• plugins/plugin-dev/skills/command-development/references/slashcommand-tool.md - New reference file (~420 lines)
• plugins/plugin-dev/skills/command-development/SKILL.md - Updated description and Additional Resources

Testing

• markdownlint passes on both files
• Progressive disclosure pattern followed (detailed content in references/)
• Trigger phrases align with issue requirements

---

🤖 Generated with Claude Code

[claude]

Claude finished @sjnims's task —— View job

---

PR Review Complete ✅

Summary

This PR looks excellent! The documentation is comprehensive, well-structured, and follows all plugin-dev conventions. This is a high-quality addition that meaningfully addresses issue #48.

---

What's Good

🎯 Comprehensive Coverage

The new slashcommand-tool.md reference file provides thorough documentation covering all key aspects:

• Clear explanation of what the SlashCommand tool is and when Claude uses it
• Visibility requirements (why description is needed)
• Character budget mechanics and optimization strategies
• Permission rule patterns with concrete examples
• Proper context for disable-model-invocation field
• Integration patterns distinguishing programmatic vs manual commands
• Troubleshooting section and best practices

📋 Follows Progressive Disclosure Pattern

• SKILL.md remains lean (~713 lines, within expected range)
• Detailed SlashCommand tool coverage properly placed in references/ directory
• Clean reference added to "Additional Resources" section

🔍 Strong Trigger Phrases

Updated skill description includes highly relevant trigger phrases:

• "SlashCommand tool"
• "programmatic command invocation"
• "disable-model-invocation"
• "prevent Claude from running command"

These phrases directly match how users would ask about this functionality.

✅ Quality Checks Pass

• ✅ Markdownlint passes with no errors
• ✅ No frontmatter changes needed (name and description already present)
• ✅ Writing style is clear and imperative (references use infinitive form appropriately)
• ✅ 418 lines of new content is substantial but appropriate for the topic scope

📝 Excellent Documentation Structure

The reference file follows a logical progression:

1. Overview → 2. How it works → 3. Visibility → 4. Budget → 5. Permissions → 6. Integration patterns → 7. Troubleshooting → 8. Best practices

Each section includes concrete examples with YAML/JSON/bash code blocks.

---

Suggestions

Minor Observation (Not Blocking)

The comparison table at line 255-260 is well-formatted and informative. One tiny enhancement could be adding a concrete example row showing a real scenario, but the current table is already very clear.

---

Checklist Verification

• ✅ Fixes issue docs(command-development): add SlashCommand tool coverage #48 - Comprehensive SlashCommand tool documentation added
• ✅ Markdown quality - markdownlint passes, proper formatting throughout
• ✅ Progressive disclosure - Detailed content in references/, SKILL.md stays lean
• ✅ Trigger phrases - Strong, relevant phrases added to skill description
• ✅ Examples included - Multiple concrete examples for each concept
• ✅ Conventions followed - Matches plugin-dev documentation patterns
• ✅ Writing style - Imperative/infinitive form for instructions, clear explanations

---

Recommendation

✅ Ready to merge. This PR successfully addresses the documentation gap around the SlashCommand tool and provides users with the information they need to understand programmatic command invocation.

Great work on this documentation addition! The progressive disclosure pattern is well-executed, and the content is thorough without being overwhelming.

---