agent-skills-catalog

Agent Skills 目录：同步的技能文件、页面和评估结果

技能目录是一组介绍存放在其他地方的文件的页面，因此页面必须准确反映该技能仓库在某个提交中的内容，不多不少。 本模块由一位已交付该模块的工程师编写，并将以下内容视为已验证属性：同步会读取某个提交中技能的每个文件，并整体替换；构建会读取磁盘，绝不访问网络；每个评估文件要么成功渲染，要么测试会说明原因并失败；评估卡片会显示每个 Agent 和提示词最近一次运行记录的结果。记录见 references/provenance.md。

适用场景

在 Next.js App Router 网站上构建或扩展页面，用于列出以仓库形式发布的 Agent Skills（每个仓库包含 SKILL.md、README.md、CHANGELOG.md 和 evals/ 文件夹），并展示其规则、发布版本、安装命令和 Agent 评估结果。

不适用场景

• 编写或加固技能本身：这属于技能自己的仓库；要根据评估运行结果修复技能，请使用同级的 skill-eval-loop 技能。
• 运行 Agent 评估：这些运行在别处执行，并提交到各技能的 evals/ 中；本模块只读取这些文件。
• 根据仓库中的 Markdown 创建博客或帮助中心：请使用同级的 blog-markdown 和 help-center-markdown 技能。这里的 Markdown 属于其他人，绝不会被编辑。
• 具有账户、上传或下载功能的包注册表或市场：其信任模型不同。

架构

skill repositories (GitHub, or local checkouts)
        |  npm run skills:sync   head sha first, every file at that sha, staged, swapped in whole
        v
content/skills/<slug>/meta.md          host-written: category, tagline, related
content/skills/<slug>/upstream/        sync-written only: SKILL.md README.md CHANGELOG.md
                                       references/provenance.md evals/*.md sync.json
content/skills/_index/README.md        optional index table: Builds and Backend cells
        |  build time, no network
        v
lib/skills/catalog.ts   getSkill(slug), getAllSkills(), categories, related     React cache()
  markdown.ts + upstream.ts   sections, rules, tables, releases, provenance (SKILL_LAYOUT)
  evals.ts                    prompts, parseEval (ok or reason), sortRuns, latestRuns
  validate.ts                 every problem the loader forgives, as errors and warnings
        |
        +-- /skills                 catalog: SkillSummary[] to a client search and filter
        +-- /skills/[slug]          a skill page, or a category page when the slug is a category
        +-- sitemap, JSON-LD        dates from the changelog, never from the build
        +-- catalog.test.ts         validateCatalog() errors fail npm test

重要事实

1. 每个技能分为两部分。 meta.md 保存仓库中没有的信息（类别、标语、相关内容），且只有托管方会写入；upstream/ 保存仓库中的文件，且只有同步程序会写入。
2. 目录布局是解析器的约定。 SKILL_LAYOUT 指定加载器读取的标题；技能若不遵循该布局，对应章节就会丢失，验证器会指出具体是哪一节。程序不会从散文中猜测内容。
3. 上游链接相对于其所属仓库。 references/x.md 在网站上并不存在，因此 SkillMarkdown 会根据文件在 GitHub 上的文件夹解析所有相对链接。
4. 技能和类别共用一个 [slug] 段。 dynamicParams = false 可确保所有页面都是静态页面；若技能 slug 与类别 id 相同，验证器会报错。
5. 运行文件是任何人都可以提交的自由文本。 只有指向组织自有仓库的 Actions 运行 URL 才会成为“Agent 日志”链接；JSON-LD 会转义 <。
6. 运行文件不能按文本排序。 -p1.md 的排序会晚于 -p1-2.md，因此排序依据依次为日期、runNumber 和名称。
7. 构建过程不需要 GitHub。 无网络的无人值守运行会提交 assets/content/ 中的示例技能，让页面、验证器和测试都有内容，并交接 npm run skills:sync。gray-matter、react-markdown、remark-gfm 和 vitest 来自 npm，而 npm 并非外部服务。模板会原样复制，而非重写：只需修改 adaptation.md 中的衔接值，五个测试文件无需修改即可运行：共 24 项测试。

硬性规则

与 README 和 adaptation.md 中的八条规则相同，顺序也一致。

绝不要在构建时或请求时获取技能。 同步会将文件写入仓库，构建则从磁盘读取，因此部署绝不依赖 GitHub 的速率限制或缓存。

在同一个提交中读取技能的每个文件。 先解析头部 SHA，再按该 SHA 获取每个文件；分支名称上的原始 URL 会缓存数分钟，可能混合两个提交的内容。

整体替换技能镜像，否则就不要替换。 先暂存文件夹，再将其重命名到目标位置，这样同步失败会保留之前的副本，而上游已删除的文件也会在此处消失。

绝不静默丢弃 eval 文件。 parseEval 会返回无法显示某个文件的原因，而 validateCatalog() 会将每个原因都转换为错误，从而使 npm test 失败。

显示每个 Agent 和提示词最新一次运行的记录结果。 失败的运行与成功的运行一样呈现，不会重新计算结果，也不会挑选看起来更好的结果；没有运行记录的 Agent 也会被点名。

将 YAML 日期规范化后，再把 frontmatter 作为文本读取。 未加引号的 date: 2026-09-26 是一个 Date，而作为文本读取的 Date 会变成空字符串，从而拒绝该次运行。

绝不要在网站上重新输入技能文本。 规则、发布内容、提示词和结果都来自 upstream/；meta.md 只包含仓库中没有的信息，同步操作绝不修改它。

只有摘要会传到客户端。 目录搜索获取的是 SkillSummary[]；在客户端组件中传递完整的 Skill，会把每个 README 都发送给每位访客。

快速开始

1. 填写接口契约、组织和类别：adaptation.md。
2. 编写配置、类别和类型，并搭建 content/skills/： data-model.md。
3. 复制同步逻辑并接入 npm run skills:sync；运行它，或者在没有网络时将 assets/content/ 复制到应用中： sync.md。
4. 复制 frontmatter、布局、Markdown 和上游读取器：parsing.md。
5. 复制 eval 解析器：evals.md。
6. 复制加载器和验证器：loader.md。
7. 添加目录页和 [slug] 页面、JSON-LD 以及站点地图：routes.md。
8. 添加组件，然后通过 data-skill-* 钩子设置样式：ui.md。
9. 复制 vitest.config.ts 和五个测试文件，接入 npm test，并运行它以及 npm run typecheck 和 npm run build：testing.md。
10. 最终交接说明不能只有 README，还必须说明：config.ts 中的组织和分支以及同步配置；每次发布技能后都会运行 npm run skills:sync 并提交其结果；技能超过大约三十个时需要使用 GITHUB_TOKEN；部署前必须设置 siteUrl（使用字面值，绝不能使用环境变量）；首次实际同步后会删除示例技能。接下来查看： extensions.md；在简化任何内容之前，先查看 provenance.md。

参考目录

场景	触发关键词	参考
将其融入现有应用	适配、接缝、组织结构、重命名、主机探测、类别、依赖项	adaptation.md
配置、类别、类型、文件夹	配置、SKILLS_CATALOG、类别、meta.md、Skill、SkillSummary、content/skills	data-model.md
将技能拉取到仓库	同步、skills:sync、GitHub、raw.githubusercontent.com、sha、GITHUB_TOKEN、速率限制、sync.json、本地	sync.md
读取 SKILL.md、README、变更日志	gray-matter、frontmatter、日期、标题、SKILL_LAYOUT、列表、表格、发布、来源信息、索引表	parsing.md
提示词和评估运行	evals、prompts.md、parseEval、结果、部分、runNumber、latestRuns、runUrl、干预	evals.md
加载目录并进行验证	getSkill、getAllSkills、缓存、相关项、validateCatalog、警告、错误	loader.md
页面、元数据、JSON-LD、站点地图	路由、page.tsx、generateStaticParams、dynamicParams、类别页面、TechArticle、BreadcrumbList、站点地图	routes.md
卡片、搜索、评估卡片、Markdown	SkillCatalog、搜索、筛选、EvalRuns、SkillMarkdown、相对链接、urlTransform、data-skill	ui.md
测试和内容验证器	vitest、npm test、catalog.test、fixture、示例技能、别名	testing.md
已发布模块之外的扩展	Markdown 文案、llms.txt、价格、行动号召、助手、评估集合、徽章	extensions.md
模板为何与早期实现不同	来源信息、审计、账本、有意保留、添加	provenance.md

这是 Timerise Skills 索引的一部分，该索引列出了相关技能。