# agent-skills-catalog (Agent Skill)

> 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.

Page: https://timerise.ai/skills/agent-skills-catalog

Agent Skill `agent-skills-catalog`: https://github.com/timerise-ai/agent-skills-catalog. Category: Content, Developer workflow. Runs on Next.js; backend: No data store, files mirrored into the repository; GitHub or local checkouts behind a seam.

Latest release: v0.1.3 (2026-11-08).

Install: npx skills add timerise-ai/agent-skills-catalog. Timerise builds it on a brief; the price comes from the brief.

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.

Build a public catalog of Agent Skills in a Next.js App Router site, generated at build time from each skill repository's own files: a sync script that mirrors SKILL.md, README.md, CHANGELOG.md, provenance.md and evals/ into the repository, a loader that reads rules, releases and the provenance ledger from them, a catalog page with search and category filter, one page per category and per skill, the agent eval results (newest run per agent and prompt, failing runs included), JSON-LD, sitemap entries and a content validator. Use when: (1) a site should list the Agent Skills an organization publishes on GitHub, with install commands, rules, versions and agent eval results, (2) skill pages show an old version after a release, or an eval run never appears on the page, (3) adding agent eval results, prompts or a provenance ledger to existing skill pages, (4) the user mentions: skills catalog, Agent Skills page, skill directory, SKILL.md, skills.sh, npx skills add, evals/prompts.md, eval results, agent evals, Claude Code, Codex CLI, Gemini CLI, skills:sync, sync.json, raw.githubusercontent.com, provenance.md, CHANGELOG.md, Keep a Changelog, TechArticle, SoftwareSourceCode. Carries a sync that reads every file of a skill at one commit and swaps the mirror in whole, a loader that never fetches, an eval parser that rejects a malformed run with its reason instead of dropping it, and a validator that fails the tests on it. Next.js App Router; where the skills come from is a seam (GitHub or local checkouts) and the section layout it reads is one table. Not a way to write a skill, not an eval runner and not a package registry.

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](references/provenance.md) carries the record.

What it builds:
- A sync that reads every file at one commit and swaps the copy in whole
- A loader that never fetches
- Catalog pages 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
- Sitemap entries
- A content validator

When to use:
- 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.

When not to use:
- **Writing or hardening a skill itself**: that is the skill's own repository; to fix one from its eval runs, the sibling `skill-eval-loop` skill.
- **Running agent evals**: the runs are made elsewhere and committed to each skill's `evals/`; this module only reads them.
- **A blog or a help center from markdown in the repository**: the sibling `blog-markdown` and `help-center-markdown` skills. Here the markdown is someone else's and is never edited.
- **A package registry or marketplace** with accounts, uploads or downloads: different trust model.

Non-negotiables:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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`.
- 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.

Not this:
- Writing a new skill or hardening one from its eval runs: The skill's own repository; the sibling [`skill-eval-loop`](https://github.com/timerise-ai/skill-eval-loop) skill for the eval loop
- Running agent evals: The eval harness of the skills index; this module only reads the results
- A blog or a help center from markdown the site owns: The sibling [`blog-markdown`](https://github.com/timerise-ai/blog-markdown) and [`help-center-markdown`](https://github.com/timerise-ai/help-center-markdown) skills
- A registry with accounts, uploads and downloads: A package registry; the trust model differs

Requirements:
- 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.

What to tell your agent:
- 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.
- 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.
- Audit our skills catalog against the skill's hard rules and list every place it breaks one.

Agent eval results (newest per agent and prompt):
- Gemini CLI (gemini-3.8-flash) on v0.1.3, 2026-11-08: pass (No data store)
- Codex CLI (gpt-6.1-sol) on v0.1.3, 2026-11-08: pass (No data store)
- Claude Code (claude-opus-5-5) on v0.1.3, 2026-11-08: pass (No data store)

Recent releases:
- v0.1.3 (2026-11-08): From scoring the prompt-1 agent eval runs of 0.1.2.
- v0.1.2 (2026-11-08): From scoring the prompt-1 agent eval runs of 0.1.1.
- v0.1.1 (2026-11-08): 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.