Skip to content

secondsky/claude-skills / plugins/claude-hook-writer/skills/claude-hook-writer

claude-hook-writer

Verified

Expert guidance for writing secure, reliable, and performant Claude Code hooks - validates design decisions, enforces best practices, and prevents common pitfalls. Use when creating, reviewing, or debugging Claude Code hooks.

references/publishing-guide.md

View on GitHub
# Publishing Hooks as PRPM Packages

Guide for packaging and publishing hooks to the PRPM registry.

---

## Package Structure

```
my-hook/
├── prpm.json          # Package manifest
├── hook.json          # Hook configuration
├── scripts/
│   └── my-hook.sh     # Hook script
└── README.md          # Documentation
```

---

## prpm.json

Package manifest with metadata:

```json
{
  "name": "@yourname/my-hook",
  "version": "1.0.0",
  "description": "Brief description shown in search results",
  "author": "Your Name",
  "format": "claude",
  "subtype": "hook",
  "tags": [
    "formatting",
    "security",
    "automation"
  ],
  "main": "hook.json",
  "scripts": {
    "test": "./test-hook.sh"
  }
}
```

---

## hook.json

Hook configuration with `${CLAUDE_PLUGIN_ROOT}` for portability:

```json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/my-hook.sh",
        "timeout": 5000
      }]
    }]
  }
}
```

**Always use `${CLAUDE_PLUGIN_ROOT}`** to reference scripts.

---

## Advanced Hook Configuration

All hook types support optional fields:

```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "./my-hook.sh",
        "timeout": 5000,
        "continue": true,
        "stopReason": "string",
        "suppressOutput": false,
        "systemMessage": "string"
      }]
    }]
  }
}
```

### `continue` (boolean, default: true)

Controls whether Claude continues after hook execution.

**When to use `false`**:
- Security hooks that must block operations
- Validation hooks that found critical errors

```json
{
  "continue": false,
  "stopReason": "Security validation failed. Review detected issues."
}
```

### `stopReason` (string)

Message displayed when `continue: false`. Explain why and what action is needed.

### `suppressOutput` (boolean, default: false)

Hides hook stdout from transcript. Stderr always shown.

**When to use `true`**:
- Verbose output not useful to users
- Background operations

### `systemMessage` (string)

Warning shown to user (non-blocking).

**Difference from `stopReason`**:
- `systemMessage`: Informational, continues
- `stopReason`: Critical, requires `continue: false`

---

## README.md Template

```markdown
# My Hook

Brief description of what this hook does.

## What It Does

- Clear bullet points
- Which events it triggers on
- Which tools it matches

## Installation

\`\`\`bash
prpm install @yourname/my-hook
\`\`\`

## Requirements

- prettier (install: `npm install -g prettier`)
- jq (install: `brew install jq`)

## Configuration

Optional: How to customize behavior.

## Examples

Show example output or behavior.

## Troubleshooting

Common issues and fixes.
```

---

## Publishing Commands

```bash
# Test locally first
prpm test

# Publish
prpm publish

# Version bumps
prpm publish patch  # 1.0.0 -> 1.0.1
prpm publish minor  # 1.0.0 -> 1.1.0
prpm publish major  # 1.0.0 -> 2.0.0
```

---

## Pre-Publish Checklist

- [ ] Validates all stdin input
- [ ] Quotes all variables
- [ ] Uses absolute paths for scripts
- [ ] Blocks sensitive files
- [ ] Handles missing tools gracefully
- [ ] Sets reasonable timeout
- [ ] Logs errors to stderr or file
- [ ] Tests with edge cases
- [ ] Tests in real Claude session
- [ ] Documents dependencies
- [ ] README includes examples
- [ ] Semantic version number
- [ ] Clear description and tags

---

## Best Practices

1. **Clear description**: Users find your hook via search
2. **Comprehensive README**: Include examples and troubleshooting
3. **Semantic versioning**: Breaking changes = major version
4. **Test before publishing**: Run `prpm test`
5. **Document dependencies**: List all required tools
6. **Provide examples**: Show expected behavior
7. **Handle errors gracefully**: Don't crash on edge cases
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall