skill-index-updater

Files (8)

• LICENSE.txt
• SKILL.md
• README.md · docs/
• evals.json · evals/
• audit-eval-contract.md · references/
• commit-and-pr.md · references/
• discovery-contract.md · references/
• manual-index.md · references/

SKILL.md (first lines)

# Skill Index Updater

You are adding new skill repository sources to the ASM (Agent Skill Manager) curated index. This is the pipeline that powers the skill catalog at https://luongnv.com/asm/ — every repo you add here becomes discoverable and installable by thousands of users.

## Example

```
User: add github.com/anthropics/skills to the index
Skill output:
  Step 1: Parsed 1 URL → anthropics/skills (NEW)
  Step 2: Discovered 14 SKILL.md files
  Step 3: Audit 13 OK / 1 WARN, eval scores 71–94
  Step 6–8: data/skill-index-resources.json + data/skill-index/anthropics_skills.json updated, catalog rebuilt
  Step 10: PR #312 opened — feat(index): add anthropics/skills (14 skills)
```

## Repo Sync Before Edits (mandatory)

Before modifying any files, pull the latest remote branch:

```bash
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"
```

If the working tree is dirty: stash, sync, then pop. If `origin` is missing or conflicts occur: stop and ask the user before continuing.

## Prerequisites

Check each before Step 1. If one fails, stop and name it.

- `node` (>= 22), `jq`, and `git` on PATH; `npm install` done in the repo, so `npx tsx` resolves
- `asm` on PATH — the Step 3 workers run `asm eval`
- `gh auth status` succeeds — Step 10 opens the PR
- `git status --porcelain -- website/ data/` prints nothing. Step 8 restores the tracked `website/` files and `data/repo-stars.json` that `build-catalog` rewrites, which is safe only from a clean start.

## Input

The user provides one or more GitHub repository URLs: `https://github.com/owner/repo`, `github.com/owner/repo`, `github:owner/repo`, or `owner/repo`. Normalize each to `owner` and `repo`.

## Pipeline

Follow these steps in order. Each step has a verification check — do not proceed to the next step if verification fails.

You are the **orchestrator**. Steps 2 and 3 are the heavy ones, and you delegate both: each names the slice of `references/` its worker needs and hands that slice over as the worker's `Input`. In those two steps you never clone a repo, read a `SKILL.md`, or run `asm eval` yourself, and you never open the two contract files — the workers do. This keeps the clones and contract text out of your context budget. (Step 7's manual-generation fallback is the one place you may call `asm eval` directly.)

**No Agent tool?** Degrade gracefully: read `references/discovery-contract.md` and `references/audit-eval-contract.md` yourself, run Steps 2 and 3 inline, in order, and say so in the Step 9 summary. The pipeline is identical; only the context cost changes.

### Step 1: Parse and Validate Input URLs

For each URL provided:

1. Extract `owner` and `repo` from the URL.
2. Request `https://api.github.com/repos/{owner}/{repo}`. A 200 response means the repo exists; any other status marks it `INVALID` with that status.
3. Replace `owner` and `repo` with the two halves of the response's `full_name`. The ingester names files and `installUrl`s with the case it is given, so `Anthropics/Skills` would otherwise create a duplicate entry.
4. Look up `github:{owner}/{repo}` in `data/skill-index-resources.json`. If present, mark it `EXISTS` (re-index); otherwise mark it `NEW`.

Output a summary table:

```
| # | Owner/Repo          | Status   | Notes                    |
|---|---------------------|----------|--------------------------|
| 1 | owner/repo          | NEW      | Will be added            |
| 2 | other/repo          | EXISTS   | Will be re-indexed       |
| 3 | bad/repo            | INVALID  | 404 - repo not found     |
```

If every repo is `INVALID`, stop and tell the user.

### Step 2: Discover Skills in Each Repository (workers, one per repo)

Spawn one discovery worker per valid repo, **in the same turn** so they run concurrently. Each worker's contract:

- Input: `references/discovery-contract.md`, plus that repo's `owner` and `repo`
- Output: the fixed JSON in that contract — `{owner, repo, tempRoot, clonePath, status, error, skills[]}`, one object per repo
- You do NOT read `references/discovery-contract.md` yourself; the worker does

Keep every worker's `tempRoot` and `clonePath`: Step 3 runs against the clone, Cleanup deletes the `tempRoot`. There is no shared `$TEMP_DIR` in your shell — the clones were made in the workers'.

Report how many skills were found per repo. If a repo returns `status: "no-skills"`, ask the user whether to include it anyway. If a repo returns `status: "clone-failed"`, skip it, report its `error`, and continue with the others.

### Step 3: Audit and Evaluate Discovered Skills (workers, one per batch)

Spawn one audit worker per repo — or per batch of ~20 skills for a large repo — again in the same turn. Each worker's contract:

- Input: `references/audit-eval-contract.md`, that repo's `clonePath` from Step 2, and the `relPath` list for its batch
- Output: the fixed JSON array in that contract — one object per skill, `{relPath, name, auditStatus, notes[], overallScore, grade}`
- You do NOT read `references/audit-eval-contract.md` yourself

No worker re-clones; they run against the Step 2 clones. Merge the workers' JSON — no re-reading of any skill file — into one combined report:

```
Repo: owner/repo (N skills discovered)

  skill-name-1        OK     92 / A    name + description present, no security flags
  skill-name-2        WARN   58 / D    missing description
  skill-name-3        FLAG   71 / C    contains shell execution patterns (exec, spawn)
```

The policy is **permissive but transparent**: accept every repo with at least one valid skill (name + description). WARN, FLAG, and low eval scores do not block inclusion; they are reported so the reviewer can decide. Keep the OK / WARN / FLAG counts per repo — Step 10's PR body uses them.

### Step 4: Check for Existing Repos to Update

For each `EXISTS` repo from Step 1:

1. Compare `data/skill-index/{owner}_{repo}.json` against the Step 2 skill list.
2. Report new skills, removed skills, and skills with changed metadata (version, description, …).
3. Ask the user to confirm. If they decline, drop that repo from Steps 6–10.

### Step 5: Create Feature Branch

If no `NEW` repo and no confirmed `EXISTS` repo remains, stop and report that there is nothing to add. If the current branch is not `main`, ask the user whether to branch from it or from `main`. Then:

```bash
git checkout -b feat/index-add-{repo-names}
```

For several repos, use `feat/index-add-multiple-repos-{date}`.

From luongnv89/asm, MIT.

More from luongnv89/asm