# skill-scout

> A Claude Code skill from Affaan M's everything-claude-code repo that searches local, marketplace, GitHub, and web sources for existing skills before creating a new one. Six-step workflow — capture intent, search local first, then remote, vet external matches for unexpected shell / file / network behavior, rank, present a use-existing / fork / create-fresh decision table.

**Use case**: Search before creating — don't author a skill that already exists, don't install one you haven't read

**Canonical URL**: https://agentcookbooks.com/skills/skill-scout/

**Topics**: claude-code, skills, skill-development

**Trigger phrases**: "is there a skill for this workflow", "find a skill before I create one", "what existing skills cover release notes"

**Source**: [Affaan M](https://github.com/affaan-m/everything-claude-code/tree/main/skills/skill-scout)

**License**: MIT

---

## What it does

`skill-scout` is the pre-create search skill in [Affaan M's everything-claude-code](https://github.com/affaan-m/everything-claude-code) — see [skills/skill-scout](https://github.com/affaan-m/everything-claude-code/tree/main/skills/skill-scout). It runs a six-step workflow before any new skill gets created: capture intent (task, triggers, domain, 3–5 keywords + synonyms), search local sources first (`~/.claude/skills/`, marketplace skills), then remote (`gh search repos`, `gh search code` filtered to `SKILL.md`), then vet external matches by reading the frontmatter and looking for unexpected shell commands, file writes, network calls, or credential handling.

The ranking is explicit: exact keyword match in skill name, then keyword/synonym match in description, then local installed or marketplace source, then maintained GitHub source with recent activity, web-only mentions last. The cap is 10 results. Presentation is a decision table — Use existing (invoke or install as-is) / Fork or extend (copy the closest and modify) / Create fresh (only after confirming no close match). New skills only get created after the user picks that path or the search finds no close match.

Anti-patterns called out: jumping to new-skill creation without searching, installing external skills without reading them, presenting long unranked weak-match lists, treating web-only mentions as trusted, editing installed marketplace originals in place. The "prefer copying into a fresh local branch and reviewing the diff" rule keeps marketplace originals clean and gives the vet step a real diff to review.

## When to use it

- User says "create a skill", "build a skill", "make a skill" or "new skill" — the trigger before authoring
- User asks "is there a skill for X?" or "does a skill exist that does Y?"
- Operator describes a workflow and the next step would be authoring — search first
- Considering forking or extending an existing skill — pull the closest first, diff before editing
- Auditing whether a new requested capability is actually a gap in the existing skill set or just an unfamiliar one

When *not* to reach for it:

- The user explicitly said "skip search, create from scratch" — acknowledge and proceed
- Auditing the *existing* installed skills — that's `skill-stocktake`
- Authoring the new skill itself — that's a separate authoring skill
- Quick "does X exist" checks on a brand-new domain — overhead exceeds value

## Install

From [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) at `skills/skill-scout/`. Drop the folder into `~/.claude/skills/skill-scout/`. The skill is markdown — runtime is `find`, `grep`, the `gh` CLI for GitHub search, and WebSearch for web mentions. No extra MCP server needed. Salvaged from a stale community PR (the upstream notes attribution); the version in this repo keeps the workflow and removes anything unmaintained.

## What a session looks like

1. **Capture intent.** "I want a skill that generates release notes from merged PRs." Task = release notes from PRs. Keywords = `release-notes`, `changelog`, synonyms = `pr-summary`, `merge-log`.
2. **Search local first.** `find ~/.claude/skills -maxdepth 2 -name SKILL.md | grep -iE "release|changelog"`. Finds two close matches: `article-writing` (general drafting) and `content-engine` (multi-format).
3. **Search remote.** `gh search code "name: release" --filename SKILL.md --limit 10` and a couple of focused web queries (`"claude code skill" release notes`).
4. **Vet external matches.** Open the top remote candidate's frontmatter and body. Look for unexpected shell commands, file writes outside `~/.claude/skills/`, network calls, credential references. If clean, mark as adoptable; otherwise drop it.
5. **Rank.** Exact name match in `release-notes-generator` (external, recently maintained) > local `article-writing` (general) > local `content-engine` (heavy).
6. **Present the decision table.** Use-existing for the external if vetted; Fork-or-extend the local `article-writing` if the external is risky; Create-fresh only if both paths fail.
7. **Operator picks.** Skill exits if the user picks "use existing" or "fork." Only on "create fresh" does the next skill (the authoring one) take over.

The discipline that makes it work: vet before adopt. The skill is explicit — don't install external skills without reading them, and prefer a fresh local branch + diff over editing marketplace originals in place. The ranking pushes web-only mentions to the bottom so they're never the default recommendation.

## Receipts

_TODO — to be filled in from a real session. Once the skill has been used to scout for a real new-skill request, this section will capture: which source (local / marketplace / GitHub / web) produced the best match for the operator's actual workflow, what the vet step found in the highest-ranked external candidate (clean / suspicious / blocked), whether the decision-table format produced a clear pick or required more iteration, and whether the operator ended up adopting an existing skill, forking, or creating fresh._

## Source and attribution

From [Affaan M's everything-claude-code](https://github.com/affaan-m/everything-claude-code/tree/main/skills/skill-scout) — an MIT-licensed skill collection covering harness construction, agent ops, video, payments, and platform-specific patterns.

License: MIT.

Quoting the search-before-create rule verbatim: *"Only create a new skill after the user chooses that path or after the search finds no close match."* The default is "find what exists" — authoring is the fallback when adoption is genuinely impossible.