Overview

These rules govern how SKILL.md is written for skills in .claude/skills. They enforce conciseness (<200 lines), explicit When to Use sections, include copy-paste Bash commands, reference scripts/ for MCP operations, and require a corresponding trigger in skill-rules.json.

How This Skill Works

Authors create a concise SKILL.md with a clear When to Use section and copy-paste Bash commands. For MCP wrapper skills, they must specify allowed-tools and reference the script in scripts/ and ensure a trigger is added in skill-rules.json, ensuring consistent documentation and proper tool access.

When to Use It

• Creating a new skill under .claude/skills
• Wrapping an MCP script as a skill
• Updating an existing SKILL.md to include a When to Use section
• Ensuring a corresponding trigger exists in skill-rules.json
• Avoiding duplication and unnecessary implementation details

Quick Start

1. Step 1: Create SKILL.md in the appropriate .claude/skills/ path with the required YAML header and sections.
2. Step 2: Populate DO/DON'T, ensure a clear When to Use, and include copy-paste Bash commands for users.
3. Step 3: If the skill is an MCP wrapper, set allowed-tools to [Bash, Read], reference the script in scripts/, and add the trigger to skill-rules.json.

Best Practices

• Keep SKILL.md concise (<200 lines)
• Include a clear When to Use section
• Provide copy-paste Bash commands for setup or usage
• Reference scripts/ for MCP operations when applicable
• Add triggers to skill-rules.json and avoid content duplication

Example Use Cases

• Example: A new MCP-wrapped skill that references a script in scripts/ and declares allowed-tools.
• Example: A skill with a concise SKILL.md under 200 lines.
• Example: A skill that includes a proper When to Use section.
• Example: A skill that has a valid trigger in skill-rules.json.
• Example: A skill that avoids implementation details in SKILL.md.

Frequently Asked Questions