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

Start with Skill.java, SkillVersion.java, SkillPackageValidator.java, and the skill, skill_version, and skill_file tables to trace the current package lifecycle. Then map how package type would flow through persistence, review and security records, events, search, REST/OpenAPI, CLI, and web UI. The issue describes a cross-cutting design proposal without naming tests or settling the type contract; done means the acceptance criteria are implemented while existing Skill behavior remains compatible.

Status — specification proposal

Updated after the October 16 contract proposal and October 22 maintainer request. The current spec-only artifact is #1008. It is proposed, not an implementation or release commitment; this issue stays open.

This revision explicitly replaces the original suggestion to exclude Knowledge from legacy search. It also clarifies that Knowledge is a classification within Skill, not a new resource identity beside Skill and Suite. Exact metadata naming, historical treatment, lifecycle and response exposure still require maintainer agreement.

Problem

SkillHub already governs Skill ownership, versions, visibility, review, storage, search, download and audit. Reusable knowledge can already be distributed in the same format:

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

This works for AI consumption, but the registry cannot reliably distinguish a knowledge-oriented package for discovery, inventory, presentation or future type-aware policy. The aim is to make that distinction explicit while reusing the existing package contract and lifecycle—not to create a second AI-facing format or a hosted knowledge service.

Proposed Solution

Treat Knowledge as a version-specific package classification within the existing Skill aggregate. Both ordinary Skills and Knowledge packages retain root SKILL.md, the existing file layout, install commands and destination. resourceType remains SKILL or SUITE.

The current recommendation is a declaration in SKILL.md frontmatter:

metadata:
  package-type: knowledge

Proposed values are exact lowercase skill and knowledge; absent means ordinary skill, without inheritance from the preceding version. Unknown/null/non-string values on new submissions are rejected. The spelling and historical applicability remain review decisions, not an already supported publish contract.

Version and identity

• A published version keeps its own classification. Changing type requires a new version through the existing applicable publish/review/scan flow; no silent rewriting of published content.
• Public discovery follows the published candidate selected by the existing entry point, not a new maximum-semver rule. Pinned version/tag/hash requests use the type of the version actually resolved. Draft/owner-preview types do not overwrite public classification. Yank and promotion retain the existing version-selection rules.
• Preserve existing owner-isolated Skill records, uniqueness/conflict checks and caller-dependent coordinate resolution. Type must not resolve a collision, bypass ownership, create a second published identity at the same coordinate or overwrite another owner's package.
• Skill and Suite may continue to share a slug through their existing distinct entry points. Suite members keep their exact SkillVersion references. This proposal does not impose a new cross-resource unique constraint.

Discovery and compatibility

• Unfiltered legacy Skill search continues to include Knowledge. Classifying a package must not make content that old clients can already consume disappear from their results.
• Existing clients continue searching, resolving, downloading and installing Knowledge as a normal Skill, without an upgrade or new command.
• Type-aware clients gain an optional current-version filter. A matching historical version must not be substituted for the current published version.
• Optional additive packageType metadata must preserve existing fields and the Skill/Suite resource enum. The draft recommends an explicit include=packageType expansion using the existing include convention, with unchanged default response shapes, including for strict legacy decoders. Initial endpoint scope is a maintainer decision.

Historical data and governance

Arbitrary frontmatter may already contain the proposed key. The draft recommends preserving all pre-feature received versions as ordinary Skills rather than retrospectively reclassifying or rejecting them; new submissions opt into the new declaration contract. The spec discusses pending historical versions and copies/promotions so raw metadata or creation time cannot accidentally change their interpretation. Storage and rollout are future implementation decisions.

Classification is an organizational distinction, not proof that content is inert, trustworthy or free of scripts. Existing authorization, visibility, review, scanning, package/file limits, download readiness, hidden/archive/yank and audit controls continue to apply.

Staged Scope

1. Review the spec-only OpenSpec artifact and settle declaration/history, lifecycle and exposure choices.
2. Separately agree a complete publish/review/search/install implementation slice with backward-compatibility tests; do not treat a documentation merge as implementation or release approval.
3. Leave external-source descriptors and dependency resolution to follow-up proposals. The first slice distributes packaged files only.

Related boundaries: #602's broader resource-library discussion was split, with suites handled by #715/#826/#828; dependency work is adjacent to #571. Following the control-plane boundary discussed in #466, this feature does not host graph/vector databases, fetch or synchronize external knowledge, probe endpoints, forward MCP/query traffic, manage runtime credentials or execute package-provided server commands. Any later descriptor would be an inert package consumed by a separately configured runtime, not a SkillHub data plane.

Alternatives Considered

• Keep knowledge as untyped Skills: immediately usable, but no reliable type-aware discovery or inventory.
• Add KNOWLEDGE.md or a parallel Knowledge resource: duplicates packaging/installation contracts and makes existing client compatibility harder.
• Create a separate KnowledgeHub: duplicates namespace, version, permission, review and storage machinery.
• Add hosted RAG/vector services: outside the registry classification problem and the first slice.

Impact and Proposed Acceptance Criteria

This is cross-cutting work across metadata/validation, version lifecycle, queries/indexing, API projections and client presentation—not merely adding a database flag. No product code, migration, deployment or runtime behavior is changed by the spec-only PR. Future acceptance must demonstrate:

• Existing untyped Skills retain their publishing, review, search, resolution, installation, visibility and yank behavior.
• Knowledge uses root SKILL.md and the normal install layout, with explicit type-aware discovery available to new callers.
• Mixed historical types, latest changes, pinned versions, unpublished previews, yank fallback/no survivor and selected-version promotion have consistent version-bound meaning.
• Invalid new declarations fail explicitly; pre-feature metadata collisions do not break already received versions or their applicable original review flow.
• Existing owner-isolated collisions and Skill/Suite identities stay unchanged; package type cannot bypass name conflicts or choose another owner's record.
• Unmodified legacy clients still find and install Knowledge; default response contracts and resource enums remain compatible, including strict decoders.
• New filters apply before pagination/counting to the current published candidate under the same access rules; stale indexes do not mislabel a version.
• Published bytes remain protected, and classification never bypasses security/review/governance.
• External descriptors, dependencies, hosted retrieval/databases and server-side execution remain outside the first slice.

Infographic

The boxes are a packaging metaphor, not a claim that Knowledge packages cannot contain scripts.