scout

name	scout
description	Search GitHub for new Claude Code skills, agents, patterns and create a PR with findings. Use this for weekly pattern discovery runs or when you want to find new AI engineering patterns.
allowed-tools	Bash, Read, Write, Edit, Grep, Glob, WebFetch, WebSearch

Scout — Claude Code Pattern Discovery

Search GitHub for new Claude Code patterns (agents, skills, hooks) relevant to this project. Evaluate, integrate useful findings, and create a PR.

Phase 1: Branch

cd /Users/pierrejonnycau/Documents/WORKS/agent-orchestrator
BRANCH="scout/$(date +%Y%m%d-%H%M%S)"
git checkout -b "$BRANCH"

Phase 2: Search GitHub

First, read the state file to know what we've already seen:

cat .claude/scout-state.json

Then run 2-3 search queries based on search_rotation_index (advance by 2-3 each run):

Query rotation (10 queries, cycle through):

Index	Query
0	gh search repos ".claude/agents" --sort updated --limit 10 --json fullName,description,updatedAt
1	gh search repos ".claude/skills" --sort updated --limit 10 --json fullName,description,updatedAt
2	gh search repos "claude code hooks" --sort updated --limit 10 --json fullName,description,updatedAt
3	gh search repos "CLAUDE.md agents skills" --sort updated --limit 10 --json fullName,description,updatedAt
4	gh search code "subagent_type" --language markdown --limit 10 --json repository,path
5	gh search code "claude/agents" filename:CLAUDE.md --limit 10 --json repository,path
6	WebSearch: "claude code agent skills best practices 2026"
7	WebSearch: "claude code multi-agent orchestration patterns"
8	WebSearch: "anthropic claude code provider agnostic architecture"
9	WebSearch: "claude code AI engineering skills hooks"

For each new repo (not in seen_repos):

gh api repos/{owner}/{repo}/contents/.claude 2>/dev/null | head -20
gh api repos/{owner}/{repo}/contents/.claude/agents 2>/dev/null
gh api repos/{owner}/{repo}/contents/.claude/skills 2>/dev/null
gh api repos/{owner}/{repo}/contents/CLAUDE.md --jq '.content' | base64 -d | head -100

Phase 3: Evaluate

For each finding, score on 4 criteria (0-1 each):

Criterion	0	0.5	1.0
Applicable	Unrelated domain	Generic dev pattern	Software/AI engineering
Novel	We already have this	Slight improvement	New capability
Quality	Undocumented snippet	Has README	Full skill with tests
Compatible	Requires different arch	Needs adaptation	Drop-in compatible

relevance = (applicable + novel + quality + compatible) / 4

Threshold: integrate if relevance > 0.5

Phase 4: Integrate (max 3 per run)

For each relevant finding, in order of relevance:

1. Identify what to create/update:

   • New skill -> .claude/skills/{name}/SKILL.md
   • New hook -> .claude/settings.json (add to existing hooks array)
   • Agent improvement -> .claude/agents/{name}.md
   • CLAUDE.md pattern -> CLAUDE.md (add section)

2. Adapt to project conventions:

   • All content in English
   • Follow existing YAML front matter format
   • Use project paths and tools
   • Keep consistent with anti-stall rules

3. Commit each integration separately:

   git add <files>
   git commit -m "Scout: integrate <pattern-name> from <source-repo>"
   

Phase 4.5: Update Documentation

After integrating patterns, update all project documentation to reflect changes:

1. CLAUDE.md — Update Skills Map table (count + new rows) if new skills were added
2. README.md — Update:
   • Test count (X tests) if tests changed
   • Skills/features mentions if applicable
   • Project structure tree if new files were added to src/ or .claude/skills/
3. docs/components.md — Update component diagrams if new core modules were added

# Check what needs updating
grep -n "Skills Map" CLAUDE.md
grep -n "tests" README.md

Commit docs updates separately:

git add CLAUDE.md README.md docs/components.md
git commit -m "Scout: update documentation with integrated patterns"

Phase 5: PR or Report

If >= 1 integration was committed:

git push -u origin "$BRANCH"
gh pr create --title "Scout: <summary>" --body "$(cat <<'EOF'
## Scout Report

### Findings
| Source | Pattern | Relevance | Action |
|--------|---------|-----------|--------|
| owner/repo | pattern-name | 0.75 | Integrated |

### Integrated Changes
- **<file>**: <description> (from <source>)

### Search Queries Used
- `query` -> N results, M new repos

Generated by Scout agent
EOF
)"

If nothing relevant found:

Update state file only (stay on main):

git checkout main
git branch -d "$BRANCH"

Edit .claude/scout-state.json: update last_run, add new repos to seen_repos, advance search_rotation_index.

State File

.claude/scout-state.json tracks progress across runs.