How to use the Skill Developer Guide agent skill (skill-developer)

What is this skill and what does it make the agent do?

A skill is a folder containing a SKILL.md file with instructions that Claude Code can load when they are relevant. This skill gives the agent knowledge about how to build skills for Claude Code: the SKILL.md format with YAML frontmatter, the skill-rules.json configuration, the trigger types, and the enforcement levels.

It also explains the hook scripts that decide when skills appear or block edits. The source includes step-by-step testing commands and the 500-line guidance for keeping skills lean.

• Explains SKILL.md structure and YAML frontmatter
• Covers skill-rules.json configuration
• Describes trigger types: keywords, intent patterns, file paths, content patterns
• Describes enforcement levels: block, suggest, warn
• Explains hook mechanisms (UserPromptSubmit, PreToolUse) and session tracking

How do you install the skill-developer skill?

Download the ZIP from this page and unzip it. For a personal install, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

Review the hook scripts before relying on them. This skill documents a setup that includes TypeScript hooks which can block file edits and read session data, so installing them without review can change how the agent behaves.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your repository
• Claude apps: Settings → Capabilities → Skills upload

What do you need before it works?

The skill documents a setup rather than containing it alone. You need Claude Code, Node.js with npx and tsx to run the TypeScript hook scripts, and Bash for the PostToolUse tracker shell script.

You also need the surrounding .claude/hooks directory and skill-rules.json configuration from the source repository. The skill explains these files but does not include them by itself. The skill runs scripts and does not use the network.

• Claude Code
• Node.js with npx and tsx
• Bash
• The .claude/hooks and skill-rules.json setup from the repository

How do you trigger the skill with natural requests?

The skill activates when you mention topics such as creating or adding skills, modifying skill triggers, debugging skill activation, working with skill-rules.json, hook mechanics, progressive disclosure, YAML frontmatter, or the 500-line rule. Ask in plain language about the task you are doing.

Requests that fit the source's scope work best, for example asking how to add a skill, why a skill did not activate, or how to tune a keyword.

• Help me create a new skill for database migrations.
• Why didn't my frontend skill activate on this prompt?
• Add a keyword trigger to skill-rules.json for deployment questions.
• Explain the difference between block and suggest enforcement.

How do you create and test a new skill?

Create the skill at .claude/skills/{skill-name}/SKILL.md with a frontmatter name and description. The description should include the trigger keywords and phrases. Then add an entry to skill-rules.json. The source gives a basic template with type, enforcement, priority and promptTriggers.

To test, the source provides commands that pipe sample JSON into the hook scripts. Run the first to test the UserPromptSubmit hook, and the second to test the PreToolUse guard.

• Keep SKILL.md under 500 lines and move details into reference files
• Add a table of contents to reference files over 100 lines
• Test with at least three real scenarios before documenting
• Refine keywords and patterns based on actual results

What do the enforcement levels mean?

Block skills can hard-block edits: the PreToolUse guard exits with code 2 and sends a message to Claude, which must use the skill to proceed. Suggest skills inject a reminder before Claude sees the prompt, and are advisory. Warn skills are low-priority advisory suggestions and are rarely used.

Only enforcement set to block can hard-block, and suggest or warn matches are always advisory.

• block: prevents Edit/Write until the skill is used, for critical mistakes
• suggest: advisory reminder, the default for domain guidance
• warn: optional low-priority hint

What about the trigger types and file layout?

The configuration supports keyword triggers, intent patterns (regex), file path patterns (glob) and content patterns (regex). The skill ships reference files for the details: SKILL_RULES_REFERENCE.md for the full schema, TRIGGER_TYPES.md, HOOK_MECHANISMS.md, PATTERNS_LIBRARY.md with ready-to-copy patterns, ADVANCED.md for future ideas, and TROUBLESHOOTING.md.

The source notes that changes to skill-rules.json currently require restarting Claude Code to take effect.

• SKILL.md: main guide
• SKILL_RULES_REFERENCE.md: configuration schema
• TRIGGER_TYPES.md and PATTERNS_LIBRARY.md: triggers and patterns
• HOOK_MECHANISMS.md: hook flow and exit codes
• TROUBLESHOOTING.md: debugging activation
• ADVANCED.md: future enhancements