Claude Code Skills

English | 日本語

A curated collection of skills, rules, and hooks for Claude Code — Anthropic's official CLI for Claude.

This repository provides a production-ready Claude Code configuration with 25 custom skills, 17 hook scripts (4 blocking + 13 advisory/infra), 6 rule sets, 6 utility scripts, and integration with third-party skill frameworks.

Design Philosophy: This project implements the principles from Harness Engineering Best Practices 2026 — deterministic quality gates via hooks, pointer-based documentation (ADR-002), and the feedback speed hierarchy (PostToolUse > pre-commit > CI > human review). Since ADR-006, the hook set is deliberately minimal: hard blocks are reserved for destructive/irreversible operations, and merge safety is delegated to GitHub branch protection + PR review rather than local gates.

git clone https://github.com/terisuke/claude-code-skills.git
cd claude-code-skills
chmod +x setup.sh
./setup.sh

Restart Claude Code after installation.

Claude Code can only use one API gateway per process. This repo ships scripts/claude-provider.sh so you can switch between the official Claude subscription (default, reliable for subagents/WebSearch) and z.ai GLM.

bash ~/.claude/scripts/claude-provider.sh status
bash ~/.claude/scripts/claude-provider.sh anthropic   # default
bash ~/.claude/scripts/claude-provider.sh zai

Details: docs/runbooks/provider-switching.md.

setup.sh installs three launchers into ~/.local/bin so that Pi, dsh and the upstream OpenCode 2.x start with the H17 common control the way the 1.x opencode and cursor-agent already do:

Sources: pi/launcher/pi, dsh/launcher/dsh, opencode/launcher/opencode2. Runbook with the live procedure: aidd-governance design/ops/runbooks/h17-human-gate-20261017.md.

claude-code-skills/
├── skills/           # 25 custom skill definitions (SKILL.md + scripts + references)
├── rules/            # 6 global rule files (coding-style, git-workflow, quality, testing, delegation, hook-deployment)
├── hooks/            # 17 hook scripts (4 blocking + 13 advisory/infra); hooks/_unused/ holds 62 retired scripts, 56 via ADR-006
├── scripts/          # 6 utility scripts (Codex orchestration, provider switching, context monitoring); scripts/_unused/ holds retired review-pipeline helpers
├── setup.sh          # One-command installation
├── settings.json     # Template settings (sanitized, no personal paths)
└── README.md

Design decisions are recorded as ADRs in docs/adr/.

To add a new ADR, use the template.

See docs/references/ for details.

This configuration integrates with the following third-party skill frameworks. They are not bundled in this repository — setup.sh installs them automatically.

Think → Plan (gstack)
  /office-hours → /plan-ceo-review → /plan-eng-review → /plan-design-review

Build → Review → Ship (custom skills + hooks)
  code-reviewer, review-loop, e2e, bugfix + 17 hook scripts

Reflect (gstack)
  /retro

This system's core differentiator is its multi-agent orchestration with automatic delegation to Codex CLI.

Claude Code (60%) — Design, parallel implementation, coordination, user interaction
  └─ Strengths: Agent teams, real-time judgment, context-shared collaboration

Codex CLI (40%) — Sequential implementation, operations, quality audits
  └─ Strengths: Worktree isolation, long-running autonomy, GitHub/Supabase integration

The agent-orchestrator skill manages team composition, wave-based execution, and cross-review protocols.

Since ADR-006, Codex CLI usage and context-budget management are not enforced by hooks — the previous context-budget-*-gate.sh suite and the 1-concurrent-call codex-task-gate.sh/codex-task-release.sh pair were retired. Route selection (Agent Team vs. Codex vs. self-execute) is agent judgement guided by rules/delegation.md; codex-parallel.sh / codex-orchestrate.sh remain available as optional utilities invoked at will, with no concurrency limit enforced locally.

check-pr-reviews.sh, classify-review-state.sh, review-comment-set-hash.sh, review-evidence-status.sh, and verify-pr-review.sh were retired to scripts/_unused/ along with the review-pipeline hooks they supported (ADR-006).

Prior to ADR-006, a multi-gate pr-ci-review-gate.sh + gate-modes/ pipeline hard-blocked gh pr create/gh pr merge locally. That pipeline is retired. Merge safety is now the responsibility of GitHub branch protection (required status checks, required reviews, no force-push) configured on main/develop, plus the ordinary PR review workflow (code-reviewer skill, optional Codex CLI second opinion via codex-review). If branch protection is disabled or misconfigured on GitHub, there is no local backstop — see ADR-006's consequences for the explicit operational requirement this creates.

This repository is built on three foundational principles:

Based on the article that underpins this system's architecture:

Since ADR-006, this repository intentionally trades some of the original article's "deterministic tools over LLM prompts everywhere" guidance for a smaller, higher-signal hook set — see docs/adr/006-minimal-safety-net.md for the false-positive-cost rationale.

The core operational principle, born from an incident where 11 of 18 hooks (61%) were "implemented" in source code but never actually fired:

"Code exists" and "system works" are separate verification steps. Code review alone cannot guarantee operational correctness.

This principle is enforced through:

• 4-stage verification: Code exists → Syntax OK → Registered in settings.json → Actually fires
• delivery_score.py: Quantitative quality scoring (hook coverage, CI pass rate, review compliance)
• enforce-hook-deploy-integrity.sh: Source ↔ deployed ↔ registered consistency check (auto-sync + orphan detection)
• CI/CD: shellcheck + JSON validation + syntax checking on every PR

Before Epic #130: Hook gate operation rate 39% (7/18) After Epic #130, before ADR-006: Hook gate operation rate 98%+ (59/59 hooks registered + deployed) After ADR-006 (current): 17/17 hooks registered + deployed — the surviving set is smaller by design, not by drift; deploy-integrity verification still applies to all of it.

Run python3 scripts/delivery_score.py to get a quantitative quality assessment:

==================================================
  Delivery Quality Score: claude-code-skills
==================================================
  Total: 99.0/100 (A+)
──────────────────────────────────────────────────
  hook_coverage            :  96.5/100
  ci_pass_rate             : 100.0/100
  soak_time                : 100.0/100
  review_compliance        : 100.0/100
==================================================

Use --json for CI/automation integration.

All P1-HIGH issues from the Epic #130 review (2026-03-24) have been resolved. P2-MEDIUM issues #136-#147 resolved in subsequent PRs. Current open items:

Full per-hook reference (event, matcher, purpose): hooks/README.md. Rationale for the reduction from 72 registered commands down to 17: ADR-006.

• git-push-guard.sh — Block force-push and direct push to protected branches
• protect-branches.sh — Prevent deletion of protected branches
• block-local-hooks-write.sh — Prevent settings.local.json from overriding global hooks
• validate-no-local-hooks.sh — Warn/block at SessionStart if such an override already exists

• auto-init-permissions.sh — No-op; permissions live in settings.json
• auto-update-plugins.sh — Update third-party plugins (24h cooldown)
• validate-provider-env.sh — Check API provider routing (Anthropic/z.ai) at session start
• enforce-branch-workflow.sh — Auto-create develop branch, warn on main/develop
• enforce-hook-deploy-integrity.sh — Verify hooks are installed and registered (auto-sync + orphan detection)
• enforce-hook-deploy-after-merge.sh — Auto-deploy hooks after a PR merge that touched hooks/
• verify-agent-output.sh — Detect agent phantom completions (#173)
• auto-commit-worktree-changes.sh — Auto-commit worktree agent changes after merge (#220)
• post-deploy-verify.sh — Inject verification checklist after deploy commands
• post-lint-format.sh — Post-write Quality Loop: auto-fix → residual check (ADR-001/003)
• notify-agent-failure.sh — Propagate agent failure context (PostToolUseFailure)
• tool-failure-recovery.sh — Error-recovery guidance on tool failure (PostToolUseFailure)
• pre-compact-context-save.sh — Save critical context before compaction (PreCompact)

56 previously-active scripts (the full review/CI merge-gate stack, factcheck suite, context-budget suite, Codex single-call gate, state-file tampering guards, and more) plus the entire former hooks/gate-modes/ dispatcher architecture are retired to hooks/_unused/. See hooks/README.md#_unused-archive for the full retired list and the rationale in ADR-006.

Important: Claude Code's matcher field accepts only a tool name regex, not an expression language. Command-level filtering must be done inside the hook script by parsing stdin JSON.

// CORRECT — matches tool name with regex
{ "matcher": "Bash" }
{ "matcher": "Edit|Write" }

// WRONG — will never fire (treated as regex against tool name)
{ "matcher": "tool == \"Bash\" && tool_input.command matches \"git push\"" }

Hook scripts receive the tool invocation as JSON on stdin and should filter by inspecting tool_input.command or tool_input.file_path internally.

Important: Do NOT echo the input JSON back to stdout on exit 0. The official pattern is simply exit 0 to allow a tool call. All hooks in this repository follow this convention.

See the official hooks documentation for details.

Based on The Complete Guide to Building Skills for Claude (Anthropic, 2026)

skill-name/              # kebab-case, no spaces, no capitals
├── SKILL.md             # Required — YAML frontmatter + Markdown instructions
├── scripts/             # Optional — Executable code (deterministic, token-efficient)
├── references/          # Optional — Docs loaded into context as needed
└── assets/              # Optional — Templates, fonts, icons used in output

No README.md, CHANGELOG.md, or auxiliary documentation inside the skill folder.

1. YAML frontmatter — Always loaded in system prompt. Provides just enough for Claude to know WHEN to use the skill.
2. SKILL.md body — Loaded when Claude thinks the skill is relevant. Contains full instructions.
3. references/ — Additional files Claude navigates only as needed.

---
name: skill-name          # Required. kebab-case, no "claude"/"anthropic" prefix
description: |             # Required. [What] + [When] + [Capabilities]. Under 1024 chars.
  What it does. Use when user says "trigger phrase".
  Do NOT use for: negative triggers.
allowed-tools: [Read, Bash, Grep]  # Optional. Restrict tool access.
license: MIT               # Optional
metadata:                  # Optional
  author: Your Name
  version: 1.0.0
---

CRITICAL: No XML angle brackets (< >) in frontmatter. Frontmatter appears in Claude's system prompt — angle brackets could inject instructions. Use [placeholder] instead.

[What it does] + [When to use it] + [Key capabilities] + [Do NOT use for]

Good:

description: Analyzes git diff and generates conventional commit messages.
  Use when staging changes or writing commit messages. Do NOT use for
  branching strategy or merge conflict resolution.

Bad:

description: Helps with projects.  # Too vague, no triggers

• Imperative form: "Run X", "Check Y" (not "You should run X")
• Specific and actionable: Run python scripts/validate.py --input {filename} not "Validate the data"
• Critical info first: Use ## Critical or ## Important headers at top
• Under 500 lines in SKILL.md body: Move details to references/
• Error handling: Include what to do when things fail
• No duplication: Information lives in SKILL.md OR references/, not both

Use <important if="condition"> tags in SKILL.md body (NOT in frontmatter) to focus Claude's attention on relevant sections:

<important if="you are deploying to production">
- Use --platform linux/amd64 for Docker builds
- Use --update-env-vars (NOT --set-env-vars)
</important>

Rules:

• Keep conditions SPECIFIC (not if="you are writing code")
• Leave universal rules UNCONDITIONAL
• If a rule applies >80% of the time, don't wrap it

Global skills count toward the per-session limit (recommended 20-50). When in doubt, start project-local.

• Folder named in kebab-case
• SKILL.md exists (exact spelling, case-sensitive)
• YAML frontmatter has --- delimiters
• name field: kebab-case, no spaces, no capitals
• description includes WHAT, WHEN, and DO NOT USE FOR
• No XML tags (< >) in frontmatter
• Instructions are clear and actionable
• Error handling included
• Examples provided
• References clearly linked
• allowed-tools restricts to minimum necessary tools
• Tested: triggers on relevant queries, doesn't trigger on unrelated
• SKILL.md body under 5,000 words

• Evaluate if >20-50 skills are enabled simultaneously
• Move detailed documentation to references/ (progressive disclosure)
• Use allowed-tools to restrict unnecessary tool access
• Add negative triggers to prevent over-triggering

1. Fork this repository
2. Add or modify skills following the Anthropic best practices above
3. Run the quality checklist before submitting PR
4. Ensure no sensitive information (API keys, project-specific URLs, team names) is included

MIT