agent-skills

AI agent skills, hooks, and project templates for Claude Code and Codex. Skills are prompt-based tools that orchestrate workflows; hooks enforce safety rules on tool calls; templates scaffold new projects.

AGENTS.md links to this file. Shared guidance lives in templates/user-agents-guidance.md, integration details in templates/user-{claude,codex}.md, and personal overlays in templates/. setup.sh detects installed agents; --target claude|codex|both overrides detection. scripts/setup_targets.py selects targets and scripts/setup_config.py owns configuration writes. Shared preferences live in ~/.agent-skills/config.json with per-agent overrides under agents; setup applies versioned migrations and retains legacy files. Canonical resources, commands, and source are ~/.agent-skills/skills/, ~/.agent-skills/scripts/, and ~/.agent-skills/source. Scripts use the selected Python 3.12+ runtime. Skill compatibility uses supportedAgents arrays in skills/compatibility.json; native capability mappings are documented in skills/shared/references/harness-capabilities.md. Codex policy integration enforces denials and defers other decisions to native approvals. New components need exclusion/removal paths and isolated-home installer tests.

Structure

skills/                # Skill definitions (SKILL.md + supporting files)
  ├── plan-work/          # Plan before building
  ├── do-work/            # Implement from a plan, commit, and open PR
  ├── code-review/        # Multi-agent parallel PR review (dialogic findings)
  ├── do-fixes/           # Apply fixes from a review, verify, commit, publish
  ├── plan-review/        # Expert review of implementation plans
  ├── create-repo/        # Monorepo scaffolding (Python scripts + Jinja2 templates)
  ├── solve-take-home/    # End-to-end take-home challenge solver
  ├── author-e2e/         # Playwright test generation from scenarios
  └── shared/             # Reusable agents, scripts (context.sh, get-diff.sh), references
hooks/
  ├── PreToolUse/      # Rule-based allow/deny engine for tool calls
  ├── MessageDisplay/  # Swaps tired phrases out of Claude's on-screen text
  └── Notification/    # macOS attention banners (click to focus the session)
templates/             # Shared, per-agent, and personal managed guidance
setup.sh               # Idempotent installer: links skills, installs hooks, registers MCP

Git workflow

• Commit frequently, push rarely. Each task gets its own commit for clean history, but only push when work is ready for review. Every push triggers CI — don't waste runs on intermediate states.
• One push per completed phase or session — not per commit.

Skill anatomy

Every skill has a SKILL.md with YAML frontmatter:

---
name: skill-name
description: Short phrase shown to user
argument-hint: "[options]"
depends-on: plan-work # optional prerequisite
context: fork # optional Claude extension; use native delegation in other agents
---

The rest of SKILL.md is the AI orchestrator prompt — phases, steps, and instructions for the supported agents. Skills may also include:

• references/ — docs the skill reads at runtime (e.g., flakiness-practices.md)
• agents/ — sub-agent definitions spawned by the skill
• scripts/ — shell/Python utilities called by the skill
• CLAUDE.md — area-specific conventions (read this when working in that skill)

Phrase swap (hooks/MessageDisplay/)

swap.py rewrites phrases in Claude's streaming text before it hits the screen — load-bearing → important. Display-only: the transcript and the model's context keep the original wording. Word list in phrases.json; personal additions in ~/.agent-skills/local-phrases.json. See hooks/MessageDisplay/CLAUDE.md.

Hook engine (hooks/PreToolUse/)

Rule-based engine that intercepts tool calls. Decision priority: deny > ask > allow > proceed.

Each rule in rules.json specifies an operation (e.g., read-path, write-path, git-force-push, bash-safe) and an action. See hooks/PreToolUse/CLAUDE.md for the full list of operations and how to add rules.

Adding a new rule:

1. Add the rule to rules.json
2. Create tests/rules/test_<slug>.py with RULE_DESCRIPTION matching the rule's description exactly
3. Include test_match, test_no_match, and at least one test_boundary_*
4. The convention checker (test_verify_rule_conventions.py) enforces this

create-repo templates (skills/create-repo/)

Python scripts handle deterministic work; the AI handles intelligence (interview, version resolution, customization, diagnostics).

Template layers: up to 4 layers, each overriding the previous:

1. templates/__common/ — universal files (all templates)
2. templates/__common/<platform>/ — platform-specific shared files (e.g., python/, ts/)
3. templates/<base>/ — base template files (when child declares "extends" in template.json)
4. templates/<template>/ — template-specific files

Each template has a template.json declaring its platform (a string like "python" or a list like ["ts", "python"] for multi-platform templates). When a list is given, each platform's __common/<platform>/ layer is applied in order. Templates can inherit from a base via "extends" and skip specific base files via "exclude" globs. Files with .j2 extension get Jinja2 rendering; others are copied as-is.

Template variables:

• {{ project_name }} — e.g., my-app
• {{ scope }} — e.g., @my-app
• {{ swift_project_name }} — PascalCase, e.g., MyApp
• {{ versions.<key> }} — resolved package versions

Directory name templating: Use __variable_name__ in template directory names to substitute context variables at scaffold time. E.g., Sources/__swift_project_name__/ becomes Sources/MyApp/. Unknown variables (like __pycache__) are left unchanged.

Version key normalization: npm names convert to underscore keys — @scope/package becomes scope_package. Strip @, replace /, -, . with _. Example: @hono/node-server → hono_node_server.

Python project: managed with uv. cd skills/create-repo && uv sync --group dev to set up.

Testing

All Python projects use uv and pytest.

Hooks (~440 tests, <1s)

make test-hooks

Runs every hooks/*/tests suite — the PreToolUse rule engine and the MessageDisplay phrase swap.

setup.sh helper (~90 tests, ~10s)

make test-scripts

Covers scripts/setup_config.py — the exclude schema, --without persistence, and every settings.json / CLAUDE.md / shell-rc primitive with its inverse — plus end-to-end runs of setup.sh against a sandbox HOME with claude and gh shimmed.

create-repo unit + structural eval (~55 tests, <1s)

cd skills/create-repo && uv run pytest tests/ -v -m "not e2e"

Scaffold E2E — interactive picker (needs pnpm, node, Docker or Postgres, ~3min)

make test-scaffolds                        # interactive — pick a template or all
make test-scaffolds TEMPLATE=fullstack-ts  # specific template
make test-scaffolds TEMPLATE=all           # all templates

In CI, set DATABASE_URL env var and the test auto-skips docker compose.

CI

GitHub Actions (.github/workflows/ci.yml) runs on push to PR branches and main:

• Unit tests — hook engine + create-repo unit/structural (~30s)
• Scaffold E2E — scaffolds all templates, runs full verify pipeline with Postgres service container (~3min)

Getting started

make init

This installs uv if missing, syncs Python environments (hooks + create-repo), and runs setup.sh to link skills and hooks. Run it once after cloning, or after switching to a new worktree.

setup.sh

Called by make init. Idempotent installer that:

1. Detects installed Claude Code and Codex agents, with optional target overrides
2. Migrates shared preferences while retaining legacy files and unrelated configuration
3. Links compatible skills, canonical resources, commands, and the source checkout
4. Installs applicable hook, permission, CLI, and MCP integrations
5. Refreshes managed CLAUDE.md and AGENTS.md guidance while preserving personal text

Components

Each step is a named component that can be installed on its own: skills, pretooluse (engine + rules + permissions), notification, message-display, window-title, attribution, mcp, guidance, cli. hooks is a group covering every hook component. Run bash setup.sh --list for descriptions.

• bash setup.sh (no arguments) always runs the full setup. Naming components selects them for that run only.
• bash setup.sh pretooluse installs only the hook engine.
• bash setup.sh --without guidance persists guidance into the exclude key of ~/.agent-skills/config.json; the section then removes what it installed, and every later bare run keeps it off. See "Opting out permanently" in the README for the schema.
• Each section in setup.sh is guarded by _want <component> and banner-tagged with # [component]. When adding a new install step, add its name to ALL_COMPONENTS, give it a _describe_component line, gate it, and give it an exclusion branch that removes what it installs (an _is_excluded <key> <name> check at the top of the section) — otherwise it silently runs on every partial install and can never be opted out of.
• All settings.json, CLAUDE.md, and shell-rc edits go through scripts/setup_config.py, whose install primitives each have an uninstall counterpart. Do not add inline Python heredocs to setup.sh; add a subcommand to the helper and a test for both directions.