Discover Skills

Produce a canonical inventory of every SKILL.md file under the scan target, plus enrichment for every Tessl tile found. Deterministic task — no LLM judgement.

Output conforms to discovery.schema.json (currently schema_version: "1.4"). The script validates its output against this schema before writing, so a malformed output will exit with code 2 rather than silently corrupting downstream phases. See references/schemas/ for all phase contracts and the shared validator.

Inputs

• SCAN_ROOT — directory to scan. Defaults to $(pwd). Used both as the auto-discovery root and as the default output base.
• OUTPUT_PATH — where to write the JSON. Defaults to $SCAN_ROOT/.skill-insights/discovery.json.
• --repo PATH (repeatable) — explicitly select repos to include. When provided, replaces auto-discovery entirely — only the listed repos are scanned. Each path can be absolute or relative to --scan-root.

Run the bundled script

# Auto-discovery: scan a single repo, OR a workspace of git children
python3 <skill-dir>/scripts/discover_skills.py \
  --scan-root "$SCAN_ROOT" \
  --output "$OUTPUT_PATH"

# Explicit selection: pick exactly which repos to include
python3 <skill-dir>/scripts/discover_skills.py \
  --scan-root "$WORKSPACE" \
  --repo "$WORKSPACE/monorepo" \
  --repo "$WORKSPACE/lightdash" \
  --output "$OUTPUT_PATH"

<skill-dir> resolves to $HOME/.tessl/tiles/tessleng/skill-insights/skills/discover-skills/ for a global install, or $(pwd)/.tessl/tiles/tessleng/skill-insights/skills/discover-skills/ for a per-repo install. The script also accepts SCAN_ROOT, OUTPUT_PATH, and SCAN_ID as environment variables if flags aren't passed.

Repo selection modes

Use --repo when you want to scan a curated subset of a workspace (e.g. only monorepo + lightdash, skipping unrelated repos in the same parent dir).

What the script does

Stdlib-only by default, with two soft dependencies: PyYAML for richer frontmatter parsing (regex fallback otherwise), and jsonschema for IO contract validation against discovery.schema.json (no validation otherwise — single stderr warning).

Per skill (deterministic, fast):

• Glob discovery for SKILL.md files
• Symlink-following walk with per-chain cycle detection (essential for Tessl-vendored installs that symlink .claude/skills/tessl__* → .tessl/tiles/...)
• Content hashing (SHA-256 of full file bytes) → vendored dedup within a repo
• YAML frontmatter parsing (best-effort, surfaces parse errors to warnings)
• Supporting-file capture: references/ / reference/ dirs, scripts/ dirs, markdown links, @imports, inline backtick paths in body
• Bundled-directory summarisation (other sibling dirs)
• Source-type classification (origin-based: a vendored tile skill stays tessl_tile_skill even when surfaced via .claude/skills/)
• Owning-package detection by walking up for tile.json / .claude-plugin/plugin.json
• Tier stamping per skill: published_tile / authored_tile / github_tile / claude_plugin / non_tile

.tessl/ exclusion: SKILL.md files inside .tessl/ (the Tessl CLI's installed-tile cache) are not included in skills[]. Those tiles are surfaced via tiles[] instead, with source: "tessl_json". This keeps the skill inventory focused on first-party content the user authored.

Per tile (Tessl-aware enrichment, requires tessl CLI + auth):

• Discovery source: every tile entry carries a source field of "tessl_json" or "filesystem". Tiles found via tessl.json declarations are tagged tessl_json; tiles discovered by walking the SKILL.md tree (e.g. authored tiles under tiles/<name>/) are tagged filesystem. When a tile is found via both methods, tessl_json wins.
• Tier classification by inspecting tessl.json source field and tile.json location
• Registry call to GET /v1/tiles/{ws}/{name}/versions/{ver} for every tile that resolves on the registry — pulls aggregate / quality / impact / security / uplift / eval scores / moderation / archived / fingerprint
• One tessl outdated --json call per scanned repo, run from that repo, mapped per tile to detect "newer version available on registry"
• One tessl tile lint per tile parsed into front-loaded + on-demand token totals (and per-skill breakdown)

If the Tessl auth file is missing (~/.tessl/api-credentials.json), registry/outdated enrichment is silently skipped — the scan still produces a valid inventory, just without registry-derived signals. tessl tile lint still runs (it's local).

Broken-reference detection (git-history backed):

For every path-shaped reference in a SKILL.md body — markdown links, @imports, inline backticks — the script:

1. Resolves the target to a repo-relative path
2. Checks git ls-tree HEAD (currently tracked)
3. Checks git log --all --name-only (ever tracked)
4. If currently tracked → records as a supporting_files[] entry
5. If ever tracked but no longer present → emits a broken link in <repo>/<skill_path>: <target> warning
6. If never tracked → silently ignored (it's a code symbol, package name, or external reference, not a repo file)

No extension allowlist. No false positives from prose mentioning paths that aren't from this repo.

Verify + summarise

After the script returns:

1. Check exit code: 0 means success. Non-zero means the scan failed — surface stderr to the user.
2. The script self-validates its output against discovery.schema.json before writing (when jsonschema is installed). For external sanity-check the version field can still be eyeballed:

   jq -e '.schema_version == "1.4"' "$OUTPUT_PATH" > /dev/null

3. Print a concise summary from the JSON:

   Skill Discovery complete (schema 1.4).
   Scan root:    <scan_root>
   Repos:        <N>
   Skills:       <N> logical (<M> paths)
   Tiles:        <N> total — <published_to_registry> in registry, <authored_only> authored only
   By source:    tessl_json=<N>, filesystem=<N>
   By tier:      published=<N>, authored=<N>, github=<N>
   Security:     <N> tiles flagged MEDIUM/HIGH/CRITICAL
   Updates:      <N> tiles outdated vs registry
   Broken refs:  <N> warnings

Requirements

The script degrades gracefully — every step is best-effort and missing capabilities surface as null in the output rather than aborting the scan.