diff --git a/skills/claude-api/SKILL.md b/skills/claude-api/SKILL.md new file mode 100644 index 0000000000..f728732791 --- /dev/null +++ b/skills/claude-api/SKILL.md @@ -0,0 +1,183 @@ +--- +name: claude-api +description: Build, debug, and optimize Claude API / Anthropic SDK applications. Covers prompt caching, thinking, tool use, batch processing, streaming, file APIs, citations, and model migrations. Trigger when code imports anthropic or @anthropic-ai/sdk. +origin: claude-code-harness +tools: Read, Write, Edit, Bash, Glob, Grep +--- + +# Claude API + +Build, debug, and optimize applications using the Claude API (Anthropic SDK). All apps built with this skill should include prompt caching. + +## When to Activate + +**Trigger on:** +- Code that imports `anthropic` or `@anthropic-ai/sdk` +- User asks about the Claude API, Anthropic SDK, or Managed Agents +- User adds or modifies Claude features: caching, thinking, tool use, batch, files, citations, memory +- User asks about a specific model (Opus, Sonnet, Haiku) +- Questions about prompt caching or cache hit rates in an Anthropic SDK project +- Migrating between Claude model versions + +**Skip when:** +- Code imports `openai` or another provider SDK +- Filename contains `-openai.py`, `-generic.py`, or similar +- Provider-neutral code with no Anthropic-specific patterns + +## Current Models (as of 2025) + +| Model | ID | Best For | +|-------|-----|----------| +| Claude Opus 4.7 | `claude-opus-4-7` | Most capable, complex reasoning | +| Claude Sonnet 4.6 | `claude-sonnet-4-6` | Balanced capability and speed | +| Claude Haiku 4.5 | `claude-haiku-4-5-20251001` | Fast, cost-efficient | + +Default to the latest and most capable model for new applications. + +## Prompt Caching (Required) + +Every app built with this skill must include prompt caching. Caching reduces cost and latency for repeated system prompts, tool definitions, and long documents. + +### Python + +```python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-7", + max_tokens=1024, + system=[ + { + "type": "text", + "text": "Your long system prompt here...", + "cache_control": {"type": "ephemeral"} + } + ], + messages=[{"role": "user", "content": "Hello"}] +) +``` + +### TypeScript + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); + +const response = await client.messages.create({ + model: "claude-opus-4-7", + max_tokens: 1024, + system: [ + { + type: "text", + text: "Your long system prompt here...", + cache_control: { type: "ephemeral" }, + }, + ], + messages: [{ role: "user", content: "Hello" }], +}); +``` + +### Cache Hit Detection + +```python +# Check cache performance +print(response.usage.cache_creation_input_tokens) # tokens written to cache +print(response.usage.cache_read_input_tokens) # tokens read from cache +``` + +## Tool Use + +```python +tools = [ + { + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string", "description": "City name"} + }, + "required": ["location"] + } + } +] + +response = client.messages.create( + model="claude-opus-4-7", + max_tokens=1024, + tools=tools, + messages=[{"role": "user", "content": "What's the weather in Paris?"}] +) +``` + +## Extended Thinking + +```python +response = client.messages.create( + model="claude-opus-4-7", + max_tokens=16000, + thinking={ + "type": "enabled", + "budget_tokens": 10000 + }, + messages=[{"role": "user", "content": "Solve this complex problem..."}] +) +``` + +## Streaming + +```python +with client.messages.stream( + model="claude-opus-4-7", + max_tokens=1024, + messages=[{"role": "user", "content": "Tell me a story"}] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +``` + +## Batch Processing + +```python +# Create a batch +batch = client.messages.batches.create( + requests=[ + {"custom_id": "req-1", "params": {"model": "claude-opus-4-7", "max_tokens": 100, "messages": [...]}}, + {"custom_id": "req-2", "params": {"model": "claude-opus-4-7", "max_tokens": 100, "messages": [...]}}, + ] +) + +# Poll for results +import time +while True: + batch = client.messages.batches.retrieve(batch.id) + if batch.processing_status == "ended": + break + time.sleep(60) +``` + +## Model Migration + +When migrating between model versions: + +1. Update the `model` string to the new ID +2. Check for deprecated parameters (some older params removed in newer models) +3. Test with the new model — behavior may differ even with the same prompt +4. Update any hardcoded model-specific limits (context window, max output tokens) + +## Common Issues + +| Issue | Cause | Fix | +|-------|-------|-----| +| Low cache hit rate | System prompt changes between calls | Make system prompt static; move dynamic content to user turn | +| `anthropic.APIStatusError: 529` | Overloaded | Implement exponential backoff | +| Tool call not executed | Model returned `tool_use` block | Handle `stop_reason: "tool_use"` and call the tool | +| Thinking not appearing | Budget too low | Increase `budget_tokens`; minimum ~1000 | + +## Related Skills + +- `agent-architecture-audit` — Audit multi-layer agent applications built on the Claude API +- `agent-harness-construction` — Build full agent harnesses using the Claude API diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000000..28a6fb6fcb --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,121 @@ +--- +name: code-review +description: Review the current diff for correctness bugs and reuse/simplification/efficiency cleanups at a given effort level. Pass --comment to post findings as inline PR comments, or --fix to apply findings to the working tree. Supports low/medium/high/max/ultra effort levels. +origin: claude-code-harness +tools: Read, Bash, Glob, Grep +--- + +# Code Review + +Review the current branch diff for correctness bugs, reuse opportunities, simplification wins, and efficiency improvements. Produces ranked findings with optional inline PR comments or automatic fixes. + +## When to Use + +- User asks for a code review of the current branch or a specific PR +- User wants findings posted as inline PR comments (`--comment`) +- User wants findings automatically applied to the working tree (`--fix`) +- User specifies an effort level: low, medium, high, max, or ultra + +**Invoke via:** `/code-review [effort] [--comment] [--fix] [PR#]` + +**Ultra mode** (`/code-review ultra` or `/code-review ultra `): launches a multi-agent cloud review. Billed and user-triggered only — do not invoke via Bash. + +## Effort Levels + +| Level | Coverage | Best For | +|-------|----------|----------| +| `low` | High-confidence, obvious bugs only | Quick sanity check before merge | +| `medium` | Moderate coverage, clear wins | Standard PR review | +| `high` | Broader coverage, may include uncertain findings | Important features or risky changes | +| `max` | Maximum breadth, includes speculative findings | Critical systems, security-sensitive changes | +| `ultra` | Deep multi-agent cloud review | Large PRs, pre-release audits | + +Default effort: `medium`. + +## Review Workflow + +### 1. Identify the Diff + +```bash +# Current branch vs main +git diff main...HEAD + +# Specific PR (with gh CLI) +gh pr diff + +# Staged changes only +git diff --cached +``` + +### 2. Collect Context + +Before reviewing, read: +- Files changed in the diff +- Adjacent files that depend on changed code +- Existing tests for changed functionality +- Any CLAUDE.md conventions that apply + +### 3. Apply Effort-Appropriate Analysis + +**Correctness bugs (all levels):** +- Logic errors, off-by-one errors, null/undefined dereferences +- Incorrect API usage, wrong argument order +- Race conditions, improper async/await +- Missing error handling at system boundaries + +**Simplification/reuse (medium+):** +- Duplicated logic that could use an existing utility +- Overly complex implementations with simpler alternatives +- Dead code or unused imports + +**Efficiency (high+):** +- N+1 queries, unnecessary re-renders, wasteful allocations +- Missing memoization or caching opportunities + +**Speculative (max only):** +- Hypothetical future issues +- Style suggestions beyond project conventions + +### 4. Rank Findings + +Order findings by: +1. **Severity** — bugs that would break production first +2. **Confidence** — high-confidence findings before speculative ones +3. **Impact** — changes that affect many callsites before isolated issues + +### 5. Output Findings + +For each finding: +- **File and line reference** — `path/to/file.ts:42` +- **Issue description** — what is wrong and why +- **Suggested fix** — concrete code change, not vague advice + +## Flags + +### `--comment` — Post as Inline PR Comments + +Posts each finding as an inline comment on the GitHub PR at the relevant line. Requires `gh` CLI authenticated. Does not modify the working tree. + +```bash +gh pr review --comment --body "..." +# or per-line: +gh api repos/:owner/:repo/pulls/:pr/comments ... +``` + +### `--fix` — Apply Findings + +After generating findings, applies fixes directly to the working tree. Equivalent to running `/simplify` after the review. Use only when findings are high-confidence. + +## What NOT to Review + +- Formatting — let the linter handle it +- Naming preferences with no correctness impact +- Architectural changes outside the PR scope +- Hypothetical future requirements (at low/medium effort) + +## Related Skills + +- `simplify` — Apply fixes from the current diff review +- `verify` — Confirm a change works by running the app +- `security-review` — Security-focused review of pending changes +- `agent-architecture-audit` — Deep audit for agent/LLM applications diff --git a/skills/fewer-permission-prompts/SKILL.md b/skills/fewer-permission-prompts/SKILL.md new file mode 100644 index 0000000000..c822f23c83 --- /dev/null +++ b/skills/fewer-permission-prompts/SKILL.md @@ -0,0 +1,110 @@ +--- +name: fewer-permission-prompts +description: Scan Claude Code transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to the project .claude/settings.json to reduce permission prompts without granting broad access. +origin: claude-code-harness +tools: Read, Write, Edit, Bash, Glob +--- + +# Fewer Permission Prompts + +Reduce Claude Code permission prompts by scanning transcripts for safe, repeated tool calls and adding a targeted allowlist to `.claude/settings.json`. + +## When to Use + +- User is tired of approving the same tool calls every session +- User asks to "reduce prompts" or "auto-allow common commands" +- You notice you're repeatedly requesting permission for read-only operations +- Setting up a new project where common safe commands are known in advance + +**Do not use to:** +- Grant broad write access (`Bash(**)`) — keep allowlists narrow +- Bypass prompts for destructive operations (deletions, force-pushes, drops) +- Skip prompts for commands that touch shared infrastructure + +## How It Works + +### 1. Scan Transcripts for Repeated Tool Calls + +Look at recent session transcripts (if available) to identify tool calls that: +- Are read-only (no side effects) +- Appear repeatedly across sessions +- Are consistently approved by the user + +Common candidates: +``` +Bash(git status) +Bash(git log *) +Bash(git diff *) +Bash(ls *) +Bash(find . *) +Bash(grep *) +Bash(node --version) +Bash(npm list *) +Read(**) +Glob(**) +``` + +### 2. Prioritize by Safety + +| Safety Level | Examples | Action | +|-------------|----------|--------| +| Safe — read-only | `git status`, `ls`, `grep`, `Read` | Allow | +| Safe — idempotent | `git diff`, `git log`, `node -e` | Allow with pattern | +| Potentially destructive | `rm`, `git reset`, `git push` | Do NOT allow | +| Always destructive | `git push --force`, `DROP TABLE` | Never allow | + +### 3. Add to Project Settings + +Edit `.claude/settings.json` (project-scoped, checked into git) or `.claude/settings.local.json` (personal, gitignored): + +```json +{ + "permissions": { + "allow": [ + "Bash(git status)", + "Bash(git log *)", + "Bash(git diff *)", + "Bash(git diff --stat *)", + "Bash(ls *)", + "Bash(ls -la *)", + "Bash(find . *)", + "Bash(grep *)", + "Bash(node --version)", + "Bash(npm list *)", + "Bash(npx tsc --noEmit)", + "Read(**)", + "Glob(**)" + ] + } +} +``` + +### 4. Validate Scope + +Before committing, confirm each entry in the allowlist: +- Uses the narrowest pattern that covers the actual use case +- Does not accidentally allow destructive variations +- Is appropriate to commit to the repo (use `settings.local.json` for personal preferences) + +## Pattern Syntax + +| Pattern | Matches | +|---------|---------| +| `Bash(git status)` | Exact command only | +| `Bash(git log *)` | `git log` with any arguments | +| `Bash(npm run *)` | Any npm script | +| `Read(**)` | Any file read | +| `Bash(find . -name *)` | `find` with name filter | + +## Settings File Choice + +| File | Use When | +|------|----------| +| `.claude/settings.json` | Team-wide allowlist — safe for everyone on the project | +| `.claude/settings.local.json` | Personal allowlist — your workflow, not teammates' | +| `~/.claude/settings.json` | Global — applies across all your projects | + +## Related Skills + +- `update-config` — Broader settings.json configuration (hooks, env vars) +- `configure-ecc` — ECC-specific hook profile configuration diff --git a/skills/init/SKILL.md b/skills/init/SKILL.md new file mode 100644 index 0000000000..e37ee684e2 --- /dev/null +++ b/skills/init/SKILL.md @@ -0,0 +1,159 @@ +--- +name: init +description: Initialize a new CLAUDE.md file with codebase documentation. Explores the project, extracts conventions, stack details, and key workflows, then writes a CLAUDE.md that gives future Claude Code sessions immediate context without re-exploration. +origin: claude-code-harness +tools: Read, Write, Bash, Glob, Grep +--- + +# Init + +Initialize a new `CLAUDE.md` file with accurate, project-specific documentation. Explores the codebase to extract the real stack, conventions, and workflows — not a template. + +## When to Use + +- Project has no `CLAUDE.md` yet +- User asks to "initialize" or "set up" CLAUDE.md +- Existing CLAUDE.md is stale and needs a full rewrite +- Onboarding a new project into Claude Code + +**Do not use if:** +- CLAUDE.md already exists and just needs small updates — edit it directly +- The project already has detailed CLAUDE.md content — avoid overwriting good documentation + +## What CLAUDE.md Is For + +`CLAUDE.md` gives Claude Code immediate context at session start without re-exploring the codebase every time. Good CLAUDE.md content: +- States what the project does and why +- Documents the stack (language, framework, package manager, test runner) +- Lists key commands (how to run, test, build, lint) +- Captures non-obvious conventions (naming, module structure, gotchas) +- Points to where things live + +Bad CLAUDE.md content: +- Generic advice Claude already knows (e.g., "write clean code") +- Out-of-date information +- Long explanations of things visible in the code + +## Discovery Workflow + +### 1. Identify the Stack + +```bash +# Language and package manager +ls package.json pyproject.toml Cargo.toml go.mod pom.xml build.gradle 2>/dev/null + +# Framework +cat package.json | grep -E '"next|"react|"vue|"express|"fastapi|"django' +cat pyproject.toml | grep -E 'fastapi|django|flask|sqlalchemy' + +# Test runner +cat package.json | grep -E '"jest|"vitest|"mocha|"playwright' +``` + +### 2. Find Key Commands + +```bash +# npm scripts +cat package.json | grep -A20 '"scripts"' + +# Makefile targets +cat Makefile | grep '^[a-z]' + +# Python entry points +cat pyproject.toml | grep '\[tool.taskipy\]\|\[tool.poe\]' -A10 +``` + +### 3. Understand the Directory Structure + +```bash +find . -maxdepth 2 -type d | grep -v node_modules | grep -v .git | grep -v __pycache__ +``` + +### 4. Extract Conventions + +Look for: +- File naming patterns (kebab-case, camelCase, PascalCase) +- Import style (absolute vs relative, barrel files) +- Test file location and naming +- Environment variable usage (`.env.example`) +- Existing CONTRIBUTING.md or docs/ folder + +### 5. Identify Non-Obvious Gotchas + +Read recent git history for clues: +```bash +git log --oneline -20 +git log --oneline --all | grep -i "fix\|hotfix\|workaround" | head -10 +``` + +## CLAUDE.md Template + +```markdown +# CLAUDE.md + +## Project Overview + +[One paragraph: what this project does and who uses it] + +## Stack + +- **Language**: [e.g., TypeScript 5, Python 3.11] +- **Framework**: [e.g., Next.js 14, FastAPI] +- **Package manager**: [npm / pnpm / yarn / pip / uv] +- **Test runner**: [Jest / Vitest / pytest / go test] +- **Database**: [if applicable] + +## Key Commands + +\`\`\`bash +# Install +npm install + +# Run dev server +npm run dev + +# Run tests +npm test + +# Build +npm run build + +# Lint +npm run lint +\`\`\` + +## Directory Structure + +\`\`\` +src/ + components/ # React components + lib/ # Shared utilities + api/ # API route handlers +tests/ # Test files (mirror src/ structure) +\`\`\` + +## Conventions + +- [File naming: kebab-case for files, PascalCase for components] +- [Imports: absolute paths via tsconfig paths aliases] +- [Tests: co-located next to source files as *.test.ts] + +## Non-Obvious Notes + +- [Any gotchas, workarounds, or environment requirements] +- [External dependencies that need manual setup] +``` + +## Quality Checks + +Before writing CLAUDE.md, verify: +- All commands in "Key Commands" actually work +- Directory structure reflects the real layout (not aspirational) +- No generic advice — every line should be project-specific + +After writing, read it back and ask: "Would a developer new to this project find this useful in their first 5 minutes?" + +## Related Skills + +- `update-config` — Configure `.claude/settings.json` hooks and permissions +- `configure-ecc` — Set up ECC plugin configuration diff --git a/skills/keybindings-help/SKILL.md b/skills/keybindings-help/SKILL.md new file mode 100644 index 0000000000..e7886bcbe7 --- /dev/null +++ b/skills/keybindings-help/SKILL.md @@ -0,0 +1,110 @@ +--- +name: keybindings-help +description: Customize Claude Code keyboard shortcuts by editing ~/.claude/keybindings.json. Use when the user wants to rebind keys, add chord shortcuts, change the submit key, or otherwise modify keybindings. +origin: claude-code-harness +tools: Read, Write, Edit +--- + +# Keybindings Help + +Customize Claude Code keyboard shortcuts by editing `~/.claude/keybindings.json`. Supports single key bindings, chord (multi-key) sequences, and context-sensitive bindings. + +## When to Use + +- User wants to rebind a key ("rebind ctrl+s to X") +- User wants to add a chord shortcut ("add a chord binding") +- User wants to change the submit key (default: Enter) +- User wants to customize keybindings in general +- User references `~/.claude/keybindings.json` + +## Keybindings File Location + +``` +~/.claude/keybindings.json +``` + +This is a global file — keybindings apply across all projects. + +## File Format + +```json +[ + { + "key": "ctrl+shift+enter", + "command": "workbench.action.chat.submit", + "when": "chatInputFocus" + }, + { + "key": "ctrl+k ctrl+r", + "command": "code-review", + "when": "inChat" + } +] +``` + +### Fields + +| Field | Required | Description | +|-------|----------|-------------| +| `key` | Yes | Key combination (see modifiers below) | +| `command` | Yes | The command or slash command to invoke | +| `when` | No | Context clause limiting when the binding is active | + +### Key Modifiers + +| Modifier | Alias | Notes | +|----------|-------|-------| +| `ctrl` | `cmd` (macOS) | Control key | +| `shift` | — | Shift key | +| `alt` | `opt` (macOS) | Alt/Option key | +| `meta` | — | Windows/Super key | + +### Chord Bindings + +Chords are two-key sequences separated by a space: + +```json +{ "key": "ctrl+k ctrl+c", "command": "toggleComment" } +``` + +The user presses `Ctrl+K`, releases, then presses `Ctrl+C`. + +## Common Customizations + +### Change Submit Key to Shift+Enter + +```json +[ + { "key": "shift+enter", "command": "chat.submit" }, + { "key": "enter", "command": "chat.newline" } +] +``` + +### Add Quick Code Review Chord + +```json +[ + { "key": "ctrl+k ctrl+r", "command": "/code-review" } +] +``` + +### Disable a Default Binding + +Set `command` to `""` (empty string) or `null` to disable: + +```json +[ + { "key": "ctrl+enter", "command": "" } +] +``` + +## Workflow + +1. **Read the current file**: `~/.claude/keybindings.json` (may not exist yet) +2. **Identify the binding** to add, change, or remove +3. **Edit or create** the file with the new binding +4. **Restart Claude Code** for changes to take effect + +## Related Skills + +- `update-config` — Edit `settings.json` for hooks, permissions, and env vars diff --git a/skills/loop/SKILL.md b/skills/loop/SKILL.md new file mode 100644 index 0000000000..85206d9fd4 --- /dev/null +++ b/skills/loop/SKILL.md @@ -0,0 +1,97 @@ +--- +name: loop +description: Run a prompt or slash command on a recurring interval using /loop. Omit the interval to let the model self-pace. Use for recurring tasks, status polling, or repeating a command at set intervals (e.g. /loop 5m /foo). Not for one-off tasks. +origin: claude-code-harness +tools: Bash +--- + +# Loop + +Run a prompt or slash command on a recurring interval. The harness re-invokes Claude on each tick with the same prompt, maintaining context across iterations. + +## When to Use + +- User wants to set up a recurring task ("check the deploy every 5 minutes") +- User wants to poll for status ("keep watching until the build passes") +- User wants to run something repeatedly on a schedule ("run /babysit-prs every 10 minutes") +- User wants Claude to self-pace iterations of a task (omit the interval) + +**Do not use for:** +- One-off tasks — just run the task directly +- Tasks that should run on a cron schedule after the session ends — use `schedule` instead + +## Invocation + +``` +/loop [interval] [prompt or /skill] +``` + +### Examples + +``` +/loop 5m /code-review # Run /code-review every 5 minutes +/loop 1m check deploy status # Poll deploy status every minute +/loop /babysit-prs # Self-paced PR monitoring +/loop 30s npm test # Run tests every 30 seconds +``` + +### Interval Format + +| Format | Meaning | +|--------|---------| +| `30s` | Every 30 seconds | +| `5m` | Every 5 minutes | +| `1h` | Every hour | +| (omitted) | Self-paced — model decides the interval | + +## Self-Paced Loops + +When no interval is given, Claude chooses its own delay between iterations based on what it's waiting for. Self-pacing is useful when: +- The work has variable duration (some iterations are fast, some slow) +- You're waiting for an external event with an unknown ETA +- The natural cadence depends on what Claude finds in each iteration + +The model picks delays to balance responsiveness against cost: +- Warm cache window (< 5 min): check frequently +- Long waits (> 5 min): space out to avoid cache misses + +## Stopping a Loop + +- Press `Ctrl+C` or close the session to stop the loop +- The loop exits automatically when the task is complete (model omits the next wake-up call) +- Use a condition in your prompt: "keep running until the CI is green" + +## Loop vs Schedule + +| Feature | `/loop` | `schedule` | +|---------|---------|-----------| +| Runs while session is active | Yes | No | +| Runs after session ends | No | Yes | +| Requires Claude Code open | Yes | No | +| Good for | Live monitoring, active polling | Nightly jobs, recurring reports | + +## Patterns + +### Poll Until Done + +``` +/loop 1m check if the deploy at staging.example.com is healthy; stop when it is +``` + +### Recurring Review + +``` +/loop 10m /code-review low +``` + +### Self-Paced Build Watch + +``` +/loop watch the CI output and report when the build passes or fails +``` + +## Related Skills + +- `schedule` — Recurring remote agents that run after the session ends +- `autonomous-loops` — Patterns for fully autonomous agent loops +- `update-config` — Configure hooks for event-driven automation (instead of polling) diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md new file mode 100644 index 0000000000..1f31976577 --- /dev/null +++ b/skills/review/SKILL.md @@ -0,0 +1,145 @@ +--- +name: review +description: Review a pull request. Fetches the PR diff, reads changed files in context, and produces ranked findings covering correctness, test coverage, and adherence to project conventions. Can post findings as inline PR comments. +origin: claude-code-harness +tools: Read, Bash, Glob, Grep +--- + +# Review + +Review a pull request end-to-end: fetch the diff, read changed files with full context, and produce ranked findings covering correctness bugs, test coverage, and project convention adherence. + +## When to Use + +- User asks to "review" a PR (by number or URL) +- User wants a thorough code review before merging +- User wants findings posted as inline GitHub PR comments +- Reviewing a PR from a teammate or dependency update + +**Invoke via:** `/review [PR# or URL]` + +For a quick diff review without a PR, use `code-review` instead. + +## Review Workflow + +### 1. Fetch the PR + +```bash +# Fetch PR metadata and diff +gh pr view --json title,body,author,baseRefName,headRefName,files,commits + +# Get the full diff +gh pr diff + +# Checkout the branch for deeper analysis +gh pr checkout +``` + +### 2. Read the PR Description + +Understand: +- What problem does this PR solve? +- What approach did the author take? +- Are there any noted trade-offs or areas for feedback? +- Is there a linked issue or spec? + +A PR description that doesn't explain the "why" is itself a finding. + +### 3. Analyze Changed Files + +For each file in the diff: +1. Read the full file (not just the diff) for context +2. Check how the change fits into the surrounding code +3. Identify callsites of changed functions +4. Check tests for the changed behavior + +### 4. Correctness Analysis + +For each change, verify: +- **Logic** — does the implementation match the intent? +- **Edge cases** — what happens at boundaries (empty, null, max)? +- **Error handling** — are failures handled at system boundaries? +- **Concurrency** — any race conditions or shared state issues? +- **API contracts** — are external/internal APIs used correctly? + +### 5. Test Coverage + +- Are the changed behaviors covered by tests? +- Do existing tests still pass with this change? +- Are edge cases tested? +- Is the happy path clearly exercised? + +### 6. Convention Adherence + +Check against project conventions (from CLAUDE.md and existing patterns): +- File naming and structure +- Import style +- Error handling patterns +- Logging conventions +- Documentation standards + +### 7. Rank and Report Findings + +Order findings by: +1. **Severity** — bugs that break production first +2. **Confidence** — high-confidence findings before speculative +3. **Scope** — findings affecting many users/callsites before isolated ones + +For each finding: +- **Location**: `path/to/file.ts:42` +- **Severity**: critical / high / medium / low +- **Issue**: what is wrong and why it matters +- **Suggestion**: concrete fix, not vague advice + +## Posting Inline Comments + +To post findings as inline PR comments: + +```bash +# Post a general comment +gh pr comment --body "Overall findings: ..." + +# Post an inline comment at a specific line +gh api repos/:owner/:repo/pulls/:pr/comments \ + --method POST \ + --field body="Issue: ..." \ + --field commit_id="" \ + --field path="src/file.ts" \ + --field line=42 +``` + +## What NOT to Review + +- Style issues the linter should catch automatically +- Naming preferences with no correctness impact +- Changes outside the PR scope (mention as a separate suggestion, don't block) +- Architectural re-designs beyond the PR's stated scope + +## Review Summary Format + +``` +## Summary + +[1-2 sentence overall assessment] + +## Findings + +### Critical +- `src/auth.ts:87` — [issue] [suggestion] + +### High +- `src/api/users.ts:23` — [issue] [suggestion] + +### Medium +- `src/utils/format.ts:11` — [issue] [suggestion] + +## Positive Notes + +[Things done especially well — optional but valuable] +``` + +## Related Skills + +- `code-review` — Review the current working tree diff (no PR required) +- `security-review` — Security-focused review of pending changes +- `verify` — Confirm the change works by running the app diff --git a/skills/run/SKILL.md b/skills/run/SKILL.md new file mode 100644 index 0000000000..f81cd31872 --- /dev/null +++ b/skills/run/SKILL.md @@ -0,0 +1,123 @@ +--- +name: run +description: Launch and drive the project's app to see a change working in practice. Use when asked to run, start, or screenshot the app, confirm a change works in the real app (not just tests), or validate local changes before pushing. +origin: claude-code-harness +tools: Read, Bash, Glob +--- + +# Run + +Launch and drive the project's application to see changes working in practice. Looks for a project-specific launch skill first, then falls back to standard patterns per project type. + +## When to Use + +- User asks to "run" or "start" the app +- User wants to "see the change working" or "confirm it works" +- User asks to screenshot or interact with the running app +- User wants to validate changes before pushing or opening a PR +- Testing a golden path or edge case in the live application + +**Not a substitute for:** +- Automated tests — run those with `npm test`, `pytest`, etc. +- Type checking — run `tsc --noEmit` separately +- Code review — use `code-review` for diff analysis + +## Launch Strategy + +### 1. Check for a Project Skill + +Look for a project-specific run skill: +```bash +ls .claude/skills/run* 2>/dev/null +cat CLAUDE.md | grep -A5 "run\|start\|launch" +``` + +If found, follow the project's documented launch instructions. + +### 2. Detect Project Type and Launch + +**Node.js / npm** +```bash +npm run dev # or start, or serve +npx ts-node src/index.ts +node scripts/main.js +``` + +**Python** +```bash +python -m uvicorn app.main:app --reload # FastAPI/Starlette +python app.py +python -m flask run +python manage.py runserver # Django +``` + +**CLI tool** +```bash +# Build first if needed +npm run build +# Then run the CLI +node dist/index.js +npx +``` + +**Browser-based / frontend** +```bash +npm run dev # Vite, Next.js, CRA +npm start +``` + +**Go** +```bash +go run main.go +go run ./cmd/server +``` + +**Rust** +```bash +cargo run +cargo run --bin +``` + +### 3. Validate the App is Running + +After launch, confirm: +- No startup errors in the output +- The expected port is listening: `curl -s http://localhost:3000/health` +- The process didn't immediately exit + +### 4. Exercise the Change + +Navigate to or invoke the specific feature that was changed: +- For web apps: make an HTTP request or open in browser +- For CLI tools: run the relevant subcommand +- For APIs: call the affected endpoint + +### 5. Check for Regressions + +After confirming the target change works, spot-check adjacent features: +- Related routes or commands +- Shared utilities the change touches +- Any feature that imports the modified file + +## Reporting + +After running the app: +- State whether the change works as expected +- Note any errors, warnings, or unexpected output +- List what was tested (golden path + any edge cases) +- If the UI cannot be tested (no display), say so explicitly rather than claiming success + +## Common Issues + +| Issue | Fix | +|-------|-----| +| Port already in use | `lsof -i :` to find the process, then kill it | +| Missing environment variables | Copy `.env.example` to `.env` and fill in values | +| Dependencies not installed | Run `npm install` or `pip install -r requirements.txt` | +| Build step required | Check `package.json` scripts for a `build` step before `start` | + +## Related Skills + +- `verify` — Confirm a specific code change works correctly +- `code-review` — Review the diff before running +- `e2e-testing` — Full end-to-end test suite diff --git a/skills/schedule/SKILL.md b/skills/schedule/SKILL.md new file mode 100644 index 0000000000..5048a2aff2 --- /dev/null +++ b/skills/schedule/SKILL.md @@ -0,0 +1,118 @@ +--- +name: schedule +description: Create, update, list, or run scheduled remote agents (routines) that execute on a cron schedule. Use when the user wants to schedule a recurring remote agent, set up automated tasks, or create a one-time scheduled run. +origin: claude-code-harness +tools: Bash +--- + +# Schedule + +Create, update, list, and run scheduled remote agents — called "routines" — that execute on a cron schedule, even when Claude Code is not running. + +## When to Use + +- User wants to schedule a recurring remote agent ("run this nightly", "every Monday morning") +- User wants to set up an automated task ("generate a weekly report") +- User wants a one-time scheduled run ("remind me to check X tomorrow", "run this once at 3pm") +- User wants to list or manage existing scheduled routines + +**Do not use for:** +- Live session polling — use `loop` instead +- One-off tasks that should run immediately — just run them now + +## Invocation + +``` +/schedule [create|list|run|update|delete] [options] +``` + +### Create a Routine + +``` +/schedule create --name "nightly-review" --cron "0 2 * * *" --prompt "/code-review" +/schedule create --name "weekly-report" --cron "0 9 * * MON" --prompt "generate weekly status report" +/schedule create --at "2024-01-15 14:00" --prompt "check if the migration is complete" +``` + +### List Routines + +``` +/schedule list +``` + +### Run a Routine Now + +``` +/schedule run nightly-review +``` + +### Update a Routine + +``` +/schedule update nightly-review --cron "0 3 * * *" +``` + +### Delete a Routine + +``` +/schedule delete nightly-review +``` + +## Cron Schedule Format + +``` +┌─── minute (0-59) +│ ┌── hour (0-23) +│ │ ┌─ day of month (1-31) +│ │ │ ┌ month (1-12) +│ │ │ │ ┌ day of week (0-6, Sun=0) +* * * * * +``` + +### Common Schedules + +| Cron | Meaning | +|------|---------| +| `0 * * * *` | Every hour | +| `0 9 * * *` | Daily at 9am | +| `0 9 * * MON` | Every Monday at 9am | +| `0 2 * * *` | Nightly at 2am | +| `*/15 * * * *` | Every 15 minutes | +| `0 0 1 * *` | First of each month | + +## One-Time Scheduled Runs + +For a one-time future run, use `--at` instead of `--cron`: + +``` +/schedule create --at "tomorrow 9am" --prompt "check if the feature flag is ready to enable" +/schedule create --at "2024-12-31 23:59" --prompt "run year-end report" +``` + +## Schedule vs Loop + +| Feature | `schedule` | `loop` | +|---------|-----------|--------| +| Runs after session ends | Yes | No | +| Requires Claude Code open | No | Yes | +| Persistent across reboots | Yes | No | +| Good for | Nightly jobs, weekly reports | Live polling, active monitoring | + +## What Routines Can Do + +Scheduled routines run a full Claude Code agent with access to: +- All tools available in a normal session +- The project working directory +- Any MCP servers configured for the project + +Routines can: +- Run code reviews, generate reports, send notifications +- Check external services and file issues +- Run tests and post results +- Any task you'd give Claude in a normal session + +## Related Skills + +- `loop` — Run a command on a recurring interval during a live session +- `autonomous-loops` — Patterns for fully autonomous agent loops +- `update-config` — Configure hooks for event-driven automation diff --git a/skills/security-review/SKILL.md b/skills/security-review/SKILL.md index 0846d70a19..2e579dd26c 100644 --- a/skills/security-review/SKILL.md +++ b/skills/security-review/SKILL.md @@ -7,9 +7,59 @@ metadata: # Security Review Skill -This skill ensures all code follows security best practices and identifies potential vulnerabilities. +Two modes: (1) **Branch review** — audit pending changes on the current branch for security issues before merge; (2) **General checklist** — comprehensive security patterns for new features. -## When to Activate +## Branch Security Review + +Use this mode when asked to "security review the current branch" or "review pending changes for security issues." + +### 1. Get the Diff + +```bash +git diff main...HEAD +# or for a specific PR: +gh pr diff +``` + +### 2. Scan for High-Risk Patterns + +```bash +# Hardcoded secrets +grep -rn "password\|secret\|api_key\|token\|credential" --include="*.ts" --include="*.js" --include="*.py" + +# SQL concatenation +grep -rn "query.*\+\|f\"SELECT\|f'SELECT" --include="*.py" --include="*.ts" + +# eval / exec +grep -rn "eval(\|exec(\|execSync(" --include="*.js" --include="*.ts" + +# shell injection +grep -rn "child_process\|subprocess\|os\.system\|shell=True" + +# Dangerous deserializers +grep -rn "pickle\.loads\|yaml\.load(\|JSON\.parse.*req\." +``` + +### 3. Check the Changed Files Against OWASP Top 10 + +For each changed file, evaluate which OWASP categories apply and verify the checklist sections below. + +### 4. Output Format + +Report findings ordered by severity: + +| Severity | Meaning | +|----------|---------| +| `critical` | Exploitable in production without special access | +| `high` | Likely exploitable with common attacker capability | +| `medium` | Exploitable under specific conditions | +| `low` | Defense-in-depth improvements | + +For each finding: file:line, severity, vulnerability class, attack scenario, recommended fix. + +--- + +## When to Use the General Checklist - Implementing authentication or authorization - Handling user input or file uploads diff --git a/skills/simplify/SKILL.md b/skills/simplify/SKILL.md new file mode 100644 index 0000000000..eee8b19e8f --- /dev/null +++ b/skills/simplify/SKILL.md @@ -0,0 +1,75 @@ +--- +name: simplify +description: Review the current diff and apply the fixes — equivalent to /code-review --fix. Finds correctness bugs, unnecessary complexity, and reuse opportunities, then applies the changes directly to the working tree. +origin: claude-code-harness +tools: Read, Write, Edit, Bash, Glob, Grep +--- + +# Simplify + +Review the current branch diff and apply fixes directly to the working tree. Equivalent to `/code-review --fix`. Targets correctness bugs, unnecessary complexity, and missed reuse opportunities. + +## When to Use + +- User asks to "simplify" the current changes +- User wants code review findings applied automatically +- User says "clean up the diff" or "fix the obvious issues" +- After a first-pass implementation that needs tidying before final review + +**Invoke via:** `/simplify` + +This is a shortcut for `/code-review --fix`. For review-only (no edits), use `code-review`. + +## What Simplify Does + +### 1. Review the Diff + +Reads the current diff against the base branch: + +```bash +git diff main...HEAD +``` + +Analyzes for: +- **Correctness bugs** — logic errors, null dereferences, wrong API usage +- **Unnecessary complexity** — verbose code with simpler equivalents +- **Missed reuse** — duplicated logic that an existing utility already handles +- **Dead code** — imports, variables, or branches that can't be reached + +### 2. Apply Fixes + +For each finding, directly edits the affected file using minimal, targeted changes. Does not: +- Reformat code the linter should handle +- Add abstractions beyond what the task requires +- Refactor code outside the diff scope +- Add comments explaining what the code does + +### 3. Report What Changed + +After applying fixes, reports: +- Which files were edited +- What was changed and why +- Any findings that were too uncertain to auto-apply (flagged for human review) + +## Simplification Principles + +These guide what gets fixed and what gets left alone: + +- **Three similar lines beat a premature abstraction** — don't DRY three callsites into a helper unless it's clearly the right move +- **Don't design for hypothetical future requirements** — only simplify what's actually in the diff +- **No half-finished implementations** — if a simplification requires follow-up work, flag it instead of applying it +- **Trust the framework** — don't add error handling for scenarios the framework already handles +- **No backwards-compatibility shims** — if something is unused, delete it cleanly + +## Scope Boundaries + +Simplify operates only on **code in the current diff**. It does not: +- Modify files not touched by the current branch +- Change test files unless the test is directly related to a fixed bug +- Touch configuration files unless misconfiguration is the bug + +## Related Skills + +- `code-review` — Review without applying fixes (for human sign-off first) +- `verify` — Confirm the simplified code still works +- `security-review` — Security pass after simplification diff --git a/skills/update-config/SKILL.md b/skills/update-config/SKILL.md new file mode 100644 index 0000000000..6c4d68574e --- /dev/null +++ b/skills/update-config/SKILL.md @@ -0,0 +1,114 @@ +--- +name: update-config +description: Configure Claude Code harness via settings.json. Use for automated behaviors (hooks), permissions, env vars, hook troubleshooting, and any changes to settings.json or settings.local.json. For simple settings like theme/model, suggest /config instead. +origin: claude-code-harness +tools: Read, Write, Edit, Bash +--- + +# Update Config + +Configure the Claude Code harness by editing `settings.json` or `settings.local.json`. This skill covers automated behaviors (hooks), permission allowlists, environment variables, and hook troubleshooting. + +## When to Use + +- User says "from now on when X", "each time X", "whenever X", "before/after X" — these require hooks, not memory +- User asks to allow a tool or command ("allow npm commands", "add bq permission") +- User wants to move a permission to global or project settings +- User wants to set an environment variable ("set DEBUG=true") +- User is troubleshooting a hook that isn't firing or is blocking +- Any direct edit to `settings.json` or `settings.local.json` + +**Do not use for:** +- Simple theme or model changes — suggest `/config` instead +- One-off tasks that don't need persistent automation + +## Key Concepts + +### Settings File Locations + +| File | Scope | +|------|-------| +| `~/.claude/settings.json` | Global — applies to all projects | +| `.claude/settings.json` | Project — checked into the repo | +| `.claude/settings.local.json` | Project-local — gitignored, personal overrides | + +### Hooks vs Memory + +Automated behaviors ("run X after every edit") **must** be implemented as hooks in `settings.json`. Claude's memory and preferences cannot execute code automatically — the harness does. Memory is for context; hooks are for automation. + +### Hook Event Types + +| Event | When it fires | +|-------|--------------| +| `PreToolUse` | Before any tool call — can block execution | +| `PostToolUse` | After any tool call completes | +| `Stop` | When Claude finishes a turn | +| `Notification` | On background notifications | + +## How It Works + +### Adding a Hook + +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": { "tool_name": "Edit" }, + "hooks": [ + { "type": "command", "command": "npx eslint --fix $CLAUDE_TOOL_INPUT_FILE_PATH" } + ] + } + ] + } +} +``` + +### Adding a Permission + +```json +{ + "permissions": { + "allow": [ + "Bash(npm run *)", + "Bash(git *)", + "Read(**)" + ] + } +} +``` + +### Setting an Environment Variable + +```json +{ + "env": { + "DEBUG": "true", + "NODE_ENV": "development" + } +} +``` + +## Workflow + +1. **Identify the target file** — global (`~/.claude/settings.json`) or project (`.claude/settings.json`) +2. **Read the current file** before editing +3. **Apply the change** — hook, permission, or env var +4. **Validate JSON** — malformed settings silently fail +5. **Test the hook** — trigger the event and confirm it fires + +## Hook Troubleshooting + +Common reasons a hook doesn't fire: + +- **Wrong event type** — `PreToolUse` vs `PostToolUse` vs `Stop` +- **Matcher too narrow** — check `tool_name` spelling (case-sensitive) +- **JSON parse error** — the entire settings file is silently skipped +- **Command exits non-zero** — for `PreToolUse`, this blocks the tool; for others it's logged +- **ECC hook gating** — if using ECC hooks, check `ECC_DISABLED_HOOKS` env var + +## Related Skills + +- `configure-ecc` — ECC-specific configuration and install profiles +- `autonomous-loops` — Setting up autonomous agent loops via hooks +- `keybindings-help` — Customize Claude Code keyboard shortcuts diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md new file mode 100644 index 0000000000..f14f2b906f --- /dev/null +++ b/skills/verify/SKILL.md @@ -0,0 +1,100 @@ +--- +name: verify +description: Verify that a code change actually works by running the app and observing behavior. Use when asked to verify a PR, confirm a fix works, test a change manually, check that a feature works, or validate local changes before pushing. +origin: claude-code-harness +tools: Read, Bash, Glob +--- + +# Verify + +Verify that a code change does what it's supposed to do by running the app and observing actual behavior — not just reading code or running type checks. + +## When to Use + +- User asks to "verify" a PR or change +- User wants to confirm a fix actually works end-to-end +- User wants manual testing of a feature before pushing +- User wants to validate local changes before a code review +- Type checking and tests pass but you need to confirm the feature works in practice + +**Not a substitute for:** +- Automated test suites — run those separately +- Code review — use `code-review` for correctness analysis +- Security review — use `security-review` for vulnerability scanning + +## Verification Workflow + +### 1. Understand What Changed + +```bash +git diff --stat HEAD~1 +git diff HEAD~1 +``` + +Identify the feature, fix, or behavior change to verify. + +### 2. Determine the Golden Path + +For a given change, identify: +- **Happy path**: the primary use case that should work +- **Edge cases**: boundary conditions or error states affected by the change +- **Regression surface**: existing features that could have broken + +### 3. Run the App + +Start the application in a mode appropriate for the change: + +```bash +# Web server +npm run dev + +# CLI tool +node scripts/ecc.js + +# Test suite (as a smoke check) +npm test +``` + +### 4. Exercise the Change + +Interact with the app to trigger the changed code path. Observe: +- Does the output match expectations? +- Are there unexpected errors in logs or console? +- Does the UI render correctly (if applicable)? + +### 5. Check for Regressions + +Exercise adjacent features that could have been affected. Look for: +- Unintended side effects +- Broken imports or missing exports +- Changed behavior in unmodified code paths + +### 6. Report Findings + +After verification: +- State clearly whether the change works as intended +- List any edge cases tested and their outcomes +- Call out any regressions found +- If you cannot test the UI (no display), say so explicitly rather than claiming success + +## Verification by Change Type + +| Change Type | Key Things to Verify | +|-------------|---------------------| +| Bug fix | Reproduce the original bug, then confirm it's gone | +| New feature | Exercise the golden path + at least one edge case | +| Refactor | All existing behavior preserved; no output changes | +| Config change | App starts cleanly; relevant feature works | +| Dependency update | No runtime errors; critical paths still work | + +## Important Notes + +- **Type checking is not verification** — `tsc --noEmit` passing means the types are consistent, not that the feature works. +- **Tests are not verification** — unit tests passing means individual units work in isolation, not that the integrated app works. +- If you cannot run the app (missing deps, CI-only environment), say so rather than skipping verification. + +## Related Skills + +- `code-review` — Correctness analysis of the diff +- `run` — Launch and drive the app for broader exploration +- `security-review` — Security audit of pending changes