Why this exists

Agents already have hundreds of skills. They still pick the wrong one, skip the good one, or install a second skill for a job that's already filled.

find-skills searches the registry when you ask "is there a skill for X?".

Only Skill You Need is the package manager on top: detect the repo, fill empty use-cases from the live ecosystem, keep a ledger, and force the agent to read the winner before it writes code.

One install. One slot per job. Never auto-replace a better skill with a worse one.

Install

npx skills add Endokelp/Only-Skill-You-Need -g -y

Then tell the agent:

set up skills for this project

or just start building. This skill should fire first.

Local clone:

npx skills add ./Only-Skill-You-Need -g -a claude-code -a cursor -y --copy

How it works

flowchart TD
  task[User task] --> skill[Read this SKILL.md]
  skill --> detect["cli.py detect"]
  detect --> empty{Project ledger empty?}
  empty -->|yes| boot[Propose starter pack]
  boot --> ask[Ask, then npx skills add]
  ask --> write[Write global + project ledger + lock]
  empty -->|no| route[Classify task into slots]
  write --> route
  route --> filled{Slot filled?}
  filled -->|yes| readWin[Read installed winner]
  readWin --> live[Live check npx skills find]
  live --> mention[Mention better if it beats the sticky gate]
  filled -->|no| ask2[Propose current best, then install]
  mention --> work[Do the actual task]
  ask2 --> work

Sticky rules

Situation What happens
Empty use-case Propose the current best. Install only after you say yes.
Occupied use-case Keep the installed skill. Mention a better one. Switch only if you ask.
Same job, second skill Refuse. Record it in rejected[].
Unknown source, <100 installs Never propose.

The ledger (screenshot this)

After bootstrap, every repo gets a human-readable status file. That is the artifact you can put on LinkedIn.

File Where Role
Global ledger ~/.agents/only-skill-you-need/ledger.json Your defaults across every repo
Project overlay .agents/only-skill-you-need/ledger.json Wins in this repo
Lockfile .agents/only-skill-you-need/lock.json Exact sources + rejected candidates
Status .agents/only-skill-you-need/STATUS.md The screenshot

What gets bootstrapped

Detects the project root only (no crawl):

You have Stack Extra slots
package.json + Next/React next UI, React, e2e, deploy
package.json node API, deploy
pyproject.toml / requirements.txt python API, database
go.mod go API
empty folder empty process pack only

Every stack includes: plan, TDD, debug, review, verify, minimal, and find-skills.

A brand-new builder with an empty folder can plan, test, debug, and review on day one.

CLI

Python 3.10+, stdlib only. Live search uses npx skills find. If that fails, bundled references/seed-best.json is used and the output says so.

python scripts/cli.py detect --root .
python scripts/cli.py bootstrap --root .           # propose — does not install
python scripts/cli.py bootstrap --root . --apply   # after you say yes
python scripts/cli.py route --root . "fix this bug"
python scripts/cli.py status --root .
python scripts/cli.py --self-check

--offline skips the network and uses the seed list.

Quality score

score = official_bonus + min(installs, 10_000_000) + min(stars, 50_000) * 10

Official bonus (anthropics, vercel-labs, obra, microsoft, supabase, firebase): 1_000_000.

A live candidate is only mentioned as an upgrade if it beats the incumbent on score and has ≥2× installs (or is official while the incumbent is not).

Tests

python -m unittest discover -s tests
python scripts/cli.py --self-check

Stdlib unittest. No extra packages. The self-check fails if ledger merge or the sticky gate breaks.

Repo layout

SKILL.md                 # agent procedure
scripts/cli.py           # detect | bootstrap | route | status
references/              # slots, quality, packs, agent paths
docs/assets/             # logo, banner, diagrams
tests/                   # 63 unit tests

License

MIT © Endokelp