Clickable prototype in 48h

Content · Developer workflow

agent-skills-catalog

A public catalog of the Agent Skills you publish on GitHub, generated at build time from each skill's own files: install command, rules, releases, provenance and the newest agent eval result per prompt, with nothing retyped.

Repository
timerise-ai/agent-skills-catalog
Released
November 8, 2026
Build it with TimeriseBuild it yourself
npx skills add timerise-ai/agent-skills-catalog
Current release
v0.1.3
Reference docs
11
Non-negotiables
8
License
MIT

The problem

What problem does agent-skills-catalog solve?

An organization that publishes Agent Skills has the facts about them in two places: the repositories, where SKILL.md, the changelog and the eval runs live, and the website, where people read about them. The website copy drifts. A page says version 0.1.3 after 0.2.0 shipped, a rule is paraphrased until it means something else, and the eval run that failed last week never shows up.

A catalog page is a page about files that live somewhere else. It should say exactly what the repository says, at one commit, and nothing else.

This skill gives your coding agent the catalog the way we built ours at timerise.ai/skills: a sync that reads every file of a skill at one commit and swaps the copy in whole, a loader that reads rules, releases and the provenance ledger from those files and never fetches at build time, a catalog with search and a category filter, one page per category and per skill, the newest eval result per agent and prompt with failing runs included, JSON-LD and sitemap entries, and a validator that fails the tests on a malformed file instead of hiding it.

The module

What does the skill build?

An agent with this skill builds one module for a Next.js App Router app, on your stack. For agent-skills-catalog that module consists of:

  • 1. A sync that reads every file at one commit and swaps the copy in whole
  • 2. A loader that never fetches
  • 3. Catalog pages with search and a category filter
  • 4. One page per category and per skill
  • 5. The newest eval result per agent and prompt with failing runs included
  • 6. JSON-LD
  • 7. Sitemap entries
  • 8. A content validator

What it needs from you

  • Next.js App Router with React 19 and TypeScript.
  • Node 22 or later for the sync script.
  • gray-matter, react-markdown, remark-gfm, and vitest for the tests.
  • Skill repositories in the shared layout, or a SKILL_LAYOUT adjusted to theirs.

Provenance

Where do the rules come from?

This skill was written by the engineer who has shipped this module; the earlier implementation it was audited against was the skills catalog of a marketing site. The templates hold the idea above as verified properties: every file of a skill is read at the sha the sync records, a failed sync leaves the previous copy untouched, every eval file either renders or fails npm test with its reason, and each eval card shows the recorded result of the newest run per agent and prompt, failing runs included. The parser, eval and content suites cover each; references/provenance.md carries the record.

Written by the engineer who has shipped this module. The earlier implementation it was audited against was the public skills catalog of a marketing site: a sync script mirroring each skill repository into the site's repository, a loader generating a catalog page, category pages and one page per skill from those files, and the agent eval results of each skill. The architecture is that module's; the templates carry the changes the audit below records.

The ledger separates what the audit changed, what was kept on purpose, and what has not run in production yet.

  1. Fixed in the templates

    • A sync right after a release could mix two commits The earlier sync read each file from raw.githubusercontent.com by branch name and asked the API for the head commit afterwards. Branch-name raw URLs answer with cache-control: max-age=300, so within five minutes of a push the files could be the previous commit's while sync.json recorded the new sha, and the page said "generated from" a commit it was not generated from.
    • A file deleted upstream stayed on the site The optional references/provenance.md was written when present and skipped when it answered 404, never removed. A skill that moved its ledger into the changelog kept showing the old file's ledger.
    • A failure halfway through a sync emptied the evals folder The earlier sync deleted upstream/evals/ before fetching its files, and any non-404 answer after that threw. The folder was left empty or partial, and the next build showed a skill with no eval runs.
    • A missing head commit read as a success When the commits API failed, the earlier sync recorded commit: null and carried on, so a rate-limited sync looked like a good one with the "generated from" line missing.
    • A malformed eval run disappeared, and the test that guarded it could not fail The earlier parser returned null for a run it could not read, the loader filtered the nulls out, and the test "every committed run parses" iterated only the runs that had parsed. A run with a typo in agent: or a missing prompt: was never shown and never reported.
    Show 1 more
    • A skill without a README rules list showed its critical facts as its rules When the README had no non-negotiables list, the earlier loader fell back to the SKILL.md critical facts (with any list-style hard rules appended), and the page titled them "the rules the module never breaks". Hard rules written as blockquotes were not read at all.

  2. Kept deliberately

    • The run number decides the order within a day Sorting result files as text puts -p1.md after -p1-2.md. runNumber reads the suffix; it looks like an avoidable helper and is not.
    • The newest run is chosen per agent and prompt text Prompts with results are never reworded, so the text identifies a prompt across renumbering, while promptIndex only records a position.
    • sync.json has no timestamp A re-sync of an unchanged repository must produce no diff, or every sync is a commit and the history means nothing.
    • An unknown category or kind fails the build A typo in meta.md would otherwise hide a skill from its category page with nothing to notice.
    • Skills and categories share one route segment /skills/content beside /skills/ksef reads well and makes the breadcrumb a path. The cost is a possible collision, which the validator turns into an error.
    Show 2 more
    • The client gets summaries only The categories and summary types live in modules with no filesystem access, so the catalog search can import them, and no whole skill is ever serialised into the page.
    • Relative links resolve into the repository The earlier implementation resolved a skill's relative links against its GitHub URL; the templates keep that and also resolve ../ and the file's own folder.
Read the full record in provenance.md ›

Non-negotiables

What are the 8 rules the module never breaks?

Every module built from this skill holds these, whoever builds it. The same list is in the skill's README and SKILL.md, so the agent reads it before it writes a line.

  1. Never fetch a skill at build or request time.

    The sync writes files into the repository and the build reads the disk, so a deploy never depends on GitHub's rate limit or its cache; the loader imports no network code and the build passes offline.

  2. Read every file of a skill at one commit.

    The head sha is resolved first and each file is read at that sha, so the page and the "generated from" line agree; the sync names the sha in every raw URL.

  3. Swap a skill's mirror in whole or not at all.

    The folder is staged and renamed into place, so a failed sync leaves the previous copy and a file deleted upstream disappears; a second run of an unchanged repository leaves git status clean.

  4. Never drop an eval file silently.

    parseEval returns the reason it cannot show a file, and validateCatalog() turns each into an error; the content suite fails on a run with no prompt.

  5. Show the recorded result of the newest run per agent and prompt.

    Failing runs render like passing ones, nothing is recomputed or picked for looking better, and an agent with no run is named; the eval suite covers the order and the selection.

  6. Normalize YAML dates before reading frontmatter as text.

    An unquoted date is a Date, and a Date read as text rejects the run; the eval suite's fixture writes its date unquoted.

  7. Never retype a skill's text on the site.

    Rules, releases, prompts and results come from upstream/, meta.md carries only what the repository does not, and the sync never writes meta.md.

  8. Only summaries cross to the client.

    The catalog search receives SkillSummary[], so no README is serialised into the page; the one client component's props are typed that way.

Fit

When should you use it, and when not?

Use it for

  • Building or extending pages on a Next.js App Router site that list Agent Skills published as repositories (each with SKILL.md, README.md, CHANGELOG.md and an evals/ folder), with their rules, releases, install commands and agent eval results.

Not for

  • Writing a new skill or hardening one from its eval runsInsteadThe skill's own repository; the sibling `skill-eval-loop` skill for the eval loop
  • Running agent evalsInsteadThe eval harness of the skills index; this module only reads the results
  • A blog or a help center from markdown the site ownsInsteadThe sibling `blog-markdown` and `help-center-markdown` skills
  • A registry with accounts, uploads and downloadsInsteadA package registry; the trust model differs

Build it yourself

How do I install it?

One command. The skills.sh CLI installs the skill into every skills-compatible agent it finds.

$ npx skills add timerise-ai/agent-skills-catalog

Claude Code

Invoke with /agent-skills-catalog

Codex CLI

Invoke with $agent-skills-catalog

Gemini CLI

Invoke with /skills

Name the agents instead with -a, for example npx skills add timerise-ai/agent-skills-catalog -a claude-code -a codex. Or clone the repository into your agent's skills folder. Nothing in it is agent-specific.

What is inside the repository (19 entries)
  • SKILL.mdEntry point: architecture, critical facts, hard rules, quick start, and the reference directory
  • README.mdThis front door
  • CHANGELOG.mdKeep a Changelog, one section per release, newest first
  • CLAUDE.mdWhat this repository is and the conventions for editing the skill itself
  • LICENSEMIT
  • references/adaptation.mdThe seam contract with the host app: skill source, layout, categories, rendering, renames, order of work, the non-negotiables restated
  • references/data-model.mdFolders, meta.md, config, categories and types
  • references/sync.mdThe sync script: one commit per skill, staged swap, the GitHub and local sources, rate limits, offline use
  • references/parsing.mdFrontmatter with date normalization, the heading map, markdown readers, releases, the ledger, the index table
  • references/evals.mdPrompts and eval run files, the parser, ordering, the newest run per agent and prompt
  • references/loader.mdThe catalog loader and the content validator
  • references/routes.mdCatalog, category and skill pages, JSON-LD, sitemap
  • references/ui.mdMarkdown with repository links, cards, catalog search, eval cards, prompts, ledger, style hooks
  • references/testing.mdvitest setup and the five test files
  • references/extensions.mdScheduled sync, Markdown copies, prices, the site assistant, eval collection, badges
  • references/provenance.mdThe engineering ledger: what the audit of the earlier implementation changed and how the templates verify it, what was kept on purpose, what is new
  • assets/content/One example skill with every file the loader reads, for a build with no network
  • evals/The prompts an operator types after installing (prompts.md) and one file per agent eval: the skill installed into an empty Next.js app, one prompt, no help, then type-checked, built and tested
  • .github/workflows/agent-eval.ymlRuns the agent evals on every published release through the index's reusable workflow; copied verbatim from the standard

Recent releases

  1. v0.1.3November 8, 2026

    From scoring the prompt-1 agent eval runs of 0.1.2.

  2. v0.1.2November 8, 2026

    From scoring the prompt-1 agent eval runs of 0.1.1.

  3. v0.1.1November 8, 2026

    Fix release, from scoring the prompt-1 agent eval runs of 0.1.0 and checking the templates on a fresh create-next-app project.

SKILL.md ›README.md ›CHANGELOG.md ›

After installing

What do I tell my agent?

Say what you need in your own words; the skill supplies the how. These are starting points, and the ones we tested say how it went.

  1. Add an Agent Skills section to our site: one page listing the skills our GitHub organization publishes, with search and categories, and a page per skill showing its rules, its latest version, how to install it and how each coding agent did in its evals. The build must not call GitHub.

    No data storeGemini CLIBuilt, checks passCodex CLIBuilt, checks passClaude CodeBuilt, checks pass

  2. Our skill pages still show the old version for a while after we release a skill, and one eval result we committed never shows up on the page. Find out why and fix it.

  3. Audit our skills catalog against the skill's hard rules and list every place it breaks one.

Tested

How does it do in each agent?

We install the skill into an empty Next.js app, give the agent one of the prompts above and no further help, then type-check, build and run the tests it left behind. Nothing is fixed by hand before the checks, and a failing run is published like a passing one. The procedure and every result are public, and the first prompt runs again before each release.

  • Gemini CLI0.67.0

    gemini-3.8-flash

    Built, checks pass
    Add an Agent Skills section to our site: one page listing the skills our GitHub organization publishes, with search and categories, and a page per skill showing its rules, its latest version, how to install it and how each coding agent did in its evals. The build must not call GitHub.
    Typecheck: passBuild: passTests: pass
    Time
    9 min
    Changed
    38 files, +5,325 lines
    Stack
    No data store
    Skill
    v0.1.3
    Run
    Nov 8, 2026

    Result file ›Agent log ›

    What we saw

    Rubric 8/8. Scored from the final summary only, so templates intact (item 2) rests on what it reports. Five files, 24 tests, and every handover item in full with its file or line.

  • Codex CLIcodex-cli 0.167.0

    gpt-6.1-sol

    Built, checks pass
    Add an Agent Skills section to our site: one page listing the skills our GitHub organization publishes, with search and categories, and a page per skill showing its rules, its latest version, how to install it and how each coding agent did in its evals. The build must not call GitHub.
    Typecheck: passBuild: passTests: pass
    Time
    1 min
    Changed
    43 files, +5,461 lines
    Stack
    No data store
    Skill
    v0.1.3
    Run
    Nov 8, 2026

    Result file ›Agent log ›

    What we saw

    Rubric 8/8. Scored from the transcript. The templates were written out by script and only siteName changed afterwards; the config and the suite ran as shipped (24 tests), the notice sits in app/skills/layout.tsx, and every handover item is in the final message.

  • Claude Code2.1.319

    claude-opus-5-5

    Built, checks pass
    Add an Agent Skills section to our site: one page listing the skills our GitHub organization publishes, with search and categories, and a page per skill showing its rules, its latest version, how to install it and how each coding agent did in its evals. The build must not call GitHub.
    Typecheck: passBuild: passTests: pass
    Time
    2 min
    Changed
    39 files, +5,362 lines
    Stack
    No data store
    Skill
    v0.1.3
    Run
    Nov 8, 2026

    Result file ›Agent log ›

    What we saw

    Rubric 8/8. Scored from the final summary. Five files, 24 tests, no template edit reported, and a complete handover. INDEX_REPO = null is a value the seam contract allows.

Build it with Timerise

How long does it take, and what does it cost?

We quote this module per project. The price depends on what it has to connect to. The path to a number is short and free:

  1. Step 1

    Brief

    Tell us what the module must connect to. Takes minutes, in a chat.

  2. Step 2

    Prototype in 48 hours

    A clickable prototype of your system and a quote, at no cost.

  3. Step 3

    Build and handoff

    One project price. Source code, documentation and IP are yours.

Two ways to get agent-skills-catalog

Build it yourself

Install the skill. Your own agent builds the module.

  • MIT licensed, no strings
  • Runs in Claude Code, Codex CLI and Gemini CLI
  • The same rules our engineers build by
$ npx skills add timerise-ai/agent-skills-catalog
Install the skill

Build it with Timerise

Send a brief. We build agent-skills-catalog into a system you own.

  • Clickable prototype and a quote within 48 hours, free
  • One project price, no subscription, no commission
  • Source code, documentation and IP handed over
3 years of support included.
Start the brief

Generated from the skill's own files at commit c13456d. Every rule above links to where the repository says it. All skills