Slash commands with args MUST always support --help

[rand-lee]

Summary

Slash commands (skills) that accept arguments must handle --help as a recognized flag and display usage information rather than silently ignoring it or falling back to default behavior.

Problem

Currently, invoking a skill with --help (e.g., /sc:gemini --help) treats the flag as an unrecognized token and silently falls back to defaults — in this case launching with $PWD as the directory. This is confusing and violates basic CLI UX expectations.

Proposed Requirement

Add the following to the skills/agents guidelines (docs/claude-code-skills-agents-guidelines.md):

Every skill that declares argument-hint in its frontmatter MUST handle --help as a recognized flag. When --help is the only argument (or is present alongside other args), the skill must display usage information covering all supported arguments and flags, then stop without executing the primary operation.

Minimum --help output should include:

• Usage line (command + argument-hint)
• Description of each positional argument
• Description of each supported flag
• At least one example invocation

Example

/sc:gemini --help

Usage: /sc:gemini [dir] [--tab] [--tmux]

Arguments:
  dir     Target directory (default: $PWD)

Flags:
  --tab   Open in a new iTerm2 tab instead of a new window
  --tmux  Create a tmux session named "{folder} - gemini"

Examples:
  /sc:gemini
  /sc:gemini ~/projects/foo --tab
  /sc:gemini ~/projects/foo --tmux

Affected Skills

All skills with argument-hint in frontmatter, including but not limited to:

• /sc:sonnet, /sc:opus, /sc:haiku, /sc:codex, /sc:gemini
• Any skill with positional or flag arguments

Notes

This requirement should be added to the ## Skills: The Discovery Layer section under ### SKILL.md Requirements, and referenced in the ## Best Practices and ## Anti-Patterns to Avoid sections.