skills-scout

by @servaltullius in AI & LLM

# Install this skill:

npx skills add servaltullius/skills-scout

Or install specific skill: npx add-skill https://github.com/servaltullius/skills-scout

# Description

Use when a user wants you to discover and optionally install new agent skills for a task, and you must get explicit consent before any global install into Codex.

# SKILL.md

name: skills-scout
description: Use when a user wants you to discover and optionally install new agent skills for a task, and you must get explicit consent before any global install into Codex.

Skills Scout

Overview

Discover relevant skills from skills.sh and install them globally for Codex only after the user reviews options and explicitly approves installation.

Core principle: Search before building; ask before installing.

How this differs from `find-skills` (vercel-labs/skills)

There is an upstream skill that covers “how to use npx skills find”. skills-scout is intentionally stricter and Codex-focused:
- Adds hard‑mode vetting (repo metadata + risky command scan) before recommending installs.
- Enforces explicit consent gates and Codex global install defaults (-g -a codex).
- Optionally pins installed skills into the repo AGENTS.md so they’re actually visible per repo.

Reference: https://github.com/vercel-labs/skills/blob/main/skills/find-skills/SKILL.md

When to Use

Use this skill when the user:
- Asks “is there a skill for X?” / “find a skill for X”
- Mentions wanting to extend agent capabilities for the task
- Says “install whatever you need” but still expects transparency/consent
- Has a common task where a skill likely exists (testing, CI/CD, PR review, docs, deploy)

Do not use this skill when the user:
- Explicitly forbids installs or network access
- Only wants an explanation (no execution)

Workflow

0) Confirm constraints (Codex global install)

Install scope: global (-g)
Target agent: codex (-a codex)
Search scope: allow all (entire ecosystem), but vet credibility before recommending
Install count: unlimited, but never install without explicit consent

If the user wants the “project start” workflow to happen by default in new repos, recommend adding a small routine to their global ~/.codex/AGENTS.md (do not edit without consent):
- Preview (dry-run): node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo .
- Apply (write): node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo . --write

1) Check what’s already installed

npx -y skills ls -g -a codex
ls -la ~/.codex/skills

If a suitable skill is already installed, use it instead of installing duplicates.

1.5) Quick project scan (to refine search + compatibility)

Before searching, do a quick scan to identify the project’s stack so you don’t recommend irrelevant skills.

Look for:
- Language/runtime (Node/Python/Go/etc.)
- Package manager (pnpm/npm/yarn/bun)
- Framework (Next.js/React/Vite/etc.)
- CI system (GitHub Actions, etc.)

Example commands (keep it fast; don’t read secrets like .env):

ls
rg --files | rg -i '^(package\\.json|pnpm-lock\\.yaml|yarn\\.lock|package-lock\\.json|bun\\.lockb|bun\\.lock|next\\.config\\.|vite\\.config\\.|tsconfig\\.json|pyproject\\.toml|requirements\\.txt|go\\.mod|cargo\\.toml|dockerfile|docker-compose\\.|\\.github/workflows/)'

Use this context to:
- build a better query (e.g., “playwright e2e pnpm nextjs”)
- mark candidates Caution/Avoid if they assume the wrong stack (e.g., bun-only skill on a pnpm repo)

2) Search for candidate skills

Turn the user request into a short keyword query (2–6 words), then run:

npx -y skills find "<query>"

Never invent results. Always run the search and present the real output (or say “no skills found”).

Tip (clean output for copy/paste/notes):

npx -y skills find "<query>" | sed -r 's/\x1B\[[0-9;]*[mK]//g'

3) Vet candidates (credibility + risk)

Before recommending any skill for installation, do a quick credibility/risk pass. “Allow all” means search all, not trust all.

Hard mode (default): evidence before labels.
- Never claim “MIT”, “recent push”, “safe”, “maintained”, etc. unless you actually verified it.
- If you cannot verify key facts (license/activity/archived), treat it as unknown and classify as Caution or Avoid.

Credibility signals (prefer):
- Maintained repo (recent activity, not archived)
- Clear owner identity (org or known maintainer)
- License present
- Multiple users/adoption signals (stars/downloads/usage), where available
- Skill text is specific, not vague marketing
- Looks compatible with this repo’s stack (package manager/framework/CI)

Risk signals (avoid or require explicit “I accept risk”):
- Asks for secrets/tokens in plaintext, or to paste credentials
- Contains destructive commands (rm -rf, sudo, editing ~/.ssh, changing shells/rc files)
- Pipes remote scripts to shell (curl ... | sh, wget ... | bash)
- Downloads/runs opaque binaries without provenance
- Broad filesystem operations outside the current repo without justification

Hard gating checks (do these, don’t guess):
1) Identify the backing repo (owner/repo) from the skill spec.
2) Fetch repo metadata (GitHub API) and record the facts:

curl -fsSL "https://api.github.com/repos/<owner>/<repo>" \
  | python -c 'import sys,json; d=json.load(sys.stdin); print(\"archived:\", d.get(\"archived\")); print(\"pushed_at:\", d.get(\"pushed_at\")); print(\"license:\", (d.get(\"license\") or {}).get(\"spdx_id\")); print(\"stars:\", d.get(\"stargazers_count\"))'

If gh is available, you may use it instead of curl:

gh api repos/<owner>/<repo> --jq '{archived, pushed_at, license:(.license.spdx_id // \"NONE\"), stars:.stargazers_count}'

If rate-limited, do not ask the user to paste a token. Ask them to set GITHUB_TOKEN in the environment (out of band) or proceed without installs.

3) Skim the skill’s SKILL.md (and any scripts it references) for the risk signals above.

Assign one of: Recommended, Caution, Avoid.

Classification rules (harder defaults):
- Avoid if any are true:
- archived: true
- license: None / NOASSERTION / missing
- Any risk signal is present (secrets-in-chat, destructive commands, curl|sh, opaque binaries, etc.)
- pushed_at is very old (e.g., > ~12 months)
- Caution if any are true:
- Repo activity is not clearly recent (e.g., pushed > ~6 months ago) or you can’t easily tell
- Low adoption signal (e.g., very low stars) or unclear scope (project-specific)
- The skill references helper scripts/binaries you have not reviewed yet
- You can’t verify metadata due to tooling/rate limits
- Recommended only if:
- Not archived, license is present, activity is recent, and no risk signals were found.

Minimum info to show the user per candidate:
- Skill spec (e.g. owner/repo@skill)
- skills.sh link
- The exact install command
- Your assessment: Recommended / Caution / Avoid (with 1-line reason)
- Evidence summary (don’t paste huge blobs): archived=… license=… pushed_at=… stars=…

Always present choices first. Use a numbered list and ask the user to pick:
- “Install 1 and 3”
- “Install all”
- “Install none; proceed without skills”

Hard mode consent rules:
- Install Recommended only after the user explicitly chooses.
- Install Caution only after the user explicitly chooses and acknowledges risk.
- Do not offer Avoid for installation by default. Only proceed if the user names it explicitly and says they accept the risk.

5) Install the selected skills (global)

npx -y skills add -g -a codex -y <owner/repo@skill>

If the skill spec contains spaces, quote it:

npx -y skills add -g -a codex -y 'owner/repo@Skill With Spaces'

Install multiple skills by repeating the command for each selection.

6) Verify installation and proceed

npx -y skills ls -g -a codex

Then load and follow the installed skill(s)’ instructions while doing the user’s task.

7) (Optional) Pin installed skills into this repo’s `AGENTS.md`

If you install skills globally, Codex may not “see” them for this repo unless they’re listed in the repo’s AGENTS.md.

This repo includes a helper script that:
- scans the current repo to infer stack keywords
- scans installed skills (global + repo-local)
- writes/updates a generated pinned section in <repo>/AGENTS.md (creates it if missing)

Dry-run (prints the would-be AGENTS.md):

node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo .

Apply changes:

node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo . --write

Notes:
- Only the block between  and  is managed.
- Re-running is idempotent.

Quick Reference

Goal	Command
Search skills	`npx -y skills find "<query>"`
Install (global)	`npx -y skills add -g -a codex -y <owner/repo@skill>`
List installed (global)	`npx -y skills ls -g -a codex`
Remove (global)	`npx -y skills remove -g -a codex -y <skill-name>`

Example (Playwright e2e setup)

User: “Playwright로 e2e 테스트 셋업 해줘. 필요한 스킬 있으면 설치해도 돼.”

1) Search:

npx -y skills find "playwright e2e"

2) Present options (example format):
- 1) microsoft/playwright@playwright-cli — https://skills.sh/microsoft/playwright/playwright-cli
- Install: npx -y skills add -g -a codex -y microsoft/playwright@playwright-cli
- 2) sickn33/antigravity-awesome-skills@playwright-skill — https://skills.sh/sickn33/antigravity-awesome-skills/playwright-skill
- Install: npx -y skills add -g -a codex -y sickn33/antigravity-awesome-skills@playwright-skill

3) Ask:
“Which ones should I install (e.g., 1, 2, 1 2, or none)? I’ll install globally for Codex.”

Common Mistakes

Installing immediately because “the user said it’s ok” (still must ask per-task)
Making up skill search results instead of running npx skills find
Recommending skills without vetting credibility/risk
Installing project-level (forgetting -g) when the user wants global
Forgetting -a codex and installing to the wrong agent
Treating unknown repos as trusted (always show source + ask first)

Red Flags — STOP and Ask

“I’ll install first and explain after”
“I can just recommend skills without searching”
“It’s probably fine; no need to vet the repo/scripts”
“Searching is slow; I’ll skip it”
“They approved once, so I can keep installing”

Rationalizations to Counter

Rationalization	Counter-rule
“Time pressure: just start fixing CI”	Run a quick `skills find` first; then ask. If user says “skip”, proceed without installs.
“User said ‘install whatever’, so no need to ask”	Still present options and ask which to install (explicit consent each time).
“It’s faster to proceed without skills”	At least check; if nothing relevant shows up, proceed normally.
“I already know what skills exist”	Don’t guess. Run `npx skills find` and present the real results.
“We can trust any skill from skills.sh”	Search is open; trust is earned. Vet credibility and scan for risky commands.

# README.md

skills-scout

한국어(KR) / English(EN)

소개 (KR)

skills-scout는 Codex에서 작업을 진행할 때, 필요한 “에이전트 스킬(Agent Skills)”을 찾아서 검증한 뒤 사용자에게 옵션을 안내하고, 명시적 동의가 있을 때만 전역으로 설치하도록 돕는 스킬입니다.

핵심 목표는 “스킬을 빨리 찾되, 무분별하게 설치하지 않기”입니다.

동작 방식 (요약)

1) 프로젝트 빠른 스캔: 현재 프로젝트의 스택/패키지 매니저/프레임워크/CI 등을 빠르게 확인해서 검색어를 정교화합니다.
2) 스킬 검색: npx skills find "<query>"로 후보를 찾습니다.
3) Hard mode 검증: 추천 전에 아래를 확인합니다.
- GitHub API로 archived, license, pushed_at, stars 등 메타데이터 확인
- SKILL.md/스크립트에서 위험 신호 스캔(예: rm -rf, sudo, curl | sh, 비밀키/토큰 요구 등)
4) 옵션 제시 → 동의 확인: skills.sh 링크 + 정확한 설치 명령을 번호로 보여주고, 사용자가 선택한 것만 설치합니다.

설치 (Codex)

Codex에 전역 설치:

npx -y skills add servaltullius/skills-scout -g -a codex -y

전역으로 설치된 Codex 스킬 목록:

npx -y skills ls -g -a codex

사용

Superpowers 시스템을 쓰는 환경이라면, 아래처럼 스킬을 로드해 사용할 수 있습니다:

~/.codex/superpowers/.codex/superpowers-codex use-skill skills-scout

참고: 이 스킬은 “설치 자동화”가 목적이 아니라, 검색→검증→동의→설치의 안전한 절차를 강제하는 것이 목적입니다.

(권장) 프로젝트 시작 시 준자동 루틴 켜기 (`~/.codex/AGENTS.md`)

처음 설치한 사람이라면, 아래 “프로젝트 시작 루틴”을 전역 ~/.codex/AGENTS.md에 추가해두는 것을 권장합니다(파일 수정은 항상 사용자 동의 후):

1) 어떤 스킬이 이 레포에 맞는지 미리보기(dry-run)
- node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo .
2) 출력 내용을 사용자에게 보여주고 적용할지 물어보기
3) 동의 시 레포 AGENTS.md에 반영(재실행해도 중복 없음)
- node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo . --write

복붙용 스니펫(전역 ~/.codex/AGENTS.md에 추가):

## Project Start Routine (Semi-Auto)

<IMPORTANT>
새 레포에서 작업을 시작하거나(또는 레포 `AGENTS.md`가 없거나 오래됐을 때) 아래를 먼저 수행합니다:

1) 설치된 스킬 중 이 레포에 맞는 것을 미리보기(dry-run):
   - `node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo .`
2) 출력 결과를 사용자에게 보여주고, 적용할지(파일 수정) 동의를 묻습니다.
3) 동의 시 레포 `AGENTS.md`를 생성/갱신합니다(재실행해도 중복 없음):
   - `node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo . --write`
4) 이후 레포 `AGENTS.md`에 핀된 스킬을 기준으로 필요한 스킬을 로드/사용합니다. 부족하면 `skills-scout`로 검색→검증→동의 후 설치합니다.

참고:
- pinning 스크립트는 `<!-- skills-scout:start -->` ~ `<!-- skills-scout:end -->` 블록만 관리합니다.
- 사용자 명시적 동의 없이 레포 파일을 수정하지 않습니다.
</IMPORTANT>

(선택) 설치된 스킬을 레포 `AGENTS.md`에 자동으로 핀(pin)하기

전역으로 스킬을 설치해도, 해당 레포의 AGENTS.md에 명시되어 있지 않으면 Codex가 “사용 가능한 스킬 목록”으로 인식하지 못할 수 있습니다.

skills-scout에는 설치된 스킬(전역 + 레포 로컬)을 스캔해서, 현재 레포에 관련 있어 보이는 스킬을 골라 AGENTS.md에 자동으로 적어주는 스크립트가 포함되어 있습니다.

드라이런(미적용, 출력만):

node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo .

적용(파일 수정):

node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo . --write

`find-skills`(vercel-labs/skills)와의 차이

skills-scout는 아래의 공식 스킬과 목표가 겹치지만, Codex 환경에서 “더 보수적으로” 스킬을 설치/운영하기 위해 추가 규칙을 강제합니다.

참고(원본): https://github.com/vercel-labs/skills/blob/main/skills/find-skills/SKILL.md

차이점 요약:
- find-skills는 Skills CLI 사용법과 “검색→옵션 제시→설치”의 기본 흐름을 안내하는 범용 스킬입니다.
- skills-scout는 Hard mode 검증(메타데이터/위험 커맨드) + 명시적 동의 게이트 + Codex 전역 설치(-g -a codex)를 기본값으로 강제합니다.
- skills-scout는 추가로, 설치된 스킬을 레포 AGENTS.md에 자동으로 핀해서 레포 단위로 스킬이 실제로 ‘보이도록’ 하는 보조 스크립트를 제공합니다.

Overview (EN)

skills-scout is a Codex skill that helps you discover relevant agent skills and install them only after:

1) a quick project scan (stack/package manager/framework/CI)
2) hard‑mode vetting (repo metadata + risky commands)
3) explicit user consent

The goal is to “find fast, install safely” — search broadly, but do not trust or install blindly.

Install (Codex)

Global install for Codex:

npx -y skills add servaltullius/skills-scout -g -a codex -y

List installed global skills for Codex:

npx -y skills ls -g -a codex

Recommended: enable the “project start” semi-auto routine (`~/.codex/AGENTS.md`)

For first-time installs, it’s recommended to add a small “project start” routine to your global ~/.codex/AGENTS.md, so each new repo begins by pinning relevant installed skills into that repo’s AGENTS.md (always ask before writing):

1) Preview (dry-run):
- node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo .
2) Show output and ask whether to apply
3) If approved, write/update repo AGENTS.md (idempotent):
- node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo . --write

Copy/paste snippet (add to global ~/.codex/AGENTS.md):

## Project Start Routine (Semi-Auto)

<IMPORTANT>
When starting work in a new repo (or when `AGENTS.md` is missing/outdated), do this first:

1) Preview which installed skills match this repo (dry-run):
   - `node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo .`
2) Show the output to the user and ask whether to apply it.
3) If approved, write/update the repo `AGENTS.md` (idempotent):
   - `node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo . --write`
4) Then follow the repo `AGENTS.md` to decide which skills to load/use. If something is missing, use `skills-scout` to find/vet/ask consent before installing.

Notes:
- The pinning script only manages the block between `<!-- skills-scout:start -->` and `<!-- skills-scout:end -->`.
- Never modify repo files without explicit user consent.
</IMPORTANT>

Optional: Pin installed skills into a repo `AGENTS.md`

Even if you install skills globally, Codex may not “see” them for a given repo unless they are listed in that repo’s AGENTS.md.

This repo includes a helper script that scans installed skills (global + repo-local), picks relevant ones for the current repo, and writes/updates a generated pinned block in <repo>/AGENTS.md (creates it if missing).

Dry-run (prints would-be AGENTS.md):

node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo .

Apply changes:

node ~/.codex/skills/skills-scout/scripts/pin-agents-md.mjs --repo . --write

How this differs from `find-skills` (vercel-labs/skills)

skills-scout overlaps with the upstream skill below, but it is intentionally stricter for Codex (install safely, not blindly).

Reference: https://github.com/vercel-labs/skills/blob/main/skills/find-skills/SKILL.md

Summary:
- find-skills is a general guide for using the Skills CLI and presenting/installing options.
- skills-scout adds hard‑mode vetting + explicit consent gates + Codex global install defaults (-g -a codex).
- skills-scout also includes an optional helper to pin installed skills into a repo AGENTS.md so they are actually “visible” per repo.

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.

skills-scout

# Description

# SKILL.md

Skills Scout

Overview

How this differs from find-skills (vercel-labs/skills)

When to Use

Workflow

0) Confirm constraints (Codex global install)

1) Check what’s already installed

1.5) Quick project scan (to refine search + compatibility)

2) Search for candidate skills

3) Vet candidates (credibility + risk)

4) Present options and ask for consent

5) Install the selected skills (global)

6) Verify installation and proceed

7) (Optional) Pin installed skills into this repo’s AGENTS.md

Quick Reference

Example (Playwright e2e setup)

Common Mistakes

Red Flags — STOP and Ask

Rationalizations to Counter

# README.md

skills-scout

소개 (KR)

동작 방식 (요약)

설치 (Codex)

사용

(권장) 프로젝트 시작 시 준자동 루틴 켜기 (~/.codex/AGENTS.md)

(선택) 설치된 스킬을 레포 AGENTS.md에 자동으로 핀(pin)하기

find-skills(vercel-labs/skills)와의 차이

Overview (EN)

Install (Codex)

Recommended: enable the “project start” semi-auto routine (~/.codex/AGENTS.md)

Optional: Pin installed skills into a repo AGENTS.md

How this differs from find-skills (vercel-labs/skills)

# Related Skills

# Supported AI Coding Agents

Confirm

Submit a Skill

How this differs from `find-skills` (vercel-labs/skills)

7) (Optional) Pin installed skills into this repo’s `AGENTS.md`

(권장) 프로젝트 시작 시 준자동 루틴 켜기 (`~/.codex/AGENTS.md`)

(선택) 설치된 스킬을 레포 `AGENTS.md`에 자동으로 핀(pin)하기

`find-skills`(vercel-labs/skills)와의 차이

Recommended: enable the “project start” semi-auto routine (`~/.codex/AGENTS.md`)

Optional: Pin installed skills into a repo `AGENTS.md`

How this differs from `find-skills` (vercel-labs/skills)