cmd: add commands for managing AI skills

[stefanprodan]

The flux-operator skills commands are used to manage AI agent skills distributed as OCI artifacts.
Skills are installed to the .agents/skills directory in the current working directory and tracked via a catalog.yaml file.

The following commands are available:

• flux-operator skills install <repository>: Install skills from an OCI artifact.
  • --tag: OCI artifact tag (default latest).
  • --agent: Agent ID(s) for which to create skill symlinks, can be specified multiple times (e.g. claude-code).
  • --verify: Verify the cosign signature of the artifact (default true).
  • --verify-oidc-issuer: OIDC issuer for signature verification (auto-derived for ghcr.io hosts).
  • --verify-oidc-subject-regex: OIDC subject regexp for signature verification (auto-derived for ghcr.io hosts).
  • --verify-trusted-root: Path to a trusted_root.json file for offline signature verification.
• flux-operator skills list: List all installed skills and their sources.
• flux-operator skills update: Check for new versions of all installed skills and update them.
  • --verify-trusted-root: Path to a trusted_root.json file for offline signature verification.
  • --dry-run: Only check for updates without installing them (exits with code 1 if updates are available).
• flux-operator skills uninstall <repository>: Uninstall all skills from the specified repository.
  • --all: Uninstall all skills from all repositories.
• flux-operator skills publish <repository>: Package a local skills directory and push it as an OCI artifact.
  • --path: Path to the skills directory (default skills).
  • --tag: OCI artifact tag, can be specified multiple times (default latest).
  • --diff-tag: Only push if the contents differ from the specified tag.
  • --annotation, -a: OCI manifest annotation in key=value format, can be specified multiple times.
  • --sign: Sign the artifact with cosign keyless (default false).
  • --output, -o: Output format (json).

---

Example:

$ flux-operator skills install oci://ghcr.io/fluxcd/agent-skills --tag main --agent claude-code --agent kiro
◎ Resolving artifact digest...
✔ Using digest sha256:23ef861c88809d387c8592e6422225f5ec1a6ecca334784eac2c8acae5600d57
◎ Verifying artifact signature...
✔ Artifact signature verified
◎ Pulling skills artifact...
◎ Installing skills...
✔ Installed 2 skill(s) from ghcr.io/fluxcd/agent-skills:main
  • gitops-cluster-debug
  • gitops-repo-audit

Generated catalog at .agents/skills/catalog.yaml (this file can be manually edited, serves as the desired state of all skills):

apiVersion: agent.fluxcd.controlplane.io/v1
kind: Catalog
spec:
  sources:
  - repository: ghcr.io/fluxcd/agent-skills
    tag: main
    targetAgents:
    - claude-code
    - kiro
    verify:
      matchOIDCIdentity:
      - issuer: https://token.actions.githubusercontent.com
        subject: ^https://github\.com/fluxcd/.*$
      provider: cosign

Generated lock at .agents/skills/catalog-lock.yaml (this file tracks the installed skills):

# This manifest was generated by flux-operator. DO NOT EDIT.
apiVersion: agent.fluxcd.controlplane.io/v1
kind: Catalog
spec:
  sources:
  - repository: ghcr.io/fluxcd/agent-skills
    tag: main
    targetAgents:
    - claude-code
    - kiro
    verify:
      matchOIDCIdentity:
      - issuer: https://token.actions.githubusercontent.com
        subject: ^https://github\.com/fluxcd/.*$
      provider: cosign
status:
  inventory:
  - annotations:
      org.opencontainers.image.created: "2026-03-11T16:47:05Z"
      org.opencontainers.image.description: AI Agent Skills for Flux CD
      org.opencontainers.image.licenses: Apache-2.0
      org.opencontainers.image.revision: refs/heads/main@sha1:506f842acca8270e72ae4964fb0d3ef78c970934
      org.opencontainers.image.source: https://github.com/fluxcd/agent-skills
    digest: sha256:9b3b5329ad7ade457cfddb1d72f514205d06d8bfb0feb3032a3e1b12965a19bd
    id: 8e890a5d
    lastUpdateAt: "2026-03-11T21:15:33Z"
    skills:
    - checksum: h1:lOkd0jRjxBhOyRzO9m55aR9CDI32hMIVAQ4GkAwTVwc=
      name: gitops-cluster-debug
    - checksum: h1:1uSv6ILjfiF/3IJ6FUZi3Esx7iKUIrKmbr5JavGDGNg=
      name: gitops-repo-audit
    url: ghcr.io/fluxcd/agent-skills:main

[matheuscscp]

LGTM! 🚀