creating-stacks.md

Creating a Stack

Guide for contributors who want to create and submit new stacks.

Stack Directory Structure

Every stack must follow this structure:

stacks/<stack-name>/
├── README.md              # Required: what's in the stack, how to install
├── CLAUDE.md              # Required: project instructions for Claude Code
├── settings.json          # Required: hook configuration
├── skills/                # Required: at least one skill
│   └── <skill-name>/
│       └── SKILL.md
├── hooks/                 # Optional: automation scripts
│   └── <hook-name>.sh
└── templates/             # Optional: project templates

Skills Format

Skills use YAML frontmatter + markdown:

---
name: my-skill
description: One-line description of when to use this skill. Be specific about trigger conditions.
---

# Skill Title

Clear, step-by-step instructions for Claude Code to follow.

## Step 1: ...

- Concrete actions
- Code examples where helpful
- Decision points with criteria

Guidelines:

• The description field is critical -- Claude Code uses it to decide when to invoke the skill
• Write instructions as if talking to a capable developer, not a beginner
• Include decision criteria, not just steps
• Provide code patterns to copy, not abstract descriptions
• Include a checklist at the end for verification

Hooks Format

Hooks are bash scripts that:

1. Read JSON from stdin
2. Extract the file path
3. Run tools on the file
4. Exit cleanly

Template:

#!/bin/bash
# PostToolUse hook: <what this hook does>
# <additional context>

set -euo pipefail

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Filter: only process relevant files
if [[ -z "$FILE_PATH" || "$FILE_PATH" != *.<extension> ]]; then
  exit 0
fi

if [[ ! -f "$FILE_PATH" ]]; then
  exit 0
fi

# Check if the tool is available
if ! command -v <tool> &> /dev/null; then
  exit 0
fi

# Run the tool
<tool> "$FILE_PATH" 2>/dev/null || true

Guidelines:

• Always check if the tool is installed (command -v)
• Always filter by file extension
• Always check if the file exists
• Use || true to prevent hook failures from blocking Claude Code
• Use set -euo pipefail for safety
• Keep hooks fast (under 30 seconds)

settings.json Structure

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/<hook-name>.sh",
            "timeout": 30,
            "statusMessage": "Running <hook-name>..."
          }
        ]
      }
    ]
  }
}

Guidelines:

• Use $CLAUDE_PROJECT_DIR for portable paths
• Set reasonable timeouts (30s for formatters, 120s for tests)
• Write clear statusMessage values

CLAUDE.md Guidelines

The CLAUDE.md should cover:

1. Language/framework conventions -- coding style, preferred libraries, patterns
2. Project structure -- where things go and why
3. Anti-patterns -- common mistakes to avoid (be specific)
4. Testing conventions -- how to write and run tests
5. Domain-specific guidance -- patterns unique to this tech stack

Do:

• Be specific and actionable
• Include code examples for non-obvious patterns
• List concrete anti-patterns with explanations

Don't:

• Repeat generic programming advice
• Include project-specific paths or names
• Add configuration that belongs in settings.json

Testing Your Stack

Before submitting, verify:

1. Fresh install test:

   mkdir /tmp/test-project && cd /tmp/test-project
   git init
   # Follow your README's install instructions exactly
   # Start Claude Code and verify everything works

2. Skills discoverable: Ask Claude to list available skills

3. Hooks fire: Edit a file and verify hooks run

4. Graceful degradation: Remove a tool (e.g., uninstall ruff) and verify hooks don't crash

Submitting a PR

1. Fork the repository
2. Create your stack in stacks/<stack-name>/
3. Add an entry to the main README's "Available Stacks" table
4. Submit a PR with:
   • A description of the stack and its target audience
   • Screenshots or examples of skills/hooks in action
   • Confirmation you've tested a fresh install