Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

feat(compatibility): write declared compatibility_json on publish, sync and backfill

未关闭
  • 哪里不对？
#119 0 条评论 0 个 reaction 已指派 1 人 在 GitHub 查看

维护者通常 1 天内回复

@mrgoonie 已经在做这个了。

开始于 2026年10月22日。

评估

这个 Issue 还没有评估数据。

描述

Problem

The catalog's compatibility display, introduced in #90 ("agent-native discovery and compatibility"), reads skills.compatibility_json and package_releases.compatibility_json. Each declaration goes through the shared validator in @skillx/contracts. Nothing on main writes either column: origin/main has no non-test writer.

So every catalog row, the .md pages, llms.txt/llms-full.txt and the MCP discovery tools report compatibility as "unknown" for every skill. The feature is live but shows nothing.

Proposal

Add a write path that fills the declared compatible map from what the publisher actually declares:

  1. Source of the declaration:
    • the SKILL.md frontmatter, or the release manifest, field compatible / compatibility (for example { "agentkit": { "status": "declared", "versions": ">=1.0.0" } });
    • for skills synced from GitHub, the same field read during seed/sync.
  2. Validate on write: use the same @skillx/contracts validator the reader uses. An invalid shape is stored as NULL ("unknown"), never as a partial value. Writes are idempotent.
  3. When to write: on release publish into package_releases.compatibility_json, and on skill create/update/sync into skills.compatibility_json. Invalidate the llms cache key, or bump its version, when a declaration changes.
  4. Backfill: a one-off backfill of existing rows from their stored SKILL.md content. Back up D1 first (Time Travel restore point plus per-table export, because the FTS5 tables block a full wrangler d1 export).
  5. Never infer: do not infer compatibility from content heuristics. Only a declaration counts.

Acceptance

  • Publishing a release with a valid declaration stores it; publishing one with an invalid declaration stores NULL. Covered by tests.
  • Creating or syncing a skill whose frontmatter declares compatibility stores it.
  • Catalog, .md, llms*.txt and MCP surfaces show the declared status for those skills.
  • The backfill has run on production after a D1 backup, with the counts of declared and unknown rows recorded.
  • Docs updated: docs/api-reference.md and the publisher guide describe how to declare compatibility.

Context: found during the review of #90 (rebuilt from #41). Related AgentKit epic: bestagentkits/agentkit#2274.

主要语言
TypeScript
星标
193
派生
43
平均合并
4 小时 5 分钟
30 天内合并 PR
54

环境准备

这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

nextlevelbuilder/skillx 的其他 Issue

查看 nextlevelbuilder/skillx 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。