-$ podman create --name tmp quay.io/skills/resume-screener:1.0.0
-$ podman cp tmp:/skills/resume-screener ./skills/
-$ podman rm tmp
+
+$ skillctl install quay.io/myorg/resume-screener:1.0.0 --target claude
-Tips: Arrow keys or click to navigate. Press N to toggle notes.
-Context: This feature was implemented in PR #21 on redhat-et/docsclaw.
-The design spec is at docs/dev/2026-04-12-oci-skill-distribution-design.md.
Agent Skills Specification: agentskills.io/specification
-
-Skills are the unit of specialization for an agent. Each skill is a self-contained
-directory with instructions (SKILL.md) and optional metadata (skill.yaml). The agent
-discovers and loads them at startup.
-
-Think of skills like plugins: the agent provides the runtime, skills provide domain expertise.
Each of these methods gets progressively closer to enterprise readiness โ
+Project: github.com/redhat-et/skillimage
Each of these methods gets progressively closer to enterprise readiness โ
ConfigMaps are already Kubernetes-native โ but all three lack the supply chain
guarantees (signing, versioning, audit) that regulated environments require.
ConfigMaps have a 1 MiB size limit (etcd constraint), so larger skills with
-examples or data files won't fit.
This is the core motivation. When you deploy AI agents in a regulated enterprise,
+examples or data files won't fit.
This is the core motivation. When you deploy AI agents in a regulated enterprise,
you need the same supply chain guarantees you have for container images: signed
artifacts, vulnerability scanning, access control, and audit logs.
Reproducibility matters because you need to prove which exact skill version
produced an agent's output โ especially in regulated industries (finance,
-healthcare, government).
ORAS (OCI Registry As Storage): oras.land
+healthcare, government).
ORAS (OCI Registry As Storage): oras.land
The OCI Distribution Specification was designed to be content-agnostic. Media types
let registries and tools distinguish content without special handling. Helm charts
@@ -1729,42 +2140,46 @@
Thank You
Community alignment: This implementation aligns with the Agent Skills OCI Artifacts
-Specification by Thomas Vitale.
+No infrastructure changes needed.
Agent Skills Specification: agentskills.io/specification
+
+Skills are the unit of specialization for an agent. Each skill is a self-contained
+directory with instructions (SKILL.md) and optional metadata (skill.yaml). The agent
+discovers and loads them at startup.
+
+Think of skills like plugins: the agent provides the runtime, skills provide domain expertise.
Skills are packaged as standard OCI images (FROM scratch), not ORAS artifacts.
+This means podman pull, skopeo copy, and Kubernetes ImageVolumes all work natively.
Media types used:
- application/vnd.oci.image.layer.v1.tar+gzip (skill content layer)
-- application/vnd.oci.image.config.v1+json (config with SkillCard metadata)
-
-The custom annotations (io.docsclaw.skill.*) carry SkillCard metadata in the manifest
-for fast inspection without pulling the full layer.
The --as-image flag produces an OCI image (with rootfs layer) instead of an OCI artifact.
-This is required for Kubernetes image volumes, which expect a proper container image that
-the kubelet can pull via the container runtime.
+- application/vnd.oci.image.config.v1+json (config)
-Credential resolution is automatic: skillctl reads podman/docker auth configs, so if you've
-done 'podman login quay.io', push/pull just works.
SkillCard schema: docsclaw.io/v1alpha1 kind: SkillCard. The metadata travels inside the
-OCI manifest annotations, so 'skill inspect' reads it without pulling the full layer.
+Skill metadata is stored in OCI manifest annotations (io.skillimage.*) for fast
+inspection without pulling the full layer.
skillctl build produces standard OCI images (FROM scratch). Since skills are OCI images,
+podman pull, skopeo copy, and Kubernetes ImageVolumes all work natively.
-Future vision: a Skill Catalog UI that queries registries, reads SkillCard metadata, and
-presents a searchable, browsable catalog of available skills โ like a curated app store
-for agent capabilities.
+Install auto-pulls from remote registries if the image isn't in the local store.
+Provenance (source registry and digest) is recorded in the installed skill's skill.yaml
+for later upgrade tracking.
SkillCard schema: skillimage.io/v1alpha1 kind: SkillCard. The metadata travels inside the
+OCI manifest annotations, so 'skillctl inspect' reads it without pulling the full layer.
The SkillCard schema is intentionally extensible: additional fields (compatibility matrix,
-test results, usage metrics) can be added without breaking existing skills.
Image Volumes (KEP-4639): GA in Kubernetes 1.33 / OpenShift 4.20.
+test results, usage metrics) can be added without breaking existing skills.
Image Volumes (KEP-4639): GA in Kubernetes 1.33 / OpenShift 4.20.
The kubelet pulls the image via the container runtime and mounts it read-only into the pod.
No init container, no PVC, no emptyDir. The image is cached in the node's container image
store โ subsequent pods that use the same skill image don't need to pull again.
This is the exact same mechanism used for container images, so existing image pull policies
-(IfNotPresent, Always), pull secrets, and registry mirrors all work.
For older clusters, the init container approach uses skillctl to pull skills from the
+(IfNotPresent, Always), pull secrets, and registry mirrors all work.
For older clusters, the init container approach uses skillctl to pull skills from the
registry before the main container starts. Use a PVC (not emptyDir) to persist the skill
cache across pod restarts and avoid filling node ephemeral storage.
Signature verification happens at pull time: --verify + --key flags enforce cosign
-verification before extracting the skill.
The before/after contrast highlights what OCI distribution adds to the picture. All the
+verification before extracting the skill.
skillctl install is the easiest way to get started. It pulls the skill image from the
+registry and extracts it into the target directory. The --target flag lets you specify
+the agent you're installing for, so the skill is extracted to the correct location.
The before/after contrast highlights what OCI distribution adds to the picture. All the
"after" properties come for free from the OCI ecosystem โ registries, sigstore, RBAC,
-pull policies โ we're just reusing existing infrastructure.
The OpenShift platform team is also building support for this. The oc-mirror tool needs a
+pull policies โ we're just reusing existing infrastructure.
The OpenShift platform team is also building support for this. The oc-mirror tool needs a
recognizable MIME type (application/vnd.redhat.agentskill.layer.v1+tar) to
identify skill artifacts for mirroring. skillctl supports this as an optional
media type alongside the standard OCI types.
@@ -1775,22 +2190,15 @@
Thank You
The podman/docker extraction path is important for users who don't want to install
-skillctl. Since skills are standard OCI images, any container runtime can pull and
-extract the content.
-
-Zip format: skillctl can bundle a .zip alongside the OCI image for consumers that
-can't work with OCI natively (e.g. some coding assistants). Low implementation
-effort โ just create a zip of the skill directory and push as an additional layer
-or separate artifact.
+automatically includes the skill images.
skillctl install is the simplest path for developers. Supports Claude Code, Cursor,
+Windsurf, OpenCode, and OpenClaw. Since skills are standard OCI images, any container
+runtime can also pull and extract the content.
skillctl tracks provenance (source registry and digest) in each installed skill's
+skill.yaml. This lets it check for newer published versions and upgrade in place.
-Ann Marie Fred (OpenShift AI) noted that coding assistants can't natively load OCI
-artifacts yet. Multiple consumption paths lower the barrier to adoption.
Resources:
-- OpenShift platform: agent skill packaging, OLM operator integration, skill discovery
-- PR #21: github.com/redhat-et/docsclaw/pull/21
-- Design spec: docs/dev/2026-04-12-oci-skill-distribution-design.md
-- OCI skills guide: docs/oci-skills-guide.md
+The upgrade command only considers published versions (no -draft or -testing suffixes)
+and uses strict semver comparison. Local skills without provenance are skipped.
Resources:
+- Project: github.com/redhat-et/skillimage
- Agent Skills OCI Spec: github.com/ThomasVitale/agents-skills-oci-artifacts-spec
- ORAS project: oras.land
-- Zot registry: zotregistry.dev
Thank you for your time. Questions and feedback welcome.