Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#119 0 comentarios 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 1 día

@mrgoonie ya está trabajando en esto.

Desde el 22/10/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
190
Forks
42
Merge medio
5 h 50 min
PR fusionados (30 d)
37

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de nextlevelbuilder/skillx

Todos los issues de nextlevelbuilder/skillx

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.