@rulemetric/skills-registry 0.12.2 → 0.12.3

package/dist/entry-identity.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Identity and metadata derivation for registry entries.
+ *
+ * Extracted from github-fetcher.ts so it can be tested without the network.
+ * Everything here is pure: (repo, path, content) in, entry metadata out.
+ *
+ * These four functions decide, for every markdown file in 379 source repos,
+ * what it is called, what it claims to be about, whether it is a skill at all,
+ * and whether it survives at all. Before this module existed the package had
+ * no tests, and each of them was wrong in a way that reached real projects.
+ */
+/** Frontmatter fields the skill formats agree on. */
+export interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+}
+/**
+ * Parse the leading YAML frontmatter block for `name` and `description`.
+ *
+ * Deliberately not a general YAML parser: it reads the two scalar fields the
+ * Anthropic/OpenCode skill formats define, including block scalars (`|`, `>`),
+ * and ignores everything else. A skill file whose frontmatter is malformed
+ * should degrade to prose extraction, not throw.
+ */
+export declare function parseFrontmatter(content: string): SkillFrontmatter;
+export declare function deriveName(filePath: string, frontmatter?: SkillFrontmatter): string;
+/**
+ * A one-line description of what the file is about.
+ *
+ * Order of authority:
+ *   1. frontmatter `description` — the author said it outright;
+ *   2. the first line of real prose;
+ *   3. nothing. An empty string is honest; the file name dressed up as a
+ *      sentence is not, and downstream scoring can see the difference.
+ *
+ * The prose scan skips what is not prose. The previous version skipped only
+ * the opening ``` fence and not the code inside it, so the first line of the
+ * first code block became the description — which is how a Python skill was
+ * published to real projects described as `def append_to(item, target=[]):`.
+ */
+export declare function extractDescription(content: string, frontmatter?: SkillFrontmatter): string;
+export type EntryKind = 'skill' | 'supporting' | 'furniture';
+export interface EntryClassification {
+    kind: EntryKind;
+    /** Why, for the build log. Never discard something without saying why. */
+    reason: string;
+}
+/**
+ * Decide whether a matched file is a skill, supporting material for one, or
+ * repo furniture.
+ *
+ * The patterns in sources.ts are as broad as `**\/*.md` for most repos, so this
+ * is the only thing standing between "every markdown file in 379 repos" and
+ * the catalog the adoption loop proposes from. Measured 2026-08-25: 3,099 of
+ * 5,850 entries lived in a support directory and 543 of trailofbits/skills'
+ * 543 entries were reference files, eval graders and agent definitions — not
+ * one of its actual skills.
+ */
+export declare function classifyEntry(filePath: string, content: string, frontmatter?: SkillFrontmatter): EntryClassification;
+/**
+ * The stable half of an entry's id: `<repo-short>--<basename>`.
+ *
+ * Kept exactly as it was. 5,850 live ids have this shape, they are embedded in
+ * `instructions.name` as `skills--<id>` and in on-disk skill directories, so
+ * moving them would orphan every adopted skill. Collisions are resolved by
+ * ADDING qualified ids for the files that currently lose, never by renaming
+ * the file that currently wins.
+ */
+export declare function baseId(repo: string, filePath: string): string;
+/**
+ * Progressively more qualified ids for the same file, most-preferred first.
+ *
+ * For a directory-shaped skill (`skills/lang-python/SKILL.md`) the directory
+ * is the identity: every such file otherwise asks for `<repo>--skill`, which
+ * names nothing and which only one file per repo can hold.
+ */
+export declare function idCandidates(repo: string, filePath: string): string[];
+/**
+ * Rank for deciding which file keeps the unqualified id when several want it.
+ *
+ * Lower wins. Assignment must not depend on which network request returned
+ * first: ids reached production through a `Promise.all` race, so a skill's id
+ * — and therefore the identity of any instruction row adopted from it — could
+ * change between two builds that saw identical repos.
+ */
+export declare function preferenceRank(kind: EntryKind, filePath: string, frontmatter: SkillFrontmatter): number;
+//# sourceMappingURL=entry-identity.d.ts.map

package/dist/entry-identity.js

@@ -0,0 +1,293 @@
+import * as path from 'node:path';
+/**
+ * Parse the leading YAML frontmatter block for `name` and `description`.
+ *
+ * Deliberately not a general YAML parser: it reads the two scalar fields the
+ * Anthropic/OpenCode skill formats define, including block scalars (`|`, `>`),
+ * and ignores everything else. A skill file whose frontmatter is malformed
+ * should degrade to prose extraction, not throw.
+ */
+export function parseFrontmatter(content) {
+    const match = /^?---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(content);
+    if (!match)
+        return {};
+    const lines = match[1].split(/\r?\n/);
+    const out = {};
+    for (let i = 0; i < lines.length; i++) {
+        const field = /^(name|description):\s*(.*)$/.exec(lines[i]);
+        if (!field)
+            continue;
+        const key = field[1];
+        if (out[key] !== undefined)
+            continue;
+        let value = field[2].trim();
+        // Block scalar: the value is the indented lines that follow, not the
+        // `|`/`>` marker. Reading the marker as the value is how a skill ended up
+        // described as "|".
+        if (value === '|' || value === '>' || /^[|>][-+]?\d*$/.test(value)) {
+            const collected = [];
+            for (let j = i + 1; j < lines.length; j++) {
+                if (lines[j].trim() === '') {
+                    collected.push('');
+                    continue;
+                }
+                if (!/^\s/.test(lines[j]))
+                    break;
+                collected.push(lines[j].trim());
+            }
+            value = collected.join(' ').replace(/\s+/g, ' ').trim();
+        }
+        else {
+            value = unquote(value);
+            // Plain multi-line scalar: continuation lines are indented and carry no
+            // `key:` of their own.
+            const continued = [value];
+            for (let j = i + 1; j < lines.length; j++) {
+                if (!/^\s+\S/.test(lines[j]))
+                    break;
+                if (/^\s*(name|description|allowed-tools|license|version|model|tools):/.test(lines[j]))
+                    break;
+                continued.push(lines[j].trim());
+            }
+            value = continued.join(' ').replace(/\s+/g, ' ').trim();
+        }
+        if (value)
+            out[key] = value;
+    }
+    return out;
+}
+function unquote(value) {
+    const quoted = /^(['"])([\s\S]*)\1$/.exec(value.trim());
+    return quoted ? quoted[2] : value.trim();
+}
+export function deriveName(filePath, frontmatter) {
+    const declared = frontmatter?.name?.trim();
+    if (declared)
+        return declared.slice(0, 120);
+    const name = path.basename(filePath, path.extname(filePath));
+    const titled = name.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()).trim();
+    // A directory-shaped skill is named by its directory: every one of them is
+    // called "SKILL", "README" or "index" otherwise.
+    if (/^(skill|readme|index|agents)$/i.test(name)) {
+        const parent = path.basename(path.dirname(filePath));
+        if (parent && parent !== '.' && parent !== '/') {
+            return parent.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()).trim();
+        }
+    }
+    return titled;
+}
+/**
+ * A one-line description of what the file is about.
+ *
+ * Order of authority:
+ *   1. frontmatter `description` — the author said it outright;
+ *   2. the first line of real prose;
+ *   3. nothing. An empty string is honest; the file name dressed up as a
+ *      sentence is not, and downstream scoring can see the difference.
+ *
+ * The prose scan skips what is not prose. The previous version skipped only
+ * the opening ``` fence and not the code inside it, so the first line of the
+ * first code block became the description — which is how a Python skill was
+ * published to real projects described as `def append_to(item, target=[]):`.
+ */
+export function extractDescription(content, frontmatter) {
+    const declared = (frontmatter ?? parseFrontmatter(content)).description?.trim();
+    if (declared)
+        return declared.slice(0, 300);
+    const body = stripFrontmatter(content);
+    let inFence = false;
+    let fenceMarker = '';
+    for (const raw of body.split('\n')) {
+        const trimmed = raw.trim();
+        const fence = /^(`{3,}|~{3,})/.exec(trimmed);
+        if (fence) {
+            if (!inFence) {
+                inFence = true;
+                fenceMarker = fence[1][0];
+            }
+            else if (fence[1][0] === fenceMarker) {
+                inFence = false;
+            }
+            continue;
+        }
+        if (inFence)
+            continue;
+        // A list item is often the first real sentence in a reference file. Judge
+        // the text, not the bullet.
+        const unlisted = trimmed.replace(/^(?:[-*+]|\d+[.)])\s+/, '');
+        if (!isProse(trimmed, unlisted))
+            continue;
+        if (unlisted.length > 10 && unlisted.length < 300)
+            return unlisted.slice(0, 200);
+    }
+    return '';
+}
+function stripFrontmatter(content) {
+    return content.replace(/^?---\r?\n[\s\S]*?\r?\n---\s*(?:\r?\n|$)/, '');
+}
+/**
+ * Is this line a sentence a human wrote about the subject?
+ *
+ * Everything rejected here was observed as a live description in the 5,850-row
+ * registry: markdown tables ("| Error | Resolution |"), link indexes
+ * ("- [Overview](...)"), shell and import lines, HTML, badges, block quotes.
+ */
+function isProse(trimmed, unlisted = trimmed) {
+    if (!trimmed)
+        return false;
+    if (trimmed.startsWith('#'))
+        return false;
+    if (trimmed.startsWith('---') || trimmed.startsWith('===') || /^\*{3,}$/.test(trimmed))
+        return false;
+    if (trimmed.startsWith('|') || /^\+?[-:| ]+\+?$/.test(trimmed))
+        return false;
+    if (trimmed.startsWith('<'))
+        return false;
+    if (trimmed.startsWith('>'))
+        return false;
+    if (/^!\[/.test(trimmed))
+        return false;
+    if (/^[-*+]\s*\[/.test(trimmed))
+        return false;
+    if (/^\d+\.\s*\[/.test(trimmed))
+        return false;
+    // Code that happens to sit outside a fence.
+    if (/^(import|from|const|let|var|function|class|def|return|export|package|using|#include)\b/.test(trimmed))
+        return false;
+    if (/^(npm|npx|pnpm|yarn|pip|pip3|uv|cargo|go|git|docker|kubectl|brew|apt|curl|bash|sh|make)\s/.test(trimmed))
+        return false;
+    if (/^[$>][\s]/.test(trimmed))
+        return false;
+    if (/^[\w.]+\s*[:=]\s*[[{]/.test(trimmed))
+        return false;
+    if (/[;{}]\s*$/.test(trimmed))
+        return false;
+    if (/^@\w/.test(trimmed))
+        return false;
+    // Markup that survived outside a fence: JSX/HTML attributes, template
+    // expressions, arrow functions. `}} src={logo.lightSrc} alt={logo.name} />`
+    // was a live description.
+    if (/=>|=\{|\/>|\}\}|\$\{/.test(trimmed))
+        return false;
+    // A section label rather than a sentence: "**PowerShell:**", "JS-specific:",
+    // "**function.json:**". Ends in a colon and says nothing after it.
+    if (/:$/.test(unlisted) && unlisted.replace(/[*`_:]/g, '').trim().split(/\s+/).length <= 4)
+        return false;
+    // A bolded key with a code value — "**SDK/package**: `azure-ai-contentsafety`"
+    // is a fact about the file, not a description of it.
+    if (/^\*\*[^*]{1,40}\*\*:\s*[`<]/.test(unlisted))
+        return false;
+    // Mostly punctuation: a sentence needs words.
+    const words = unlisted.replace(/[`*_[\]()<>{}|#]/g, ' ').trim().split(/\s+/).filter((w) => /[a-z]{2}/i.test(w));
+    if (words.length < 4)
+        return false;
+    // A bare key: value line — frontmatter that escaped a malformed block, or a
+    // config sample. "name: Backend Developer" was a live description on 1,894
+    // entries.
+    if (/^[a-z][\w-]{0,30}:\s*\S/i.test(trimmed) && !/\s/.test(trimmed.split(':')[0]))
+        return false;
+    return true;
+}
+/** Directories whose contents support a skill rather than being one. */
+const SUPPORT_DIR = /(^|\/)(references?|resources?|examples?|assets?|templates?|schemas?|fixtures?|img|images|screenshots?)\//i;
+/** Directories that are machinery, not publishable content. */
+const FURNITURE_DIR = /(^|\/)(evals?|tests?|__tests__|node_modules|\.github\/workflows|dist|build|coverage)\//i;
+/** Repo furniture: present in every repo, about the repo, never a skill. */
+const FURNITURE_FILE = /^(license|licence|changelog|contributing|code_of_conduct|security|notice|authors|maintainers|governance|support|funding|history|upgrading|migration|todo)$/i;
+/**
+ * Decide whether a matched file is a skill, supporting material for one, or
+ * repo furniture.
+ *
+ * The patterns in sources.ts are as broad as `**\/*.md` for most repos, so this
+ * is the only thing standing between "every markdown file in 379 repos" and
+ * the catalog the adoption loop proposes from. Measured 2026-08-25: 3,099 of
+ * 5,850 entries lived in a support directory and 543 of trailofbits/skills'
+ * 543 entries were reference files, eval graders and agent definitions — not
+ * one of its actual skills.
+ */
+export function classifyEntry(filePath, content, frontmatter) {
+    const base = path.basename(filePath, path.extname(filePath));
+    const fm = frontmatter ?? parseFrontmatter(content);
+    if (FURNITURE_FILE.test(base))
+        return { kind: 'furniture', reason: `repo furniture (${base})` };
+    if (FURNITURE_DIR.test(filePath))
+        return { kind: 'furniture', reason: 'build/test/eval machinery' };
+    // A declared skill is a skill wherever it lives. The format's whole point is
+    // that the author says so; second-guessing a file that carries both fields
+    // is how a real skill gets thrown away.
+    if (fm.name && fm.description)
+        return { kind: 'skill', reason: 'declares name + description' };
+    if (/^skill$/i.test(base))
+        return { kind: 'skill', reason: 'SKILL.md' };
+    if (SUPPORT_DIR.test(filePath))
+        return { kind: 'supporting', reason: 'lives in a support directory' };
+    return { kind: 'skill', reason: 'standalone document' };
+}
+/**
+ * The stable half of an entry's id: `<repo-short>--<basename>`.
+ *
+ * Kept exactly as it was. 5,850 live ids have this shape, they are embedded in
+ * `instructions.name` as `skills--<id>` and in on-disk skill directories, so
+ * moving them would orphan every adopted skill. Collisions are resolved by
+ * ADDING qualified ids for the files that currently lose, never by renaming
+ * the file that currently wins.
+ */
+export function baseId(repo, filePath) {
+    const repoShort = repo.split('/').pop() ?? repo;
+    return `${repoShort}--${slug(path.basename(filePath, path.extname(filePath)))}`;
+}
+/** Files whose own name says nothing — the directory is the skill's name. */
+const DIRECTORY_SHAPED = /^(skill|readme|index|agents|main)$/i;
+/**
+ * Progressively more qualified ids for the same file, most-preferred first.
+ *
+ * For a directory-shaped skill (`skills/lang-python/SKILL.md`) the directory
+ * is the identity: every such file otherwise asks for `<repo>--skill`, which
+ * names nothing and which only one file per repo can hold.
+ */
+export function idCandidates(repo, filePath) {
+    const [owner, name] = splitRepo(repo);
+    const short = name;
+    const rawBase = path.basename(filePath, path.extname(filePath));
+    const parentDir = slug(path.basename(path.dirname(filePath)));
+    const base = DIRECTORY_SHAPED.test(rawBase) && parentDir ? parentDir : slug(rawBase);
+    const parent = base === parentDir ? '' : parentDir;
+    const candidates = [`${short}--${base}`];
+    if (parent && parent !== base && parent !== '.')
+        candidates.push(`${short}--${parent}-${base}`);
+    candidates.push(`${slug(owner)}-${short}--${base}`);
+    if (parent && parent !== base && parent !== '.')
+        candidates.push(`${slug(owner)}-${short}--${parent}-${base}`);
+    candidates.push(`${slug(owner)}-${short}--${slug(stripExt(filePath))}`);
+    return candidates.map((c) => c.slice(0, 160));
+}
+function splitRepo(repo) {
+    const parts = repo.split('/');
+    return parts.length > 1 ? [parts[0], parts[parts.length - 1]] : ['', repo];
+}
+function stripExt(filePath) {
+    return filePath.slice(0, filePath.length - path.extname(filePath).length);
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+/**
+ * Rank for deciding which file keeps the unqualified id when several want it.
+ *
+ * Lower wins. Assignment must not depend on which network request returned
+ * first: ids reached production through a `Promise.all` race, so a skill's id
+ * — and therefore the identity of any instruction row adopted from it — could
+ * change between two builds that saw identical repos.
+ */
+export function preferenceRank(kind, filePath, frontmatter) {
+    if (kind === 'furniture')
+        return 4;
+    if (kind === 'supporting')
+        return 3;
+    if (frontmatter.name && frontmatter.description)
+        return 0;
+    if (/^skill$/i.test(path.basename(filePath, path.extname(filePath))))
+        return 1;
+    return 2;
+}
+//# sourceMappingURL=entry-identity.js.map

package/dist/entry-identity.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entry-identity.test.d.ts.map

package/dist/entry-identity.test.js

@@ -0,0 +1,229 @@
+import { describe, it, expect } from 'vitest';
+import { parseFrontmatter, extractDescription, deriveName, classifyEntry, baseId, idCandidates, preferenceRank, } from './entry-identity.js';
+/**
+ * Every case below was taken from the live 5,850-entry registry on 2026-08-25.
+ * The package had no tests until this file; each of these shipped.
+ */
+describe('parseFrontmatter', () => {
+    it('reads the description an author declared', () => {
+        const fm = parseFrontmatter('---\nname: Backend Developer\ndescription: FastAPI/Python specialist\n---\n\n# Hi\n');
+        expect(fm.name).toBe('Backend Developer');
+        expect(fm.description).toBe('FastAPI/Python specialist');
+    });
+    it('reads a block scalar rather than its marker', () => {
+        // Live entry skills--create-foundry-project was described as "|".
+        const fm = parseFrontmatter('---\nname: foundry-create-project\ndescription: |\n  Scaffold a Foundry project\n  with the standard layout.\n---\n');
+        expect(fm.description).toBe('Scaffold a Foundry project with the standard layout.');
+    });
+    it('strips quotes', () => {
+        expect(parseFrontmatter('---\ndescription: "Quoted thing"\n---\n').description).toBe('Quoted thing');
+    });
+    it('returns nothing when there is no frontmatter', () => {
+        expect(parseFrontmatter('# Title\n\nSome prose.\n')).toEqual({});
+    });
+    it('does not throw on malformed frontmatter', () => {
+        expect(() => parseFrontmatter('---\n: : :\n')).not.toThrow();
+    });
+});
+describe('extractDescription', () => {
+    it('prefers the declared description over the first prose line', () => {
+        const content = '---\nname: x\ndescription: The declared one\n---\n\nThe first prose line, which is not it.\n';
+        expect(extractDescription(content)).toBe('The declared one');
+    });
+    it('never returns a line from inside a fenced code block', () => {
+        // skills--lang-python shipped to real projects described as
+        // "def append_to(item, target=[]):".
+        const content = [
+            '# Python Sharp Edges',
+            '',
+            '## Mutable Default Arguments',
+            '',
+            '```python',
+            '# DANGEROUS: Default is shared across all calls',
+            'def append_to(item, target=[]):',
+            '    target.append(item)',
+            '```',
+            '',
+            'Mutable default arguments are evaluated once at definition time.',
+        ].join('\n');
+        expect(extractDescription(content)).toBe('Mutable default arguments are evaluated once at definition time.');
+    });
+    it('does not return a markdown table row', () => {
+        const content = '# Errors\n\n| Error | Resolution |\n| --- | --- |\n| ENOENT | check the path |\n\nCommon failures and how to recover from them.\n';
+        expect(extractDescription(content)).toBe('Common failures and how to recover from them.');
+    });
+    it('does not return a link index entry', () => {
+        const content = '# Home\n\n- [Overview](https://agentskills.io/home.md): A simple format\n\nAn index of the available guides.\n';
+        expect(extractDescription(content)).toBe('An index of the available guides.');
+    });
+    it('does not return a bare key: value line', () => {
+        // 1,894 entries were described with their own frontmatter "name:" line.
+        const content = '---\nname: Backend Developer\n---\n\nname: Backend Developer\n\nA specialist for backend work.\n';
+        expect(extractDescription(content)).toBe('A specialist for backend work.');
+    });
+    it('does not return a shell or import line that sits outside a fence', () => {
+        const content = '# Setup\n\nnpm i @microsoft/applicationinsights-react-js history\n\nWire the SDK into a React application.\n';
+        expect(extractDescription(content)).toBe('Wire the SDK into a React application.');
+    });
+    it('returns empty rather than inventing a description from the file name', () => {
+        expect(extractDescription('# Title\n\n```\ncode\n```\n')).toBe('');
+    });
+    it('does not return JSX or template markup that escaped a fence', () => {
+        const content = '# Logos\n\n}} src={logo.lightSrc} alt={logo.name} />\n\nRenders the brand logo for the current theme.\n';
+        expect(extractDescription(content)).toBe('Renders the brand logo for the current theme.');
+    });
+    it('does not return a bare section label', () => {
+        const content = '# Functions\n\n**PowerShell:**\n\nBindings are declared in function.json for each language.\n';
+        expect(extractDescription(content)).toBe('Bindings are declared in function.json for each language.');
+    });
+    it('does not return a bolded key with a code value', () => {
+        const content = '# SDK\n\n**SDK/package**: `azure-ai-contentsafety`\n\nDetect harmful content in text and images.\n';
+        expect(extractDescription(content)).toBe('Detect harmful content in text and images.');
+    });
+    it('keeps a sentence that happens to be a list item, without its bullet', () => {
+        const content = '# Auth\n\n- Auth uses a subscription key string rather than a credential object.\n';
+        expect(extractDescription(content)).toBe('Auth uses a subscription key string rather than a credential object.');
+    });
+    it('requires a sentence, not a handful of symbols', () => {
+        expect(extractDescription('# X\n\n`a` | `b`\n')).toBe('');
+    });
+});
+describe('deriveName', () => {
+    it('prefers the declared name', () => {
+        expect(deriveName('skills/x/SKILL.md', { name: 'azure-kusto-graph' })).toBe('azure-kusto-graph');
+    });
+    it('names a directory-shaped skill after its directory, not "Skill"', () => {
+        expect(deriveName('plugins/p/skills/sharp-edges/SKILL.md')).toBe('Sharp Edges');
+    });
+    it('titles a flat file from its basename', () => {
+        expect(deriveName('skills/lang-python.md')).toBe('Lang Python');
+    });
+});
+describe('classifyEntry', () => {
+    it('treats a reference sub-file as supporting material', () => {
+        const p = 'plugins/sharp-edges/skills/sharp-edges/references/lang-python.md';
+        expect(classifyEntry(p, '# Python Sharp Edges\n').kind).toBe('supporting');
+    });
+    it('treats eval graders as furniture', () => {
+        const p = 'plugins/audit-context-building/evals/contract-continuity/graders/unchecked-credit-path.md';
+        expect(classifyEntry(p, '# Grader\n').kind).toBe('furniture');
+    });
+    it('treats repo furniture as furniture', () => {
+        expect(classifyEntry('CHANGELOG.md', '# Changelog\n').kind).toBe('furniture');
+        expect(classifyEntry('docs/CONTRIBUTING.md', '# Contributing\n').kind).toBe('furniture');
+    });
+    it('keeps a declared skill even inside a support directory', () => {
+        const p = 'skills/a/references/real-skill.md';
+        const content = '---\nname: real-skill\ndescription: Does a real thing\n---\n';
+        expect(classifyEntry(p, content).kind).toBe('skill');
+    });
+    it('keeps SKILL.md', () => {
+        expect(classifyEntry('plugins/p/skills/s/SKILL.md', '# S\n').kind).toBe('skill');
+    });
+    it('keeps a standalone document', () => {
+        expect(classifyEntry('skills/tdd-workflow.md', '# TDD\n').kind).toBe('skill');
+    });
+});
+describe('id assignment', () => {
+    it('keeps the historical id shape', () => {
+        expect(baseId('trailofbits/skills', 'a/b/lang-python.md')).toBe('skills--lang-python');
+    });
+    it('offers the historical id first so existing entries never move', () => {
+        expect(idCandidates('trailofbits/skills', 'a/b/lang-python.md')[0]).toBe('skills--lang-python');
+    });
+    it('identifies a directory-shaped skill by its directory', () => {
+        // Every SKILL.md in every repo named "skills" wanted the single id
+        // "skills--skill"; all but the first were dropped with no log line.
+        const a = idCandidates('trailofbits/skills', 'plugins/p/skills/sharp-edges/SKILL.md');
+        const b = idCandidates('microsoft/skills', 'plugins/q/skills/kusto/SKILL.md');
+        expect(a[0]).toBe('skills--sharp-edges');
+        expect(b[0]).toBe('skills--kusto');
+        expect(a[0]).not.toBe(b[0]);
+    });
+    it('still resolves a genuine collision between two repos', () => {
+        // Same skill name, two of the four repos called "skills".
+        const a = idCandidates('trailofbits/skills', 'skills/testing/SKILL.md');
+        const b = idCandidates('microsoft/skills', 'skills/testing/SKILL.md');
+        expect(a[0]).toBe(b[0]);
+        const fallbacks = [...a.slice(1), ...b.slice(1)];
+        expect(new Set(fallbacks).size).toBe(fallbacks.length);
+    });
+    it('distinguishes two files in one repo that share a basename', () => {
+        const a = idCandidates('x/skills', 'skills/alpha/SKILL.md');
+        const b = idCandidates('x/skills', 'skills/beta/SKILL.md');
+        expect(a[1]).not.toBe(b[1]);
+    });
+    it('ranks a declared skill above supporting material for the plain id', () => {
+        const skill = preferenceRank('skill', 'skills/s/SKILL.md', { name: 'n', description: 'd' });
+        const support = preferenceRank('supporting', 'skills/s/references/r.md', {});
+        expect(skill).toBeLessThan(support);
+    });
+    it('ranks SKILL.md above a standalone document', () => {
+        expect(preferenceRank('skill', 'a/SKILL.md', {})).toBeLessThan(preferenceRank('skill', 'a/notes.md', {}));
+    });
+});
+describe('assignIds (via the shape it must guarantee)', () => {
+    it('gives every colliding file an id instead of dropping all but one', async () => {
+        const { assignIds } = await import('./github-fetcher.js');
+        const draft = (repo, p, rank) => ({
+            id: '', name: '', description: '', category: 'other', tags: [], tools: ['claude_code'],
+            source: { repo, path: p, url: '', license: 'MIT' }, content: '', updatedAt: '',
+            _idCandidates: idCandidates(repo, p), _rank: rank,
+        });
+        // All four repos are named "skills" and all four ship a "testing" skill.
+        const drafts = [
+            draft('trailofbits/skills', 'plugins/a/skills/testing/SKILL.md', 1),
+            draft('microsoft/skills', 'plugins/b/skills/testing/SKILL.md', 1),
+            draft('browser-act/skills', 'skills/testing/SKILL.md', 1),
+            draft('wondelai/skills', 'skills/testing/SKILL.md', 1),
+        ];
+        const { entries, collisions } = assignIds(drafts);
+        expect(entries).toHaveLength(4);
+        expect(new Set(entries.map((e) => e.id)).size).toBe(4);
+        expect(collisions).toBe(3);
+    });
+    it('is deterministic regardless of the order sources returned', async () => {
+        const { assignIds } = await import('./github-fetcher.js');
+        const draft = (repo, p, rank) => ({
+            id: '', name: '', description: '', category: 'other', tags: [], tools: ['claude_code'],
+            source: { repo, path: p, url: '', license: 'MIT' }, content: '', updatedAt: '',
+            _idCandidates: idCandidates(repo, p), _rank: rank,
+        });
+        const a = draft('trailofbits/skills', 'shared/SKILL.md', 1);
+        const b = draft('microsoft/skills', 'shared/SKILL.md', 1);
+        const forward = assignIds([a, b]).entries.map((e) => `${e.source.repo}=${e.id}`).sort();
+        const reverse = assignIds([b, a]).entries.map((e) => `${e.source.repo}=${e.id}`).sort();
+        expect(forward).toEqual(reverse);
+    });
+    it('gives the plain id to the real skill, not to its reference file', async () => {
+        const { assignIds } = await import('./github-fetcher.js');
+        const mk = (p, rank) => ({
+            id: '', name: '', description: '', category: 'other', tags: [], tools: ['claude_code'],
+            source: { repo: 'trailofbits/skills', path: p, url: '', license: 'MIT' }, content: '', updatedAt: '',
+            _idCandidates: idCandidates('trailofbits/skills', p), _rank: rank,
+        });
+        const skill = mk('plugins/p/skills/lang-python/SKILL.md', 0);
+        const reference = mk('plugins/p/skills/sharp-edges/references/lang-python.md', 3);
+        const { entries } = assignIds([reference, skill]);
+        const byPath = new Map(entries.map((e) => [e.source.path, e.id]));
+        expect(byPath.get('plugins/p/skills/lang-python/SKILL.md')).toBe('skills--lang-python');
+        expect(byPath.get('plugins/p/skills/sharp-edges/references/lang-python.md')).not.toBe('skills--lang-python');
+    });
+});
+describe('scoreRecency', () => {
+    it('scores the source commit date, not the build timestamp', async () => {
+        const { computeQualityScore } = await import('./scoring.js');
+        const base = {
+            id: 'x', name: 'x', description: 'a description long enough to count', category: 'other',
+            tags: ['a'], tools: ['claude_code'], source: { repo: 'a/b', path: 'c.md', url: '', license: 'MIT' },
+            content: '# x\n\nsome content here\n',
+        };
+        const old = new Date(Date.now() - 800 * 86_400_000).toISOString();
+        const fresh = new Date().toISOString();
+        // Same build, very different source ages — the factor must separate them.
+        const stale = computeQualityScore({ ...base, updatedAt: fresh, sourceUpdatedAt: old });
+        const current = computeQualityScore({ ...base, updatedAt: fresh, sourceUpdatedAt: fresh });
+        expect(stale.factors.recency).toBeLessThan(current.factors.recency);
+    });
+});
+//# sourceMappingURL=entry-identity.test.js.map

package/dist/fetch-registry.js

@@ -67,7 +67,7 @@ async function main() {
     console.log(`Fetching skills from ${sources.length} sources${includeAll ? ' (Tier 1 + 2)' : ' (Tier 1)'}...\n`);
     const previousShas = loadPreviousShas();
     const previousEntriesByRepo = loadPreviousEntriesByRepo();
-    const { entries: freshEntries, treeShas } = await fetchAllSources(sources, {
+    const { entries: freshEntries, treeShas, collisions, dropped } = await fetchAllSources(sources, {
         previousShas,
         onProgress: (source, count, skipped) => {
             if (skipped) {
@@ -165,6 +165,31 @@ async function main() {
     }
     console.log('\nBy tool:', Object.fromEntries(byTool));
     console.log('By category:', Object.fromEntries(byCat));
+    const byKind = new Map();
+    for (const s of entries)
+        byKind.set(s.kind ?? 'skill', (byKind.get(s.kind ?? 'skill') ?? 0) + 1);
+    console.log('By kind:', Object.fromEntries(byKind));
+    // What this build refused, and why. Both numbers were previously invisible:
+    // a colliding entry was dropped by `if (!seenIds.has(id))` with no counter,
+    // which is how the registry came to hold 5,850 entries and 18 SKILL.md files
+    // while reporting a clean run every time.
+    console.log(`\nId collisions resolved with a qualified id: ${collisions}`);
+    if (dropped.length > 0) {
+        const byReason = new Map();
+        for (const d of dropped)
+            byReason.set(d.reason, (byReason.get(d.reason) ?? 0) + 1);
+        console.log(`Rejected as machinery: ${dropped.length}`);
+        for (const [reason, n] of [...byReason].sort((a, b) => b[1] - a[1])) {
+            console.log(`  ${String(n).padStart(5)}  ${reason}`);
+        }
+    }
+    const undescribed = entries.filter((s) => !s.description).length;
+    if (undescribed > 0) {
+        // Reported rather than papered over. An entry with no describable prose is
+        // a fact about the source file; inventing a description from its file name
+        // is what produced `def append_to(item, target=[]):`.
+        console.log(`\nEntries with no extractable description: ${undescribed}`);
+    }
 }
 main().catch(err => {
     console.error('Fatal:', err);

package/dist/github-fetcher.d.ts

@@ -19,9 +19,26 @@ export declare function shouldRetrySecondaryRateLimit(retryAfterSeconds: number)
  */
 export declare function _resetOctokitForTests(): void;
 export interface FetchSourceResult {
-    entries: SkillEntry[];
+    entries: DraftEntry[];
     treeSha: string | null;
     skipped: boolean;
+    /** Files matched by the patterns but rejected as machinery, with the reason.
+     *  Counted rather than silently skipped — a pattern that starts sweeping up
+     *  a repo's CI directory should be visible in the build log. */
+    dropped: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+/**
+ * An entry before its id is final.
+ *
+ * `_idCandidates` and `_rank` exist only between fetch and id assignment; they
+ * are stripped before the entry is written to the registry.
+ */
+export interface DraftEntry extends SkillEntry {
+    _idCandidates: string[];
+    _rank: number;
 }
 /**
  * Fetch all skills from a single registry source.
@@ -42,7 +59,43 @@ export interface FetchAllResult {
     entries: SkillEntry[];
     /** Map of repo → current tree SHA, for caching across runs. */
     treeShas: Map<string, string>;
+    /** How many entries needed a qualified id. Reported, never silent. */
+    collisions: number;
+    /** Files rejected as machinery, with the reason. */
+    dropped: Array<{
+        path: string;
+        reason: string;
+    }>;
 }
-/** Fetch skills from multiple sources, in parallel, deduplicating by id. */
+/**
+ * Assign a final, unique id to every drafted entry.
+ *
+ * Two properties matter, and neither held before:
+ *
+ * 1. **Deterministic.** Ids used to be handed out first-come inside a
+ *    `Promise.all` race, so which of two colliding files kept the plain id
+ *    depended on which HTTP response landed first. An entry's id is the
+ *    identity of the `instructions` row adopted from it, so a build could
+ *    silently re-point an adopted skill. Sorting by (rank, repo, path) makes
+ *    the outcome a function of the inputs alone.
+ *
+ * 2. **Total.** The loser of a collision used to be dropped — no entry, no
+ *    log. `deriveId` was `<repo-short>--<basename>`, which ignores the
+ *    directory AND the repo owner, so all four repos named `skills` and all
+ *    nine named `cursorrules` shared one namespace, and every `SKILL.md`
+ *    anywhere in a repo wanted the single id `<repo>--skill`. Measured
+ *    2026-08-25: the registry held 5,850 entries and just 18 SKILL.md files;
+ *    trailofbits/skills contributed 543 entries, of which none were its
+ *    actual skills — they had all collided into one id and been discarded,
+ *    leaving only the `references/` files behind them.
+ *
+ * Ranking puts declared skills ahead of supporting material, so where a real
+ * skill and one of its reference files compete, the skill keeps the plain id.
+ */
+export declare function assignIds(drafts: DraftEntry[]): {
+    entries: SkillEntry[];
+    collisions: number;
+};
+/** Fetch skills from multiple sources in parallel. */
 export declare function fetchAllSources(sources: RegistrySource[], options?: FetchAllOptions): Promise<FetchAllResult>;
 //# sourceMappingURL=github-fetcher.d.ts.map

package/dist/github-fetcher.js

@@ -3,6 +3,7 @@ import { Octokit } from 'octokit';
 import { retry } from '@octokit/plugin-retry';
 import { throttling } from '@octokit/plugin-throttling';
 import pLimit from 'p-limit';
+import { parseFrontmatter, extractDescription, deriveName, classifyEntry, idCandidates, preferenceRank, } from './entry-identity.js';
 // ── HTTP layer ───────────────────────────────────────────────────────────────
 const GITHUB_RAW = 'https://raw.githubusercontent.com';
 const USER_AGENT = 'rulemetric-skills-registry';
@@ -222,29 +223,6 @@ function patternToRegex(pattern) {
         .replace(/<<GLOBSTAR>>/g, '.*');
     return new RegExp(`^${escaped}$`);
 }
-function deriveId(repo, filePath) {
-    const repoShort = repo.split('/').pop() ?? repo;
-    const name = path.basename(filePath, path.extname(filePath))
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-|-$/g, '');
-    return `${repoShort}--${name}`;
-}
-function deriveName(filePath) {
-    const name = path.basename(filePath, path.extname(filePath));
-    return name.replace(/[-_]+/g, ' ').replace(/\b\w/g, c => c.toUpperCase()).trim();
-}
-function extractDescription(content) {
-    const lines = content.split('\n');
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('---') || trimmed.startsWith('```'))
-            continue;
-        if (trimmed.length > 10 && trimmed.length < 300)
-            return trimmed.slice(0, 200);
-    }
-    return deriveName(lines[0] ?? '');
-}
 function inferCategory(filePath, content) {
     const lower = (filePath + ' ' + content.slice(0, 500)).toLowerCase();
     if (/\btest|tdd|vitest|jest|pytest\b/.test(lower))
@@ -311,9 +289,9 @@ const FILE_CONCURRENCY = pLimit(8);
 export async function fetchSource(source, previousTreeSha) {
     const meta = await fetchRepoMeta(source.repo);
     if (!meta)
-        return { entries: [], treeSha: null, skipped: false };
+        return { entries: [], treeSha: null, skipped: false, dropped: [] };
     if (previousTreeSha && previousTreeSha === meta.treeSha) {
-        return { entries: [], treeSha: meta.treeSha, skipped: true };
+        return { entries: [], treeSha: meta.treeSha, skipped: true, dropped: [] };
     }
     const branch = source.branch ?? meta.defaultBranch;
     const tree = await fetchTree(source.repo, meta.treeSha);
@@ -325,15 +303,24 @@ export async function fetchSource(source, previousTreeSha) {
             return false;
         return matchesPatterns(item.path, source.patterns);
     });
+    const dropped = [];
     const entries = await Promise.all(matchedFiles.map(file => FILE_CONCURRENCY(async () => {
         const url = `${GITHUB_RAW}/${source.repo}/${branch}/${file.path}`;
         const result = await fetchRaw(url);
         if (!result.body || result.body.trim().length < 20)
             return null;
         const content = result.body;
-        const id = deriveId(source.repo, file.path);
-        const name = deriveName(file.path);
-        const description = extractDescription(content);
+        const frontmatter = parseFrontmatter(content);
+        const classification = classifyEntry(file.path, content, frontmatter);
+        // Machinery — eval graders, CI config, CHANGELOG — is not content
+        // anybody would adopt. Dropped here rather than scored low, because a
+        // low score still leaves it reachable by search and by nomination.
+        if (classification.kind === 'furniture') {
+            dropped.push({ path: file.path, reason: classification.reason });
+            return null;
+        }
+        const name = deriveName(file.path, frontmatter);
+        const description = extractDescription(content, frontmatter);
         const category = inferCategory(file.path, content);
         const tags = inferTags(file.path, content);
         const languages = inferLanguages(content);
@@ -342,7 +329,12 @@ export async function fetchSource(source, previousTreeSha) {
         // error), so the field is populated even on a degraded run.
         const sourceUpdatedAt = (await fetchFileCommitDate(source.repo, file.path)) ?? meta.pushedAt ?? undefined;
         return {
-            id,
+            // Provisional. Final ids are assigned across all sources at once so
+            // two repos racing for the same id cannot decide it between them.
+            id: idCandidates(source.repo, file.path)[0],
+            _idCandidates: idCandidates(source.repo, file.path),
+            _rank: preferenceRank(classification.kind, file.path, frontmatter),
+            kind: classification.kind,
             name,
             description,
             category: category !== 'other' ? category : source.defaultCategory,
@@ -365,26 +357,77 @@ export async function fetchSource(source, previousTreeSha) {
         entries: entries.filter((e) => e !== null),
         treeSha: meta.treeSha,
         skipped: false,
+        dropped,
     };
 }
 const SOURCE_CONCURRENCY = pLimit(4);
-/** Fetch skills from multiple sources, in parallel, deduplicating by id. */
+/**
+ * Assign a final, unique id to every drafted entry.
+ *
+ * Two properties matter, and neither held before:
+ *
+ * 1. **Deterministic.** Ids used to be handed out first-come inside a
+ *    `Promise.all` race, so which of two colliding files kept the plain id
+ *    depended on which HTTP response landed first. An entry's id is the
+ *    identity of the `instructions` row adopted from it, so a build could
+ *    silently re-point an adopted skill. Sorting by (rank, repo, path) makes
+ *    the outcome a function of the inputs alone.
+ *
+ * 2. **Total.** The loser of a collision used to be dropped — no entry, no
+ *    log. `deriveId` was `<repo-short>--<basename>`, which ignores the
+ *    directory AND the repo owner, so all four repos named `skills` and all
+ *    nine named `cursorrules` shared one namespace, and every `SKILL.md`
+ *    anywhere in a repo wanted the single id `<repo>--skill`. Measured
+ *    2026-08-25: the registry held 5,850 entries and just 18 SKILL.md files;
+ *    trailofbits/skills contributed 543 entries, of which none were its
+ *    actual skills — they had all collided into one id and been discarded,
+ *    leaving only the `references/` files behind them.
+ *
+ * Ranking puts declared skills ahead of supporting material, so where a real
+ * skill and one of its reference files compete, the skill keeps the plain id.
+ */
+export function assignIds(drafts) {
+    const ordered = [...drafts].sort((a, b) => a._rank - b._rank
+        || a.source.repo.localeCompare(b.source.repo)
+        || a.source.path.localeCompare(b.source.path));
+    const taken = new Set();
+    const entries = [];
+    let collisions = 0;
+    for (const draft of ordered) {
+        const candidates = draft._idCandidates;
+        let id = candidates.find((candidate) => !taken.has(candidate));
+        if (!id) {
+            // Every qualified form is taken too — fall back to the full path, which
+            // is unique within a repo by construction.
+            collisions++;
+            let n = 2;
+            const stem = candidates[candidates.length - 1];
+            while (taken.has(`${stem}-${n}`))
+                n++;
+            id = `${stem}-${n}`;
+        }
+        else if (id !== candidates[0]) {
+            collisions++;
+        }
+        taken.add(id);
+        const { _idCandidates, _rank, ...entry } = draft;
+        entries.push({ ...entry, id });
+    }
+    return { entries, collisions };
+}
+/** Fetch skills from multiple sources in parallel. */
 export async function fetchAllSources(sources, options = {}) {
-    const allEntries = [];
-    const seenIds = new Set();
+    const drafts = [];
     const treeShas = new Map();
+    const dropped = [];
     await Promise.all(sources.map(source => SOURCE_CONCURRENCY(async () => {
         try {
             const previous = options.previousShas?.get(source.repo);
             const result = await fetchSource(source, previous);
             if (result.treeSha)
                 treeShas.set(source.repo, result.treeSha);
-            for (const entry of result.entries) {
-                if (!seenIds.has(entry.id)) {
-                    seenIds.add(entry.id);
-                    allEntries.push(entry);
-                }
-            }
+            drafts.push(...result.entries);
+            dropped.push(...result.dropped);
             options.onProgress?.(source.repo, result.entries.length, result.skipped);
         }
         catch (err) {
@@ -392,6 +435,7 @@ export async function fetchAllSources(sources, options = {}) {
             options.onProgress?.(source.repo, 0, false);
         }
     })));
-    return { entries: allEntries, treeShas };
+    const { entries, collisions } = assignIds(drafts);
+    return { entries, treeShas, collisions, dropped };
 }
 //# sourceMappingURL=github-fetcher.js.map

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { fetchSource, fetchAllSources, shouldRetryRateLimit, shouldRetrySecondar
 export { TIER_1_SOURCES, TIER_2_SOURCES } from './sources.js';
 export { loadDiscoveredSources } from './discovered.js';
 export { computeQualityScore, type QualityScore } from './scoring.js';
+export { parseFrontmatter, extractDescription, deriveName, classifyEntry, baseId, idCandidates, preferenceRank, type SkillFrontmatter, type EntryKind, type EntryClassification, } from './entry-identity.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,4 +3,5 @@ export { fetchSource, fetchAllSources, shouldRetryRateLimit, shouldRetrySecondar
 export { TIER_1_SOURCES, TIER_2_SOURCES } from './sources.js';
 export { loadDiscoveredSources } from './discovered.js';
 export { computeQualityScore } from './scoring.js';
+export { parseFrontmatter, extractDescription, deriveName, classifyEntry, baseId, idCandidates, preferenceRank, } from './entry-identity.js';
 //# sourceMappingURL=index.js.map

package/dist/recompute.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recompute.d.ts.map

package/dist/recompute.js

@@ -0,0 +1,100 @@
+/**
+ * Re-derive entry metadata from content already in registry.json.
+ *
+ * A fix to `extractDescription` or `classifyEntry` only reaches the catalog on
+ * the next full crawl, which needs GitHub API budget and a clean rate-limit
+ * window. But `registry.json` already stores every file's `content`, so the
+ * derivation can simply be run again offline — no network, no quota, and the
+ * result is byte-comparable against what shipped.
+ *
+ * IDS ARE NEVER TOUCHED HERE. An entry's id is the identity of the
+ * `instructions` row synced from it and of any skill directory adopted from
+ * that row; re-assigning ids without the full crawl would orphan adopted
+ * skills to fix a description. Collision repair belongs to the crawl, which
+ * can see the files that were dropped.
+ *
+ *   pnpm --filter @rulemetric/skills-registry recompute [--write]
+ *
+ * Without `--write` it reports what would change and exits.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseFrontmatter, extractDescription, deriveName, classifyEntry } from './entry-identity.js';
+import { computeQualityScore } from './scoring.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const REGISTRY_PATH = path.resolve(here, '..', 'registry.json');
+const INDEX_PATH = path.resolve(here, '..', 'registry-index.json');
+function main() {
+    const write = process.argv.includes('--write');
+    const registry = JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf-8'));
+    const entries = registry.skills;
+    let descriptionsChanged = 0;
+    let namesChanged = 0;
+    let kindsSet = 0;
+    let nowUndescribed = 0;
+    const furniture = [];
+    const samples = [];
+    for (const entry of entries) {
+        const content = entry.content ?? '';
+        const filePath = entry.source?.path ?? '';
+        const frontmatter = parseFrontmatter(content);
+        const description = extractDescription(content, frontmatter);
+        if (description !== entry.description) {
+            descriptionsChanged++;
+            if (!description)
+                nowUndescribed++;
+            if (samples.length < 12 && description) {
+                samples.push(`  ${entry.id}\n     was: ${JSON.stringify((entry.description ?? '').slice(0, 70))}\n     now: ${JSON.stringify(description.slice(0, 70))}`);
+            }
+            entry.description = description;
+        }
+        const name = deriveName(filePath, frontmatter);
+        if (name !== entry.name) {
+            namesChanged++;
+            entry.name = name;
+        }
+        const classification = classifyEntry(filePath, content, frontmatter);
+        // Machinery is recorded but NOT removed here. Deleting rows is the crawl's
+        // job: the API sync upserts by id and has no delete path, so dropping an
+        // entry from this file would leave the row in the database with no way to
+        // notice. Reported so the next crawl's removal is expected.
+        if (classification.kind === 'furniture') {
+            furniture.push(entry.id);
+            entry.kind = 'supporting';
+        }
+        else if (entry.kind !== classification.kind) {
+            entry.kind = classification.kind;
+        }
+        if (entry.kind)
+            kindsSet++;
+        entry.qualityScore = computeQualityScore(entry);
+    }
+    const byKind = new Map();
+    for (const entry of entries)
+        byKind.set(entry.kind ?? 'skill', (byKind.get(entry.kind ?? 'skill') ?? 0) + 1);
+    console.log(`entries                  : ${entries.length}`);
+    console.log(`descriptions changed     : ${descriptionsChanged}`);
+    console.log(`  of which now empty     : ${nowUndescribed}  (no extractable prose — honest, and scored as such)`);
+    console.log(`names changed            : ${namesChanged}`);
+    console.log(`kind assigned            : ${kindsSet}`);
+    console.log(`by kind                  : ${JSON.stringify(Object.fromEntries(byKind))}`);
+    console.log(`machinery (flagged, removed on next crawl): ${furniture.length}`);
+    if (samples.length > 0)
+        console.log(`\nsample description changes:\n${samples.join('\n')}`);
+    if (!write) {
+        console.log('\nDry run. Pass --write to update registry.json and registry-index.json.');
+        return;
+    }
+    registry.generatedAt = new Date().toISOString();
+    fs.writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2));
+    const index = {
+        version: registry.version,
+        generatedAt: registry.generatedAt,
+        skills: entries.map(({ content, ...rest }) => rest),
+    };
+    fs.writeFileSync(INDEX_PATH, JSON.stringify(index, null, 2));
+    console.log(`\nWrote ${REGISTRY_PATH}\nWrote ${INDEX_PATH}`);
+}
+main();
+//# sourceMappingURL=recompute.js.map

package/dist/scoring.js

@@ -83,10 +83,24 @@ function scoreCompleteness(skill) {
         score += 3;
     return Math.min(25, score);
 }
+/**
+ * How recently the skill itself changed.
+ *
+ * `updatedAt` is the build timestamp — every entry in a build shares it, so
+ * scoring against it measures when we last scraped, not when the author last
+ * touched the file, and the factor drifts uniformly as the registry ages
+ * instead of discriminating between entries. `sourceUpdatedAt` is the file's
+ * most recent commit date and is populated on every entry (5,850/5,850,
+ * measured 2026-08-25). Prefer it; fall back only for entries built before
+ * that field existed.
+ */
 function scoreRecency(skill) {
-    if (!skill.updatedAt)
+    const stamp = skill.sourceUpdatedAt ?? skill.updatedAt;
+    if (!stamp)
+        return 0;
+    const updated = new Date(stamp);
+    if (Number.isNaN(updated.getTime()))
         return 0;
-    const updated = new Date(skill.updatedAt);
     const now = new Date();
     const daysSince = (now.getTime() - updated.getTime()) / (1000 * 60 * 60 * 24);
     if (daysSince <= 7)

package/dist/types.d.ts

@@ -22,6 +22,17 @@ export interface SkillEntry {
     frameworks?: string[];
     /** Where the skill content came from */
     source: SkillSource;
+    /**
+     * What this file is: a skill, or material that supports one.
+     *
+     * `supporting` marks reference files, examples and resources that live
+     * beside a skill — `references/lang-python.md` under the `sharp-edges`
+     * skill, say. They are worth keeping and searching, but they are not
+     * standalone skills, and proposing one for adoption puts a fragment of
+     * another skill's documentation into a real project. Absent on entries
+     * built before this field existed; treat undefined as 'skill'.
+     */
+    kind?: 'skill' | 'supporting';
     /** Raw content in available formats */
     content: string;
     /** Popularity metrics for ranking */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulemetric/skills-registry",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "publishConfig": {
     "access": "public"
   },
@@ -25,6 +25,10 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"
+    },
+    "./entry-identity": {
+      "types": "./dist/entry-identity.d.ts",
+      "default": "./dist/entry-identity.js"
     }
   },
   "dependencies": {
@@ -46,6 +50,8 @@
     "type-check": "tsc --noEmit",
     "fetch": "tsx src/fetch-registry.ts",
     "discover": "tsx src/discover-sources.ts",
-    "sync:api": "node scripts/sync-to-api.mjs"
+    "sync:api": "node scripts/sync-to-api.mjs",
+    "test": "vitest run",
+    "recompute": "tsx src/recompute.ts"
   }
 }