lythoskill-curator · {{PACKAGE_VERSION}} · 2026-09-09 · sha256 1b9350bf000e077f
lythoskill-curator {{PACKAGE_VERSION}}B
Immutable. This exact content is served forever at /api/v1/blob/1b9350bf000e077f.
---
name: lythoskill-curator
version: {{PACKAGE_VERSION}}
description: |
Skill curator (买家秀 — "buyer show": hands-on QA notes, as opposed to the
author's own 卖家秀 "seller show" claims). Scans your local cold pool,
indexes SKILL.md frontmatter into REGISTRY.json + catalog.db. CLI is mechanical
glue (scan/query/tag/audit/find) — YOU are the agent who combines curator's local cache
with WebSearch, deep research, and arena testing to discover, annotate, fact-check,
and recommend. Curator = card searcher (查卡器) + personal notes (备注) + composition
taste (组卡审美). Reconciler-style: any filesystem
state → scan → converges to clean index. Auto-backup; rollback via `restore`.
when_to_use: |
Find a skill for X, search skills, what skills do I have, list all skills,
catalog skills, explore cold pool, scan skill pool, skill index, update index,
recommend a deck, is there a skill for Y, discover skills, cold pool query,
skill lookup, what's available, curator query, curator scan, curator audit,
curator tag, annotate skill, fact-check skill, cross-reference skill quality,
find path for <name>, how to add <name>, what's the path for,
bare name to full path, where is skill <name>, how do I install <name>,
curator find, lookup skill path, skill locator for.
ALSO trigger when user wants to do a task and you need to find the right skill:
curator query local cache → WebSearch for new candidates →
curator add + curator tag → arena test → curator tag --qa → recommend with confidence.
allowed-tools:
- Bash(bunx @lythos/skill-curator@{{PACKAGE_VERSION}} *)
- WebSearch
- WebFetch
# ── deck governance metadata (consumed by lythoskill tooling only) ──
deck_managed_dirs:
- ~/.agents/skill-repos/.lythoskill-curator/
---
# Skill Curator
> Curator's perspective (买家秀 "buyer show" — what hands-on use actually found,
> versus the author's 卖家秀 "seller show" claims) = card searcher + personal notes
> + composition taste.
> CLI is mechanical glue (scan, query, tag, audit). Agent does the thinking.
## Mental Model: Curator = the Curator's Perspective (策展者)
Curator is NOT a discovery engine. It's the **curator's personal knowledge base** —
a card searcher + personal notes system for the skill ecosystem.
**Two complementary modes**:
| Mode | Metaphor | What it does |
|------|----------|-------------|
| Journalist (记者) | Investigation + narrative + expression | Fact-check claims, cross-reference sources, detect bias, assign confidence |
| Architect (架构师) | Composition aesthetics | Understand synergies, deduce combos, judge structural fit, design archetypes |
**Composition taste (组卡审美) has three inputs**:
1. **Arena field data** — quantitative: scores, pass/fail, performance data
2. **Design critique** — qualitative: your own judgment of a skill's design, clarity, fit
3. **Combo reasoning** — systemic: how skills compose, what synergies emerge, what archetype they form
A curator doesn't just verify facts (Journalist mode). A curator understands **how skills
combine to be beautiful** (Architect mode). This is what separates a card database from
a deck builder.
**Curator builds on deck + arena**: it never evaluates a skill in isolation — it evaluates
"this card, in this deck, on this task." Arena tests deck-level capability; curator records
deck-task-level QA. A card that excels in one deck may be useless in another; the Architect
mode exists to reason about exactly this context dependence.
## Discovery SOP (Agent-Driven)
The explore slot is dominated by **agent + search** (gh CLI first, WebSearch as fallback).
Curator's job is NOT to be the discovery engine — it's the **local cache** that makes
discovery faster, and the **enrichment layer** that remembers what was found.
```
1. curator find <bare-name> ← local cold pool: "already have it?"
2. curator query "SELECT name, description FROM skills ← local cache: "anything similar?"
WHERE description LIKE '%<keyword>%'"
3. gh search code "<bare-name>" --filename "SKILL.md" ← GitHub code search: precise, hits exact name
4. gh search repos "<keyword>" --topic "agent-skills" ← GitHub topic search: discover skill repos
5. WebSearch for "<name> skill site:github.com" ← web fallback (site: prefix when supported)
6. WebFetch / gh CLI to inspect candidates ← deep dive
7. curator add <locator> --pool ... ← seed cold pool
8. curator scan ← re-index
9. curator tag <name> --niche "<classification>" ← agent-enriched metadata (L3)
[--qa '{"source_type":"self/arena","signal_value":8,...}']
10. arena single/vs ← test before adopting
11. curator tag <name> --qa '{"source_type":"self/arena"...}' ← record test results
12. Recommend with confidence: "skill X fits because... ← agent reasoning
(3 arena PASS + hub A confirms + curator scan clean)"
```
**Curator is NOT the discovery engine.** It's the agent's local data source.
The agent combines curator query + gh search + WebSearch + its own reasoning for
discover → rank → recommend.
### Three Discovery Scenarios
| Scenario | What you know | Start here |
|----------|--------------|------------|
| "I know the skill name" | bare name (e.g., "fullstack-dev") | `curator find` → gh search code |
| "I know the person/org" | fuzzy name (e.g., a Chinese creator's online handle) | WebSearch → gh search code for precise path |
| "I know the repo URL" | repo URL (e.g., `github.com/lijigang/ljg-skills`) | gh api peek → curator add |
### Search Precision Ladder
When `curator find` misses, use these in order — fastest to broadest:
| Priority | Method | Speed | Precision | Example |
|----------|--------|-------|-----------|---------|
| 1 | `gh search code "<name>" --filename "SKILL.md"` | ~2s | Highest | `gh search code "fullstack-dev" --filename "SKILL.md"` |
| 2 | `gh search code "<name> skill" --filename "SKILL.md"` | ~3s | High | broader match |
| 3 | `gh search repos "<topic>" --topic "agent-skills"` | ~3s | Medium | `gh search repos "writer" --topic "agent-skills"` |
| 4 | WebSearch `"<name> skill site:github.com"` | ~5s | Medium | site: prefix for domain filtering |
| 5 | WebSearch `"skill <name>"` | ~5s | Broad | without site: prefix |
`gh search code` is the most effective because it searches file CONTENTS — a skill named
"fullstack-dev" always has `name: fullstack-dev` in its SKILL.md frontmatter. This is
more precise than repo search or web search.
### Repo Exploration — "I know the repo, what's inside?"
Common social-media discovery pattern: someone shares a GitHub repo URL, but you don't
know what skills it contains. Common for monorepos (e.g., `JimLiu/baoyu-skills` has 22,
`lijigang/ljg-skills` has 21). Use `gh api` to peek without cloning:
```bash
# 1. List top-level files/dirs in the repo
gh api repos/<owner>/<repo>/contents --jq '.[].name'
# 2. If there's a skills/ dir, list it
gh api repos/<owner>/<repo>/contents/skills --jq '.[].name'
# 3. Optionally peek at specific SKILL.md frontmatter
gh api repos/<owner>/<repo>/contents/skills/<name>/SKILL.md --jq '.content' | base64 -d | head -10
```
**Real example** — discovering what's in `lijigang/ljg-skills`:
```
$ gh api repos/lijigang/ljg-skills/contents/skills --jq '.[].name'
ljg-book ljg-card ljg-invest ljg-learn ljg-paper ljg-plain
ljg-present ljg-push ljg-qa ljg-rank ljg-read ljg-think
ljg-travel ljg-word ljg-writes ... (21 skills total)
$ gh api repos/lijigang/ljg-skills/contents/skills/ljg-think/SKILL.md \
--jq '.content' | base64 -d | head -5
---
name: ljg-think
description: Arrow-to-the-root — a vertical deep-drill thinking tool...
```
Once you've identified the skills you want, `curator add` the repo normally.
### gh CLI Auth Bootstrap
**`gh` is the backbone of skill discovery.** Without it, you lose the top 3 most precise
search methods (code search, repo topic search). WebSearch alone is 5x slower and 10x
less precise. Strongly recommend the user install and auth `gh` before using curator.
If `gh` commands fail with authentication errors, do NOT silently skip:
1. **Check for existing token**: look for `.github-token` in the project root, or
`GITHUB_TOKEN` / `GH_TOKEN` env vars. If found, export it:
```bash
export GH_TOKEN=$(cat .github-token)
```
2. **Ask the user to install gh**: if `gh` CLI is missing entirely, tell the user:
> `gh` CLI is required for precise skill discovery. Install it:
> - macOS: `brew install gh`
> - Linux: `curl -fsSL https://cli.github.com/install.sh | bash`
> - Then: `gh auth login`
> Or if you have a token: `echo "ghp_xxx" > .github-token && export GH_TOKEN=$(cat .github-token)`
3. **Ask for a token**: if gh is installed but not authed:
> `gh` needs a GitHub token. You can:
> - Create one at https://github.com/settings/tokens (no scopes needed for public repos)
> - Run: `echo "ghp_xxx" > .github-token`
> - Or: `export GH_TOKEN=ghp_xxx`
4. **Fall back to WebSearch ONLY if user declines**: slower, less precise, but works
without auth. Remind the user what they're giving up.
## Commands
### Index the cold pool (scan)
```bash
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} [POOL_PATH]
# Defaults: POOL_PATH = ~/.agents/skill-repos
# Output = <pool>/.lythoskill-curator/
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} ~/.agents/skill-repos --output /tmp/my-index/
```
Reconciler-style: converges any state to a clean index. Auto-backup before rebuild.
### Tag — agent-enriched metadata (L3, the curator's own "buyer show")
```bash
# Write niche tags (curator's personal classification)
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} tag <skill-name> --niche "meta.governance.deck"
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} tag <skill-name> --niche "code-review" --niche "security"
# Write QA signal with provenance (REQUIRED)
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} tag <skill-name> \
--qa '{"source_type":"self/arena","source_name":"arena-single-2026-05-18","signal_type":"score","signal_value":8}'
# Reference external hub assessment (L2, with provenance)
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} tag <skill-name> \
--qa '{"source_type":"hub/agentskill.sh","source_url":"https://...","signal_type":"securityScore","signal_value":95}'
```
**Tag is agent-enriched metadata: the curator's own QA notes, written after hands-on
testing.** Skill authors write the L1 layer (description — the "seller show", what the
author advertises). The curator writes the L3 layer (niche + QA — the "buyer show", what
actual use found). These are separate data layers; a scan never overwrites the curator's
notes with author claims.
Re-scan preserves agent-written tags (merge strategy: scan updates name/description/path,
preserves niches column).
**QA provenance schema**: every signal must carry `source_type`, `source_name`, and `signal_value`.
No-provenance signals are rejected. See ADR-20260518123403810.
### Niche Taxonomy — naming conventions for agent-written tags
Niche tags follow a hierarchical prefix convention. When tagging, use these patterns:
| Prefix | Pattern | Example | Meaning |
|--------|---------|---------|---------|
| `hub/` | `hub/<source>/trending/<date>` | `hub/skills-sh/trending/2026-05-20` | External hub trending reference |
| `domain/` | `domain/<classification>` | `domain/data-engineering`, `domain/general` | Domain specialization level |
| freeform | any string without prefix | `code-review`, `security` | Curator's personal classification |
**To discover existing niches** (before tagging, know what's already there):
```bash
curator query "SELECT DISTINCT json_each.value, COUNT(*) as cnt FROM skills, json_each(niches) WHERE json_each.value NOT LIKE 'qa:%' GROUP BY 1 ORDER BY cnt DESC"
```
### External Hub Cross-Reference Workflow
Skills.sh, LobeHub, and other registries track install counts and trending metrics. Cross-reference their data into curator:
```
1. WebFetch <hub-url> → extract top N skill names + ranks + install counts
2. For each name: curator find <name> → HIT or MISS?
3. For HIT: curator tag <name> --niche "hub/<source>/trending/<date>" \
--qa '{"source_type":"hub/<source>","source_name":"<source>-<date>","source_url":"...","signal_type":"installs_alltime","signal_value":<n>,"rank":<r>}'
4. Batch: use SQLite directly for bulk operations (see Gotchas)
```
**Real example** — skills.sh top 17 cross-referenced against 871-skill cold pool (2026-05-20):
- 4 HITs: find-skills (#1, 1.6M), frontend-design (#2, 433K), web-design-guidelines (#5, 331K, antfu not vercel), skill-creator (#26, 219K)
- 13 MISS: mostly Vercel/Microsoft/Azure skills not yet in cold pool
- `web-design-guidelines` name collision: skills.sh tracks vercel-labs version, cold pool has antfu version — same capability slot, different ecosystems
### Domain Tagging from Path Structure
Some skill repos organize skills by domain (e.g., `plugins/<domain>/skills/<name>/`). Extract this:
```bash
# Discover domains embedded in path structure
curator query "SELECT DISTINCT SUBSTR(path, INSTR(path, 'plugins/')+8, INSTR(SUBSTR(path, INSTR(path, 'plugins/')+8), '/')-1) as domain FROM skills WHERE path LIKE '%plugins/%/skills/%'"
# Tag each skill with its domain
# For wshobson-style repos (plugins/<domain>/skills/...): tag with "domain/<domain>"
# For flat repos (skills/<name>/): tag with "domain/general"
```
This is how the 155 wshobson skills got `domain/data-engineering`, `domain/python-development`, etc., and 305 antigravity skills got `domain/general`.
### Query the index
```bash
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} query "SELECT name, type FROM skills WHERE description LIKE '%diagram%'"
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} query --db ./catalog.db "SELECT * FROM catalog_meta"
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} query "PRAGMA table_info(skills)"
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} query # show schema overview
```
Output is Markdown table. SQL is a good DSL for showing intent — declarative, readable.
### Find — bare name to full path lookup
```bash
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} find <bare-name>
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} find fullstack-dev
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} find fullstack-dev --db ./catalog.db
```
Output: full locator path + ready-to-use `deck add` command + `skill-deck.toml` snippet.
Looks up `name` field in catalog.db. Local-only — searches skills already in your cold pool.
**Example — user discovers "fullstack-dev" on social media, wants to add it:**
HIT (skill already in cold pool):
```
$ curator find fullstack-dev
name: fullstack-dev
path: github.com/MiniMax-AI/skills/skills/fullstack-dev
type: standard
# deck add:
bunx @lythos/skill-deck add fullstack-dev \
--path github.com/MiniMax-AI/skills/skills/fullstack-dev
# or add to skill-deck.toml:
[tool.skills.fullstack-dev]
path = "github.com/MiniMax-AI/skills/skills/fullstack-dev"
```
MISS — not in cold pool yet:
```
$ curator find fullstack-dev
🔍 "fullstack-dev" not found in local cold pool.
To add it:
1. gh search code "fullstack-dev" --filename "SKILL.md" ← find the repo
2. curator add github.com/<owner>/<repo> --pool ~/.agents/skill-repos
3. curator find fullstack-dev # then it will hit
Or ask your agent — it can gh search code → curator add → deck add in one flow.
See Discovery SOP → Search Precision Ladder for fallback methods.
```
**Ambiguity**: bare names are not unique — `fullstack-dev` exists in both MiniMax-AI/skills and
ChatGLM/skills. When multiple matches exist, `find` lists all options with their full paths
and any niche tags (hub references, domain classification) to help disambiguate:
```
⚠️ 2 skills share the name "airflow-dag-patterns":
airflow-dag-patterns → ...antigravity-skills/... (standard) 🏷️ domain/general
airflow-dag-patterns → ...wshobson/.../data-engineering/... (standard) 🏷️ domain/data-engineering
Pick ONE and specify its full path with deck add:
bunx @lythos/skill-deck add airflow-dag-patterns --path ...antigravity-skills/...
⚠️ deck link will fail if two skills have the same name. Choose one.
```
**Disambiguation heuristic**: prefer domain-specialized over `domain/general`, prefer hub-validated
(skills.sh trending) over unvalidated. Name collision is a strong signal that multiple ecosystems
implement the same capability slot — pick the one matching your context.
### Audit the index
```bash
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} audit
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} audit --db ./catalog.db
```
Checks: missing frontmatter, type anomalies, orphan scripts, deck_skill_type coverage,
**legacy pattern detection** (deprecated references like `skills.sh`, `deck status sh`,
`HANDOFF.md` in SKILL.md body). Empty niches are NOT violations — niches are agent-enriched,
not author-declared.
### Add a skill to the cold pool
```bash
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} add github.com/owner/repo --pool ~/.agents/skill-repos
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} add github.com/owner/repo --pool ~/.agents/skill-repos --dry-run
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} add github.com/owner/repo --pool ~/.agents/skill-repos \
--output /tmp/my-index/
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} add github.com/owner/repo --pool ~/.agents/skill-repos \
--reason "Found via WebSearch for code review skills" --branch main
```
`--output` controls where `additions.jsonl` and the write-through cache land. Default: `<pool>/.lythoskill-curator/`. Use it to point to a different location.
### Refresh upstreams (plan-first)
```bash
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} refresh-plan
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} refresh-execute
```
### Rollback
```bash
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} restore
```
## Fact-Check + Confidence Evaluation (Journalist mode)
The curator's verification layer — not just collecting QA signals, but verifying
claims and assigning structured confidence. The agent is a **journalist** (记者,
the investigator role): investigation + narrative synthesis + expression.
### Fact-Check Workflow
```
1. curator query → get skill's current QA signals
2. Agent cross-references:
- Author claim (L1): "fast and reliable"
- Arena self-test (L3): 30s timeout? → contradiction → flag
- Hub A (L2): score 9/10 vs Hub B (L2): score 4/10 → signal divergence → needs self-test
- 3 independent arena runs agree → evidence convergence → HIGH confidence
3. curator tag --qa → write structured confidence assessment
```
### Confidence Dimensions
- **Evidence quantity**: how many independent sources
- **Evidence quality**: self-test > shared arena > hub > author claim
- **Evidence consistency**: convergent or contradictory?
- **Freshness**: recent test > 6-month-old data
### Source-Filtered Bias Detection
Toggle sources to see different composite pictures:
- All sources: 8/10
- Exclude Hub A: 6/10 (Hub A systematically rates +2 on TypeScript skills)
- Self-test only: 7/10 (smaller sample, higher confidence per sample)
This difference IS the signal. Curator doesn't decide which source to trust —
it shows the multi-source picture and lets the agent/user judge.
### Confidence Output Format
```
Claim X: HIGH confidence (3 self-tests PASS + 1 hub confirms, 0 contradictions)
Claim Y: LOW confidence (author-only claim, no independent verification)
Claim Z: CONTRADICTED (author says "fast", arena shows 30s timeout)
```
## Typical Queries
```bash
# Skills by agent-enriched niche
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} query "SELECT name, niches FROM skills WHERE niches LIKE '%agent-tagged%'"
# Duplicate detection
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} query \
"SELECT name, path FROM skills WHERE name IN (SELECT name FROM skills GROUP BY name HAVING COUNT(*) > 1)"
# Combo / transient / fork skills
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} query "SELECT name, deck_skill_type, source FROM skills WHERE deck_skill_type IS NOT NULL"
# Managed directory overlaps
bunx @lythos/skill-curator@{{PACKAGE_VERSION}} query "SELECT name, managed_dirs FROM skills WHERE managed_dirs LIKE '%cortex/%'"
```
## Curator + Deck + Arena Workflow
```
curator scan → catalog.db "What's in my collection?"
↓
agent: curator query + WebSearch "Find me a skill for X" (discovery)
↓
curator find <bare-name> "What's the full path?" (lookup, ADR-20260519225831495)
↓
curator add + curator scan "Add to cold pool" (collection)
↓
curator tag --niche ... [--qa ...] "Write my notes" (enrichment)
↓
deck add + deck link "Activate in working set" (use)
↓
arena single/vs "Test it myself" (verify)
↓
curator tag --qa '{"source_type":"self/arena"...}' "Record result" (remember)
↓
Next discovery: richer cache + QA → better recommendations (compound)
```
**Data flywheel**: more usage → more QA data → better curator → better recommendations →
more targeted testing → even more QA data. Curator's value compounds over time
while deck/arena deliver steady-state value.
## Gotchas
**Agent-enriched niches, not frontmatter-extracted**: niches come from `curator tag`,
not from SKILL.md frontmatter. Scan preserves existing niches on re-scan (merge strategy).
**Empty niche is NOT a violation**: audit no longer flags empty niches. Skills without
agent-enriched metadata are normal — especially newly indexed skills.
**Legacy pattern detection**: audit checks SKILL.md bodies for deprecated references
(`skills.sh`, `deck status sh`, `HANDOFF.md`, `deck update`). Mechanical detection,
agent judges severity.
**Reconciler mental model**: K8s-controller-style. One `curator` run converges any state
to clean. Auto-backup before rebuild. Use `curator restore` to roll back.
**Index freshness**: query stderr shows generation time. >7 days → warning.
**catalog.db not found**: run `curator` first to scan and build the index.
**JSON array fields**: `niches`, `managed_dirs`, `trigger_phrases` stored as JSON strings
in SQLite. Use `json_extract()` for element access.
**QA provenance required**: every QA signal via `--qa` must include `source_type` and
`source_name`. No-provenance signals are rejected.
**Feed concept survives as schema, not adapter code**: curator does NOT implement HTTP
API adapters. Agent uses WebSearch/WebFetch/gh CLI for external discovery. Curator
can maintain feed schemas (URL patterns, data shapes) as metadata — but the execution
is agent-side. See ADR-20260508230803515.
**Shell batch gotcha**: `$(bun ... 2>/dev/null)` in a loop corrupts PATH on subsequent
iterations. For batch operations (bulk find, bulk tag), use SQLite directly via
`curator query` or a Bun/Node script reading catalog.db. Single commands are safe.
**Same-name deck link conflict**: `deck link` fails if two skills share a bare name.
Use `curator find` first to detect collisions. Pick ONE — the path is what matters
to deck, not the name. `deck add <name> --path <full-locator>` is explicit.
## Supporting References
Read these **only when the specific topic arises**:
| When you need to… | Read |
|--------------------|------|
| Understand the REGISTRY.json schema and field meanings | [references/registry-schema.md](./references/registry-schema.md) |
| Write SQL queries against catalog.db | [references/catalog-db.md](./references/catalog-db.md) |
| Build a recommendation from the index (agent workflow) | [references/recommendation-workflow.md](./references/recommendation-workflow.md) |
| Identify skill combination patterns (pipeline, modality…) | [references/combination-patterns.md](./references/combination-patterns.md) |
| Understand curator's design principles | [references/design-principles.md](./references/design-principles.md) |
| See the full data flow and trust model | [references/architecture.md](./references/architecture.md) |
| Understand WHY curator is this shape (ecosystem structural constraints, steel-man analysis) | [references/why-this-shape.md](./references/why-this-shape.md) |