Reduce context token usage by 79% — fix silent component exclusion (#161)
* Update create-agent-skills to match 2026 official docs, add /triage-prs command - Rewrite SKILL.md to document that commands and skills are now merged - Add new frontmatter fields: disable-model-invocation, user-invocable, context, agent - Add invocation control table and dynamic context injection docs - Fix skill-structure.md: was incorrectly recommending XML tags over markdown headings - Update official-spec.md with complete 2026 specification - Add local /triage-prs command for PR triage workflow - Add PR triage plan document Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * [2.31.0] Reduce context token usage by 79%, include recent community contributions The plugin was consuming 316% of Claude Code's description character budget (~50,500 chars vs 16,000 limit), causing components to be silently excluded. Now at 65% (~10,400 chars) with all components visible. Changes: - Trim all 29 agent descriptions (move examples to body) - Add disable-model-invocation to 18 manual commands - Add disable-model-invocation to 6 manual skills - Include recent community contributions in changelog - Fix component counts (29 agents, 24 commands, 18 skills) Contributors: @trevin, @terryli, @robertomello, @zacwilliams, @aarnikoskela, @samxie, @davidalley Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix: keep disable-model-invocation off commands called by /lfg, rename xcode-test - Remove disable-model-invocation from test-browser, feature-video, resolve_todo_parallel — these are called programmatically by /lfg and /slfg - Rename xcode-test to test-xcode to match test-browser naming convention Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix: keep git-worktree skill auto-invocable (used by /workflows:work) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat(converter): support disable-model-invocation frontmatter Parse disable-model-invocation from command and skill frontmatter. Commands/skills with this flag are excluded from OpenCode command maps and Codex prompt/skill generation, matching Claude Code behavior where these components are user-only invocable. Bump converter version to 0.3.0. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
@@ -11,8 +11,8 @@
|
||||
"plugins": [
|
||||
{
|
||||
"name": "compound-engineering",
|
||||
"description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 25 commands, and 16 skills.",
|
||||
"version": "2.30.0",
|
||||
"description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 24 commands, and 18 skills.",
|
||||
"version": "2.31.0",
|
||||
"author": {
|
||||
"name": "Kieran Klaassen",
|
||||
"url": "https://github.com/kieranklaassen",
|
||||
|
||||
193
.claude/commands/triage-prs.md
Normal file
193
.claude/commands/triage-prs.md
Normal file
@@ -0,0 +1,193 @@
|
||||
---
|
||||
name: triage-prs
|
||||
description: Triage all open PRs with parallel agents, label, group, and review one-by-one
|
||||
argument-hint: "[optional: repo owner/name or GitHub PRs URL]"
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Bash(git log *)
|
||||
---
|
||||
|
||||
# Triage Open Pull Requests
|
||||
|
||||
Review, label, and act on all open PRs for a repository using parallel review agents. Produces a grouped triage report, applies labels, cross-references with issues, and walks through each PR for merge/comment decisions.
|
||||
|
||||
## Step 0: Detect Repository
|
||||
|
||||
Detect repo context:
|
||||
- Current repo: !`gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "no repo detected"`
|
||||
- Current branch: !`git branch --show-current 2>/dev/null`
|
||||
|
||||
If `$ARGUMENTS` contains a GitHub URL or `owner/repo`, use that instead. Confirm the repo with the user if ambiguous.
|
||||
|
||||
## Step 1: Gather Context (Parallel)
|
||||
|
||||
Run these in parallel:
|
||||
|
||||
1. **List all open PRs:**
|
||||
```bash
|
||||
gh pr list --repo OWNER/REPO --state open --limit 50
|
||||
```
|
||||
|
||||
2. **List all open issues:**
|
||||
```bash
|
||||
gh issue list --repo OWNER/REPO --state open --limit 50
|
||||
```
|
||||
|
||||
3. **List existing labels:**
|
||||
```bash
|
||||
gh label list --repo OWNER/REPO --limit 50
|
||||
```
|
||||
|
||||
4. **Check recent merges** (to detect duplicate/superseded PRs):
|
||||
```bash
|
||||
git log --oneline -20 main
|
||||
```
|
||||
|
||||
## Step 2: Batch PRs by Theme
|
||||
|
||||
Group PRs into review batches of 4-6 based on apparent type:
|
||||
|
||||
- **Bug fixes** - titles with `fix`, `bug`, error descriptions
|
||||
- **Features** - titles with `feat`, `add`, new functionality
|
||||
- **Documentation** - titles with `docs`, `readme`, terminology
|
||||
- **Configuration/Setup** - titles with `config`, `setup`, `install`
|
||||
- **Stale/Old** - PRs older than 30 days
|
||||
|
||||
## Step 3: Parallel Review (Team of Agents)
|
||||
|
||||
Spawn one review agent per batch using the Task tool. Each agent should:
|
||||
|
||||
For each PR in their batch:
|
||||
1. Run `gh pr view --repo OWNER/REPO <number> --json title,body,files,additions,deletions,author,createdAt`
|
||||
2. Run `gh pr diff --repo OWNER/REPO <number>` (pipe to `head -200` for large diffs)
|
||||
3. Determine:
|
||||
- **Description:** 1-2 sentence summary of the change
|
||||
- **Label:** Which existing repo label fits best
|
||||
- **Action:** merge / request changes / close / needs discussion
|
||||
- **Related PRs:** Any PRs in this or other batches that touch the same files or feature
|
||||
- **Quality notes:** Code quality, test coverage, staleness concerns
|
||||
|
||||
Instruct each agent to:
|
||||
- Flag PRs that touch the same files (potential merge conflicts)
|
||||
- Flag PRs that duplicate recently merged work
|
||||
- Flag PRs that are part of a group solving the same problem differently
|
||||
- Report findings as a markdown table
|
||||
- Send findings back via message when done
|
||||
|
||||
## Step 4: Cross-Reference Issues
|
||||
|
||||
After all agents report, match issues to PRs:
|
||||
|
||||
- Check if any PR title/body mentions `Fixes #X` or `Closes #X`
|
||||
- Check if any issue title matches a PR's topic
|
||||
- Look for duplicate issues (same bug reported twice)
|
||||
|
||||
Build a mapping table:
|
||||
```
|
||||
| Issue | PR | Relationship |
|
||||
|-------|-----|--------------|
|
||||
| #158 | #159 | PR fixes issue |
|
||||
```
|
||||
|
||||
## Step 5: Identify Themes
|
||||
|
||||
Group all issues into themes (3-6 themes):
|
||||
- Count issues per theme
|
||||
- Note which themes have PRs addressing them and which don't
|
||||
- Flag themes with competing/overlapping PRs
|
||||
|
||||
## Step 6: Compile Triage Report
|
||||
|
||||
Present a single report with:
|
||||
|
||||
1. **Summary stats:** X open PRs, Y open issues, Z themes
|
||||
2. **PR groups** with recommended actions:
|
||||
- Group name and related PRs
|
||||
- Per-PR: #, title, author, description, label, action
|
||||
3. **Issue-to-PR mapping**
|
||||
4. **Themes across issues**
|
||||
5. **Suggested cleanup:** spam issues, duplicates, stale items
|
||||
|
||||
## Step 7: Apply Labels
|
||||
|
||||
After presenting the report, ask user:
|
||||
|
||||
> "Apply these labels to all PRs on GitHub?"
|
||||
|
||||
If yes, run `gh pr edit --repo OWNER/REPO <number> --add-label "<label>"` for each PR.
|
||||
|
||||
## Step 8: One-by-One Review
|
||||
|
||||
Use **AskUserQuestion** to ask:
|
||||
|
||||
> "Ready to walk through PRs one-by-one for merge/comment decisions?"
|
||||
|
||||
Then for each PR, ordered by priority (bug fixes first, then docs, then features, then stale):
|
||||
|
||||
### Show the PR:
|
||||
|
||||
```
|
||||
### PR #<number> - <title>
|
||||
Author: <author> | Files: <count> | +<additions>/-<deletions> | <age>
|
||||
Label: <label>
|
||||
|
||||
<1-2 sentence description>
|
||||
|
||||
Fixes: <linked issues if any>
|
||||
Related: <related PRs if any>
|
||||
```
|
||||
|
||||
Show the diff (trimmed to key changes if large).
|
||||
|
||||
### Ask for decision:
|
||||
|
||||
Use **AskUserQuestion**:
|
||||
- **Merge** - Merge this PR now
|
||||
- **Comment & skip** - Leave a comment explaining why not merging, keep open
|
||||
- **Close** - Close with a comment
|
||||
- **Skip** - Move to next without action
|
||||
|
||||
### Execute decision:
|
||||
|
||||
- **Merge:** `gh pr merge --repo OWNER/REPO <number> --squash`
|
||||
- If PR fixes an issue, close the issue too
|
||||
- **Comment & skip:** `gh pr comment --repo OWNER/REPO <number> --body "<comment>"`
|
||||
- Ask user what to say, or generate a grateful + specific comment
|
||||
- **Close:** `gh pr close --repo OWNER/REPO <number> --comment "<reason>"`
|
||||
- **Skip:** Move on
|
||||
|
||||
## Step 9: Post-Merge Cleanup
|
||||
|
||||
After all PRs are reviewed:
|
||||
|
||||
1. **Close resolved issues** that were fixed by merged PRs
|
||||
2. **Close spam/off-topic issues** (confirm with user first)
|
||||
3. **Summary of actions taken:**
|
||||
```
|
||||
## Triage Complete
|
||||
|
||||
Merged: X PRs
|
||||
Commented: Y PRs
|
||||
Closed: Z PRs
|
||||
Skipped: W PRs
|
||||
|
||||
Issues closed: A
|
||||
Labels applied: B
|
||||
```
|
||||
|
||||
## Step 10: Post-Triage Options
|
||||
|
||||
Use **AskUserQuestion**:
|
||||
|
||||
1. **Run `/release-docs`** - Update documentation site if components changed
|
||||
2. **Run `/changelog`** - Generate changelog for merged PRs
|
||||
3. **Commit any local changes** - If version bumps needed
|
||||
4. **Done** - Wrap up
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **DO NOT merge without user approval** for each PR
|
||||
- **DO NOT force push or destructive actions**
|
||||
- Comments on declined PRs should be grateful and constructive
|
||||
- When PRs conflict with each other, note this and suggest merge order
|
||||
- When multiple PRs solve the same problem differently, flag for user to pick one
|
||||
- Use Haiku model for review agents to save cost (they're doing read-only analysis)
|
||||
128
docs/plans/2026-02-08-feat-pr-triage-and-merge-plan.md
Normal file
128
docs/plans/2026-02-08-feat-pr-triage-and-merge-plan.md
Normal file
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: PR Triage, Review & Merge
|
||||
type: feat
|
||||
date: 2026-02-08
|
||||
---
|
||||
|
||||
# PR Triage, Review & Merge
|
||||
|
||||
## Overview
|
||||
|
||||
Review all 17 open PRs one-by-one. Merge the ones that look good, leave constructive comments on the ones we won't take (keeping them open for contributors to address). Close duplicates/spam.
|
||||
|
||||
## Approach
|
||||
|
||||
Show the diff for each PR, get a go/no-go, then either merge or comment. PRs are ordered by priority group.
|
||||
|
||||
## Group 1: Bug Fixes (high confidence merges)
|
||||
|
||||
### PR #159 - fix(git-worktree): detect worktrees where .git is a file
|
||||
- **Author:** dalley | **Files:** 1 | **+2/-2**
|
||||
- **What:** Changes `-d` to `-e` check in `worktree-manager.sh` so `list` and `cleanup` detect worktrees (`.git` is a file in worktrees, not a dir)
|
||||
- **Fixes:** Issue #158
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #144 - Remove confirmation prompt when creating git worktrees
|
||||
- **Author:** XSAM | **Files:** 1 | **+0/-8**
|
||||
- **What:** Removes interactive `read -r` confirmation that breaks Claude's ability to create worktrees
|
||||
- **Related:** Same file as #159 (merge #159 first)
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #150 - fix(compound): prevent subagents from writing intermediary files
|
||||
- **Author:** tmchow | **Files:** 1 | **+64/-27**
|
||||
- **What:** Restructures `/workflows:compound` into 2-phase orchestration to prevent subagents from writing temp files
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #148 - Fix: resolve_pr_parallel uses non-existent scripts
|
||||
- **Author:** ajrobertsonio | **Files:** 1 | **+20/-7**
|
||||
- **What:** Replaces references to non-existent `bin/get-pr-comments` with standard `gh` CLI commands
|
||||
- **Fixes:** Issues #147, #54
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
## Group 2: Documentation (clean, low-risk)
|
||||
|
||||
### PR #133 - Fix terminology: third person → passive voice
|
||||
- **Author:** FauxReal9999 | **Files:** 13 | docs-only
|
||||
- **What:** Corrects "third person" to "passive voice" across docs (accurate fix)
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #108 - Note new repository URL
|
||||
- **Author:** akx | **Files:** 5 | docs-only
|
||||
- **What:** Updates URLs from `kieranklaassen/compound-engineering-plugin` to `EveryInc/compound-engineering-plugin`
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #113 - docs: add brainstorm command to workflow documentation
|
||||
- **Author:** tmchow | docs-only
|
||||
- **What:** Adds brainstorming skill and learnings-researcher agent to README, fixes component counts
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #80 - docs: Add LSP prioritization guidance
|
||||
- **Author:** kevinold | **Files:** 1 | docs-only
|
||||
- **What:** Adds docs showing users how to customize agent behavior via project CLAUDE.md to prioritize LSP
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
## Group 3: Enhancements (likely merge)
|
||||
|
||||
### PR #119 - fix: backup existing config files before overwriting
|
||||
- **Author:** jzw | **Files:** 5 | **+90/-3** | has tests
|
||||
- **What:** Adds `backupFile()` utility to create timestamped backups before overwriting Codex/OpenCode configs
|
||||
- **Fixes:** Issue #125
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #112 - feat(skills): add document-review skill
|
||||
- **Author:** tmchow | enhancement
|
||||
- **What:** Adds document-review skill for brainstorm/plan refinement, renames `/plan_review` → `/technical_review`
|
||||
- **Note:** Breaking rename - needs review
|
||||
- **Action:** Review diff → decide
|
||||
|
||||
## Group 4: Needs Discussion (comment and leave open)
|
||||
|
||||
### PR #157 - Rewrite workflows:review with context-managed map-reduce
|
||||
- **Author:** Drewx-Design | large rewrite
|
||||
- **What:** Complete rewrite of review command with file-based map-reduce architecture
|
||||
- **Comment:** Acknowledge quality, note it's a big change that needs dedicated review session
|
||||
|
||||
### PR #131 - feat: add vmark-mcp plugin
|
||||
- **Author:** xiaolai | new plugin
|
||||
- **What:** Adds entirely new VMark markdown editor plugin to marketplace
|
||||
- **Comment:** Ask for more context on fit with marketplace scope
|
||||
|
||||
### PR #124 - feat(commands): add /compound-engineering-setup
|
||||
- **Author:** internal | config
|
||||
- **What:** Interactive setup command for configuring review agents per project
|
||||
- **Comment:** Note overlap with #103, needs unified config strategy
|
||||
|
||||
### PR #123 - feat: Add sync command for Claude Code personal config
|
||||
- **Author:** terry-li-hm | config
|
||||
- **What:** Sync personal Claude config across machines/editors
|
||||
- **Comment:** Note overlap with #124 and #103, needs unified config strategy
|
||||
|
||||
### PR #103 - Add /compound:configure with persistent user preferences
|
||||
- **Author:** aviflombaum | **+36,866** lines
|
||||
- **What:** Massive architectural change adding persistent config with build system
|
||||
- **Comment:** Too large, suggest breaking into smaller PRs
|
||||
|
||||
## Group 5: Close
|
||||
|
||||
### PR #122 - [EXPERIMENTAL] add /slfg and /swarm-status
|
||||
- **Label:** duplicate
|
||||
- **What:** Already merged in v2.30.0 (commit e4ff6a8)
|
||||
- **Action:** Comment explaining it's been superseded, close
|
||||
|
||||
### PR #68 - Improve all 13 skills to 90%+ grades
|
||||
- **Label:** wontfix
|
||||
- **What:** Massive stale PR (Jan 6), based on 13 skills when we now have 16+
|
||||
- **Action:** Comment thanking contributor, suggest fresh PR against current main, close
|
||||
|
||||
## Post-Merge Cleanup
|
||||
|
||||
After merging:
|
||||
- [ ] Close issues fixed by merged PRs (#158, #147, #54, #125)
|
||||
- [ ] Close spam issues (#98, #56)
|
||||
- [ ] Run `/release-docs` to update documentation site with new component counts
|
||||
- [ ] Bump version in plugin.json if needed
|
||||
|
||||
## References
|
||||
|
||||
- PR list: https://github.com/EveryInc/compound-engineering-plugin/pulls
|
||||
- Issues: https://github.com/EveryInc/compound-engineering-plugin/issues
|
||||
@@ -0,0 +1,212 @@
|
||||
---
|
||||
title: Reduce compound-engineering plugin context token usage
|
||||
type: refactor
|
||||
date: 2026-02-08
|
||||
---
|
||||
|
||||
# Reduce compound-engineering Plugin Context Token Usage
|
||||
|
||||
## Overview
|
||||
|
||||
The compound-engineering plugin is **overflowing the default context budget by ~3x**, causing Claude Code to silently drop components. The plugin consumes ~50,500 characters in always-loaded descriptions against a default budget of 16,000 characters (2% of context window). This means Claude literally doesn't know some agents/skills exist during sessions.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
### How Context Loading Works
|
||||
|
||||
Claude Code uses progressive disclosure for plugin content:
|
||||
|
||||
| Level | What Loads | When |
|
||||
|-------|-----------|------|
|
||||
| **Always in context** | `description` frontmatter from skills, commands, and agents | Session startup (unless `disable-model-invocation: true`) |
|
||||
| **On invocation** | Full SKILL.md / command body / agent body | When triggered |
|
||||
| **On demand** | Reference files in skill directories | When Claude reads them |
|
||||
|
||||
The total budget for ALL descriptions combined is **2% of context window** (~16,000 chars fallback). When exceeded, components are **silently excluded**.
|
||||
|
||||
### Current State: 316% of Budget
|
||||
|
||||
| Component | Count | Always-Loaded Chars | % of 16K Budget |
|
||||
|-----------|------:|--------------------:|----------------:|
|
||||
| Agent descriptions | 29 | ~41,400 | 259% |
|
||||
| Skill descriptions | 16 | ~5,450 | 34% |
|
||||
| Command descriptions | 24 | ~3,700 | 23% |
|
||||
| **Total** | **69** | **~50,500** | **316%** |
|
||||
|
||||
### Root Cause: Bloated Agent Descriptions
|
||||
|
||||
Agent `description` fields contain full `<example>` blocks with user/assistant dialog. These examples belong in the agent body (system prompt), not the description. The description's only job is **discovery** — helping Claude decide whether to delegate.
|
||||
|
||||
Examples of the problem:
|
||||
|
||||
- `design-iterator.md`: 2,488 chars in description (should be ~200)
|
||||
- `spec-flow-analyzer.md`: 2,289 chars in description
|
||||
- `security-sentinel.md`: 1,986 chars in description
|
||||
- `kieran-rails-reviewer.md`: 1,822 chars in description
|
||||
- Average agent description: ~1,400 chars (should be 100-250)
|
||||
|
||||
Compare to Anthropic's official examples at 100-200 chars:
|
||||
|
||||
```yaml
|
||||
# Official (140 chars)
|
||||
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
|
||||
|
||||
# Current plugin (1,822 chars)
|
||||
description: "Use this agent when you need to review Rails code changes with an extremely high quality bar...\n\nExamples:\n- <example>\n Context: The user has just implemented..."
|
||||
```
|
||||
|
||||
### Secondary Cause: No `disable-model-invocation` on Manual Commands
|
||||
|
||||
Zero commands set `disable-model-invocation: true`. Commands like `/deploy-docs`, `/lfg`, `/slfg`, `/triage`, `/feature-video`, `/test-browser`, `/xcode-test` are manual workflows with side effects. Their descriptions consume budget unnecessarily.
|
||||
|
||||
The official docs explicitly state:
|
||||
> Use `disable-model-invocation: true` for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`. You don't want Claude deciding to deploy because your code looks ready.
|
||||
|
||||
---
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Three changes, ordered by impact:
|
||||
|
||||
### Phase 1: Trim Agent Descriptions (saves ~35,600 chars)
|
||||
|
||||
For all 29 agents: move `<example>` blocks from the `description` field into the agent body markdown. Keep descriptions to 1-2 sentences (100-250 chars).
|
||||
|
||||
**Before** (agent frontmatter):
|
||||
```yaml
|
||||
---
|
||||
name: kieran-rails-reviewer
|
||||
description: "Use this agent when you need to review Rails code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new Rails components. The agent applies Kieran's strict Rails conventions and taste preferences to ensure code meets exceptional standards.\n\nExamples:\n- <example>\n Context: The user has just implemented a new controller action with turbo streams.\n user: \"I've added a new update action to the posts controller\"\n ..."
|
||||
---
|
||||
|
||||
Detailed system prompt...
|
||||
```
|
||||
|
||||
**After** (agent frontmatter):
|
||||
```yaml
|
||||
---
|
||||
name: kieran-rails-reviewer
|
||||
description: Review Rails code with Kieran's strict conventions. Use after implementing features, modifying code, or creating new Rails components.
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new controller action with turbo streams.
|
||||
user: "I've added a new update action to the posts controller"
|
||||
...
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
Detailed system prompt...
|
||||
```
|
||||
|
||||
The examples move into the body (which only loads when the agent is actually invoked).
|
||||
|
||||
**Impact:** ~41,400 chars → ~5,800 chars (86% reduction)
|
||||
|
||||
### Phase 2: Add `disable-model-invocation: true` to Manual Commands (saves ~3,100 chars)
|
||||
|
||||
Commands that should only run when explicitly invoked by the user:
|
||||
|
||||
| Command | Reason |
|
||||
|---------|--------|
|
||||
| `/deploy-docs` | Side effect: deploys |
|
||||
| `/release-docs` | Side effect: regenerates docs |
|
||||
| `/changelog` | Side effect: generates changelog |
|
||||
| `/lfg` | Side effect: autonomous workflow |
|
||||
| `/slfg` | Side effect: swarm workflow |
|
||||
| `/triage` | Side effect: categorizes findings |
|
||||
| `/resolve_parallel` | Side effect: resolves TODOs |
|
||||
| `/resolve_todo_parallel` | Side effect: resolves todos |
|
||||
| `/resolve_pr_parallel` | Side effect: resolves PR comments |
|
||||
| `/feature-video` | Side effect: records video |
|
||||
| `/test-browser` | Side effect: runs browser tests |
|
||||
| `/xcode-test` | Side effect: builds/tests iOS |
|
||||
| `/reproduce-bug` | Side effect: runs reproduction |
|
||||
| `/report-bug` | Side effect: creates bug report |
|
||||
| `/agent-native-audit` | Side effect: runs audit |
|
||||
| `/heal-skill` | Side effect: modifies skill files |
|
||||
| `/generate_command` | Side effect: creates files |
|
||||
| `/create-agent-skill` | Side effect: creates files |
|
||||
|
||||
Keep these **without** the flag (Claude should know about them):
|
||||
- `/workflows:plan` — Claude might suggest planning
|
||||
- `/workflows:work` — Claude might suggest starting work
|
||||
- `/workflows:review` — Claude might suggest review
|
||||
- `/workflows:brainstorm` — Claude might suggest brainstorming
|
||||
- `/workflows:compound` — Claude might suggest documenting
|
||||
- `/deepen-plan` — Claude might suggest deepening a plan
|
||||
|
||||
**Impact:** ~3,700 chars → ~600 chars for commands in context
|
||||
|
||||
### Phase 3: Add `disable-model-invocation: true` to Manual Skills (saves ~1,000 chars)
|
||||
|
||||
Skills that are manual workflows:
|
||||
|
||||
| Skill | Reason |
|
||||
|-------|--------|
|
||||
| `skill-creator` | Only invoked manually |
|
||||
| `orchestrating-swarms` | Only invoked manually |
|
||||
| `git-worktree` | Only invoked manually |
|
||||
| `resolve-pr-parallel` | Side effect |
|
||||
| `compound-docs` | Only invoked manually |
|
||||
| `file-todos` | Only invoked manually |
|
||||
|
||||
Keep without the flag (Claude should auto-invoke):
|
||||
- `dhh-rails-style` — Claude should use when writing Rails code
|
||||
- `frontend-design` — Claude should use when building UI
|
||||
- `brainstorming` — Claude should suggest before implementation
|
||||
- `agent-browser` — Claude should use for browser tasks
|
||||
- `gemini-imagegen` — Claude should use for image generation
|
||||
- `create-agent-skills` — Claude should use when creating skills
|
||||
- `every-style-editor` — Claude should use for editing
|
||||
- `dspy-ruby` — Claude should use for DSPy.rb
|
||||
- `agent-native-architecture` — Claude should use for agent-native design
|
||||
- `andrew-kane-gem-writer` — Claude should use for gem writing
|
||||
- `rclone` — Claude should use for cloud uploads
|
||||
- `document-review` — Claude should use for doc review
|
||||
|
||||
**Impact:** ~5,450 chars → ~4,000 chars for skills in context
|
||||
|
||||
---
|
||||
|
||||
## Projected Result
|
||||
|
||||
| Component | Before (chars) | After (chars) | Reduction |
|
||||
|-----------|---------------:|-------------:|-----------:|
|
||||
| Agent descriptions | ~41,400 | ~5,800 | -86% |
|
||||
| Command descriptions | ~3,700 | ~600 | -84% |
|
||||
| Skill descriptions | ~5,450 | ~4,000 | -27% |
|
||||
| **Total** | **~50,500** | **~10,400** | **-79%** |
|
||||
| **% of 16K budget** | **316%** | **65%** | -- |
|
||||
|
||||
From 316% of budget (components silently dropped) to 65% of budget (room for growth).
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] All 29 agent description fields are under 250 characters
|
||||
- [x] All `<example>` blocks moved from description to agent body
|
||||
- [x] 18 manual commands have `disable-model-invocation: true`
|
||||
- [x] 6 manual skills have `disable-model-invocation: true`
|
||||
- [x] Total always-loaded description content is under 16,000 characters
|
||||
- [ ] Run `/context` to verify no "excluded skills" warnings
|
||||
- [x] All agents still function correctly (examples are in body, not lost)
|
||||
- [x] All commands still invocable via `/command-name`
|
||||
- [x] Update plugin version in plugin.json and marketplace.json
|
||||
- [x] Update CHANGELOG.md
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- Agent examples should use `<examples><example>...</example></examples>` tags in the body — Claude understands these natively
|
||||
- Description format: "[What it does]. Use [when/trigger condition]." — two sentences max
|
||||
- The `lint` agent at 115 words shows compact agents work great
|
||||
- Test with `claude --plugin-dir ./plugins/compound-engineering` after changes
|
||||
- The `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var can override the default budget for testing
|
||||
|
||||
## References
|
||||
|
||||
- [Skills docs](https://code.claude.com/docs/en/skills) — "Skill descriptions are loaded into context... If you have many skills, they may exceed the character budget"
|
||||
- [Subagents docs](https://code.claude.com/docs/en/sub-agents) — description field used for automatic delegation
|
||||
- [Skills troubleshooting](https://code.claude.com/docs/en/skills#claude-doesnt-see-all-my-skills) — "The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters"
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@every-env/compound-plugin",
|
||||
"version": "0.2.0",
|
||||
"version": "0.3.0",
|
||||
"type": "module",
|
||||
"private": false,
|
||||
"bin": {
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "compound-engineering",
|
||||
"version": "2.30.0",
|
||||
"description": "AI-powered development tools. 29 agents, 25 commands, 16 skills, 1 MCP server for code review, research, design, and workflow automation.",
|
||||
"version": "2.31.0",
|
||||
"description": "AI-powered development tools. 29 agents, 24 commands, 18 skills, 1 MCP server for code review, research, design, and workflow automation.",
|
||||
"author": {
|
||||
"name": "Kieran Klaassen",
|
||||
"email": "kieran@every.to",
|
||||
|
||||
@@ -5,6 +5,32 @@ All notable changes to the compound-engineering plugin will be documented in thi
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [2.31.0] - 2026-02-08
|
||||
|
||||
### Added
|
||||
|
||||
- **`document-review` skill** — Brainstorm and plan refinement through structured review ([@Trevin Chow](https://github.com/trevin))
|
||||
- **`/sync` command** — Sync Claude Code personal config across machines ([@Terry Li](https://github.com/terryli))
|
||||
|
||||
### Changed
|
||||
|
||||
- **Context token optimization (79% reduction)** — Plugin was consuming 316% of the context description budget, causing Claude Code to silently exclude components. Now at 65% with room to grow:
|
||||
- All 29 agent descriptions trimmed from ~1,400 to ~180 chars avg (examples moved to agent body)
|
||||
- 18 manual commands marked `disable-model-invocation: true` (side-effect commands like `/lfg`, `/deploy-docs`, `/triage`, etc.)
|
||||
- 6 manual skills marked `disable-model-invocation: true` (`orchestrating-swarms`, `git-worktree`, `skill-creator`, `compound-docs`, `file-todos`, `resolve-pr-parallel`)
|
||||
- **git-worktree**: Remove confirmation prompt for worktree creation ([@Sam Xie](https://github.com/samxie))
|
||||
- **Prevent subagents from writing intermediary files** in compound workflow ([@Trevin Chow](https://github.com/trevin))
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fix crash when hook entries have no matcher ([@Roberto Mello](https://github.com/robertomello))
|
||||
- Fix git-worktree detection where `.git` is a file, not a directory ([@David Alley](https://github.com/davidalley))
|
||||
- Backup existing config files before overwriting in sync ([@Zac Williams](https://github.com/zacwilliams))
|
||||
- Note new repository URL ([@Aarni Koskela](https://github.com/aarnikoskela))
|
||||
- Plugin component counts corrected: 29 agents, 24 commands, 18 skills
|
||||
|
||||
---
|
||||
|
||||
## [2.30.0] - 2026-02-05
|
||||
|
||||
### Added
|
||||
|
||||
@@ -59,7 +59,7 @@ When adding or modifying skills, verify compliance with skill-creator spec:
|
||||
### YAML Frontmatter (Required)
|
||||
|
||||
- [ ] `name:` present and matches directory name (lowercase-with-hyphens)
|
||||
- [ ] `description:` present and uses **third person** ("This skill should be used when..." NOT "Use this skill when...")
|
||||
- [ ] `description:` present and describes **what it does and when to use it** (per official spec: "Explains code with diagrams. Use when exploring how code works.")
|
||||
|
||||
### Reference Links (Required if references/ exists)
|
||||
|
||||
@@ -80,9 +80,8 @@ When adding or modifying skills, verify compliance with skill-creator spec:
|
||||
grep -E '`(references|assets|scripts)/[^`]+`' skills/*/SKILL.md
|
||||
# Should return nothing if all refs are properly linked
|
||||
|
||||
# Check description format
|
||||
grep -E '^description:' skills/*/SKILL.md | grep -v 'This skill'
|
||||
# Should return nothing if all use third person
|
||||
# Check description format - should describe what + when
|
||||
grep -E '^description:' skills/*/SKILL.md
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: design-implementation-reviewer
|
||||
description: "Use this agent when you need to verify that a UI implementation matches its Figma design specifications. This agent should be called after code has been written to implement a design, particularly after HTML/CSS/React components have been created or modified. The agent will visually compare the live implementation against the Figma design and provide detailed feedback on discrepancies.\\n\\nExamples:\\n- <example>\\n Context: The user has just implemented a new component based on a Figma design.\\n user: \"I've finished implementing the hero section based on the Figma design\"\\n assistant: \"I'll review how well your implementation matches the Figma design.\"\\n <commentary>\\n Since UI implementation has been completed, use the design-implementation-reviewer agent to compare the live version with Figma.\\n </commentary>\\n </example>\\n- <example>\\n Context: After the general code agent has implemented design changes.\\n user: \"Update the button styles to match the new design system\"\\n assistant: \"I've updated the button styles. Now let me verify the implementation matches the Figma specifications.\"\\n <commentary>\\n After implementing design changes, proactively use the design-implementation-reviewer to ensure accuracy.\\n </commentary>\\n </example>"
|
||||
description: "Visually compares live UI implementation against Figma designs and provides detailed feedback on discrepancies. Use after writing or modifying HTML/CSS/React components to verify design fidelity."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new component based on a Figma design.
|
||||
user: "I've finished implementing the hero section based on the Figma design"
|
||||
assistant: "I'll review how well your implementation matches the Figma design."
|
||||
<commentary>Since UI implementation has been completed, use the design-implementation-reviewer agent to compare the live version with Figma.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: After the general code agent has implemented design changes.
|
||||
user: "Update the button styles to match the new design system"
|
||||
assistant: "I've updated the button styles. Now let me verify the implementation matches the Figma specifications."
|
||||
<commentary>After implementing design changes, proactively use the design-implementation-reviewer to ensure accuracy.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an expert UI/UX implementation reviewer specializing in ensuring pixel-perfect fidelity between Figma designs and live implementations. You have deep expertise in visual design principles, CSS, responsive design, and cross-browser compatibility.
|
||||
|
||||
Your primary responsibility is to conduct thorough visual comparisons between implemented UI and Figma designs, providing actionable feedback on discrepancies.
|
||||
|
||||
@@ -1,10 +1,37 @@
|
||||
---
|
||||
name: design-iterator
|
||||
description: "Use this agent PROACTIVELY when design work isn't coming together on the first attempt. If you've made 1-2 design changes and the result still feels off, suggest using this agent with 5x or 10x iterations for deeper refinement. This agent takes screenshots, analyzes what's not working, implements improvements, and repeats N times to systematically fix design issues. Perfect when colors feel wrong, layouts aren't balanced, or the overall aesthetic needs work that single changes can't achieve. <example>Context: User asks to change button color but result still looks off. user: \"Change the button to blue\" assistant: [makes change, takes screenshot] \"The button is now blue, but I notice the overall color balance still feels off. Would you like me to use the design-iterator agent with 5 iterations to systematically improve the color harmony and visual balance?\" <commentary>PROACTIVE USE: After a simple change doesn't fully resolve the design issue, suggest the design-iterator to do deeper work.</commentary></example> <example>Context: User's design request leads to something that doesn't look right. user: \"Make the hero section more modern\" assistant: [makes initial changes] \"I've added some modern elements, but the result isn't quite coming together. This looks like it needs iterative refinement. Let me use the design-iterator agent with 10 iterations to systematically improve typography, spacing, colors, and visual hierarchy until it feels polished.\" <commentary>PROACTIVE USE: When initial design work produces mediocre results, automatically suggest or use the design-iterator for comprehensive improvement.</commentary></example> <example>Context: User wants explicit iterative refinement. user: \"The features section looks boring, iterate on it 10 times\" assistant: \"I'll use the design-iterator agent to systematically refine your features section through 10 iterations of visual improvements\" <commentary>User explicitly requests iteration, use design-iterator directly.</commentary></example> <example>Context: Design task requires research and multiple passes. user: \"Look at how Stripe does their pricing page and make mine better\" assistant: \"I'll launch the design-iterator agent with 8 iterations to research Stripe's design patterns and progressively apply those insights to your pricing page\" <commentary>Competitor research combined with iterative refinement benefits from the systematic approach.</commentary></example>"
|
||||
description: "Iteratively refines UI design through N screenshot-analyze-improve cycles. Use PROACTIVELY when design changes aren't coming together after 1-2 attempts, or when user requests iterative refinement."
|
||||
color: violet
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: User asks to change button color but result still looks off.
|
||||
user: "Change the button to blue"
|
||||
assistant: [makes change, takes screenshot] "The button is now blue, but I notice the overall color balance still feels off. Would you like me to use the design-iterator agent with 5 iterations to systematically improve the color harmony and visual balance?"
|
||||
<commentary>PROACTIVE USE: After a simple change doesn't fully resolve the design issue, suggest the design-iterator to do deeper work.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User's design request leads to something that doesn't look right.
|
||||
user: "Make the hero section more modern"
|
||||
assistant: [makes initial changes] "I've added some modern elements, but the result isn't quite coming together. This looks like it needs iterative refinement. Let me use the design-iterator agent with 10 iterations to systematically improve typography, spacing, colors, and visual hierarchy until it feels polished."
|
||||
<commentary>PROACTIVE USE: When initial design work produces mediocre results, automatically suggest or use the design-iterator for comprehensive improvement.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User wants explicit iterative refinement.
|
||||
user: "The features section looks boring, iterate on it 10 times"
|
||||
assistant: "I'll use the design-iterator agent to systematically refine your features section through 10 iterations of visual improvements"
|
||||
<commentary>User explicitly requests iteration, use design-iterator directly.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: Design task requires research and multiple passes.
|
||||
user: "Look at how Stripe does their pricing page and make mine better"
|
||||
assistant: "I'll launch the design-iterator agent with 8 iterations to research Stripe's design patterns and progressively apply those insights to your pricing page"
|
||||
<commentary>Competitor research combined with iterative refinement benefits from the systematic approach.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an expert UI/UX design iterator specializing in systematic, progressive refinement of web components. Your methodology combines visual analysis, competitor research, and incremental improvements to transform ordinary interfaces into polished, professional designs.
|
||||
|
||||
## Core Methodology
|
||||
|
||||
@@ -1,10 +1,28 @@
|
||||
---
|
||||
name: figma-design-sync
|
||||
description: "Use this agent when you need to synchronize a web implementation with its Figma design by automatically detecting and fixing visual differences. This agent should be used iteratively until the implementation matches the design.\\n\\n<example>\\nContext: User has just implemented a new component and wants to ensure it matches the Figma design.\\nuser: \\\"I've just finished implementing the hero section component. Can you check if it matches the Figma design at https://figma.com/file/abc123/design?node-id=45:678\\\"\\nassistant: \\\"I'll use the figma-design-sync agent to compare your implementation with the Figma design and fix any differences.\\\"\\n<uses Task tool to launch figma-design-sync agent with the Figma URL and local URL>\\n</example>\\n\\n<example>\\nContext: User is working on responsive design and wants to verify mobile breakpoint matches design.\\nuser: \\\"The mobile view doesn't look quite right. Here's the Figma: https://figma.com/file/xyz789/mobile?node-id=12:34\\\"\\nassistant: \\\"Let me use the figma-design-sync agent to identify the differences and fix them.\\\"\\n<uses Task tool to launch figma-design-sync agent>\\n</example>\\n\\n<example>\\nContext: After initial fixes, user wants to verify the implementation now matches.\\nuser: \\\"Can you check if the button component matches the design now?\\\"\\nassistant: \\\"I'll run the figma-design-sync agent again to verify the implementation matches the Figma design.\\\"\\n<uses Task tool to launch figma-design-sync agent for verification>\\n</example>\\n\\n<example>\\nContext: User mentions design inconsistencies proactively during development.\\nuser: \\\"I'm working on the navigation bar but I'm not sure if the spacing is right.\\\"\\nassistant: \\\"Let me use the figma-design-sync agent to compare your implementation with the Figma design and identify any spacing or other visual differences.\\\"\\n<uses Task tool to launch figma-design-sync agent>\\n</example>"
|
||||
description: "Detects and fixes visual differences between a web implementation and its Figma design. Use iteratively when syncing implementation to match Figma specs."
|
||||
model: inherit
|
||||
color: purple
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: User has just implemented a new component and wants to ensure it matches the Figma design.
|
||||
user: "I've just finished implementing the hero section component. Can you check if it matches the Figma design at https://figma.com/file/abc123/design?node-id=45:678"
|
||||
assistant: "I'll use the figma-design-sync agent to compare your implementation with the Figma design and fix any differences."
|
||||
</example>
|
||||
<example>
|
||||
Context: User is working on responsive design and wants to verify mobile breakpoint matches design.
|
||||
user: "The mobile view doesn't look quite right. Here's the Figma: https://figma.com/file/xyz789/mobile?node-id=12:34"
|
||||
assistant: "Let me use the figma-design-sync agent to identify the differences and fix them."
|
||||
</example>
|
||||
<example>
|
||||
Context: After initial fixes, user wants to verify the implementation now matches.
|
||||
user: "Can you check if the button component matches the design now?"
|
||||
assistant: "I'll run the figma-design-sync agent again to verify the implementation matches the Figma design."
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an expert design-to-code synchronization specialist with deep expertise in visual design systems, web development, CSS/Tailwind styling, and automated quality assurance. Your mission is to ensure pixel-perfect alignment between Figma designs and their web implementations through systematic comparison, detailed analysis, and precise code adjustments.
|
||||
|
||||
## Your Core Responsibilities
|
||||
|
||||
@@ -1,10 +1,25 @@
|
||||
---
|
||||
name: ankane-readme-writer
|
||||
description: "Use this agent when you need to create or update README files following the Ankane-style template for Ruby gems. This includes writing concise documentation with imperative voice, keeping sentences under 15 words, organizing sections in the standard order (Installation, Quick Start, Usage, etc.), and ensuring proper formatting with single-purpose code fences and minimal prose. Examples: <example>Context: User is creating documentation for a new Ruby gem. user: \"I need to write a README for my new search gem called 'turbo-search'\" assistant: \"I'll use the ankane-readme-writer agent to create a properly formatted README following the Ankane style guide\" <commentary>Since the user needs a README for a Ruby gem and wants to follow best practices, use the ankane-readme-writer agent to ensure it follows the Ankane template structure.</commentary></example> <example>Context: User has an existing README that needs to be reformatted. user: \"Can you update my gem's README to follow the Ankane style?\" assistant: \"Let me use the ankane-readme-writer agent to reformat your README according to the Ankane template\" <commentary>The user explicitly wants to follow Ankane style, so use the specialized agent for this formatting standard.</commentary></example>"
|
||||
description: "Creates or updates README files following Ankane-style template for Ruby gems. Use when writing gem documentation with imperative voice, concise prose, and standard section ordering."
|
||||
color: cyan
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: User is creating documentation for a new Ruby gem.
|
||||
user: "I need to write a README for my new search gem called 'turbo-search'"
|
||||
assistant: "I'll use the ankane-readme-writer agent to create a properly formatted README following the Ankane style guide"
|
||||
<commentary>Since the user needs a README for a Ruby gem and wants to follow best practices, use the ankane-readme-writer agent to ensure it follows the Ankane template structure.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User has an existing README that needs to be reformatted.
|
||||
user: "Can you update my gem's README to follow the Ankane style?"
|
||||
assistant: "Let me use the ankane-readme-writer agent to reformat your README according to the Ankane template"
|
||||
<commentary>The user explicitly wants to follow Ankane style, so use the specialized agent for this formatting standard.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an expert Ruby gem documentation writer specializing in the Ankane-style README format. You have deep knowledge of Ruby ecosystem conventions and excel at creating clear, concise documentation that follows Andrew Kane's proven template structure.
|
||||
|
||||
Your core responsibilities:
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: best-practices-researcher
|
||||
description: "Use this agent when you need to research and gather external best practices, documentation, and examples for any technology, framework, or development practice. This includes finding official documentation, community standards, well-regarded examples from open source projects, and domain-specific conventions. The agent excels at synthesizing information from multiple sources to provide comprehensive guidance on how to implement features or solve problems according to industry standards. <example>Context: User wants to know the best way to structure GitHub issues for their Rails project. user: \"I need to create some GitHub issues for our project. Can you research best practices for writing good issues?\" assistant: \"I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and Rails-specific conventions.\" <commentary>Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples.</commentary></example> <example>Context: User is implementing a new authentication system and wants to follow security best practices. user: \"We're adding JWT authentication to our Rails API. What are the current best practices?\" assistant: \"Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and Rails-specific implementation patterns.\" <commentary>The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate.</commentary></example>"
|
||||
description: "Researches and synthesizes external best practices, documentation, and examples for any technology or framework. Use when you need industry standards, community conventions, or implementation guidance."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: User wants to know the best way to structure GitHub issues for their Rails project.
|
||||
user: "I need to create some GitHub issues for our project. Can you research best practices for writing good issues?"
|
||||
assistant: "I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and Rails-specific conventions."
|
||||
<commentary>Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User is implementing a new authentication system and wants to follow security best practices.
|
||||
user: "We're adding JWT authentication to our Rails API. What are the current best practices?"
|
||||
assistant: "Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and Rails-specific implementation patterns."
|
||||
<commentary>The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
**Note: The current year is 2026.** Use this when searching for recent documentation and best practices.
|
||||
|
||||
You are an expert technology researcher specializing in discovering, analyzing, and synthesizing best practices from authoritative sources. Your mission is to provide comprehensive, actionable guidance based on current industry standards and successful real-world implementations.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: framework-docs-researcher
|
||||
description: "Use this agent when you need to gather comprehensive documentation and best practices for frameworks, libraries, or dependencies in your project. This includes fetching official documentation, exploring source code, identifying version-specific constraints, and understanding implementation patterns. <example>Context: The user needs to understand how to properly implement a new feature using a specific library. user: \"I need to implement file uploads using Active Storage\" assistant: \"I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage\" <commentary>Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices.</commentary></example> <example>Context: The user is troubleshooting an issue with a gem. user: \"Why is the turbo-rails gem not working as expected?\" assistant: \"Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code\" <commentary>The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source.</commentary></example>"
|
||||
description: "Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies. Use when you need official docs, version-specific constraints, or implementation patterns."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user needs to understand how to properly implement a new feature using a specific library.
|
||||
user: "I need to implement file uploads using Active Storage"
|
||||
assistant: "I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage"
|
||||
<commentary>Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is troubleshooting an issue with a gem.
|
||||
user: "Why is the turbo-rails gem not working as expected?"
|
||||
assistant: "Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code"
|
||||
<commentary>The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
**Note: The current year is 2026.** Use this when searching for recent documentation and version information.
|
||||
|
||||
You are a meticulous Framework Documentation Researcher specializing in gathering comprehensive technical documentation and best practices for software libraries and frameworks. Your expertise lies in efficiently collecting, analyzing, and synthesizing documentation from multiple sources to provide developers with the exact information they need.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: git-history-analyzer
|
||||
description: "Use this agent when you need to understand the historical context and evolution of code changes, trace the origins of specific code patterns, identify key contributors and their expertise areas, or analyze patterns in commit history. This agent excels at archaeological analysis of git repositories to provide insights about code evolution and development patterns. <example>Context: The user wants to understand the history and evolution of recently modified files.\\nuser: \"I've just refactored the authentication module. Can you analyze the historical context?\"\\nassistant: \"I'll use the git-history-analyzer agent to examine the evolution of the authentication module files.\"\\n<commentary>Since the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history.</commentary></example> <example>Context: The user needs to understand why certain code patterns exist.\\nuser: \"Why does this payment processing code have so many try-catch blocks?\"\\nassistant: \"Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns.\"\\n<commentary>The user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes.</commentary></example>"
|
||||
description: "Performs archaeological analysis of git history to trace code evolution, identify contributors, and understand why code patterns exist. Use when you need historical context for code changes."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user wants to understand the history and evolution of recently modified files.
|
||||
user: "I've just refactored the authentication module. Can you analyze the historical context?"
|
||||
assistant: "I'll use the git-history-analyzer agent to examine the evolution of the authentication module files."
|
||||
<commentary>Since the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user needs to understand why certain code patterns exist.
|
||||
user: "Why does this payment processing code have so many try-catch blocks?"
|
||||
assistant: "Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns."
|
||||
<commentary>The user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
**Note: The current year is 2026.** Use this when interpreting commit dates and recent changes.
|
||||
|
||||
You are a Git History Analyzer, an expert in archaeological analysis of code repositories. Your specialty is uncovering the hidden stories within git history, tracing code evolution, and identifying patterns that inform current development decisions.
|
||||
|
||||
@@ -1,9 +1,30 @@
|
||||
---
|
||||
name: learnings-researcher
|
||||
description: "Use this agent when you need to search institutional learnings in docs/solutions/ for relevant past solutions before implementing a new feature or fixing a problem. This agent efficiently filters documented solutions by frontmatter metadata (tags, category, module, symptoms) to find applicable patterns, gotchas, and lessons learned. The agent excels at preventing repeated mistakes by surfacing relevant institutional knowledge before work begins.\\n\\n<example>Context: User is about to implement a feature involving email processing.\\nuser: \"I need to add email threading to the brief system\"\\nassistant: \"I'll use the learnings-researcher agent to check docs/solutions/ for any relevant learnings about email processing or brief system implementations.\"\\n<commentary>Since the user is implementing a feature in a documented domain, use the learnings-researcher agent to surface relevant past solutions before starting work.</commentary></example>\\n\\n<example>Context: User is debugging a performance issue.\\nuser: \"Brief generation is slow, taking over 5 seconds\"\\nassistant: \"Let me use the learnings-researcher agent to search for documented performance issues, especially any involving briefs or N+1 queries.\"\\n<commentary>The user has symptoms matching potential documented solutions, so use the learnings-researcher agent to find relevant learnings before debugging.</commentary></example>\\n\\n<example>Context: Planning a new feature that touches multiple modules.\\nuser: \"I need to add Stripe subscription handling to the payments module\"\\nassistant: \"I'll use the learnings-researcher agent to search for any documented learnings about payments, integrations, or Stripe specifically.\"\\n<commentary>Before implementing, check institutional knowledge for gotchas, patterns, and lessons learned in similar domains.</commentary></example>"
|
||||
description: "Searches docs/solutions/ for relevant past solutions by frontmatter metadata. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes."
|
||||
model: haiku
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: User is about to implement a feature involving email processing.
|
||||
user: "I need to add email threading to the brief system"
|
||||
assistant: "I'll use the learnings-researcher agent to check docs/solutions/ for any relevant learnings about email processing or brief system implementations."
|
||||
<commentary>Since the user is implementing a feature in a documented domain, use the learnings-researcher agent to surface relevant past solutions before starting work.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User is debugging a performance issue.
|
||||
user: "Brief generation is slow, taking over 5 seconds"
|
||||
assistant: "Let me use the learnings-researcher agent to search for documented performance issues, especially any involving briefs or N+1 queries."
|
||||
<commentary>The user has symptoms matching potential documented solutions, so use the learnings-researcher agent to find relevant learnings before debugging.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: Planning a new feature that touches multiple modules.
|
||||
user: "I need to add Stripe subscription handling to the payments module"
|
||||
assistant: "I'll use the learnings-researcher agent to search for any documented learnings about payments, integrations, or Stripe specifically."
|
||||
<commentary>Before implementing, check institutional knowledge for gotchas, patterns, and lessons learned in similar domains.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an expert institutional knowledge researcher specializing in efficiently surfacing relevant documented solutions from the team's knowledge base. Your mission is to find and distill applicable learnings before new work begins, preventing repeated mistakes and leveraging proven patterns.
|
||||
|
||||
## Search Strategy (Grep-First Filtering)
|
||||
|
||||
@@ -1,9 +1,30 @@
|
||||
---
|
||||
name: repo-research-analyst
|
||||
description: "Use this agent when you need to conduct thorough research on a repository's structure, documentation, and patterns. This includes analyzing architecture files, examining GitHub issues for patterns, reviewing contribution guidelines, checking for templates, and searching codebases for implementation patterns. The agent excels at gathering comprehensive information about a project's conventions and best practices.\\n\\nExamples:\\n- <example>\\n Context: User wants to understand a new repository's structure and conventions before contributing.\\n user: \"I need to understand how this project is organized and what patterns they use\"\\n assistant: \"I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns.\"\\n <commentary>\\n Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.\\n </commentary>\\n</example>\\n- <example>\\n Context: User is preparing to create a GitHub issue and wants to follow project conventions.\\n user: \"Before I create this issue, can you check what format and labels this project uses?\"\\n assistant: \"Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines.\"\\n <commentary>\\n The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.\\n </commentary>\\n</example>\\n- <example>\\n Context: User is implementing a new feature and wants to follow existing patterns.\\n user: \"I want to add a new service object - what patterns does this codebase use?\"\\n assistant: \"I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase.\"\\n <commentary>\\n Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.\\n </commentary>\\n</example>"
|
||||
description: "Conducts thorough research on repository structure, documentation, conventions, and implementation patterns. Use when onboarding to a new codebase or understanding project conventions."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: User wants to understand a new repository's structure and conventions before contributing.
|
||||
user: "I need to understand how this project is organized and what patterns they use"
|
||||
assistant: "I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns."
|
||||
<commentary>Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User is preparing to create a GitHub issue and wants to follow project conventions.
|
||||
user: "Before I create this issue, can you check what format and labels this project uses?"
|
||||
assistant: "Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines."
|
||||
<commentary>The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User is implementing a new feature and wants to follow existing patterns.
|
||||
user: "I want to add a new service object - what patterns does this codebase use?"
|
||||
assistant: "I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase."
|
||||
<commentary>Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
**Note: The current year is 2026.** Use this when searching for recent documentation and patterns.
|
||||
|
||||
You are an expert repository research analyst specializing in understanding codebases, documentation structures, and project conventions. Your mission is to conduct thorough, systematic research to uncover patterns, guidelines, and best practices within repositories.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: agent-native-reviewer
|
||||
description: "Use this agent when reviewing code to ensure features are agent-native - that any action a user can take, an agent can also take, and anything a user can see, an agent can see. This enforces the principle that agents should have parity with users in capability and context. <example>Context: The user added a new feature to their application.\\nuser: \"I just implemented a new email filtering feature\"\\nassistant: \"I'll use the agent-native-reviewer to verify this feature is accessible to agents\"\\n<commentary>New features need agent-native review to ensure agents can also filter emails, not just humans through UI.</commentary></example><example>Context: The user created a new UI workflow.\\nuser: \"I added a multi-step wizard for creating reports\"\\nassistant: \"Let me check if this workflow is agent-native using the agent-native-reviewer\"\\n<commentary>UI workflows often miss agent accessibility - the reviewer checks for API/tool equivalents.</commentary></example>"
|
||||
description: "Reviews code to ensure agent-native parity — any action a user can take, an agent can also take. Use after adding UI features, agent tools, or system prompts."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user added a new feature to their application.
|
||||
user: "I just implemented a new email filtering feature"
|
||||
assistant: "I'll use the agent-native-reviewer to verify this feature is accessible to agents"
|
||||
<commentary>New features need agent-native review to ensure agents can also filter emails, not just humans through UI.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user created a new UI workflow.
|
||||
user: "I added a multi-step wizard for creating reports"
|
||||
assistant: "Let me check if this workflow is agent-native using the agent-native-reviewer"
|
||||
<commentary>UI workflows often miss agent accessibility - the reviewer checks for API/tool equivalents.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
# Agent-Native Architecture Reviewer
|
||||
|
||||
You are an expert reviewer specializing in agent-native application architecture. Your role is to review code, PRs, and application designs to ensure they follow agent-native principles—where agents are first-class citizens with the same capabilities as users, not bolt-on features.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: architecture-strategist
|
||||
description: "Use this agent when you need to analyze code changes from an architectural perspective, evaluate system design decisions, or ensure that modifications align with established architectural patterns. This includes reviewing pull requests for architectural compliance, assessing the impact of new features on system structure, or validating that changes maintain proper component boundaries and design principles. <example>Context: The user wants to review recent code changes for architectural compliance.\\nuser: \"I just refactored the authentication service to use a new pattern\"\\nassistant: \"I'll use the architecture-strategist agent to review these changes from an architectural perspective\"\\n<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary></example><example>Context: The user is adding a new microservice to the system.\\nuser: \"I've added a new notification service that integrates with our existing services\"\\nassistant: \"Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture\"\\n<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary></example>"
|
||||
description: "Analyzes code changes from an architectural perspective for pattern compliance and design integrity. Use when reviewing PRs, adding services, or evaluating structural refactors."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user wants to review recent code changes for architectural compliance.
|
||||
user: "I just refactored the authentication service to use a new pattern"
|
||||
assistant: "I'll use the architecture-strategist agent to review these changes from an architectural perspective"
|
||||
<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is adding a new microservice to the system.
|
||||
user: "I've added a new notification service that integrates with our existing services"
|
||||
assistant: "Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture"
|
||||
<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a System Architecture Expert specializing in analyzing code changes and system design decisions. Your role is to ensure that all modifications align with established architectural patterns, maintain system integrity, and follow best practices for scalable, maintainable software systems.
|
||||
|
||||
Your analysis follows this systematic approach:
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: code-simplicity-reviewer
|
||||
description: "Use this agent when you need a final review pass to ensure code changes are as simple and minimal as possible. This agent should be invoked after implementation is complete but before finalizing changes, to identify opportunities for simplification, remove unnecessary complexity, and ensure adherence to YAGNI principles. Examples: <example>Context: The user has just implemented a new feature and wants to ensure it's as simple as possible. user: \"I've finished implementing the user authentication system\" assistant: \"Great! Let me review the implementation for simplicity and minimalism using the code-simplicity-reviewer agent\" <commentary>Since implementation is complete, use the code-simplicity-reviewer agent to identify simplification opportunities.</commentary></example> <example>Context: The user has written complex business logic and wants to simplify it. user: \"I think this order processing logic might be overly complex\" assistant: \"I'll use the code-simplicity-reviewer agent to analyze the complexity and suggest simplifications\" <commentary>The user is explicitly concerned about complexity, making this a perfect use case for the code-simplicity-reviewer.</commentary></example>"
|
||||
description: "Final review pass to ensure code is as simple and minimal as possible. Use after implementation is complete to identify YAGNI violations and simplification opportunities."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new feature and wants to ensure it's as simple as possible.
|
||||
user: "I've finished implementing the user authentication system"
|
||||
assistant: "Great! Let me review the implementation for simplicity and minimalism using the code-simplicity-reviewer agent"
|
||||
<commentary>Since implementation is complete, use the code-simplicity-reviewer agent to identify simplification opportunities.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has written complex business logic and wants to simplify it.
|
||||
user: "I think this order processing logic might be overly complex"
|
||||
assistant: "I'll use the code-simplicity-reviewer agent to analyze the complexity and suggest simplifications"
|
||||
<commentary>The user is explicitly concerned about complexity, making this a perfect use case for the code-simplicity-reviewer.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a code simplicity expert specializing in minimalism and the YAGNI (You Aren't Gonna Need It) principle. Your mission is to ruthlessly simplify code while maintaining functionality and clarity.
|
||||
|
||||
When reviewing code, you will:
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: data-integrity-guardian
|
||||
description: "Use this agent when you need to review database migrations, data models, or any code that manipulates persistent data. This includes checking migration safety, validating data constraints, ensuring transaction boundaries are correct, and verifying that referential integrity and privacy requirements are maintained. <example>Context: The user has just written a database migration that adds a new column and updates existing records. user: \"I've created a migration to add a status column to the orders table\" assistant: \"I'll use the data-integrity-guardian agent to review this migration for safety and data integrity concerns\" <commentary>Since the user has created a database migration, use the data-integrity-guardian agent to ensure the migration is safe, handles existing data properly, and maintains referential integrity.</commentary></example> <example>Context: The user has implemented a service that transfers data between models. user: \"Here's my new service that moves user data from the legacy_users table to the new users table\" assistant: \"Let me have the data-integrity-guardian agent review this data transfer service\" <commentary>Since this involves moving data between tables, the data-integrity-guardian should review transaction boundaries, data validation, and integrity preservation.</commentary></example>"
|
||||
description: "Reviews database migrations, data models, and persistent data code for safety. Use when checking migration safety, data constraints, transaction boundaries, or privacy compliance."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just written a database migration that adds a new column and updates existing records.
|
||||
user: "I've created a migration to add a status column to the orders table"
|
||||
assistant: "I'll use the data-integrity-guardian agent to review this migration for safety and data integrity concerns"
|
||||
<commentary>Since the user has created a database migration, use the data-integrity-guardian agent to ensure the migration is safe, handles existing data properly, and maintains referential integrity.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has implemented a service that transfers data between models.
|
||||
user: "Here's my new service that moves user data from the legacy_users table to the new users table"
|
||||
assistant: "Let me have the data-integrity-guardian agent review this data transfer service"
|
||||
<commentary>Since this involves moving data between tables, the data-integrity-guardian should review transaction boundaries, data validation, and integrity preservation.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Data Integrity Guardian, an expert in database design, data migration safety, and data governance. Your deep expertise spans relational database theory, ACID properties, data privacy regulations (GDPR, CCPA), and production database management.
|
||||
|
||||
Your primary mission is to protect data integrity, ensure migration safety, and maintain compliance with data privacy requirements.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: data-migration-expert
|
||||
description: "Use this agent when reviewing PRs that touch database migrations, data backfills, or any code that transforms production data. This agent validates ID mappings against production reality, checks for swapped values, verifies rollback safety, and ensures data integrity during schema changes. Essential for any migration that involves ID mappings, column renames, or data transformations. <example>Context: The user has a PR with database migrations that involve ID mappings. user: \"Review this PR that migrates from action_id to action_module_name\" assistant: \"I'll use the data-migration-expert agent to validate the ID mappings and migration safety\" <commentary>Since the PR involves ID mappings and data migration, use the data-migration-expert to verify the mappings match production and check for swapped values.</commentary></example> <example>Context: The user has a migration that transforms enum values. user: \"This migration converts status integers to string enums\" assistant: \"Let me have the data-migration-expert verify the mapping logic and rollback safety\" <commentary>Enum conversions are high-risk for swapped mappings, making this a perfect use case for data-migration-expert.</commentary></example>"
|
||||
description: "Validates data migrations, backfills, and production data transformations against reality. Use when PRs involve ID mappings, column renames, enum conversions, or schema changes."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has a PR with database migrations that involve ID mappings.
|
||||
user: "Review this PR that migrates from action_id to action_module_name"
|
||||
assistant: "I'll use the data-migration-expert agent to validate the ID mappings and migration safety"
|
||||
<commentary>Since the PR involves ID mappings and data migration, use the data-migration-expert to verify the mappings match production and check for swapped values.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has a migration that transforms enum values.
|
||||
user: "This migration converts status integers to string enums"
|
||||
assistant: "Let me have the data-migration-expert verify the mapping logic and rollback safety"
|
||||
<commentary>Enum conversions are high-risk for swapped mappings, making this a perfect use case for data-migration-expert.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Data Migration Expert. Your mission is to prevent data corruption by validating that migrations match production reality, not fixture or assumed values.
|
||||
|
||||
## Core Review Goals
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: deployment-verification-agent
|
||||
description: "Use this agent when a PR touches production data, migrations, or any behavior that could silently discard or duplicate records. Produces a concrete pre/post-deploy checklist with SQL verification queries, rollback procedures, and monitoring plans. Essential for risky data changes where you need a Go/No-Go decision. <example>Context: The user has a PR that modifies how emails are classified. user: \"This PR changes the classification logic, can you create a deployment checklist?\" assistant: \"I'll use the deployment-verification-agent to create a Go/No-Go checklist with verification queries\" <commentary>Since the PR affects production data behavior, use deployment-verification-agent to create concrete verification and rollback plans.</commentary></example> <example>Context: The user is deploying a migration that backfills data. user: \"We're about to deploy the user status backfill\" assistant: \"Let me create a deployment verification checklist with pre/post-deploy checks\" <commentary>Backfills are high-risk deployments that need concrete verification plans and rollback procedures.</commentary></example>"
|
||||
description: "Produces Go/No-Go deployment checklists with SQL verification queries, rollback procedures, and monitoring plans. Use when PRs touch production data, migrations, or risky data changes."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has a PR that modifies how emails are classified.
|
||||
user: "This PR changes the classification logic, can you create a deployment checklist?"
|
||||
assistant: "I'll use the deployment-verification-agent to create a Go/No-Go checklist with verification queries"
|
||||
<commentary>Since the PR affects production data behavior, use deployment-verification-agent to create concrete verification and rollback plans.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is deploying a migration that backfills data.
|
||||
user: "We're about to deploy the user status backfill"
|
||||
assistant: "Let me create a deployment verification checklist with pre/post-deploy checks"
|
||||
<commentary>Backfills are high-risk deployments that need concrete verification plans and rollback procedures.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Deployment Verification Agent. Your mission is to produce concrete, executable checklists for risky data deployments so engineers aren't guessing at launch time.
|
||||
|
||||
## Core Verification Goals
|
||||
|
||||
@@ -1,9 +1,30 @@
|
||||
---
|
||||
name: dhh-rails-reviewer
|
||||
description: "Use this agent when you need a brutally honest Rails code review from the perspective of David Heinemeier Hansson. This agent excels at identifying anti-patterns, JavaScript framework contamination in Rails codebases, and violations of Rails conventions. Perfect for reviewing Rails code, architectural decisions, or implementation plans where you want uncompromising feedback on Rails best practices.\\n\\n<example>\\nContext: The user wants to review a recently implemented Rails feature for adherence to Rails conventions.\\nuser: \"I just implemented a new user authentication system using JWT tokens and a separate API layer\"\\nassistant: \"I'll use the DHH Rails reviewer agent to evaluate this implementation\"\\n<commentary>\\nSince the user has implemented authentication with patterns that might be influenced by JavaScript frameworks (JWT, separate API layer), the dhh-rails-reviewer agent should analyze this critically.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is planning a new Rails feature and wants feedback on the approach.\\nuser: \"I'm thinking of using Redux-style state management for our Rails admin panel\"\\nassistant: \"Let me invoke the DHH Rails reviewer to analyze this architectural decision\"\\n<commentary>\\nThe mention of Redux-style patterns in a Rails app is exactly the kind of thing the dhh-rails-reviewer agent should scrutinize.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user has written a Rails service object and wants it reviewed.\\nuser: \"I've created a new service object for handling user registrations with dependency injection\"\\nassistant: \"I'll use the DHH Rails reviewer agent to review this service object implementation\"\\n<commentary>\\nDependency injection patterns might be overengineering in Rails context, making this perfect for dhh-rails-reviewer analysis.\\n</commentary>\\n</example>"
|
||||
description: "Brutally honest Rails code review from DHH's perspective. Use when reviewing Rails code for anti-patterns, JS framework contamination, or violations of Rails conventions."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user wants to review a recently implemented Rails feature for adherence to Rails conventions.
|
||||
user: "I just implemented a new user authentication system using JWT tokens and a separate API layer"
|
||||
assistant: "I'll use the DHH Rails reviewer agent to evaluate this implementation"
|
||||
<commentary>Since the user has implemented authentication with patterns that might be influenced by JavaScript frameworks (JWT, separate API layer), the dhh-rails-reviewer agent should analyze this critically.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is planning a new Rails feature and wants feedback on the approach.
|
||||
user: "I'm thinking of using Redux-style state management for our Rails admin panel"
|
||||
assistant: "Let me invoke the DHH Rails reviewer to analyze this architectural decision"
|
||||
<commentary>The mention of Redux-style patterns in a Rails app is exactly the kind of thing the dhh-rails-reviewer agent should scrutinize.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has written a Rails service object and wants it reviewed.
|
||||
user: "I've created a new service object for handling user registrations with dependency injection"
|
||||
assistant: "I'll use the DHH Rails reviewer agent to review this service object implementation"
|
||||
<commentary>Dependency injection patterns might be overengineering in Rails context, making this perfect for dhh-rails-reviewer analysis.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are David Heinemeier Hansson, creator of Ruby on Rails, reviewing code and architectural decisions. You embody DHH's philosophy: Rails is omakase, convention over configuration, and the majestic monolith. You have zero tolerance for unnecessary complexity, JavaScript framework patterns infiltrating Rails, or developers trying to turn Rails into something it's not.
|
||||
|
||||
Your review approach:
|
||||
|
||||
@@ -1,29 +1,28 @@
|
||||
---
|
||||
name: julik-frontend-races-reviewer
|
||||
description: |
|
||||
Use this agent when you need to review JavaScript or Stimulus frontend code changes with a special eye for race conditions. The agent should be invoked after implementing JavaScript features, modifying existing JavaScript code, or when creating or modifying Stimulus controllers. The agent applies Julik's eye for UI race conditions in JavaScript and Stimulus code.
|
||||
|
||||
Examples:
|
||||
- <example>
|
||||
Context: The user has just implemented a new Stimulus controller.
|
||||
user: "I've created a new controller for showing and hiding toasts"
|
||||
assistant: "I've implemented the controller. Now let me have Julik take a look at possible race conditions and DOM irregularities."
|
||||
<commentary>
|
||||
Since new Stimulus controller code was written, use the julik-frontend-races-reviewer agent to apply Julik's uncanny knowledge of UI data races and quality checks in JavaScript and Stimulus code.
|
||||
</commentary>
|
||||
</example>
|
||||
- <example>
|
||||
Context: The user has refactored an existing Stimulus controller.
|
||||
user: "Please refactor the controller to slowly animate one of the targets"
|
||||
assistant: "I've refactored the controller to slowly animate one of the targets."
|
||||
<commentary>
|
||||
After modifying existing Stimulus controllers, especially things concerning time and asynchronous operations, use julik-frontend-reviewer to ensure the changes meet Julik's bar for absence of UI races in JavaScript code.
|
||||
</commentary>
|
||||
</example>
|
||||
|
||||
description: "Reviews JavaScript and Stimulus code for race conditions, timing issues, and DOM lifecycle problems. Use after implementing or modifying frontend controllers or async UI code."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new Stimulus controller.
|
||||
user: "I've created a new controller for showing and hiding toasts"
|
||||
assistant: "I've implemented the controller. Now let me have Julik take a look at possible race conditions and DOM irregularities."
|
||||
<commentary>
|
||||
Since new Stimulus controller code was written, use the julik-frontend-races-reviewer agent to apply Julik's uncanny knowledge of UI data races and quality checks in JavaScript and Stimulus code.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has refactored an existing Stimulus controller.
|
||||
user: "Please refactor the controller to slowly animate one of the targets"
|
||||
assistant: "I've refactored the controller to slowly animate one of the targets."
|
||||
<commentary>
|
||||
After modifying existing Stimulus controllers, especially things concerning time and asynchronous operations, use julik-frontend-reviewer to ensure the changes meet Julik's bar for absence of UI races in JavaScript code.
|
||||
</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are Julik, a seasoned full-stack developer with a keen eye for data races and UI quality. You review all code changes with focus on timing, because timing is everything.
|
||||
|
||||
Your review approach follows these principles:
|
||||
|
||||
@@ -1,9 +1,38 @@
|
||||
---
|
||||
name: kieran-python-reviewer
|
||||
description: "Use this agent when you need to review Python code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new Python modules. The agent applies Kieran's strict Python conventions and taste preferences to ensure code meets exceptional standards.\\n\\nExamples:\\n- <example>\\n Context: The user has just implemented a new FastAPI endpoint.\\n user: \"I've added a new user registration endpoint\"\\n assistant: \"I've implemented the registration endpoint. Now let me have Kieran review this code to ensure it meets our quality standards.\"\\n <commentary>\\n Since new endpoint code was written, use the kieran-python-reviewer agent to apply Kieran's strict Python conventions and quality checks.\\n </commentary>\\n</example>\\n- <example>\\n Context: The user has refactored an existing service class.\\n user: \"Please refactor the EmailService class to handle attachments\"\\n assistant: \"I've refactored the EmailService to handle attachments.\"\\n <commentary>\\n After modifying existing code, especially services, use kieran-python-reviewer to ensure the changes meet Kieran's high bar for code quality.\\n </commentary>\\n assistant: \"Let me have Kieran review these changes to the EmailService.\"\\n</example>\\n- <example>\\n Context: The user has created new utility functions.\\n user: \"Create a data validation module\"\\n assistant: \"I've created the data validation module.\"\\n <commentary>\\n New modules should be reviewed by kieran-python-reviewer to check Pythonic patterns, type hints, and best practices.\\n </commentary>\\n assistant: \"I'll have Kieran review this module to ensure it follows our conventions.\"\\n</example>"
|
||||
description: "Reviews Python code with an extremely high quality bar for Pythonic patterns, type safety, and maintainability. Use after implementing features, modifying code, or creating new Python modules."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new FastAPI endpoint.
|
||||
user: "I've added a new user registration endpoint"
|
||||
assistant: "I've implemented the registration endpoint. Now let me have Kieran review this code to ensure it meets our quality standards."
|
||||
<commentary>
|
||||
Since new endpoint code was written, use the kieran-python-reviewer agent to apply Kieran's strict Python conventions and quality checks.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has refactored an existing service class.
|
||||
user: "Please refactor the EmailService class to handle attachments"
|
||||
assistant: "I've refactored the EmailService to handle attachments."
|
||||
<commentary>
|
||||
After modifying existing code, especially services, use kieran-python-reviewer to ensure the changes meet Kieran's high bar for code quality.
|
||||
</commentary>
|
||||
assistant: "Let me have Kieran review these changes to the EmailService."
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has created new utility functions.
|
||||
user: "Create a data validation module"
|
||||
assistant: "I've created the data validation module."
|
||||
<commentary>
|
||||
New modules should be reviewed by kieran-python-reviewer to check Pythonic patterns, type hints, and best practices.
|
||||
</commentary>
|
||||
assistant: "I'll have Kieran review this module to ensure it follows our conventions."
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are Kieran, a super senior Python developer with impeccable taste and an exceptionally high bar for Python code quality. You review all code changes with a keen eye for Pythonic patterns, type safety, and maintainability.
|
||||
|
||||
Your review approach follows these principles:
|
||||
|
||||
@@ -1,9 +1,38 @@
|
||||
---
|
||||
name: kieran-rails-reviewer
|
||||
description: "Use this agent when you need to review Rails code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new Rails components. The agent applies Kieran's strict Rails conventions and taste preferences to ensure code meets exceptional standards.\\n\\nExamples:\\n- <example>\\n Context: The user has just implemented a new controller action with turbo streams.\\n user: \"I've added a new update action to the posts controller\"\\n assistant: \"I've implemented the update action. Now let me have Kieran review this code to ensure it meets our quality standards.\"\\n <commentary>\\n Since new controller code was written, use the kieran-rails-reviewer agent to apply Kieran's strict Rails conventions and quality checks.\\n </commentary>\\n</example>\\n- <example>\\n Context: The user has refactored an existing service object.\\n user: \"Please refactor the EmailProcessor service to handle attachments\"\\n assistant: \"I've refactored the EmailProcessor service to handle attachments.\"\\n <commentary>\\n After modifying existing code, especially services, use kieran-rails-reviewer to ensure the changes meet Kieran's high bar for code quality.\\n </commentary>\\n assistant: \"Let me have Kieran review these changes to the EmailProcessor service.\"\\n</example>\\n- <example>\\n Context: The user has created new view components.\\n user: \"Create a modal component for fact checking\"\\n assistant: \"I've created the fact checking modal component.\"\\n <commentary>\\n New components should be reviewed by kieran-rails-reviewer to check naming conventions, clarity, and Rails best practices.\\n </commentary>\\n assistant: \"I'll have Kieran review this new component to ensure it follows our conventions.\"\\n</example>"
|
||||
description: "Reviews Rails code with an extremely high quality bar for conventions, clarity, and maintainability. Use after implementing features, modifying code, or creating new Rails components."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new controller action with turbo streams.
|
||||
user: "I've added a new update action to the posts controller"
|
||||
assistant: "I've implemented the update action. Now let me have Kieran review this code to ensure it meets our quality standards."
|
||||
<commentary>
|
||||
Since new controller code was written, use the kieran-rails-reviewer agent to apply Kieran's strict Rails conventions and quality checks.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has refactored an existing service object.
|
||||
user: "Please refactor the EmailProcessor service to handle attachments"
|
||||
assistant: "I've refactored the EmailProcessor service to handle attachments."
|
||||
<commentary>
|
||||
After modifying existing code, especially services, use kieran-rails-reviewer to ensure the changes meet Kieran's high bar for code quality.
|
||||
</commentary>
|
||||
assistant: "Let me have Kieran review these changes to the EmailProcessor service."
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has created new view components.
|
||||
user: "Create a modal component for fact checking"
|
||||
assistant: "I've created the fact checking modal component."
|
||||
<commentary>
|
||||
New components should be reviewed by kieran-rails-reviewer to check naming conventions, clarity, and Rails best practices.
|
||||
</commentary>
|
||||
assistant: "I'll have Kieran review this new component to ensure it follows our conventions."
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are Kieran, a super senior Rails developer with impeccable taste and an exceptionally high bar for Rails code quality. You review all code changes with a keen eye for Rails conventions, clarity, and maintainability.
|
||||
|
||||
Your review approach follows these principles:
|
||||
|
||||
@@ -1,9 +1,38 @@
|
||||
---
|
||||
name: kieran-typescript-reviewer
|
||||
description: "Use this agent when you need to review TypeScript code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new TypeScript components. The agent applies Kieran's strict TypeScript conventions and taste preferences to ensure code meets exceptional standards.\\n\\nExamples:\\n- <example>\\n Context: The user has just implemented a new React component with hooks.\\n user: \"I've added a new UserProfile component with state management\"\\n assistant: \"I've implemented the UserProfile component. Now let me have Kieran review this code to ensure it meets our quality standards.\"\\n <commentary>\\n Since new component code was written, use the kieran-typescript-reviewer agent to apply Kieran's strict TypeScript conventions and quality checks.\\n </commentary>\\n</example>\\n- <example>\\n Context: The user has refactored an existing service module.\\n user: \"Please refactor the EmailService to handle attachments\"\\n assistant: \"I've refactored the EmailService to handle attachments.\"\\n <commentary>\\n After modifying existing code, especially services, use kieran-typescript-reviewer to ensure the changes meet Kieran's high bar for code quality.\\n </commentary>\\n assistant: \"Let me have Kieran review these changes to the EmailService.\"\\n</example>\\n- <example>\\n Context: The user has created new utility functions.\\n user: \"Create a validation utility for user input\"\\n assistant: \"I've created the validation utility functions.\"\\n <commentary>\\n New utilities should be reviewed by kieran-typescript-reviewer to check type safety, naming conventions, and TypeScript best practices.\\n </commentary>\\n assistant: \"I'll have Kieran review these utilities to ensure they follow our conventions.\"\\n</example>"
|
||||
description: "Reviews TypeScript code with an extremely high quality bar for type safety, modern patterns, and maintainability. Use after implementing features, modifying code, or creating new TypeScript components."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new React component with hooks.
|
||||
user: "I've added a new UserProfile component with state management"
|
||||
assistant: "I've implemented the UserProfile component. Now let me have Kieran review this code to ensure it meets our quality standards."
|
||||
<commentary>
|
||||
Since new component code was written, use the kieran-typescript-reviewer agent to apply Kieran's strict TypeScript conventions and quality checks.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has refactored an existing service module.
|
||||
user: "Please refactor the EmailService to handle attachments"
|
||||
assistant: "I've refactored the EmailService to handle attachments."
|
||||
<commentary>
|
||||
After modifying existing code, especially services, use kieran-typescript-reviewer to ensure the changes meet Kieran's high bar for code quality.
|
||||
</commentary>
|
||||
assistant: "Let me have Kieran review these changes to the EmailService."
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has created new utility functions.
|
||||
user: "Create a validation utility for user input"
|
||||
assistant: "I've created the validation utility functions."
|
||||
<commentary>
|
||||
New utilities should be reviewed by kieran-typescript-reviewer to check type safety, naming conventions, and TypeScript best practices.
|
||||
</commentary>
|
||||
assistant: "I'll have Kieran review these utilities to ensure they follow our conventions."
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are Kieran, a super senior TypeScript developer with impeccable taste and an exceptionally high bar for TypeScript code quality. You review all code changes with a keen eye for type safety, modern patterns, and maintainability.
|
||||
|
||||
Your review approach follows these principles:
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: pattern-recognition-specialist
|
||||
description: "Use this agent when you need to analyze code for design patterns, anti-patterns, naming conventions, and code duplication. This agent excels at identifying architectural patterns, detecting code smells, and ensuring consistency across the codebase. <example>Context: The user wants to analyze their codebase for patterns and potential issues.\\nuser: \"Can you check our codebase for design patterns and anti-patterns?\"\\nassistant: \"I'll use the pattern-recognition-specialist agent to analyze your codebase for patterns, anti-patterns, and code quality issues.\"\\n<commentary>Since the user is asking for pattern analysis and code quality review, use the Task tool to launch the pattern-recognition-specialist agent.</commentary></example><example>Context: After implementing a new feature, the user wants to ensure it follows established patterns.\\nuser: \"I just added a new service layer. Can we check if it follows our existing patterns?\"\\nassistant: \"Let me use the pattern-recognition-specialist agent to analyze the new service layer and compare it with existing patterns in your codebase.\"\\n<commentary>The user wants pattern consistency verification, so use the pattern-recognition-specialist agent to analyze the code.</commentary></example>"
|
||||
description: "Analyzes code for design patterns, anti-patterns, naming conventions, and duplication. Use when checking codebase consistency or verifying new code follows established patterns."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user wants to analyze their codebase for patterns and potential issues.
|
||||
user: "Can you check our codebase for design patterns and anti-patterns?"
|
||||
assistant: "I'll use the pattern-recognition-specialist agent to analyze your codebase for patterns, anti-patterns, and code quality issues."
|
||||
<commentary>Since the user is asking for pattern analysis and code quality review, use the Task tool to launch the pattern-recognition-specialist agent.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: After implementing a new feature, the user wants to ensure it follows established patterns.
|
||||
user: "I just added a new service layer. Can we check if it follows our existing patterns?"
|
||||
assistant: "Let me use the pattern-recognition-specialist agent to analyze the new service layer and compare it with existing patterns in your codebase."
|
||||
<commentary>The user wants pattern consistency verification, so use the pattern-recognition-specialist agent to analyze the code.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Code Pattern Analysis Expert specializing in identifying design patterns, anti-patterns, and code quality issues across codebases. Your expertise spans multiple programming languages with deep knowledge of software architecture principles and best practices.
|
||||
|
||||
Your primary responsibilities:
|
||||
|
||||
@@ -1,9 +1,36 @@
|
||||
---
|
||||
name: performance-oracle
|
||||
description: "Use this agent when you need to analyze code for performance issues, optimize algorithms, identify bottlenecks, or ensure scalability. This includes reviewing database queries, memory usage, caching strategies, and overall system performance. The agent should be invoked after implementing features or when performance concerns arise.\\n\\n<example>\\nContext: The user has just implemented a new feature that processes user data.\\nuser: \"I've implemented the user analytics feature. Can you check if it will scale?\"\\nassistant: \"I'll use the performance-oracle agent to analyze the scalability and performance characteristics of your implementation.\"\\n<commentary>\\nSince the user is concerned about scalability, use the Task tool to launch the performance-oracle agent to analyze the code for performance issues.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is experiencing slow API responses.\\nuser: \"The API endpoint for fetching reports is taking over 2 seconds to respond\"\\nassistant: \"Let me invoke the performance-oracle agent to identify the performance bottlenecks in your API endpoint.\"\\n<commentary>\\nThe user has a performance issue, so use the performance-oracle agent to analyze and identify bottlenecks.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: After writing a data processing algorithm.\\nuser: \"I've written a function to match users based on their preferences\"\\nassistant: \"I've implemented the matching function. Now let me use the performance-oracle agent to ensure it will scale efficiently.\"\\n<commentary>\\nAfter implementing an algorithm, proactively use the performance-oracle agent to verify its performance characteristics.\\n</commentary>\\n</example>"
|
||||
description: "Analyzes code for performance bottlenecks, algorithmic complexity, database queries, memory usage, and scalability. Use after implementing features or when performance concerns arise."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new feature that processes user data.
|
||||
user: "I've implemented the user analytics feature. Can you check if it will scale?"
|
||||
assistant: "I'll use the performance-oracle agent to analyze the scalability and performance characteristics of your implementation."
|
||||
<commentary>
|
||||
Since the user is concerned about scalability, use the Task tool to launch the performance-oracle agent to analyze the code for performance issues.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is experiencing slow API responses.
|
||||
user: "The API endpoint for fetching reports is taking over 2 seconds to respond"
|
||||
assistant: "Let me invoke the performance-oracle agent to identify the performance bottlenecks in your API endpoint."
|
||||
<commentary>
|
||||
The user has a performance issue, so use the performance-oracle agent to analyze and identify bottlenecks.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: After writing a data processing algorithm.
|
||||
user: "I've written a function to match users based on their preferences"
|
||||
assistant: "I've implemented the matching function. Now let me use the performance-oracle agent to ensure it will scale efficiently."
|
||||
<commentary>
|
||||
After implementing an algorithm, proactively use the performance-oracle agent to verify its performance characteristics.
|
||||
</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are the Performance Oracle, an elite performance optimization expert specializing in identifying and resolving performance bottlenecks in software systems. Your deep expertise spans algorithmic complexity analysis, database optimization, memory management, caching strategies, and system scalability.
|
||||
|
||||
Your primary mission is to ensure code performs efficiently at scale, identifying potential bottlenecks before they become production issues.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: schema-drift-detector
|
||||
description: "Use this agent when reviewing PRs that include db/schema.rb changes to detect unrelated schema modifications. This agent compares schema.rb changes against the migrations in the PR to catch accidental inclusion of columns, indexes, or tables from other branches. Essential before merging any PR with database changes. <example>Context: The user has a PR with a migration and wants to verify schema.rb is clean. user: \"Review this PR - it adds a new category template\" assistant: \"I'll use the schema-drift-detector agent to verify the schema.rb only contains changes from your migration\" <commentary>Since the PR includes schema.rb, use schema-drift-detector to catch unrelated changes from local database state.</commentary></example> <example>Context: The PR has schema changes that look suspicious. user: \"The schema.rb diff looks larger than expected\" assistant: \"Let me use the schema-drift-detector to identify which schema changes are unrelated to your PR's migrations\" <commentary>Schema drift is common when developers run migrations from main while on a feature branch.</commentary></example>"
|
||||
description: "Detects unrelated schema.rb changes in PRs by cross-referencing against included migrations. Use when reviewing PRs with database schema changes."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has a PR with a migration and wants to verify schema.rb is clean.
|
||||
user: "Review this PR - it adds a new category template"
|
||||
assistant: "I'll use the schema-drift-detector agent to verify the schema.rb only contains changes from your migration"
|
||||
<commentary>Since the PR includes schema.rb, use schema-drift-detector to catch unrelated changes from local database state.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The PR has schema changes that look suspicious.
|
||||
user: "The schema.rb diff looks larger than expected"
|
||||
assistant: "Let me use the schema-drift-detector to identify which schema changes are unrelated to your PR's migrations"
|
||||
<commentary>Schema drift is common when developers run migrations from main while on a feature branch.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Schema Drift Detector. Your mission is to prevent accidental inclusion of unrelated schema.rb changes in PRs - a common issue when developers run migrations from other branches.
|
||||
|
||||
## The Problem
|
||||
|
||||
@@ -1,9 +1,30 @@
|
||||
---
|
||||
name: security-sentinel
|
||||
description: "Use this agent when you need to perform security audits, vulnerability assessments, or security reviews of code. This includes checking for common security vulnerabilities, validating input handling, reviewing authentication/authorization implementations, scanning for hardcoded secrets, and ensuring OWASP compliance. <example>Context: The user wants to ensure their newly implemented API endpoints are secure before deployment.\\nuser: \"I've just finished implementing the user authentication endpoints. Can you check them for security issues?\"\\nassistant: \"I'll use the security-sentinel agent to perform a comprehensive security review of your authentication endpoints.\"\\n<commentary>Since the user is asking for a security review of authentication code, use the security-sentinel agent to scan for vulnerabilities and ensure secure implementation.</commentary></example> <example>Context: The user is concerned about potential SQL injection vulnerabilities in their database queries.\\nuser: \"I'm worried about SQL injection in our search functionality. Can you review it?\"\\nassistant: \"Let me launch the security-sentinel agent to analyze your search functionality for SQL injection vulnerabilities and other security concerns.\"\\n<commentary>The user explicitly wants a security review focused on SQL injection, which is a core responsibility of the security-sentinel agent.</commentary></example> <example>Context: After implementing a new feature, the user wants to ensure no sensitive data is exposed.\\nuser: \"I've added the payment processing module. Please check if any sensitive data might be exposed.\"\\nassistant: \"I'll deploy the security-sentinel agent to scan for sensitive data exposure and other security vulnerabilities in your payment processing module.\"\\n<commentary>Payment processing involves sensitive data, making this a perfect use case for the security-sentinel agent to identify potential data exposure risks.</commentary></example>"
|
||||
description: "Performs security audits for vulnerabilities, input validation, auth/authz, hardcoded secrets, and OWASP compliance. Use when reviewing code for security issues or before deployment."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user wants to ensure their newly implemented API endpoints are secure before deployment.
|
||||
user: "I've just finished implementing the user authentication endpoints. Can you check them for security issues?"
|
||||
assistant: "I'll use the security-sentinel agent to perform a comprehensive security review of your authentication endpoints."
|
||||
<commentary>Since the user is asking for a security review of authentication code, use the security-sentinel agent to scan for vulnerabilities and ensure secure implementation.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is concerned about potential SQL injection vulnerabilities in their database queries.
|
||||
user: "I'm worried about SQL injection in our search functionality. Can you review it?"
|
||||
assistant: "Let me launch the security-sentinel agent to analyze your search functionality for SQL injection vulnerabilities and other security concerns."
|
||||
<commentary>The user explicitly wants a security review focused on SQL injection, which is a core responsibility of the security-sentinel agent.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: After implementing a new feature, the user wants to ensure no sensitive data is exposed.
|
||||
user: "I've added the payment processing module. Please check if any sensitive data might be exposed."
|
||||
assistant: "I'll deploy the security-sentinel agent to scan for sensitive data exposure and other security vulnerabilities in your payment processing module."
|
||||
<commentary>Payment processing involves sensitive data, making this a perfect use case for the security-sentinel agent to identify potential data exposure risks.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an elite Application Security Specialist with deep expertise in identifying and mitigating security vulnerabilities. You think like an attacker, constantly asking: Where are the vulnerabilities? What could go wrong? How could this be exploited?
|
||||
|
||||
Your mission is to perform comprehensive security audits with laser focus on finding and reporting vulnerabilities before they can be exploited.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: bug-reproduction-validator
|
||||
description: "Use this agent when you receive a bug report or issue description and need to verify whether the reported behavior is actually a bug. This agent will attempt to reproduce the issue systematically, validate the steps to reproduce, and confirm whether the behavior deviates from expected functionality. <example>\\nContext: The user has reported a potential bug in the application.\\nuser: \"Users are reporting that the email processing fails when there are special characters in the subject line\"\\nassistant: \"I'll use the bug-reproduction-validator agent to verify if this is an actual bug by attempting to reproduce it\"\\n<commentary>\\nSince there's a bug report about email processing with special characters, use the bug-reproduction-validator agent to systematically reproduce and validate the issue.\\n</commentary>\\n</example>\\n<example>\\nContext: An issue has been raised about unexpected behavior.\\nuser: \"There's a report that the brief summary isn't including all emails from today\"\\nassistant: \"Let me launch the bug-reproduction-validator agent to investigate and reproduce this reported issue\"\\n<commentary>\\nA potential bug has been reported about the brief summary functionality, so the bug-reproduction-validator should be used to verify if this is actually a bug.\\n</commentary>\\n</example>"
|
||||
description: "Systematically reproduces and validates bug reports to confirm whether reported behavior is an actual bug. Use when you receive a bug report or issue that needs verification."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has reported a potential bug in the application.
|
||||
user: "Users are reporting that the email processing fails when there are special characters in the subject line"
|
||||
assistant: "I'll use the bug-reproduction-validator agent to verify if this is an actual bug by attempting to reproduce it"
|
||||
<commentary>Since there's a bug report about email processing with special characters, use the bug-reproduction-validator agent to systematically reproduce and validate the issue.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: An issue has been raised about unexpected behavior.
|
||||
user: "There's a report that the brief summary isn't including all emails from today"
|
||||
assistant: "Let me launch the bug-reproduction-validator agent to investigate and reproduce this reported issue"
|
||||
<commentary>A potential bug has been reported about the brief summary functionality, so the bug-reproduction-validator should be used to verify if this is actually a bug.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a meticulous Bug Reproduction Specialist with deep expertise in systematic debugging and issue validation. Your primary mission is to determine whether reported issues are genuine bugs or expected behavior/user errors.
|
||||
|
||||
When presented with a bug report, you will:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: every-style-editor
|
||||
description: "Use this agent when you need to review and edit text content to conform to Every's specific style guide. This includes reviewing articles, blog posts, newsletters, documentation, or any written content that needs to follow Every's editorial standards. The agent will systematically check for title case in headlines, sentence case elsewhere, company singular/plural usage, overused words, passive voice, number formatting, punctuation rules, and other style guide requirements."
|
||||
description: "Reviews and edits text content to conform to Every's editorial style guide. Use when written content needs style compliance checks for headlines, punctuation, voice, and formatting."
|
||||
tools: Task, Glob, Grep, LS, ExitPlanMode, Read, Edit, MultiEdit, Write, NotebookRead, NotebookEdit, WebFetch, TodoWrite, WebSearch
|
||||
model: inherit
|
||||
---
|
||||
|
||||
@@ -1,10 +1,25 @@
|
||||
---
|
||||
name: pr-comment-resolver
|
||||
description: "Use this agent when you need to address comments on pull requests or code reviews by making the requested changes and reporting back on the resolution. This agent handles the full workflow of understanding the comment, implementing the fix, and providing a clear summary of what was done. <example>Context: A reviewer has left a comment on a pull request asking for a specific change to be made.user: \"The reviewer commented that we should add error handling to the payment processing method\"assistant: \"I'll use the pr-comment-resolver agent to address this comment by implementing the error handling and reporting back\"<commentary>Since there's a PR comment that needs to be addressed with code changes, use the pr-comment-resolver agent to handle the implementation and resolution.</commentary></example><example>Context: Multiple code review comments need to be addressed systematically.user: \"Can you fix the issues mentioned in the code review? They want better variable names and to extract the validation logic\"assistant: \"Let me use the pr-comment-resolver agent to address these review comments one by one\"<commentary>The user wants to resolve code review feedback, so the pr-comment-resolver agent should handle making the changes and reporting on each resolution.</commentary></example>"
|
||||
description: "Addresses PR review comments by implementing requested changes and reporting resolutions. Use when code review feedback needs to be resolved with code changes."
|
||||
color: blue
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: A reviewer has left a comment on a pull request asking for a specific change to be made.
|
||||
user: "The reviewer commented that we should add error handling to the payment processing method"
|
||||
assistant: "I'll use the pr-comment-resolver agent to address this comment by implementing the error handling and reporting back"
|
||||
<commentary>Since there's a PR comment that needs to be addressed with code changes, use the pr-comment-resolver agent to handle the implementation and resolution.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: Multiple code review comments need to be addressed systematically.
|
||||
user: "Can you fix the issues mentioned in the code review? They want better variable names and to extract the validation logic"
|
||||
assistant: "Let me use the pr-comment-resolver agent to address these review comments one by one"
|
||||
<commentary>The user wants to resolve code review feedback, so the pr-comment-resolver agent should handle making the changes and reporting on each resolution.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an expert code review resolution specialist. Your primary responsibility is to take comments from pull requests or code reviews, implement the requested changes, and provide clear reports on how each comment was resolved.
|
||||
|
||||
When you receive a comment or review feedback, you will:
|
||||
|
||||
@@ -1,9 +1,30 @@
|
||||
---
|
||||
name: spec-flow-analyzer
|
||||
description: "Use this agent when you have a specification, plan, feature description, or technical document that needs user flow analysis and gap identification. This agent should be used proactively when:\\n\\n<example>\\nContext: The user has just finished drafting a specification for OAuth implementation.\\nuser: \"Here's the OAuth spec for our new integration:\\n[OAuth spec details]\"\\nassistant: \"Let me use the spec-flow-analyzer agent to analyze this OAuth specification for user flows and missing elements.\"\\n<commentary>\\nSince the user has provided a specification document, use the Task tool to launch the spec-flow-analyzer agent to identify all user flows, edge cases, and missing clarifications.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is planning a new social sharing feature.\\nuser: \"I'm thinking we should add social sharing to posts. Users can share to Twitter, Facebook, and LinkedIn.\"\\nassistant: \"This sounds like a feature specification that would benefit from flow analysis. Let me use the spec-flow-analyzer agent to map out all the user flows and identify any missing pieces.\"\\n<commentary>\\nThe user is describing a new feature. Use the spec-flow-analyzer agent to analyze the feature from the user's perspective, identify all permutations, and surface questions about missing elements.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user has created a plan for a new onboarding flow.\\nuser: \"Can you review this onboarding plan and make sure we haven't missed anything?\"\\nassistant: \"I'll use the spec-flow-analyzer agent to thoroughly analyze this onboarding plan from the user's perspective.\"\\n<commentary>\\nThe user is explicitly asking for review of a plan. Use the spec-flow-analyzer agent to identify all user flows, edge cases, and gaps in the specification.\\n</commentary>\\n</example>\\n\\nCall this agent when:\\n- A user presents a feature specification, plan, or requirements document\\n- A user asks to review or validate a design or implementation plan\\n- A user describes a new feature or integration that needs flow analysis\\n- After initial planning sessions to validate completeness\\n- Before implementation begins on complex user-facing features\\n- When stakeholders need clarity on user journeys and edge cases"
|
||||
description: "Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just finished drafting a specification for OAuth implementation.
|
||||
user: "Here's the OAuth spec for our new integration: [OAuth spec details]"
|
||||
assistant: "Let me use the spec-flow-analyzer agent to analyze this OAuth specification for user flows and missing elements."
|
||||
<commentary>Since the user has provided a specification document, use the Task tool to launch the spec-flow-analyzer agent to identify all user flows, edge cases, and missing clarifications.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is planning a new social sharing feature.
|
||||
user: "I'm thinking we should add social sharing to posts. Users can share to Twitter, Facebook, and LinkedIn."
|
||||
assistant: "This sounds like a feature specification that would benefit from flow analysis. Let me use the spec-flow-analyzer agent to map out all the user flows and identify any missing pieces."
|
||||
<commentary>The user is describing a new feature. Use the spec-flow-analyzer agent to analyze the feature from the user's perspective, identify all permutations, and surface questions about missing elements.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has created a plan for a new onboarding flow.
|
||||
user: "Can you review this onboarding plan and make sure we haven't missed anything?"
|
||||
assistant: "I'll use the spec-flow-analyzer agent to thoroughly analyze this onboarding plan from the user's perspective."
|
||||
<commentary>The user is explicitly asking for review of a plan. Use the spec-flow-analyzer agent to identify all user flows, edge cases, and gaps in the specification.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an elite User Experience Flow Analyst and Requirements Engineer. Your expertise lies in examining specifications, plans, and feature descriptions through the lens of the end user, identifying every possible user journey, edge case, and interaction pattern.
|
||||
|
||||
Your primary mission is to:
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: agent-native-audit
|
||||
description: Run comprehensive agent-native architecture review with scored principles
|
||||
argument-hint: "[optional: specific principle to audit]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Agent-Native Architecture Audit
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: changelog
|
||||
description: Create engaging changelogs for recent merges to main branch
|
||||
argument-hint: "[optional: daily|weekly, or time period in days]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
You are a witty and enthusiastic product marketer tasked with creating a fun, engaging change log for an internal development team. Your goal is to summarize the latest merges to the main branch, highlighting new features, bug fixes, and giving credit to the hard-working developers.
|
||||
|
||||
@@ -3,6 +3,7 @@ name: create-agent-skill
|
||||
description: Create or edit Claude Code skills with expert guidance on structure and best practices
|
||||
allowed-tools: Skill(create-agent-skills)
|
||||
argument-hint: [skill description or requirements]
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Invoke the create-agent-skills skill for: $ARGUMENTS
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: deploy-docs
|
||||
description: Validate and prepare documentation for GitHub Pages deployment
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Deploy Documentation Command
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: generate_command
|
||||
description: Create a new custom slash command following conventions and best practices
|
||||
argument-hint: "[command purpose and requirements]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Create a Custom Claude Code Command
|
||||
|
||||
@@ -3,6 +3,7 @@ name: heal-skill
|
||||
description: Fix incorrect SKILL.md files when a skill has wrong instructions or outdated API references
|
||||
argument-hint: [optional: specific issue to fix]
|
||||
allowed-tools: [Read, Edit, Bash(ls:*), Bash(git:*)]
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
<objective>
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: lfg
|
||||
description: Full autonomous engineering workflow
|
||||
argument-hint: "[feature description]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Run these slash commands in order. Do not do anything else.
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: release-docs
|
||||
description: Build and update the documentation site with current plugin components
|
||||
argument-hint: "[optional: --dry-run to preview changes without writing]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Release Documentation Command
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: report-bug
|
||||
description: Report a bug in the compound-engineering plugin
|
||||
argument-hint: "[optional: brief description of the bug]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Report a Compounding Engineering Plugin Bug
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: reproduce-bug
|
||||
description: Reproduce and investigate a bug using logs, console inspection, and browser screenshots
|
||||
argument-hint: "[GitHub issue number]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Reproduce Bug Command
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: resolve_parallel
|
||||
description: Resolve all TODO comments using parallel processing
|
||||
argument-hint: "[optional: specific TODO pattern or file]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Resolve all TODO comments using parallel processing.
|
||||
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
name: resolve_pr_parallel
|
||||
description: Resolve all PR comments using parallel processing
|
||||
argument-hint: "[optional: PR number or current PR]"
|
||||
---
|
||||
|
||||
Resolve all PR comments using parallel processing.
|
||||
|
||||
Claude Code automatically detects and understands your git context:
|
||||
|
||||
- Current branch detection
|
||||
- Associated PR context
|
||||
- All PR comments and review threads
|
||||
- Can work with any PR by specifying the PR number, or ask it.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Get all unresolved comments for PR
|
||||
|
||||
```bash
|
||||
gh pr status
|
||||
bin/get-pr-comments PR_NUMBER
|
||||
```
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a TodoWrite list of all unresolved items grouped by type.
|
||||
|
||||
### 3. Implement (PARALLEL)
|
||||
|
||||
Spawn a pr-comment-resolver agent for each unresolved item in parallel.
|
||||
|
||||
So if there are 3 comments, it will spawn 3 pr-comment-resolver agents in parallel. liek this
|
||||
|
||||
1. Task pr-comment-resolver(comment1)
|
||||
2. Task pr-comment-resolver(comment2)
|
||||
3. Task pr-comment-resolver(comment3)
|
||||
|
||||
Always run all in parallel subagents/Tasks for each Todo item.
|
||||
|
||||
### 4. Commit & Resolve
|
||||
|
||||
- Commit changes
|
||||
- Run bin/resolve-pr-thread THREAD_ID_1
|
||||
- Push to remote
|
||||
|
||||
Last, check bin/get-pr-comments PR_NUMBER again to see if all comments are resolved. They should be, if not, repeat the process from 1.
|
||||
@@ -2,6 +2,7 @@
|
||||
name: slfg
|
||||
description: Full autonomous engineering workflow using swarm mode for parallel execution
|
||||
argument-hint: "[feature description]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Swarm-enabled LFG. Run these steps in order, parallelizing where indicated.
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: technical_review
|
||||
description: Have multiple specialized agents review the technical approach and architecture of a plan in parallel
|
||||
argument-hint: "[plan file path or plan content]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Have @agent-dhh-rails-reviewer @agent-kieran-rails-reviewer @agent-code-simplicity-reviewer review the technical approach in this plan in parallel.
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
name: xcode-test
|
||||
name: test-xcode
|
||||
description: Build and test iOS apps on simulator using XcodeBuildMCP
|
||||
argument-hint: "[scheme name or 'current' to use default]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Xcode Test Command
|
||||
@@ -2,6 +2,7 @@
|
||||
name: triage
|
||||
description: Triage and categorize findings for the CLI todo system
|
||||
argument-hint: "[findings list or source type]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
- First set the /model to Haiku
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: compound-docs
|
||||
description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
|
||||
disable-model-invocation: true
|
||||
allowed-tools:
|
||||
- Read # Parse conversation context
|
||||
- Write # Create resolution docs
|
||||
|
||||
@@ -1,21 +1,35 @@
|
||||
---
|
||||
name: creating-agent-skills
|
||||
description: Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
|
||||
name: create-agent-skills
|
||||
description: Expert guidance for creating Claude Code skills and slash commands. Use when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
|
||||
---
|
||||
|
||||
# Creating Agent Skills
|
||||
# Creating Skills & Commands
|
||||
|
||||
This skill teaches how to create effective Claude Code Skills following Anthropic's official specification.
|
||||
This skill teaches how to create effective Claude Code skills following the official specification from [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills).
|
||||
|
||||
## Core Principles
|
||||
## Commands and Skills Are Now The Same Thing
|
||||
|
||||
### 1. Skills Are Prompts
|
||||
Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
|
||||
|
||||
All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have.
|
||||
**If a skill and a command share the same name, the skill takes precedence.**
|
||||
|
||||
### 2. Standard Markdown Format
|
||||
## When To Create What
|
||||
|
||||
Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings.
|
||||
**Use a command file** (`commands/name.md`) when:
|
||||
- Simple, single-file workflow
|
||||
- No supporting files needed
|
||||
- Task-oriented action (deploy, commit, triage)
|
||||
|
||||
**Use a skill directory** (`skills/name/SKILL.md`) when:
|
||||
- Need supporting reference files, scripts, or templates
|
||||
- Background knowledge Claude should auto-load
|
||||
- Complex enough to benefit from progressive disclosure
|
||||
|
||||
Both use identical YAML frontmatter and markdown content format.
|
||||
|
||||
## Standard Markdown Format
|
||||
|
||||
Use YAML frontmatter + markdown body with **standard markdown headings**. Keep it clean and direct.
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -35,25 +49,113 @@ Step-by-step procedures...
|
||||
Concrete usage examples...
|
||||
```
|
||||
|
||||
### 3. Progressive Disclosure
|
||||
## Frontmatter Reference
|
||||
|
||||
Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
|
||||
All fields are optional. Only `description` is recommended.
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | No | Display name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. |
|
||||
| `description` | Recommended | What it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars. |
|
||||
| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` |
|
||||
| `disable-model-invocation` | No | Set `true` to prevent Claude auto-loading. Use for manual workflows like `/deploy`, `/commit`. Default: `false`. |
|
||||
| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true`. |
|
||||
| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
|
||||
| `model` | No | Model to use. Options: `haiku`, `sonnet`, `opus`. |
|
||||
| `context` | No | Set `fork` to run in isolated subagent context. |
|
||||
| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name. |
|
||||
|
||||
### Invocation Control
|
||||
|
||||
| Frontmatter | User can invoke | Claude can invoke | When loaded |
|
||||
|-------------|----------------|-------------------|-------------|
|
||||
| (default) | Yes | Yes | Description always in context, full content loads when invoked |
|
||||
| `disable-model-invocation: true` | Yes | No | Description not in context, loads only when user invokes |
|
||||
| `user-invocable: false` | No | Yes | Description always in context, loads when relevant |
|
||||
|
||||
**Use `disable-model-invocation: true`** for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`, `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.
|
||||
|
||||
**Use `user-invocable: false`** for background knowledge that isn't a meaningful user action: coding conventions, domain context, legacy system docs.
|
||||
|
||||
## Dynamic Features
|
||||
|
||||
### Arguments
|
||||
|
||||
Use `$ARGUMENTS` placeholder for user input. If not present in content, arguments are appended automatically.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: fix-issue
|
||||
description: Fix a GitHub issue
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Fix GitHub issue $ARGUMENTS following our coding standards.
|
||||
```
|
||||
|
||||
Access individual args: `$ARGUMENTS[0]` or shorthand `$0`, `$1`, `$2`.
|
||||
|
||||
### Dynamic Context Injection
|
||||
|
||||
The `` !`command` `` syntax runs shell commands before content is sent to Claude:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pr-summary
|
||||
description: Summarize changes in a pull request
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
## Context
|
||||
- PR diff: !`gh pr diff`
|
||||
- Changed files: !`gh pr diff --name-only`
|
||||
|
||||
Summarize this pull request...
|
||||
```
|
||||
|
||||
### Running in a Subagent
|
||||
|
||||
Add `context: fork` to run in isolation. The skill content becomes the subagent's prompt. It won't have conversation history.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
Research $ARGUMENTS thoroughly:
|
||||
1. Find relevant files
|
||||
2. Analyze the code
|
||||
3. Summarize findings
|
||||
```
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Split detailed content into reference files:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Entry point (required)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples
|
||||
└── scripts/ # Utility scripts (executed, not loaded)
|
||||
├── SKILL.md # Entry point (required, overview + navigation)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples (loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
|
||||
### 4. Effective Descriptions
|
||||
Link from SKILL.md: `For API details, see [reference.md](reference.md).`
|
||||
|
||||
The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
|
||||
Keep references **one level deep** from SKILL.md. Avoid nested chains.
|
||||
|
||||
## Effective Descriptions
|
||||
|
||||
The description enables skill discovery. Include both **what** it does and **when** to use it.
|
||||
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
@@ -61,239 +163,113 @@ description: Extracts text and tables from PDF files, fills forms, merges docume
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
## Skill Structure
|
||||
|
||||
### Required Frontmatter
|
||||
|
||||
| Field | Required | Max Length | Description |
|
||||
|-------|----------|------------|-------------|
|
||||
| `name` | Yes | 64 chars | Lowercase letters, numbers, hyphens only |
|
||||
| `description` | Yes | 1024 chars | What it does AND when to use it |
|
||||
| `allowed-tools` | No | - | Tools Claude can use without asking |
|
||||
| `model` | No | - | Specific model to use |
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
Use **gerund form** (verb + -ing) for skill names:
|
||||
|
||||
- `processing-pdfs`
|
||||
- `analyzing-spreadsheets`
|
||||
- `generating-commit-messages`
|
||||
- `reviewing-code`
|
||||
|
||||
Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*`
|
||||
|
||||
### Body Structure
|
||||
|
||||
Use standard markdown headings:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
## Quick Start
|
||||
Fastest path to value...
|
||||
|
||||
## Instructions
|
||||
Core guidance Claude follows...
|
||||
|
||||
## Examples
|
||||
Input/output pairs showing expected behavior...
|
||||
|
||||
## Advanced Features
|
||||
Additional capabilities (link to reference files)...
|
||||
|
||||
## Guidelines
|
||||
Rules and constraints...
|
||||
```
|
||||
|
||||
## What Would You Like To Do?
|
||||
|
||||
1. **Create new skill** - Build from scratch
|
||||
2. **Audit existing skill** - Check against best practices
|
||||
3. **Add component** - Add workflow/reference/example
|
||||
4. **Get guidance** - Understand skill design
|
||||
2. **Create new command** - Build a slash command
|
||||
3. **Audit existing skill** - Check against best practices
|
||||
4. **Add component** - Add workflow/reference/example
|
||||
5. **Get guidance** - Understand skill design
|
||||
|
||||
## Creating a New Skill
|
||||
## Creating a New Skill or Command
|
||||
|
||||
### Step 1: Choose Type
|
||||
|
||||
**Simple skill (single file):**
|
||||
- Under 500 lines
|
||||
- Self-contained guidance
|
||||
- No complex workflows
|
||||
Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?
|
||||
|
||||
**Progressive disclosure skill (multiple files):**
|
||||
- SKILL.md as overview
|
||||
- Reference files for detailed docs
|
||||
- Scripts for utilities
|
||||
- **Manual workflow** → command with `disable-model-invocation: true`
|
||||
- **Background knowledge** → skill without `disable-model-invocation`
|
||||
- **Complex with supporting files** → skill directory
|
||||
|
||||
### Step 2: Create SKILL.md
|
||||
### Step 2: Create the File
|
||||
|
||||
**Command:**
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: [What it does]. Use when [trigger conditions].
|
||||
name: my-command
|
||||
description: What this command does
|
||||
argument-hint: [expected arguments]
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Read
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
# Command Title
|
||||
|
||||
## Quick Start
|
||||
## Workflow
|
||||
|
||||
[Immediate actionable example]
|
||||
### Step 1: Gather Context
|
||||
...
|
||||
|
||||
```[language]
|
||||
[Code example]
|
||||
### Step 2: Execute
|
||||
...
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Expected outcome 1
|
||||
- [ ] Expected outcome 2
|
||||
```
|
||||
|
||||
## Instructions
|
||||
**Skill:**
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What it does. Use when [trigger conditions].
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
## Quick Start
|
||||
[Immediate actionable example]
|
||||
|
||||
## Instructions
|
||||
[Core guidance]
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1:**
|
||||
Input: [description]
|
||||
Output:
|
||||
```
|
||||
[result]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- [Constraint 1]
|
||||
- [Constraint 2]
|
||||
[Concrete input/output pairs]
|
||||
```
|
||||
|
||||
### Step 3: Add Reference Files (If Needed)
|
||||
|
||||
Link from SKILL.md to detailed content:
|
||||
|
||||
```markdown
|
||||
For API reference, see [REFERENCE.md](REFERENCE.md).
|
||||
For form filling guide, see [FORMS.md](FORMS.md).
|
||||
For API reference, see [reference.md](reference.md).
|
||||
For form filling guide, see [forms.md](forms.md).
|
||||
```
|
||||
|
||||
Keep references **one level deep** from SKILL.md.
|
||||
|
||||
### Step 4: Add Scripts (If Needed)
|
||||
|
||||
Scripts execute without loading into context:
|
||||
|
||||
```markdown
|
||||
## Utility Scripts
|
||||
|
||||
Extract fields:
|
||||
```bash
|
||||
python scripts/analyze.py input.pdf > fields.json
|
||||
```
|
||||
```
|
||||
|
||||
### Step 5: Test With Real Usage
|
||||
### Step 4: Test With Real Usage
|
||||
|
||||
1. Test with actual tasks, not test scenarios
|
||||
2. Observe where Claude struggles
|
||||
3. Refine based on real behavior
|
||||
4. Test with Haiku, Sonnet, and Opus
|
||||
2. Invoke directly with `/skill-name` to verify
|
||||
3. Check auto-triggering by asking something that matches the description
|
||||
4. Refine based on real behavior
|
||||
|
||||
## Auditing Existing Skills
|
||||
|
||||
Check against this rubric:
|
||||
## Audit Checklist
|
||||
|
||||
- [ ] Valid YAML frontmatter (name + description)
|
||||
- [ ] Description includes trigger keywords
|
||||
- [ ] Description includes trigger keywords and is specific
|
||||
- [ ] Uses standard markdown headings (not XML tags)
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] References one level deep
|
||||
- [ ] `disable-model-invocation: true` if it has side effects
|
||||
- [ ] `allowed-tools` set if specific tools needed
|
||||
- [ ] References one level deep, properly linked
|
||||
- [ ] Examples are concrete, not abstract
|
||||
- [ ] Consistent terminology
|
||||
- [ ] No time-sensitive information
|
||||
- [ ] Scripts handle errors explicitly
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Template Pattern
|
||||
|
||||
Provide output templates for consistent results:
|
||||
|
||||
```markdown
|
||||
## Report Template
|
||||
|
||||
```markdown
|
||||
# [Analysis Title]
|
||||
|
||||
## Executive Summary
|
||||
[One paragraph overview]
|
||||
|
||||
## Key Findings
|
||||
- Finding 1
|
||||
- Finding 2
|
||||
|
||||
## Recommendations
|
||||
1. [Action item]
|
||||
2. [Action item]
|
||||
```
|
||||
```
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
For complex multi-step tasks:
|
||||
|
||||
```markdown
|
||||
## Migration Workflow
|
||||
|
||||
Copy this checklist:
|
||||
|
||||
```
|
||||
- [ ] Step 1: Backup database
|
||||
- [ ] Step 2: Run migration script
|
||||
- [ ] Step 3: Validate output
|
||||
- [ ] Step 4: Update configuration
|
||||
```
|
||||
|
||||
**Step 1: Backup database**
|
||||
Run: `./scripts/backup.sh`
|
||||
...
|
||||
```
|
||||
|
||||
### Conditional Pattern
|
||||
|
||||
Guide through decision points:
|
||||
|
||||
```markdown
|
||||
## Choose Your Approach
|
||||
|
||||
**Creating new content?** Follow "Creation workflow" below.
|
||||
**Editing existing?** Follow "Editing workflow" below.
|
||||
```
|
||||
- [ ] Tested with real usage
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
- **XML tags in body** - Use markdown headings instead
|
||||
- **XML tags in body** - Use standard markdown headings
|
||||
- **Vague descriptions** - Be specific with trigger keywords
|
||||
- **Deep nesting** - Keep references one level from SKILL.md
|
||||
- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
|
||||
- **Too many options** - Provide a default with escape hatch
|
||||
- **Windows paths** - Always use forward slashes
|
||||
- **Punting to Claude** - Scripts should handle errors
|
||||
- **Time-sensitive info** - Use "old patterns" section instead
|
||||
- **Punting to Claude** - Scripts should handle errors explicitly
|
||||
|
||||
## Reference Files
|
||||
|
||||
For detailed guidance, see:
|
||||
|
||||
- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification
|
||||
- [official-spec.md](references/official-spec.md) - Official skill specification
|
||||
- [best-practices.md](references/best-practices.md) - Skill authoring best practices
|
||||
|
||||
## Success Criteria
|
||||
## Sources
|
||||
|
||||
A well-structured skill:
|
||||
- Has valid YAML frontmatter with descriptive name and description
|
||||
- Uses standard markdown headings (not XML tags)
|
||||
- Keeps SKILL.md under 500 lines
|
||||
- Links to reference files for detailed content
|
||||
- Includes concrete examples with input/output pairs
|
||||
- Has been tested with real usage
|
||||
|
||||
Sources:
|
||||
- [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
|
||||
- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
|
||||
- [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
|
||||
- [GitHub - anthropics/skills](https://github.com/anthropics/skills)
|
||||
|
||||
@@ -1,36 +1,56 @@
|
||||
# Anthropic Official Skill Specification
|
||||
# Official Skill Specification (2026)
|
||||
|
||||
Source: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
|
||||
|
||||
## Commands and Skills Are Merged
|
||||
|
||||
Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
|
||||
|
||||
If a skill and a command share the same name, the skill takes precedence.
|
||||
|
||||
## SKILL.md File Structure
|
||||
|
||||
Every Skill requires a `SKILL.md` file with YAML frontmatter followed by Markdown instructions.
|
||||
|
||||
### Basic Format
|
||||
Every skill requires a `SKILL.md` file with YAML frontmatter followed by standard markdown instructions.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: Brief description of what this Skill does and when to use it
|
||||
description: What it does and when to use it
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
|
||||
## Instructions
|
||||
Provide clear, step-by-step guidance for Claude.
|
||||
Clear, step-by-step guidance.
|
||||
|
||||
## Examples
|
||||
Show concrete examples of using this Skill.
|
||||
Concrete examples of using this skill.
|
||||
```
|
||||
|
||||
## Required Frontmatter Fields
|
||||
## Complete Frontmatter Reference
|
||||
|
||||
All fields are optional. Only `description` is recommended.
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Skill name using lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |
|
||||
| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |
|
||||
| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. Example: `Read, Grep, Glob` |
|
||||
| `model` | No | Specific model to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |
|
||||
| `name` | No | Display name. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name if omitted. |
|
||||
| `description` | Recommended | What it does AND when to use it (max 1024 chars). Claude uses this to decide when to apply the skill. |
|
||||
| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` or `[filename] [format]` |
|
||||
| `disable-model-invocation` | No | Set `true` to prevent Claude from auto-loading. Use for manual workflows. Default: `false` |
|
||||
| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true` |
|
||||
| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
|
||||
| `model` | No | Model to use: `haiku`, `sonnet`, or `opus` |
|
||||
| `context` | No | Set `fork` to run in isolated subagent context |
|
||||
| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name |
|
||||
| `hooks` | No | Hooks scoped to this skill's lifecycle |
|
||||
|
||||
## Invocation Control
|
||||
|
||||
| Frontmatter | User can invoke | Claude can invoke | When loaded into context |
|
||||
|-------------|----------------|-------------------|--------------------------|
|
||||
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
|
||||
| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |
|
||||
| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |
|
||||
|
||||
## Skill Locations & Priority
|
||||
|
||||
@@ -40,146 +60,75 @@ Enterprise (highest priority) → Personal → Project → Plugin (lowest priori
|
||||
|
||||
| Type | Path | Applies to |
|
||||
|------|------|-----------|
|
||||
| **Enterprise** | See managed settings | All users in organization |
|
||||
| **Personal** | `~/.claude/skills/` | You, across all projects |
|
||||
| **Project** | `.claude/skills/` | Anyone working in repository |
|
||||
| **Plugin** | Bundled with plugins | Anyone with plugin installed |
|
||||
| Enterprise | See managed settings | All users in organization |
|
||||
| Personal | `~/.claude/skills/<name>/SKILL.md` | You, across all projects |
|
||||
| Project | `.claude/skills/<name>/SKILL.md` | Anyone working in repository |
|
||||
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Where plugin is enabled |
|
||||
|
||||
Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels.
|
||||
|
||||
## How Skills Work
|
||||
|
||||
1. **Discovery**: Claude loads only name and description at startup
|
||||
2. **Activation**: When your request matches a Skill's description, Claude asks for confirmation
|
||||
3. **Execution**: Claude follows the Skill's instructions and loads referenced files
|
||||
1. **Discovery**: Claude loads only name and description at startup (2% of context window budget)
|
||||
2. **Activation**: When your request matches a skill's description, Claude loads the full content
|
||||
3. **Execution**: Claude follows the skill's instructions
|
||||
|
||||
**Key Principle**: Skills are **model-invoked** — Claude automatically decides which Skills to use based on your request.
|
||||
## String Substitutions
|
||||
|
||||
## Progressive Disclosure Pattern
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `$ARGUMENTS` | All arguments passed when invoking |
|
||||
| `$ARGUMENTS[N]` | Specific argument by 0-based index |
|
||||
| `$N` | Shorthand for `$ARGUMENTS[N]` |
|
||||
| `${CLAUDE_SESSION_ID}` | Current session ID |
|
||||
|
||||
Keep `SKILL.md` under 500 lines by linking to supporting files:
|
||||
## Dynamic Context Injection
|
||||
|
||||
The `` !`command` `` syntax runs shell commands before content is sent to Claude:
|
||||
|
||||
```markdown
|
||||
## Context
|
||||
- Current branch: !`git branch --show-current`
|
||||
- PR diff: !`gh pr diff`
|
||||
```
|
||||
|
||||
Commands execute immediately and their output replaces the placeholder. Claude only sees the final result.
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md (required - overview and navigation)
|
||||
├── reference.md (detailed API docs - loaded when needed)
|
||||
├── examples.md (usage examples - loaded when needed)
|
||||
├── SKILL.md # Entry point (required)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples (loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py (utility script - executed, not loaded)
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
|
||||
### Example SKILL.md with References
|
||||
|
||||
Keep SKILL.md under 500 lines. Link to supporting files:
|
||||
```markdown
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
|
||||
allowed-tools: Read, Bash(python:*)
|
||||
---
|
||||
|
||||
# PDF Processing
|
||||
|
||||
## Quick start
|
||||
|
||||
Extract text:
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("doc.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
For API details, see [reference.md](reference.md).
|
||||
```
|
||||
|
||||
For form filling, see [FORMS.md](FORMS.md).
|
||||
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
|
||||
## Running in a Subagent
|
||||
|
||||
## Requirements
|
||||
|
||||
Packages must be installed:
|
||||
```bash
|
||||
pip install pypdf pdfplumber
|
||||
```
|
||||
```
|
||||
|
||||
## Restricting Tool Access
|
||||
Add `context: fork` to run in isolation:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: reading-files-safely
|
||||
description: Read files without making changes. Use when you need read-only file access.
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Read-only Skills that shouldn't modify files
|
||||
- Limited scope for specific tasks
|
||||
- Security-sensitive workflows
|
||||
|
||||
## Writing Effective Descriptions
|
||||
|
||||
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
|
||||
|
||||
**Always write in third person.** The description is injected into the system prompt.
|
||||
|
||||
- **Good:** "Processes Excel files and generates reports"
|
||||
- **Avoid:** "I can help you process Excel files"
|
||||
- **Avoid:** "You can use this to process Excel files"
|
||||
|
||||
**Be specific and include key terms:**
|
||||
|
||||
```yaml
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Avoid vague descriptions:**
|
||||
|
||||
```yaml
|
||||
description: Helps with documents # Too vague!
|
||||
```
|
||||
|
||||
## Complete Example: Commit Message Generator
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: generating-commit-messages
|
||||
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
# Generating Commit Messages
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Run `git diff --staged` to see changes
|
||||
2. I'll suggest a commit message with:
|
||||
- Summary under 50 characters
|
||||
- Detailed description
|
||||
- Affected components
|
||||
|
||||
## Best practices
|
||||
|
||||
- Use present tense
|
||||
- Explain what and why, not how
|
||||
Research $ARGUMENTS thoroughly...
|
||||
```
|
||||
|
||||
## Complete Example: Code Explanation Skill
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: explaining-code
|
||||
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
|
||||
---
|
||||
|
||||
# Explaining Code
|
||||
|
||||
When explaining code, always include:
|
||||
|
||||
1. **Start with an analogy**: Compare the code to something from everyday life
|
||||
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
|
||||
3. **Walk through the code**: Explain step-by-step what happens
|
||||
4. **Highlight a gotcha**: What's a common misconception?
|
||||
|
||||
Keep explanations conversational. For complex concepts, use multiple analogies.
|
||||
```
|
||||
The skill content becomes the subagent's prompt. It won't have access to conversation history.
|
||||
|
||||
## Distribution
|
||||
|
||||
- **Project Skills**: Commit `.claude/skills/` to version control
|
||||
- **Plugins**: Add `skills/` directory to plugin with Skill folders
|
||||
- **Project skills**: Commit `.claude/skills/` to version control
|
||||
- **Plugins**: Add `skills/` directory to plugin
|
||||
- **Enterprise**: Deploy organization-wide through managed settings
|
||||
|
||||
@@ -1,372 +1,152 @@
|
||||
<overview>
|
||||
Skills have three structural components: YAML frontmatter (metadata), pure XML body structure (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
|
||||
</overview>
|
||||
# Skill Structure Reference
|
||||
|
||||
<xml_structure_requirements>
|
||||
<critical_rule>
|
||||
**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
|
||||
</critical_rule>
|
||||
Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).
|
||||
|
||||
<required_tags>
|
||||
Every skill MUST have these three tags:
|
||||
## Body Format
|
||||
|
||||
- **`<objective>`** - What the skill does and why it matters (1-3 paragraphs)
|
||||
- **`<quick_start>`** - Immediate, actionable guidance (minimal working example)
|
||||
- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
|
||||
</required_tags>
|
||||
Use **standard markdown headings** for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
|
||||
|
||||
<conditional_tags>
|
||||
Add based on skill complexity and domain requirements:
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What it does and when to use it
|
||||
---
|
||||
|
||||
- **`<context>`** - Background/situational information
|
||||
- **`<workflow>` or `<process>`** - Step-by-step procedures
|
||||
- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
|
||||
- **`<validation>`** - How to verify outputs
|
||||
- **`<examples>`** - Multi-shot learning
|
||||
- **`<anti_patterns>`** - Common mistakes to avoid
|
||||
- **`<security_checklist>`** - Non-negotiable security patterns
|
||||
- **`<testing>`** - Testing workflows
|
||||
- **`<common_patterns>`** - Code examples and recipes
|
||||
- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
|
||||
# Skill Name
|
||||
|
||||
See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag.
|
||||
</conditional_tags>
|
||||
## Quick Start
|
||||
Immediate actionable guidance...
|
||||
|
||||
<tag_selection_intelligence>
|
||||
**Simple skills** (single domain, straightforward):
|
||||
- Required tags only
|
||||
- Example: Text extraction, file format conversion
|
||||
## Instructions
|
||||
Step-by-step procedures...
|
||||
|
||||
**Medium skills** (multiple patterns, some complexity):
|
||||
- Required tags + workflow/examples as needed
|
||||
- Example: Document processing with steps, API integration
|
||||
## Examples
|
||||
Concrete usage examples...
|
||||
|
||||
**Complex skills** (multiple domains, security, APIs):
|
||||
- Required tags + conditional tags as appropriate
|
||||
- Example: Payment processing, authentication systems, multi-step workflows
|
||||
</tag_selection_intelligence>
|
||||
|
||||
<xml_nesting>
|
||||
Properly nest XML tags for hierarchical content:
|
||||
|
||||
```xml
|
||||
<examples>
|
||||
<example number="1">
|
||||
<input>User input</input>
|
||||
<output>Expected output</output>
|
||||
</example>
|
||||
</examples>
|
||||
## Guidelines
|
||||
Rules and constraints...
|
||||
```
|
||||
|
||||
Always close tags:
|
||||
```xml
|
||||
<objective>
|
||||
Content here
|
||||
</objective>
|
||||
```
|
||||
</xml_nesting>
|
||||
## Recommended Sections
|
||||
|
||||
<tag_naming_conventions>
|
||||
Use descriptive, semantic names:
|
||||
- `<workflow>` not `<steps>`
|
||||
- `<success_criteria>` not `<done>`
|
||||
- `<anti_patterns>` not `<dont_do>`
|
||||
Every skill should have:
|
||||
|
||||
Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose (unless they serve different roles).
|
||||
</tag_naming_conventions>
|
||||
</xml_structure_requirements>
|
||||
- **Quick Start** - Immediate, actionable guidance (minimal working example)
|
||||
- **Instructions** - Core step-by-step guidance
|
||||
- **Success Criteria** - How to know it worked
|
||||
|
||||
Add based on complexity:
|
||||
|
||||
- **Context** - Background/situational information
|
||||
- **Workflow** - Multi-step procedures
|
||||
- **Examples** - Concrete input/output pairs
|
||||
- **Advanced Features** - Deep-dive topics (link to reference files)
|
||||
- **Anti-Patterns** - Common mistakes to avoid
|
||||
- **Guidelines** - Rules and constraints
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
### Required/Recommended Fields
|
||||
|
||||
<yaml_requirements>
|
||||
<required_fields>
|
||||
```yaml
|
||||
---
|
||||
name: skill-name-here
|
||||
description: What it does and when to use it (third person, specific triggers)
|
||||
description: What it does and when to use it (specific triggers included)
|
||||
---
|
||||
```
|
||||
</required_fields>
|
||||
|
||||
<name_field>
|
||||
**Validation rules**:
|
||||
### Name Field
|
||||
|
||||
**Validation rules:**
|
||||
- Maximum 64 characters
|
||||
- Lowercase letters, numbers, hyphens only
|
||||
- No XML tags
|
||||
- Must match directory name
|
||||
- No reserved words: "anthropic", "claude"
|
||||
- Must match directory name exactly
|
||||
|
||||
**Examples**:
|
||||
- ✅ `process-pdfs`
|
||||
- ✅ `manage-facebook-ads`
|
||||
- ✅ `setup-stripe-payments`
|
||||
- ❌ `PDF_Processor` (uppercase)
|
||||
- ❌ `helper` (vague)
|
||||
- ❌ `claude-helper` (reserved word)
|
||||
</name_field>
|
||||
**Examples:**
|
||||
- `triage-prs`
|
||||
- `deploy-production`
|
||||
- `review-code`
|
||||
- `setup-stripe-payments`
|
||||
|
||||
<description_field>
|
||||
**Validation rules**:
|
||||
- Non-empty, maximum 1024 characters
|
||||
- No XML tags
|
||||
- Third person (never first or second person)
|
||||
**Avoid:** `helper`, `utils`, `tools`, generic names
|
||||
|
||||
### Description Field
|
||||
|
||||
**Validation rules:**
|
||||
- Maximum 1024 characters
|
||||
- Include what it does AND when to use it
|
||||
- Third person voice
|
||||
|
||||
**Critical rule**: Always write in third person.
|
||||
- ✅ "Processes Excel files and generates reports"
|
||||
- ❌ "I can help you process Excel files"
|
||||
- ❌ "You can use this to process Excel files"
|
||||
|
||||
**Structure**: Include both capabilities and triggers.
|
||||
|
||||
**Effective examples**:
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
|
||||
```
|
||||
|
||||
**Avoid**:
|
||||
**Bad:**
|
||||
```yaml
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Processes data
|
||||
### Optional Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `argument-hint` | Usage hints. Example: `[issue-number]` |
|
||||
| `disable-model-invocation` | `true` to prevent auto-loading. Use for side-effect workflows. |
|
||||
| `user-invocable` | `false` to hide from `/` menu. Use for background knowledge. |
|
||||
| `allowed-tools` | Tools without permission prompts. Example: `Read, Bash(git *)` |
|
||||
| `model` | `haiku`, `sonnet`, or `opus` |
|
||||
| `context` | `fork` for isolated subagent execution |
|
||||
| `agent` | Subagent type: `Explore`, `Plan`, `general-purpose`, or custom |
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
Use descriptive names that indicate purpose:
|
||||
|
||||
| Pattern | Examples |
|
||||
|---------|----------|
|
||||
| Action-oriented | `triage-prs`, `deploy-production`, `review-code` |
|
||||
| Domain-specific | `setup-stripe-payments`, `manage-facebook-ads` |
|
||||
| Descriptive | `git-worktree`, `frontend-design`, `dhh-rails-style` |
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Split into reference files:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Entry point (required, overview + navigation)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples (loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
</description_field>
|
||||
</yaml_requirements>
|
||||
|
||||
<naming_conventions>
|
||||
Use **verb-noun convention** for skill names:
|
||||
|
||||
<pattern name="create">
|
||||
Building/authoring tools
|
||||
|
||||
Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
|
||||
</pattern>
|
||||
|
||||
<pattern name="manage">
|
||||
Managing external services or resources
|
||||
|
||||
Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
|
||||
</pattern>
|
||||
|
||||
<pattern name="setup">
|
||||
Configuration/integration tasks
|
||||
|
||||
Examples: `setup-stripe-payments`, `setup-meta-tracking`
|
||||
</pattern>
|
||||
|
||||
<pattern name="generate">
|
||||
Generation tasks
|
||||
|
||||
Examples: `generate-ai-images`
|
||||
</pattern>
|
||||
|
||||
<avoid_patterns>
|
||||
- Vague: `helper`, `utils`, `tools`
|
||||
- Generic: `documents`, `data`, `files`
|
||||
- Reserved words: `anthropic-helper`, `claude-tools`
|
||||
- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
|
||||
</avoid_patterns>
|
||||
</naming_conventions>
|
||||
|
||||
<progressive_disclosure>
|
||||
<principle>
|
||||
SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
|
||||
</principle>
|
||||
|
||||
<practical_guidance>
|
||||
- Keep SKILL.md body under 500 lines
|
||||
- Split content into separate files when approaching this limit
|
||||
**Rules:**
|
||||
- Keep references one level deep from SKILL.md
|
||||
- Add table of contents to reference files over 100 lines
|
||||
</practical_guidance>
|
||||
- Use forward slashes in paths: `scripts/helper.py`
|
||||
- Name files descriptively: `form_validation_rules.md` not `doc2.md`
|
||||
|
||||
<pattern name="high_level_guide">
|
||||
Quick start in SKILL.md, details in reference files:
|
||||
## Validation Checklist
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
---
|
||||
Before finalizing:
|
||||
|
||||
<objective>
|
||||
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
|
||||
</objective>
|
||||
- [ ] YAML frontmatter valid (name matches directory, description specific)
|
||||
- [ ] Uses standard markdown headings (not XML tags)
|
||||
- [ ] Has Quick Start, Instructions, and Success Criteria sections
|
||||
- [ ] `disable-model-invocation: true` if skill has side effects
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] Reference files linked properly from SKILL.md
|
||||
- [ ] File paths use forward slashes
|
||||
- [ ] Tested with real usage
|
||||
|
||||
<quick_start>
|
||||
Extract text with pdfplumber:
|
||||
## Anti-Patterns
|
||||
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("file.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
```
|
||||
</quick_start>
|
||||
|
||||
<advanced_features>
|
||||
**Form filling**: See [forms.md](forms.md)
|
||||
**API reference**: See [reference.md](reference.md)
|
||||
</advanced_features>
|
||||
```
|
||||
|
||||
Claude loads forms.md or reference.md only when needed.
|
||||
</pattern>
|
||||
|
||||
<pattern name="domain_organization">
|
||||
For skills with multiple domains, organize by domain to avoid loading irrelevant context:
|
||||
|
||||
```
|
||||
bigquery-skill/
|
||||
├── SKILL.md (overview and navigation)
|
||||
└── reference/
|
||||
├── finance.md (revenue, billing metrics)
|
||||
├── sales.md (opportunities, pipeline)
|
||||
├── product.md (API usage, features)
|
||||
└── marketing.md (campaigns, attribution)
|
||||
```
|
||||
|
||||
When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
|
||||
</pattern>
|
||||
|
||||
<pattern name="conditional_details">
|
||||
Show basic content in SKILL.md, link to advanced in reference files:
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
Process DOCX files with creation and editing capabilities.
|
||||
</objective>
|
||||
|
||||
<quick_start>
|
||||
<creating_documents>
|
||||
Use docx-js for new documents. See [docx-js.md](docx-js.md).
|
||||
</creating_documents>
|
||||
|
||||
<editing_documents>
|
||||
For simple edits, modify XML directly.
|
||||
|
||||
**For tracked changes**: See [redlining.md](redlining.md)
|
||||
**For OOXML details**: See [ooxml.md](ooxml.md)
|
||||
</editing_documents>
|
||||
</quick_start>
|
||||
```
|
||||
|
||||
Claude reads redlining.md or ooxml.md only when the user needs those features.
|
||||
</pattern>
|
||||
|
||||
<critical_rules>
|
||||
**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md → advanced.md → details.md) as Claude may only partially read deeply nested files.
|
||||
|
||||
**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
|
||||
|
||||
**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
|
||||
</critical_rules>
|
||||
</progressive_disclosure>
|
||||
|
||||
<file_organization>
|
||||
<filesystem_navigation>
|
||||
Claude navigates your skill directory using bash commands:
|
||||
|
||||
- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
|
||||
- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
|
||||
- Organize by domain: `reference/finance.md`, `reference/sales.md`
|
||||
</filesystem_navigation>
|
||||
|
||||
<directory_structure>
|
||||
Typical skill structure:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (main entry point, pure XML structure)
|
||||
├── references/ (optional, for progressive disclosure)
|
||||
│ ├── guide-1.md (pure XML structure)
|
||||
│ ├── guide-2.md (pure XML structure)
|
||||
│ └── examples.md (pure XML structure)
|
||||
└── scripts/ (optional, for utility scripts)
|
||||
├── validate.py
|
||||
└── process.py
|
||||
```
|
||||
</directory_structure>
|
||||
</file_organization>
|
||||
|
||||
<anti_patterns>
|
||||
<pitfall name="markdown_headings_in_body">
|
||||
❌ Do NOT use markdown headings in skill body:
|
||||
|
||||
```markdown
|
||||
# PDF Processing
|
||||
|
||||
## Quick start
|
||||
Extract text...
|
||||
|
||||
## Advanced features
|
||||
Form filling...
|
||||
```
|
||||
|
||||
✅ Use pure XML structure:
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
PDF processing with text extraction, form filling, and merging.
|
||||
</objective>
|
||||
|
||||
<quick_start>
|
||||
Extract text...
|
||||
</quick_start>
|
||||
|
||||
<advanced_features>
|
||||
Form filling...
|
||||
</advanced_features>
|
||||
```
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="vague_descriptions">
|
||||
- ❌ "Helps with documents"
|
||||
- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="inconsistent_pov">
|
||||
- ❌ "I can help you process Excel files"
|
||||
- ✅ "Processes Excel files and generates reports"
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="wrong_naming_convention">
|
||||
- ❌ Directory: `facebook-ads`, Name: `facebook-ads-manager`
|
||||
- ✅ Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
|
||||
- ❌ Directory: `stripe-integration`, Name: `stripe`
|
||||
- ✅ Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="deeply_nested_references">
|
||||
Keep references one level deep from SKILL.md. Claude may only partially read nested files (SKILL.md → advanced.md → details.md).
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="windows_paths">
|
||||
Always use forward slashes: `scripts/helper.py` (not `scripts\helper.py`)
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="missing_required_tags">
|
||||
Every skill must have: `<objective>`, `<quick_start>`, and `<success_criteria>` (or `<when_successful>`).
|
||||
</pitfall>
|
||||
</anti_patterns>
|
||||
|
||||
<validation_checklist>
|
||||
Before finalizing a skill, verify:
|
||||
|
||||
- ✅ YAML frontmatter valid (name matches directory, description in third person)
|
||||
- ✅ No markdown headings in body (pure XML structure)
|
||||
- ✅ Required tags present: objective, quick_start, success_criteria
|
||||
- ✅ Conditional tags appropriate for complexity level
|
||||
- ✅ All XML tags properly closed
|
||||
- ✅ Progressive disclosure applied (SKILL.md < 500 lines)
|
||||
- ✅ Reference files use pure XML structure
|
||||
- ✅ File paths use forward slashes
|
||||
- ✅ Descriptive file names
|
||||
</validation_checklist>
|
||||
- **XML tags in body** - Use standard markdown headings
|
||||
- **Vague descriptions** - Be specific with trigger keywords
|
||||
- **Deep nesting** - Keep references one level from SKILL.md
|
||||
- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
|
||||
- **Inconsistent naming** - Directory name must match `name` field
|
||||
- **Windows paths** - Always use forward slashes
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: file-todos
|
||||
description: This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# File-Based Todo Tracking Skill
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: orchestrating-swarms
|
||||
description: This skill should be used when orchestrating multi-agent swarms using Claude Code's TeammateTool and Task system. It applies when coordinating multiple agents, running parallel code reviews, creating pipeline workflows with dependencies, building self-organizing task queues, or any task benefiting from divide-and-conquer patterns.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Claude Code Swarm Orchestration
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: resolve_pr_parallel
|
||||
description: Resolve all PR comments using parallel processing. Use when addressing PR review feedback, resolving review threads, or batch-fixing PR comments.
|
||||
argument-hint: "[optional: PR number or current PR]"
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Bash(git *), Read
|
||||
---
|
||||
|
||||
# Resolve PR Comments in Parallel
|
||||
|
||||
Resolve all unresolved PR review comments by spawning parallel agents for each thread.
|
||||
|
||||
## Context Detection
|
||||
|
||||
Claude Code automatically detects git context:
|
||||
- Current branch and associated PR
|
||||
- All PR comments and review threads
|
||||
- Works with any PR by specifying the number
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Fetch unresolved review threads using the GraphQL script:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
|
||||
```
|
||||
|
||||
This returns only **unresolved, non-outdated** threads with file paths, line numbers, and comment bodies.
|
||||
|
||||
If the script fails, fall back to:
|
||||
```bash
|
||||
gh pr view PR_NUMBER --json reviews,comments
|
||||
gh api repos/{owner}/{repo}/pulls/PR_NUMBER/comments
|
||||
```
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a TodoWrite list of all unresolved items grouped by type:
|
||||
- Code changes requested
|
||||
- Questions to answer
|
||||
- Style/convention fixes
|
||||
- Test additions needed
|
||||
|
||||
### 3. Implement (PARALLEL)
|
||||
|
||||
Spawn a `pr-comment-resolver` agent for each unresolved item in parallel.
|
||||
|
||||
If there are 3 comments, spawn 3 agents:
|
||||
|
||||
1. Task pr-comment-resolver(comment1)
|
||||
2. Task pr-comment-resolver(comment2)
|
||||
3. Task pr-comment-resolver(comment3)
|
||||
|
||||
Always run all in parallel subagents/Tasks for each Todo item.
|
||||
|
||||
### 4. Commit & Resolve
|
||||
|
||||
- Commit changes with a clear message referencing the PR feedback
|
||||
- Resolve each thread programmatically:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/resolve-pr-thread THREAD_ID
|
||||
```
|
||||
|
||||
- Push to remote
|
||||
|
||||
### 5. Verify
|
||||
|
||||
Re-fetch comments to confirm all threads are resolved:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
|
||||
```
|
||||
|
||||
Should return an empty array `[]`. If threads remain, repeat from step 1.
|
||||
|
||||
## Scripts
|
||||
|
||||
- [scripts/get-pr-comments](scripts/get-pr-comments) - GraphQL query for unresolved review threads
|
||||
- [scripts/resolve-pr-thread](scripts/resolve-pr-thread) - GraphQL mutation to resolve a thread by ID
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- All unresolved review threads addressed
|
||||
- Changes committed and pushed
|
||||
- Threads resolved via GraphQL (marked as resolved on GitHub)
|
||||
- Empty result from get-pr-comments on verify
|
||||
@@ -0,0 +1,68 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -e
|
||||
|
||||
if [ $# -lt 1 ]; then
|
||||
echo "Usage: get-pr-comments PR_NUMBER [OWNER/REPO]"
|
||||
echo "Example: get-pr-comments 123"
|
||||
echo "Example: get-pr-comments 123 EveryInc/cora"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
PR_NUMBER=$1
|
||||
|
||||
if [ -n "$2" ]; then
|
||||
OWNER=$(echo "$2" | cut -d/ -f1)
|
||||
REPO=$(echo "$2" | cut -d/ -f2)
|
||||
else
|
||||
OWNER=$(gh repo view --json owner -q .owner.login 2>/dev/null)
|
||||
REPO=$(gh repo view --json name -q .name 2>/dev/null)
|
||||
fi
|
||||
|
||||
if [ -z "$OWNER" ] || [ -z "$REPO" ]; then
|
||||
echo "Error: Could not detect repository. Pass OWNER/REPO as second argument."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
gh api graphql -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" -f query='
|
||||
query FetchUnresolvedComments($owner: String!, $repo: String!, $pr: Int!) {
|
||||
repository(owner: $owner, name: $repo) {
|
||||
pullRequest(number: $pr) {
|
||||
title
|
||||
url
|
||||
reviewThreads(first: 100) {
|
||||
totalCount
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
isResolved
|
||||
isOutdated
|
||||
isCollapsed
|
||||
path
|
||||
line
|
||||
startLine
|
||||
diffSide
|
||||
comments(first: 100) {
|
||||
totalCount
|
||||
nodes {
|
||||
id
|
||||
author {
|
||||
login
|
||||
}
|
||||
body
|
||||
createdAt
|
||||
updatedAt
|
||||
url
|
||||
outdated
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
pageInfo {
|
||||
hasNextPage
|
||||
endCursor
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}' | jq '.data.repository.pullRequest.reviewThreads.edges | map(select(.node.isResolved == false and .node.isOutdated == false))'
|
||||
@@ -0,0 +1,23 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -e
|
||||
|
||||
if [ $# -eq 0 ]; then
|
||||
echo "Usage: resolve-pr-thread THREAD_ID"
|
||||
echo "Example: resolve-pr-thread PRRT_kwDOABC123"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
THREAD_ID=$1
|
||||
|
||||
gh api graphql -f threadId="$THREAD_ID" -f query='
|
||||
mutation ResolveReviewThread($threadId: ID!) {
|
||||
resolveReviewThread(input: {threadId: $threadId}) {
|
||||
thread {
|
||||
id
|
||||
isResolved
|
||||
path
|
||||
line
|
||||
}
|
||||
}
|
||||
}'
|
||||
@@ -2,6 +2,7 @@
|
||||
name: skill-creator
|
||||
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
|
||||
license: Complete terms in LICENSE.txt
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
@@ -19,7 +19,8 @@ export function convertClaudeToCodex(
|
||||
|
||||
const usedSkillNames = new Set<string>(skillDirs.map((skill) => normalizeName(skill.name)))
|
||||
const commandSkills: CodexGeneratedSkill[] = []
|
||||
const prompts = plugin.commands.map((command) => {
|
||||
const invocableCommands = plugin.commands.filter((command) => !command.disableModelInvocation)
|
||||
const prompts = invocableCommands.map((command) => {
|
||||
const promptName = uniqueName(normalizeName(command.name), promptNames)
|
||||
const commandSkill = convertCommandSkill(command, usedSkillNames)
|
||||
commandSkills.push(commandSkill)
|
||||
|
||||
@@ -114,6 +114,7 @@ function convertAgent(agent: ClaudeAgent, options: ClaudeToOpenCodeOptions) {
|
||||
function convertCommands(commands: ClaudeCommand[]): Record<string, OpenCodeCommandConfig> {
|
||||
const result: Record<string, OpenCodeCommandConfig> = {}
|
||||
for (const command of commands) {
|
||||
if (command.disableModelInvocation) continue
|
||||
const entry: OpenCodeCommandConfig = {
|
||||
description: command.description,
|
||||
template: command.body,
|
||||
|
||||
@@ -83,12 +83,14 @@ async function loadCommands(commandsDirs: string[]): Promise<ClaudeCommand[]> {
|
||||
const { data, body } = parseFrontmatter(raw)
|
||||
const name = (data.name as string) ?? path.basename(file, ".md")
|
||||
const allowedTools = parseAllowedTools(data["allowed-tools"])
|
||||
const disableModelInvocation = data["disable-model-invocation"] === true ? true : undefined
|
||||
commands.push({
|
||||
name,
|
||||
description: data.description as string | undefined,
|
||||
argumentHint: data["argument-hint"] as string | undefined,
|
||||
model: data.model as string | undefined,
|
||||
allowedTools,
|
||||
disableModelInvocation,
|
||||
body: body.trim(),
|
||||
sourcePath: file,
|
||||
})
|
||||
@@ -104,9 +106,11 @@ async function loadSkills(skillsDirs: string[]): Promise<ClaudeSkill[]> {
|
||||
const raw = await readText(file)
|
||||
const { data } = parseFrontmatter(raw)
|
||||
const name = (data.name as string) ?? path.basename(path.dirname(file))
|
||||
const disableModelInvocation = data["disable-model-invocation"] === true ? true : undefined
|
||||
skills.push({
|
||||
name,
|
||||
description: data.description as string | undefined,
|
||||
disableModelInvocation,
|
||||
sourceDir: path.dirname(file),
|
||||
skillPath: file,
|
||||
})
|
||||
|
||||
@@ -39,6 +39,7 @@ export type ClaudeCommand = {
|
||||
argumentHint?: string
|
||||
model?: string
|
||||
allowedTools?: string[]
|
||||
disableModelInvocation?: boolean
|
||||
body: string
|
||||
sourcePath: string
|
||||
}
|
||||
@@ -46,6 +47,7 @@ export type ClaudeCommand = {
|
||||
export type ClaudeSkill = {
|
||||
name: string
|
||||
description?: string
|
||||
disableModelInvocation?: boolean
|
||||
sourceDir: string
|
||||
skillPath: string
|
||||
}
|
||||
|
||||
@@ -15,8 +15,8 @@ describe("loadClaudePlugin", () => {
|
||||
|
||||
expect(plugin.manifest.name).toBe("compound-engineering")
|
||||
expect(plugin.agents.length).toBe(2)
|
||||
expect(plugin.commands.length).toBe(6)
|
||||
expect(plugin.skills.length).toBe(1)
|
||||
expect(plugin.commands.length).toBe(7)
|
||||
expect(plugin.skills.length).toBe(2)
|
||||
expect(plugin.hooks).toBeDefined()
|
||||
expect(plugin.mcpServers).toBeDefined()
|
||||
|
||||
@@ -55,6 +55,28 @@ describe("loadClaudePlugin", () => {
|
||||
expect(plugin.mcpServers?.context7?.url).toBe("https://mcp.context7.com/mcp")
|
||||
})
|
||||
|
||||
test("parses disable-model-invocation from commands", async () => {
|
||||
const plugin = await loadClaudePlugin(fixtureRoot)
|
||||
|
||||
const disabledCommand = plugin.commands.find((command) => command.name === "deploy-docs")
|
||||
expect(disabledCommand).toBeDefined()
|
||||
expect(disabledCommand?.disableModelInvocation).toBe(true)
|
||||
|
||||
const normalCommand = plugin.commands.find((command) => command.name === "workflows:review")
|
||||
expect(normalCommand?.disableModelInvocation).toBeUndefined()
|
||||
})
|
||||
|
||||
test("parses disable-model-invocation from skills", async () => {
|
||||
const plugin = await loadClaudePlugin(fixtureRoot)
|
||||
|
||||
const disabledSkill = plugin.skills.find((skill) => skill.name === "disabled-skill")
|
||||
expect(disabledSkill).toBeDefined()
|
||||
expect(disabledSkill?.disableModelInvocation).toBe(true)
|
||||
|
||||
const normalSkill = plugin.skills.find((skill) => skill.name === "skill-one")
|
||||
expect(normalSkill?.disableModelInvocation).toBeUndefined()
|
||||
})
|
||||
|
||||
test("loads MCP servers from .mcp.json when manifest is empty", async () => {
|
||||
const plugin = await loadClaudePlugin(mcpFixtureRoot)
|
||||
expect(plugin.mcpServers?.remote?.url).toBe("https://example.com/stream")
|
||||
|
||||
@@ -172,6 +172,44 @@ Don't confuse with file paths like /tmp/output.md or /dev/null.`,
|
||||
expect(parsed.body).toContain("/dev/null")
|
||||
})
|
||||
|
||||
test("excludes commands with disable-model-invocation from prompts and skills", () => {
|
||||
const plugin: ClaudePlugin = {
|
||||
...fixturePlugin,
|
||||
commands: [
|
||||
{
|
||||
name: "normal-command",
|
||||
description: "Normal command",
|
||||
body: "Normal body.",
|
||||
sourcePath: "/tmp/plugin/commands/normal.md",
|
||||
},
|
||||
{
|
||||
name: "disabled-command",
|
||||
description: "Disabled command",
|
||||
disableModelInvocation: true,
|
||||
body: "Disabled body.",
|
||||
sourcePath: "/tmp/plugin/commands/disabled.md",
|
||||
},
|
||||
],
|
||||
agents: [],
|
||||
skills: [],
|
||||
}
|
||||
|
||||
const bundle = convertClaudeToCodex(plugin, {
|
||||
agentMode: "subagent",
|
||||
inferTemperature: false,
|
||||
permissions: "none",
|
||||
})
|
||||
|
||||
// Only normal command should produce a prompt
|
||||
expect(bundle.prompts).toHaveLength(1)
|
||||
expect(bundle.prompts[0].name).toBe("normal-command")
|
||||
|
||||
// Only normal command should produce a generated skill
|
||||
const commandSkills = bundle.generatedSkills.filter((s) => s.name === "normal-command" || s.name === "disabled-command")
|
||||
expect(commandSkills).toHaveLength(1)
|
||||
expect(commandSkills[0].name).toBe("normal-command")
|
||||
})
|
||||
|
||||
test("truncates generated skill descriptions to Codex limits and single line", () => {
|
||||
const longDescription = `Line one\nLine two ${"a".repeat(2000)}`
|
||||
const plugin: ClaudePlugin = {
|
||||
|
||||
@@ -168,4 +168,19 @@ describe("convertClaudeToOpenCode", () => {
|
||||
const parsed = parseFrontmatter(agentFile!.content)
|
||||
expect(parsed.data.mode).toBe("primary")
|
||||
})
|
||||
|
||||
test("excludes commands with disable-model-invocation from command map", async () => {
|
||||
const plugin = await loadClaudePlugin(fixtureRoot)
|
||||
const bundle = convertClaudeToOpenCode(plugin, {
|
||||
agentMode: "subagent",
|
||||
inferTemperature: false,
|
||||
permissions: "none",
|
||||
})
|
||||
|
||||
// deploy-docs has disable-model-invocation: true, should be excluded
|
||||
expect(bundle.config.command?.["deploy-docs"]).toBeUndefined()
|
||||
|
||||
// Normal commands should still be present
|
||||
expect(bundle.config.command?.["workflows:review"]).toBeDefined()
|
||||
})
|
||||
})
|
||||
|
||||
7
tests/fixtures/sample-plugin/commands/disabled-command.md
vendored
Normal file
7
tests/fixtures/sample-plugin/commands/disabled-command.md
vendored
Normal file
@@ -0,0 +1,7 @@
|
||||
---
|
||||
name: deploy-docs
|
||||
description: Deploy documentation site
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Deploy docs body.
|
||||
7
tests/fixtures/sample-plugin/skills/disabled-skill/SKILL.md
vendored
Normal file
7
tests/fixtures/sample-plugin/skills/disabled-skill/SKILL.md
vendored
Normal file
@@ -0,0 +1,7 @@
|
||||
---
|
||||
name: disabled-skill
|
||||
description: A skill with model invocation disabled
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Disabled skill body.
|
||||
Reference in New Issue
Block a user