external-app-create

cozystack:external-app-create

This skill scaffolds a new Cozystack external app package. It creates all files needed for the app to appear in the Cozystack dashboard and be deployable via the GitOps pipeline (GitRepository → Flux HelmRelease → ApplicationDefinition).

This is a generate-only skill. It never applies anything to a cluster, never commits, and never pushes. The user handles git operations themselves.

Work in reasoning mode. Follow the phases in order. When a step fails or is ambiguous, stop and ask — do not guess API shapes or secret names.

Use the phrasing "cozystack:external-app-create" (not "the skill") in messages to the user, and state progress at each phase boundary.

Match the operator's natural language detected from prior conversation messages — use it in prompts, AskUserQuestion options, summaries, and gates. Generated Helm template files, ApplicationDefinition values, and any text destined for git or the cozystack dashboard stay in their canonical form (usually English) per cozystack's public-content rules.

Phase 1 — Parse arguments

$ARGUMENTS contains the free-form tail after /cozystack:external-app-create. Extract:

• Positional <app-name> — lowercase, hyphen-separated (e.g., immich, my-app). Required.
• --depends-on=<list> — comma-separated dependency names (e.g., postgres, redis). Default: none.
• --operator=<url> — Helm chart repository URL for a required operator (e.g., https://immich-app.github.io/immich-charts). Default: none.
• --repo-dir=<path> — path to the external-apps repository root. Default: current working directory.

If <app-name> is missing, use AskUserQuestion to ask for it.

Phase 2 — Pre-flight checks

Bail early if any check fails.

1. Repository structure: verify $REPO_DIR contains init.yaml, packages/core/platform/Chart.yaml, scripts/package.mk, and the five platform template files packages/core/platform/templates/{namespaces,helmrepositories,helmreleases,helmcharts,cozyrds}.yaml. If any are missing, tell the user to cd into the external-apps repo root or pass --repo-dir — Phase 8 appends to all five.
2. Tools installed: check that yq (v4), jq, base64, helm, and cozyvalues-gen are available via command -v. If cozyvalues-gen is missing, print:

   cozyvalues-gen is required. Install it from:
   https://github.com/cozystack/cozyvalues-gen/releases/latest
   

   Do not install it automatically. Stop.
3. No collision: verify packages/apps/$APP_NAME/ does not already exist. If it does, stop and ask the user whether to overwrite or pick a different name.
4. Cozystack contract resolution source: Phase 4 Step 2 needs to read packages/system/<dep>-rd/cozyrds/<dep>.yaml from cozystack. Detect the best available source in this order and record it as $COZYSTACK_CONTRACT_SOURCE:
   • local — $COZYSTACK_REPO is set and points at a cozystack checkout containing packages/system/. Fastest, works offline.
   • github — gh CLI is authenticated (gh auth status succeeds). Resolves against cozystack/cozystack@main.
   • cluster — kubectl config current-context succeeds and the target context is a cozystack cluster. Authoritative for that cluster version; read-only.