📖 ADR 0015 on skill packaging and delivery (#141)

Proposes dropping skillctl for an ordinary Containerfile, letting one
image carry a bundle of skills, and assembling `/opt/skills` in an init
container that validates what it assembled. Inline and git sources stop
needing an image at all: inline becomes a ConfigMap, git is cloned at
pod start, and the controller still builds nothing.

skillctl was already producing a plain OCI image from a directory, and
charging us a `skill.yaml` that duplicated the SKILL.md frontmatter.
`skillctl install --target goose` isn't supported at v0.7.2 either, so
the local dev story ADR 0001 promised was never reachable.

Cloning git at pod start is the thing ADR 0001 rejected as "pallet as
runtime sync engine", so this supersedes that explicitly rather than
contradicting it quietly, and takes the loss: a git source needs the
network at startup, isn't auditable by digest, and doesn't work
air-gapped. That's bounded to `spec.source`, and the remedy is to build
the repo into an image. Image and inline still need no network at pod
start, so the air-gap requirement is scoped rather than overturned.
Resolving git controller-side into a ConfigMap would remove the cost and
stays open: `spec.source` means the same thing either way, so it can be
adopted later without an API change.

Also revises where ADR 0014 sources its rules list. `KONVEYOR_RULES` set
from `spec.type` can't work for a bundle, since the controller never
sees inside the image and so can't say which of the skills is a rule.
#135 needs updating alongside this if the decision holds.

One question is left open rather than settled: whether a SkillCard
should be able to demote a skill whose frontmatter declares it a rule.
Promotion is harmless, demotion turns a constraint into a suggestion,
which is what ADR 0014 rejected an alternative over. I'd like a second
opinion on that one before it hardens.

The ADR lists the docs in CONTEXT.md and README.md that stop being true.
They aren't touched here on purpose: this merges as `proposed` with no
implementation, so those docs still describe the system as it actually
is, and editing them now would make them wrong.

A prototype of all of it exists and produced the measurements quoted in
the ADR, including the four-case probe on minikube with CRI-O 1.35.0 and
k8s v1.34.0. It's held back pending review of the decisions, so this PR
is the ADR alone.

Refs #44


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Updated the glossary to clarify AgentSkills.io `SKILL.md` formatting
and distinguish on-demand skills from always-loaded rules.
* Documented support for skills delivered through OCI images, Git
sources, and inline configuration.
* Added guidance for selecting skills from multi-skill packages using
`subPath`.
* Added an architectural decision record describing skill assembly,
validation, naming, and delivery workflows.
* Updated infrastructure and relationship documentation to reflect the
revised skill packaging model.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Fabian von Feilitzsch <fabian@fabianism.us>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: fabianvf

CONTEXT.md

@@ -2,28 +2,36 @@
 
 ## Core Resources
 
-**SkillCard** — An individual agent capability or behavioral constraint,
-following the skillimage.io/v1alpha1 SkillCard format. A SkillCard with
-`type: skill` (default) is on-demand — only its name and description
-are loaded at startup; the full content activates when the agent
-invokes it. A SkillCard with `type: rule` is always-loaded — its full
-content is injected into every agent turn. A SkillCard CR supports
-three source types: an OCI
-image ref (pre-built artifact), a git source URL (controller clones,
-builds, and pushes the OCI artifact), or inline markdown content
-(controller builds and pushes). All three converge to a resolved OCI
-image ref in status. Examples: "maven-migration" (skill),
-"no-javax-imports" (rule).
+**SkillCard** — Exactly one agent capability or behavioral constraint.
+The skill itself is an AgentSkills.io directory: a `SKILL.md` carrying
+YAML frontmatter, optionally alongside supporting files. A SkillCard
+with `type: skill` (default) is on-demand — only its name and
+description are loaded at startup; the full content activates when the
+agent invokes it. A SkillCard with `type: rule` is always-loaded — its
+full content is injected into every agent turn. `type` lives on the CR,
+never in skill content, which keeps `SKILL.md` valid against the Agent
+Skills spec. A SkillCard names one of three sources: an OCI image ref,
+a git source URL, or inline markdown. Only the image source resolves to
+an artifact; inline is delivered as a ConfigMap and git is cloned at pod
+start, so nothing is built in-cluster. An image or repository holding
+several skills is addressed with `subPath`, since a SkillCard is always
+one skill. Examples: "maven-migration" (skill), "no-javax-imports"
+(rule). See ADR 0015.
 
-**SkillCollection** — A group of skills, following the
-skillimage.io/v1alpha1 SkillCollection format. Each entry references a
-skill by OCI image ref, git source URL, or SkillCard CR name. The
-controller creates SkillCard CRs for git-sourced entries and reports
-readiness when all child SkillCards are resolved. An Agent references
-SkillCollections to gain access to sets of related capabilities.
-Examples: "konveyor-quarkus-skills" (a collection of 15 migration
-skills from a git repo), "enterprise-rules" (a curated set of rules
-as OCI images).
+**SkillCollection** — A named group of skills an Agent can reference in
+one line. Each entry references a skill by SkillCard CR name, or names a
+source directly. Grouping is separate from packaging: a collection may
+gather skills from several images, and one image may hold several skills
+that no collection groups. An Agent references SkillCollections to gain
+access to sets of related capabilities. Examples:
+"konveyor-quarkus-skills" (a collection of 15 migration skills),
+"enterprise-rules" (a curated set of rules).
+
+_Not yet true_: the controller does not create SkillCard CRs for entries
+that name a source directly, though it likely should. Whether a
+collection becomes the primary type users write, resolving a multi-skill
+source into one generated SkillCard per skill, is an open question in
+ADR 0015.
 
 **Gateway** — An LLM service endpoint serving exactly one provider/model
 combination. Each Gateway declares a provider type (e.g. `anthropic`,
@@ -111,13 +119,15 @@ results.
 
 ## Infrastructure
 
-**skillimage** — Red Hat Emerging Technologies project
-(redhat-et/skillimage) providing OCI-based packaging and distribution
-for agent skills and rules. The `skillctl` CLI builds, validates,
-promotes, pushes, pulls, and installs skills. SkillCard and
-SkillCollection are skillimage's YAML metadata formats — our
-Kubernetes CRDs adopt the same shape. Supported install targets:
-claude, cursor, windsurf, opencode, openclaw.
+**Agent Skills** — The open skill format at agentskills.io, originally
+from Anthropic and adopted across agent clients. A skill is a directory
+holding a `SKILL.md` with YAML frontmatter (`name` and `description`
+required, plus `license`, `compatibility`, `metadata` and
+`allowed-tools`), optionally alongside `scripts/`, `references/` and
+`assets/`. The field set is closed, and the `skills-ref` reference
+library validates against it. Our skills are this format, and our
+SkillCard and SkillCollection CRDs keep their names from skillimage
+without adopting its packaging. See ADR 0015.
 
 **Agent Sandbox** — Kubernetes SIG Apps project
 (kubernetes-sigs/agent-sandbox) providing CRDs for isolated, stateful
@@ -250,11 +260,11 @@ it belongs in the harness.
 
 ## Relationships
 
-- A **SkillCard** resolves to an OCI artifact from one of three
-  sources: OCI image ref, git source, or inline content.
-- A **SkillCollection** references skills by OCI image ref, git
-  source, or **SkillCard** CR name. Git-sourced entries produce child
-  **SkillCard** CRs.
+- A **SkillCard** is one skill, from one of three sources: OCI image
+  ref, git source, or inline content. Only the image source resolves to
+  an artifact; the others are delivered without one.
+- A **SkillCollection** groups skills, by **SkillCard** CR name or by
+  naming a source directly.
 - An **Agent** references zero or more **SkillCards** and zero or more
   **SkillCollections**.
 - An **Agent** references one or more **Gateways** — declaring the