From 4571cf2dbf71dfc97129833c20a5a61dad8d9afc Mon Sep 17 00:00:00 2001 From: Win Huang Date: Thu, 16 Apr 2026 12:36:43 +0800 Subject: [PATCH] Make skill vs command distinction visually unmissable - Add visual comparison box in Overview Mode section B - List skills and commands separately before mixing in categories - Add [SKILL] and [CMD] prefix requirement for every item in category map - Users could not tell which items were auto-loaded vs manual Co-Authored-By: Claude Opus 4.6 (1M context) --- SKILL.md | 5 +---- commands/guide.md | 54 ++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 50 insertions(+), 9 deletions(-) diff --git a/SKILL.md b/SKILL.md index e320b74..505f00f 100644 --- a/SKILL.md +++ b/SKILL.md @@ -41,10 +41,7 @@ For each command .md, read the frontmatter `description` field. The filename (wi Scan all installed skills and commands, then present: 1. **Summary** -- How many skills, how many commands, grouped by category -2. **Category map** -- Group skills by purpose. Use a visual flow to show the recommended order: - ``` - [Phase 1] --> [Phase 2] --> [Phase 3] --> [Phase 4] - ``` +2. **Category map** -- Dynamically group skills by their actual purpose (security, development, finance, writing, etc.). Do NOT assume all skills belong to the same domain. Only show workflow arrows within a category if the skills have a natural sequential order. Always prefix each item with `[SKILL]` or `[CMD]`. 3. **Complete reference table** -- Each command with a one-line plain-language description 4. **"Where do I start?"** -- Based on the types of skills installed, suggest a concrete first step diff --git a/commands/guide.md b/commands/guide.md index 9368e00..50bf519 100644 --- a/commands/guide.md +++ b/commands/guide.md @@ -83,16 +83,60 @@ Present a complete guide with these sections: - Y slash commands available (type `/command` to use) **B) Skills vs Commands -- What's the difference?** -Explain in one paragraph: Skills load automatically when Claude detects relevant context. Slash commands need you to type `/command-name` to activate. Users don't need to do anything to "turn on" skills. +Explain clearly with a visual comparison box: + +``` ++-------------------------------+-------------------------------+ +| SKILLS (背景知識) | COMMANDS (動作指令) | +| Auto-loaded, no action needed | You type /command to trigger | ++-------------------------------+-------------------------------+ +| Like a textbook on your desk | Like a tool you pick up | +| Claude reads it when relevant | You decide when to use it | +| You do NOTHING to activate | You MUST type the command | ++-------------------------------+-------------------------------+ +``` + +Then list them separately: + +**Your Skills (auto-loaded):** +List each skill with a marker like `[SKILL]` prefix and one-line description. + +**Your Commands (type to use):** +List each command with the actual `/command` syntax and one-line description. + +This separation is critical -- many users don't understand the difference. Make it visually impossible to confuse. **C) Category Map** -Group all skills and commands by purpose. Show a visual workflow: +IMPORTANT: Do NOT use a hardcoded workflow like "recon → hunt → validate → report". The user may have skills from completely different domains (security, accounting, design, DevOps, etc.). + +Instead, dynamically categorize based on what is actually installed: + +1. Read the name and description of every scanned skill and command +2. Group them into natural categories based on their actual purpose (e.g., "Security / Bug Bounty", "Finance / Accounting", "Development Tools", "Writing / Documentation", etc.) +3. If skills within a category have a natural workflow order, show it with arrows +4. If they don't have a sequential relationship, just list them as a group + +For each category, use this format for EVERY item: +- `[SKILL] skill-name` — description (auto-loaded, you do nothing) +- `[CMD] /command-name` — description (you type this to trigger) + +Never list a skill or command without its `[SKILL]` or `[CMD]` prefix. + +Example with mixed domains: ``` -[Phase 1: Preparation] --> [Phase 2: Execution] --> [Phase 3: Validation] --> [Phase 4: Output] -``` +## Security / Bug Bounty +[Preparation] → [Recon] → [Hunting] → [Validation] → [Reporting] +...items... + +## Accounting +[CMD] /invoice-scan — ... +[SKILL] tax-rules — ... -Under each phase, list relevant skills and commands with one-line descriptions. +## Development Tools +[CMD] /lint — ... +[SKILL] code-review — ... +``` **D) Complete Command Reference** A table with columns: Command | What it does | When to use it | Example