[Feature] Support Knowledge as a first-class package type

[xiaoyaner0201]

Problem

SkillHub already provides a useful lifecycle for governed Skill packages: namespace ownership, versions, visibility, review, storage, search, download, and related governance features. The same package contract can also carry reusable knowledge without introducing a second AI-facing format.

A concrete current workaround is to publish a product handbook or domain corpus as an ordinary Skill:

product-handbook/
├── SKILL.md              # tells the AI when and how to use the knowledge
├── references/           # Markdown, text, JSON, YAML, etc.
└── assets/

This already works for AI consumption, but SkillHub cannot distinguish the package from an action-oriented Skill. As a result:

• discovery cannot intentionally separate executable/action-oriented Skills from knowledge-oriented packages;
• review, policy, and presentation cannot become type-aware;
• operators cannot filter or inventory Knowledge packages as a category;
• a future Skill-to-Knowledge reference cannot target an explicitly typed package revision (dependency modeling itself should remain a follow-up aligned with Feat: Introduce Skill Dependency Graph Resolution and Conflict Detection for Composite Agent Workflows #571).

This is related to #602's broader idea of a unified AI resource library, but this issue proposes one scoped design slice: Knowledge as a first-class package type while preserving the existing Skill package contract. If maintainers prefer, this can be tracked as a concrete sub-scope of #602 rather than as a separate roadmap item.

It also follows the control-plane boundary discussed in #466: SkillHub would govern packages and inert descriptors, not host databases or become a live MCP/data-plane gateway.

The current implementation already has reusable building blocks in Skill, SkillVersion, and the skill / skill_version / skill_file tables. One visible package-format boundary is that SkillPackageValidator requires a root SKILL.md, while SkillMetadataParser already preserves arbitrary frontmatter.

Introducing a package type is nevertheless cross-cutting: the domain model, repositories, review/security records, events, search documents and SQL, API/DTO paths, storage conventions, CLI behavior, social features, and web routes are currently Skill-shaped. The proposal is to reuse their behavior where appropriate, not to assume a one-column migration completes the feature.

Proposed Solution

Introduce a stored package type discriminator, initially:

SKILL
KNOWLEDGE

Existing records and packages without an explicit type would be treated as SKILL, preserving current behavior.

Both package types continue to use a root SKILL.md. A Knowledge package therefore remains directly understandable and installable by Skill-compatible AI clients: the SKILL.md body explains when and how to use the knowledge, while the stored type lets SkillHub organize, filter, review, and present it appropriately.

The type could be declared in SKILL.md frontmatter or in the publish request (the exact contract is a maintainer/API decision). Illustrative frontmatter only:

---
name: product-handbook
description: Curated product and support knowledge
version: 1.0.0
metadata:
  package-type: knowledge
---

This avoids inventing KNOWLEDGE.md and reuses the existing AI-facing Skill semantics, parser, validator, package layout, download, and install flow.

Identity and compatibility

For the MVP, @namespace/slug should remain unique across all package types. A Namespace cannot contain both a SKILL and a KNOWLEDGE package with the same slug. This keeps existing resolve and install coordinates unambiguous.

Recommended compatibility behavior:

• exact resolve/download/install by @namespace/slug remains type-neutral and can consume either package type;
• the installed destination and AI contract remain the existing Skill directory plus root SKILL.md;
• existing search/list behavior keeps its current SKILL default so Knowledge packages do not silently change legacy discovery results;
• type-aware clients can request KNOWLEDGE explicitly or request all package types.

Maintainers may prefer a different discovery default, but coordinate identity should remain unambiguous.

MVP: packaged knowledge

The first vertical slice should support portable plain-text or structured knowledge using the existing package layout:

my-knowledge/
├── SKILL.md              # metadata plus AI-facing usage instructions
├── references/           # Markdown, text, JSON, YAML, etc.
└── assets/               # optional supporting assets

The SKILL.md body tells an AI when to load the material, which references are authoritative, and how to use or cite them. This covers handbooks, product/domain documentation, policies, glossaries, curated research, and other knowledge distributed with a fixed revision.

Published Knowledge versions should follow the existing published-version lifecycle: published package content is not overwritten, while the existing yank semantics remain available. Draft/review replacement behavior does not need to become stricter than current Skill behavior.

Future-compatible mode: external knowledge descriptor

A later slice could allow the same SKILL.md package to describe knowledge maintained outside SkillHub, such as a graph database, document service, or local index accessed through an existing CLI/tool adapter.

Such a descriptor should be an inert, downloadable manifest plus AI-facing instructions. It may describe a source kind, adapter/contract identifier, capabilities such as search or traverse, schema version, and provenance. It must not contain credentials or executable server-side commands.

This later slice must not make SkillHub resolve local connection profiles, probe endpoints, synchronize or index content, validate reachability, forward queries, execute CLI commands, or host graph/vector databases. Those remain responsibilities of the consuming AI/runtime and its separately configured tools.

Suggested First Vertical Slice

1. Add package_type (or an equivalent domain abstraction), defaulting existing data to SKILL.
2. Keep one globally unique @namespace/slug coordinate across package types.
3. Allow type declaration through the existing SKILL.md metadata or publish contract.
4. Reuse the root SKILL.md parser, structural validation, file storage, and package download/install format.
5. Extend publish/review/security/search/audit behavior where necessary so it is explicitly type-aware; do not assume every current Skill-specific path is automatically reusable.
6. Add a package-type filter to REST/OpenAPI, official CLI discovery, and the web UI.
7. Preserve legacy search defaults and current Skill behavior; allow exact coordinate resolution and installation of Knowledge packages through the existing Skill-compatible layout.
8. Limit MVP content to packaged files. Defer external descriptors and cross-package dependencies to follow-up design.

The implementation could start with a discriminator on the current aggregate or extract a generic package aggregate with type-specific projections. A discriminator better matches the reuse goal and may reduce initial scope; a generic aggregate may be cleaner if many package types are expected. This is a maintainer architecture decision rather than a requirement of the proposal.

Alternatives Considered

1. Keep publishing untyped knowledge-only Skills. This is the current workable fallback and preserves AI compatibility, but provides no reliable discovery, policy, inventory, or presentation distinction.
2. Introduce a separate KNOWLEDGE.md entry point and parser. Makes the distinction explicit, but duplicates a working AI-facing contract and requires every client to learn a new package convention.
3. Build a separate KnowledgeHub service. Provides a clean boundary but duplicates namespace, version, permission, review, storage, search, and governance machinery.
4. Add hosted RAG/vector-database features directly to SkillHub. This is a much larger data-plane scope and is not required for governing typed Knowledge packages.

Impact

• Implementation surface: Cross-cutting across domain, persistence, publish/review, search, APIs, CLI, and UI; intended as a staged change rather than a trivial schema flag.
• Data model: Requires a backward-compatible package type discriminator or shared package abstraction. Existing rows remain SKILL.
• Identity: Keeps @namespace/slug unique across package types, avoiding ambiguous legacy routes.
• Packaging/validation: Continues to require and parse root SKILL.md; no second entry-file format is required.
• Versioning: Reuses current draft/review/published/yanked semantics rather than claiming every pre-publication version is immutable.
• Search: Adds type-aware indexing/filtering while preserving the legacy default.
• Governance: Existing review, security, audit, version-tag, discovery-label, and social paths may need explicit type-aware extension; they are not assumed to be one generic lifecycle already.
• AI/client compatibility: Existing clients can install and interpret a known Knowledge coordinate through the normal SKILL.md flow; type-aware clients gain dedicated discovery and presentation.
• Deployment: No graph database, vector database, retrieval engine, synchronization worker, or new runtime service is required for the MVP.

Contract Or SDK Impact

This proposal would add an optional/defaulted package type to REST/OpenAPI, search results, and the official CLI. Backward compatibility should be explicit:

• current Skill publish/resolve/install routes, package layout, and payloads continue to work;
• existing records and packages without an explicit type are treated as SKILL;
• both package types use root SKILL.md and the existing AI-facing semantics;
• one coordinate identifies at most one package regardless of type;
• legacy discovery continues to default to SKILL;
• exact resolution/download/installation can remain package-type neutral;
• the initial contract covers packaged content only;
• no SkillHub-hosted retrieval, endpoint probing, synchronization, MCP forwarding, credential management, or arbitrary server-side CLI execution is introduced.

MVP Acceptance Criteria

• An existing Skill can be published, resolved, installed, reviewed, searched, and yanked with no behavioral change after migration.
• A pure-text Knowledge package uses root SKILL.md and the existing package layout.
• A Knowledge package can be published with its own globally unambiguous coordinate and version, reviewed, discovered with package_type=KNOWLEDGE, downloaded, installed into the normal Skill-compatible destination, and consumed by an AI through its SKILL.md instructions.
• Packages without an explicit type continue to behave as SKILL.
• Published Knowledge package content cannot be silently overwritten; existing yank behavior remains available.
• Namespace visibility and permissions apply to Knowledge packages.
• Legacy search/list behavior does not begin returning Knowledge packages unless the caller opts into that type or a future compatibility decision changes the default.
• A Namespace cannot contain a Skill and Knowledge package with the same slug.
• External-source descriptors, endpoint/profile resolution, synchronization, runtime execution, and cross-package dependencies are not required for the MVP.
• The server does not host a graph/vector database or execute package-provided commands as part of this feature.

[github-actions]

Issue Triage

• Route: triage/core
• Priority: priority/p1 (4.0/5)
• Effort: effort/l (5/5)
• Confidence: 5/5
• Risk: high
• Analysis Mode: rules-only

Why

• Touches core SkillHub workflows (publish, publishing, review).
• Contains urgency signals (cannot, security).
• Open for 7 days; entering the 2-week closure warm-up window.
• Issue includes operator or product impact details.
• Text suggests a bounded change (text, documentation, label).

High-Risk Signals

• Mentions sensitive areas (security, auth, credential).
• Issue mentions API, SDK, or contract changes.

Maintainer Brief

Summary: skill_version / skill_file tables. One visible package-format boundary is that SkillPackageValidator requires a root SKILL.md, while SkillMetadataParser already preserves arbitrary frontmatter. Introducing a package type is nevertheless cross-cutting: the domain model, repositories, review/security records, events, search documents and SQL, API/DTO paths, storage conventions, CLI behavior, social features, and web routes are currently Skill-shaped. The proposal is to reuse their behavior where appropriate, not to assume a one-column migration completes the feature.
Why core:

• Touches a higher-risk area where automated fixes should not be trusted without maintainer review.
• Likely spans multiple modules or a public compatibility surface.
• Mentions sensitive areas (security, auth, credential).
• Issue mentions API, SDK, or contract changes.
  Reproduction or operator path:
• SkillHub already provides a useful lifecycle for governed Skill packages: namespace ownership, versions, visibility, review, storage, search, download, and related governance features. The same package contract can also carry reusable knowledge without introducing a second AI-facing format.
• A concrete current workaround is to publish a product handbook or domain corpus as an ordinary Skill:
• product-handbook/
  Suspected areas:
• CLI publish command option parsing and namespace-aware publish flow
• Skill installation flow and registry/lockfile integration
• Local skill sync flow and publish diff detection
• Registry discovery and CLI query workflow
• Public API contract, generated SDKs, and compatibility surface
  Risks to watch:
• Mentions sensitive areas (security, auth, credential).
• Issue mentions API, SDK, or contract changes.
• Namespace-scoped behavior can regress default publish/install flows if fallback routing is not preserved.
  Validation checklist:
• Validate the primary reported workflow end-to-end after the fix.
• Check for downstream API/SDK/CLI compatibility expectations before shipping.
• Verify both namespace-scoped behavior and the default non-namespace flow.

Next Action

• Hand the issue to a core maintainer and use a local programming agent for reproduction, scoping, and validation.

---

问题分流结果

• 路由: triage/core
• 优先级: priority/p1 (4.0/5)
• 修复投入: effort/l (5/5)
• 信息完整度: 5/5
• 风险: 高
• 分析模式: rules-only

原因

• 涉及 SkillHub 核心流程（publish, publishing, review）
• 包含紧急信号（cannot, security）
• 已打开 7 天，开始进入 2 周闭环预热窗口
• 包含用户或产品影响说明
• 文本显示改动范围较可控（text, documentation, label）

高风险信号

• 提到敏感区域（security, auth, credential）
• 提到 API、SDK 或契约变更

维护者交接摘要

概要: SkillHub already provides a useful lifecycle for governed Skill packages: namespace ownership, versions, visibility, review, storage, search, download, and related governance features. The same package contract can also carry reusable knowledge without introducing a second AI-facing format. A concrete current workaround is to publish a product handbook or domain corpus as an ordinary Skill: text product-handbook/ ├── SKILL.md # tells the AI when and how to use the knowledge ├── references/ # Markdown, text, JSON, YAML, etc. └── assets/ This already works for AI consumption, but SkillHub cannot distinguish the package from an action-oriented Skill. As a result: - discovery cannot intentionally separate executable/action-oriented Skills from knowledge-oriented packages; - review, policy, and presentation cannot become type-aware; - operators cannot filter or inventory Knowledge packages as a category; - a future Skill-to-Knowledge reference cannot target an explicitly typed package revision (dependency modeling itself should remain a follow-up aligned with #571). This is related to #602's broader idea of a unified AI resource library, but this issue proposes one scoped design slice: Knowledge as a first-class package type while preserving the existing Skill package contract. If maintainers prefer, this can be tracked as a concrete sub-scope of #602 rather than as a separate roadmap item. It also follows the control-plane boundary discussed in #466: SkillHub would govern packages and inert descriptors, not host databases or become a live MCP/data-plane gateway. The current implementation already has reusable building blocks in Skill, SkillVersion, and the skill
为何进入 core:

• 触及高风险区域，未经 maintainer 审查不应直接信任自动修复
• 大概率跨多个模块或公共兼容面
• 提到敏感区域（security, auth, credential）
• 提到 API、SDK 或契约变更
  复现路径或操作路径:
• SkillHub already provides a useful lifecycle for governed Skill packages: namespace ownership, versions, visibility, review, storage, search, download, and related governance features. The same package contract can also carry reusable knowledge without introducing a second AI-facing format.
• A concrete current workaround is to publish a product handbook or domain corpus as an ordinary Skill:
• product-handbook/
  怀疑影响区域:
• CLI 发布命令参数解析与 namespace 感知发布流程
• 技能安装流程与 registry/lockfile 集成
• 本地技能同步流程与发布 diff 检测
• Registry 发现与 CLI 查询流程
• 公开 API 契约、生成 SDK 与兼容性表面
  重点风险:
• 提到敏感区域（security, auth, credential）
• 提到 API、SDK 或契约变更
• namespace 范围行为如果没有保留 fallback routing，可能回归默认 publish/install 流程
  验证清单:
• 修复后端到端验证主报告流程
• 发布前检查下游 API/SDK/CLI 的兼容性预期
• 同时验证 namespace 范围行为与默认非 namespace 流程

下一步

• 交给 core maintainer，并结合本地编程Agent协助完成复现、收敛范围与验证闭环

[xiaoyaner0201]

Clarification: this proposal does not require a new KNOWLEDGE.md entry point.

Both SKILL and KNOWLEDGE packages should keep the existing root SKILL.md, parser, validator, package layout, install flow, and AI-facing semantics. The type is only a persisted organization/governance discriminator: existing AI clients can still consume the package as a normal Skill, while type-aware SkillHub clients can present and filter it as Knowledge.

I updated the proposal and acceptance criteria accordingly. The same SKILL.md can either guide the AI to use packaged references/ content or describe how to retrieve knowledge through an external graph/CLI/tool adapter.