proposal: Agent Skills catalog and deployah skills install

[atkrad]

Problem

Deployah's Spec-to-Release model (developer deployah.yaml vs platform file, no Helm authorship) is easy for humans who read the README and easy for agents to get wrong (they default to writing Deployments/Helm charts). There is no official, installable set of Agent Skills (SKILL.md) that teach agents Deployah workflows.

Cursor can import skills from GitHub, and the Agent Skills layout is an open standard (agentskills.io), but Deployah has neither a published catalog nor a CLI path to install them into a project.

Goals

• Publish a small official skill catalog for Deployah (portable SKILL.md folders).
• Document install via Cursor (GitHub import) and via CLI.
• Add deployah skills subcommands to list/install/update/remove skills into standard agent skill directories.
• Keep skills versioned independently of the Go binary (catalog repo or dedicated path), with an optional lockfile (commit SHA / tag).
• Stay on the open skill format; do not invent a proprietary package format.

Non-goals

• Running an LLM inside Deployah, or making deployah skills an agent runtime.
• Embedding large skill bodies in the release binary.
• Cursor team marketplace packaging in v1 (nice follow-up).
• Replacing README/docs; skills complement docs for agent workflows.
• Teaching every future feature (build proposal: optional Dockerfile / Buildx image build #26/proposal: optional Cloud Native Buildpacks image build #27, KEDA proposal: support KEDA event-driven autoscaling #25, mesh proposal: first-class platform service mesh config #23/proposal: developer mesh traffic intent #24) in v1; add skills as those land.

Proposed design

Catalog (publish)

Prefer a dedicated repo, e.g. deployah-dev/skills (name open):

skills/
  deployah-spec/SKILL.md
  deployah-platform/SKILL.md
  deployah-init/SKILL.md
  deployah-plan-deploy/SKILL.md
  deployah-extras/SKILL.md
index.yaml              # name, description, version, path, optional minDeployah
README.md               # Cursor UI + CLI install

Main Deployah README links to the catalog. Skills may include references/ for field tables and examples; keep each SKILL.md short.

v1 skill list (suggestion):

Skill	Triggers	Content
deployah-spec	deployah.yaml, writing components	schema, roles/kinds, expose, resources, not-yet-deployable fields
deployah-platform	platform file, profiles	domains, TLS, storageClasses, merge rules, ownership split
deployah-init	new project	deployah init, local cluster, first deploy
deployah-plan-deploy	plan/deploy/debug	plan UX, hostname guard, capabilities, common errors
deployah-extras	extras/CRDs	.deployah/extras, reserved identities

Use paths frontmatter where useful (**/deployah.yaml, **/deployah.platform.yaml).

Also support Cursor install without CLI: GitHub URL import per Cursor skills docs.

CLI (deployah skills)

Thin installer only:

deployah skills list
deployah skills install [name|all] [--global] [--source URL] [--ref tag|sha]
deployah skills update [name|all]
deployah skills remove <name>
deployah skills path

Default	Effect
Project install	./.agents/skills/<name>/ (cross-agent; Cursor discovers this)
--global	~/.agents/skills/<name>/ (document ~/.cursor/skills/ as alternate)
Source	https://github.com/deployah-dev/skills (override via flag / DEPLOYAH_SKILLS_URL)
Method	Shallow clone or release archive; copy skill dirs; write .deployah/skills.lock with pinned ref

Security: only configured sources; show what will be written; do not execute skill scripts/ at install time.

Optional: index.yaml minDeployah warns when the CLI is too old.

Behavior / UX notes

• install is idempotent; update refreshes to latest catalog ref (or pinned --ref).
• Prefer .agents/skills/ so the same files work in Cursor and other Agent Skills clients.
• Project vs global: document that teams may commit project skills or gitignore them and install in CI/devcontainer.

Alternatives considered

1. Skills only inside the main deployah git repo (.agents/skills/). Fine for contributors; weak for app teams who never clone deployah. Catalog repo is better for consumers; optional mirror/submodule later.
2. Cursor marketplace only. Leaves CLI/OSS users without a path; defer marketplace.
3. Ship skills inside the binary. Hard to update; wrong artifact type.
4. Depend on a third-party skills package manager only (e.g. community skills-pm). Useful ecosystem, but Deployah should own an official one-liner for its catalog.

Compatibility and migration

• Additive CLI; no change to deploy/plan behavior.
• No requirement to install skills to use Deployah.
• Related future skills: Compose migrate (proposal: import Docker Compose into a Deployah spec #20), KEDA (proposal: support KEDA event-driven autoscaling #25), Dockerfile/buildpacks (proposal: optional Dockerfile / Buildx image build #26/proposal: optional Cloud Native Buildpacks image build #27), mesh (docs: service mesh via profiles (podAnnotations / podLabels) #22–proposal: developer mesh traffic intent #24).

Test plan

• Catalog: each skill has valid frontmatter (name, description); name matches folder
• Unit: install copies into .agents/skills/ and writes lockfile
• Unit: --global, remove, refuse unknown skill name
• Manual: Cursor discovers installed skills; /deployah-spec works
• Docs: README section "AI / Agent Skills" with both install paths

Checklist

• I searched existing issues and discussions
• This includes enough design detail for implementation (not only a wish)