Volcengine Prepare

Volcengine Prepare Skill

Analyze a repo, explain viable Volcengine deployment paths, and decide the resource management path. Treat this skill as decision support, not as a workflow engine. Do not make a heavy report schema the goal.

---

0. Core behavior

Default flow:

1. Resolve the repo from a local path or Git URL. 2. Run the analyzer to identify language, framework, port, Docker/compose shape, dependencies, migrations, entrypoint, and the deployable service surface. 3. Optionally verify the current Volcengine identity and region when credentials are available. 4. Present a ranked list of ECS / VKE / veFaaS only after a deployable service surface is clear. Include every materially viable path; explain why each path is attractive or costly. Use ecs | vke | vefaas as machine-readable mode values. 5. Recommend a resource management path, but ask the user to choose cli or iac. Recommend IaC for VKE, managed dependencies, team-managed infrastructure, or plan/diff/destroy requirements; recommend CLI for pure ECS single-VM deployments, temporary validation, missing Terraform, blocked provider registry access, or explicit CLI preference. 6. Ask only for product/lifecycle ambiguity, resource reuse, and the resource management choice. If the user says "you decide", use the first ranked runtime path, the recommended resource management path from these rules, and new isolated resources. 7. Persist only minimal state in .volcengine/ when the work will continue across steps.

Before ranking ECS / VKE / veFaaS, identify the concrete deploy target: the repo, subdirectory, command, artifact, static output, or existing cloud app/function that a path can actually run, containerize, expose, or serve. File-level signals are evidence, not conclusions. A Dockerfile, compose file, package.json, framework dependency, or build/dev/test script does not by itself prove the repo is deployable.

Do not run strict tool dependency checks during recommendation. Check path-specific tools only after the user chooses a path.

State directory:

.volcengine/
  deploy-choice.json       # chosen mode/resource strategy, when persistence is useful
  created-resources.json   # maintained by deploy only for CLI fast path
  terraform/               # IaC working files, only when infra_management=iac
  iac-outputs.json         # Terraform outputs consumed by deploy

Use /tmp only for temporary clones or caches.

---

1. Resolve and analyze the repo

For Git URLs, clone to a temporary cache. For local paths, analyze in place.

input="${1:-.}"
if [[ "$input" =~ ^(https?|git@) ]]; then
  repo_name=$(basename "$input" .git)
  cache_dir="/tmp/volcengine-prepare/$repo_name"
  mkdir -p "$cache_dir"
  [ -d "$cache_dir/src/.git" ] || git clone --depth 1 "$input" "$cache_dir/src"
  repo_dir="$cache_dir/src"
else
  repo_dir=$(cd "$input" && pwd)
  repo_name=$(basename "$repo_dir")
fi
git_sha=$(cd "$repo_dir" && git rev-parse --short HEAD 2>/dev/null || echo "unversioned")

Run:

skill_dir="$(dirname "$0")"   # or the path to this skill
analysis=$(bash "$skill_dir/scripts/analyze-repo.sh" "$repo_dir")
echo "$analysis" | jq .

Show the important findings in plain language:

Project: <repo_name> @ <git_sha>
Runtime: <language> / <framework>
Deployable subdir: <deploy_subdir or repo root>
Deployable surface: <web service | rpc service | http api | static/html site | full-stack app | user-specified service | unclear>
Entrypoint: <entrypoint>
Port: <port>
Packaging signals: Dockerfile=<yes/no>, compose=<yes/no if detected>
Dependencies: <mysql, redis, ...>
Migrations: <paths or none>

If the analyzer cannot identify a concrete ECS/VKE/veFaaS deploy target, ask what subdirectory, service, command, artifact, static output, or existing veFaaS app/function should be deployed before recommending a path. Downgrade to confirmation instead of a strong recommendation when the repo appears to be primarily build tooling, packaging, examples, docs, or reusable code rather than an application surface.

A deploy target is something that can be run, containerized, exposed, or served by ECS, VKE, or veFaaS. Useful evidence includes, but is not limited to:

• a long-running process with a start command,
• a listening port or RPC/API/HTTP route,
• a static/HTML site entry or build output intended for serving,
• a health check or smoke endpoint,
• frontend and backend/API pieces with a clear service boundary,
• an explicit user instruction naming the service, subdirectory, command, artifact, or runtime target.

Do not infer deployability from a Dockerfile, package scripts, or build tooling alone.

---

2. Optional cloud identity check

If VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY, and VOLCENGINE_REGION are set, verify identity:

ve sts GetCallerIdentity

Do not read ~/.volcengine/config.json; it may contain secrets. If env vars are absent, keep the recommendation going and tell the user credential checks will happen when executing the chosen path.

If cloud service availability matters for a near-term choice, run the read-only probe:

services=$(bash "$skill_dir/scripts/check-region-services.sh")
echo "$services" | jq .

Surface permission or region notes in the corresponding option; do not hide that option.

Prechecks are advisory, not gates. If you can cheaply check quotas or permissions, present the result as a risk:

<quota/permission> may be insufficient; continuing could fail when creating resources. Proceed anyway?

If account real-name verification or balance cannot be queried reliably, give a short reminder instead of inventing a check:

Creating cloud resources may require a real-name-verified account with sufficient balance/credit; if creation fails, resolve the account status in the console first.

---

3. Recommend deployment paths

Use `references/deploy-mode-heuristics.md` for the detailed decision rules. Present a ranked list, not recommended=true/false flags or scoring internals. If the deployable surface is unclear, present the ambiguity first and ask the smallest follow-up question before ranking.

Include every materially viable option; do not force a full ECS / VKE / veFaaS comparison when the repo or user request clearly rules a path out. Mention a non-viable path only when its exclusion helps the user decide.

• ECS: VM path. Best for targets that can run on a Linux VM, such as Web/API/RPC services, full-stack apps, static-site serving processes, binaries, Docker/compose apps, workers, scheduled commands, or apps needing OS/network/disk/debugging control.
• VKE: Container/Kubernetes path. Best for containerized or Kubernetes-shaped targets, such as multi-service apps, Web/API/RPC containers, workers, Jobs/CronJobs, rolling updates, replicas, HPA, Ingress/Service, GPU workloads, or production container operations.
• veFaaS: Serverless path. Best only when the target fits the volcengine-vefaas skill workflow: supported Web/API or frontend/static frameworks, or an existing veFaaS app/function. Prefer ECS/VKE for long-running workers, multi-service orchestration, complex migrations, unsupported event/task/trigger creation, custom system dependencies, or no available API Gateway. If the user chooses it, switch to/call the volcengine-vefaas skill for deployment; if that fails, return to the main flow so the user can retry or choose ECS/VKE.

Include:

• why it is ranked where it is
• rough cost level (low, medium, medium-high)
• operational tradeoffs
• known blockers or setup needed if the user chooses it
• resource management recommendation (iac or cli) and why

Do not check every tool before the user chooses. Phrase setup needs as decision guidance:

Resource management needs user confirmation: recommend Terraform/volcenginecc for VKE, managed database/cache/storage/LB/domain/certificate, or long-lived team resources; recommend the ve CLI fast path (record a resource ledger) for plain single-VM ECS, temporary validation, or when Terraform / the provider registry is unavailable.
Choosing VKE will check kubectl; if you choose IaC it will also check terraform/provider availability.
Choosing veFaaS switches to / calls the `volcengine-vefaas` skill to check the vefaas CLI, login status, and framework detection; on failure it returns here so you can fix it and retry, or switch to ECS/VKE.

---

4. Ask only necessary questions

After showing the ranked list, ask only what cannot be safely inferred:

1. Deployment mode: defaults to the top-ranked option. Choose ECS / VKE / veFaaS (recorded as `ecs` / `vke` / `vefaas`).
2. Resource strategy: defaults to a new isolated project deploy-<repo> with new resources; you may also reuse existing resources.
3. Database product/engine, only when a managed database is detected or requested: choose `rds/mysql`, `rds/postgresql`, `rds/sqlserver`, `aidap/supabase`, or `aidap/postgresql`.
4. Resource management: recommend <cli|iac>; confirm whether to use the CLI resource ledger or Terraform/IaC.

For MySQL dependencies, use database_product=rds and database_engine=mysql unless the user rejects managed RDS. For SQL Server dependencies, use database_product=rds and database_engine=sqlserver. For PostgreSQL dependencies, preserve explicit user intent first: choose RDS PostgreSQL for an explicit RDS / managed RDS instance request, choose AIDAP PostgreSQL for an explicit AIDAP/serverless PostgreSQL request, and choose AIDAP Supabase for an explicit Supabase request. When the product is ambiguous and the user has not delegated the choice, ask because RDS PostgreSQL, AIDAP PostgreSQL, and AIDAP Supabase are different choices.

Ask whether to use Terraform/IaC explicitly. Give a recommendation, but do not turn it into a default:

Resource management recommendation: choose Terraform/volcenginecc for VKE, managed dependencies, long-lived team resources, or when you need plan/diff/destroy; choose the ve CLI fast path (record a resource ledger) for plain single-VM ECS, a temporary demo, or when Terraform / the provider registry is unavailable. Confirm `iac` or `cli`.

If the user says "you decide", use:

• deployment mode: first ranked option
• resources: create new isolated Volcengine project deploy-<repo>
• database product/engine: infer exact engines when unambiguous (mysql -> rds/mysql, sqlserver -> rds/sqlserver); for PostgreSQL, choose AIDAP Supabase (database_product=aidap, database_engine=supabase) when the project has no explicit RDS/AIDAP PostgreSQL/Supabase signal.
• resource management: apply the table in `references/deploy-mode-heuristics.md`: plain ECS single-VM without managed dependencies can be cli; VKE, managed dependencies, team-owned infrastructure, or plan/diff/destroy needs are iac

If the user chooses reuse, ask for only the resource IDs needed by that path. Reused resources must not be destroyed by cleanup.

---

5. Persist the user's choice only when useful

If execution continues in the same conversation, no file is required. If the user may resume later or the next step needs a durable handoff, write only a small choice record:

{
  "schema_version": "1",
  "repo_dir": "/absolute/path",
  "repo_name": "my-app",
  "git_sha": "abc1234",
  "region": "cn-beijing",
  "mode": "ecs",
  "port": 8080,
  "dependencies": ["postgresql", "redis"],
  "database_product": "aidap",
  "database_engine": "supabase",
  "resource_strategy": "create-isolated-project",
  "project": "deploy-my-app",
  "infra_management": "cli"
}

Write it to .volcengine/deploy-choice.json.

Do not write score tables, rationale arrays, or a full recommendation matrix unless the user asks for a report.

---

6. Summary template

Project detection:
- Runtime: <language>/<framework>
- Deployable surface: <surface or unclear, with evidence>
- Entrypoint/port: <entrypoint> / <port>
- Packaging signals: Dockerfile=<yes/no>, Compose=<yes/no>
- Dependencies: <deps or none>
- Database choice: <none | database_product=rds engine=mysql|postgresql|sqlserver | database_product=aidap engine=supabase|postgresql>
- Migrations: <paths or none>
- Resource management recommendation: <iac|cli> (VKE/managed dependencies/team resources usually suggest iac; plain single-VM ECS or unavailable IaC usually suggests cli)

Ranked order:
1. <mode>
   Reason: ...
   Tradeoff: ...
   Rough cost: ...

2. <mode>
   ...

3. <mode>
   ...

Please confirm:
1. Deployment mode: defaults to <first mode>
2. Resource strategy: defaults to a new isolated project deploy-<repo>; reuse is also possible
3. Resource management: recommend <iac|cli>; confirm `iac` or `cli`

Deploy Mode Heuristics

Use this when volcengine-prepare explains ECS / VKE / veFaaS choices. The output is a ranked recommendation for the user, not a score table and not a filter. Show every materially viable path, pick a default deployment mode when the deploy target is clear, and ask for lifecycle, reuse, and resource-management choices. Use ecs | vke | vefaas as machine-readable mode values.

Ranking rules

Rank by deployable service surface first. Do not demote a path just because a local tool is missing; tool checks happen after the user chooses.

If analysis reports deploy_subdir, rank the app in that subdirectory. Only treat a repo or subdirectory as deployable when there is a concrete target: the repo, subdirectory, command, artifact, static output, or existing cloud app/function that a path can actually run, containerize, expose, or serve.

File and framework signals are only evidence. A Dockerfile, compose file, package.json, framework dependency, or build/dev/test script does not by itself mean the repo is deployable.

Before ranking, identify whether there is a concrete deploy target for ECS, VKE, or veFaaS: something that can be run, containerized, exposed, or served by one of those paths.

Useful evidence includes, but is not limited to: a long-running process, start command, listening port, RPC/API/HTTP route, health/smoke endpoint, static/frontend build output intended to be served, clear frontend/backend service boundaries, existing veFaaS app/function, or a user-provided subdirectory, service, command, artifact, or runtime target.

If the surface is unclear, ask one focused follow-up before giving a strong recommendation:

I can see build/package signals, but not the deploy target yet. Which subdirectory, service, command, artifact, static output, or existing veFaaS app/function should be deployed?

Use this downgrade path for repos that look like a library/SDK, CLI tool, agent skill, plugin, desktop app, tutorial/demo fragment, documentation-only project, or monorepo root without a selected app. These repos are not ECS/VKE/veFaaS deployment targets by default. If the user explicitly asks to deploy one, continue by identifying the concrete runtime surface, such as a docs site, example app, demo API, service command, static build output, or artifact to run; do not reject the request just because of the repo category.

Prefer ECS when

• The user wants the fastest path to a public URL.
• The deployable surface can run on a Linux VM as a Web/API/RPC service, full-stack app, static-site serving process, binary, Docker/compose app, worker, or scheduled command.
• The project is simple enough for one VM or a small number of VMs.
• The repo has external dependencies but the selected service does not need Kubernetes-level rollout, autoscaling, or multi-service orchestration.
• The app needs OS, network, disk, package, or debugging control.
• The user needs a quick validation, fastest public URL, or one-VM shape. For resource management, recommend CLI for pure ECS single-VM deployments, especially when Terraform or provider registry access is unavailable. Recommend IaC for ECS when it is team-managed, needs managed dependencies, or needs plan/diff/destroy safety.

ECS packaging:

Explain the default ECS shape:

• It creates or reuses an ECS instance.
• New public services get an EIP as the access endpoint.
• Ask the user whether to open SSH 22. If they do not want SSH, deploy and debug through Cloud Assistant.
• Approximate cost: medium (ECS instance + system disk + EIP/bandwidth; plus any managed dependencies).

Prefer VKE when

• The selected deployable surface is containerized or naturally maps to Kubernetes workloads.
• The app needs multiple replicas, rolling updates, HPA, Kubernetes Jobs/CronJobs, Ingress/Service, or network policies.
• The selected app has multiple services, multiple languages, or several long-running processes.
• Migrations or workers need a cleaner lifecycle than a single systemd service.
• The workload needs GPU resources or production container operations.
• The user wants a production-shaped container platform.

Recommend Terraform/volcenginecc for VKE resource creation because clusters, node pools, CR, LB, and managed dependencies benefit from plan/diff/destroy safety. Use ve CLI plus .volcengine/created-resources.json only if the user chooses CLI after seeing the tradeoff, for temporary validation, or when Terraform is unavailable.

Approximate cost: medium-high (VKE nodes + CR + CLB/EIP + bandwidth; plus databases/cache/storage).

Prefer veFaaS when

• The target fits the volcengine-vefaas skill workflow: a supported Web/API framework, supported frontend/static framework, or an existing veFaaS app/function.
• The target is an MCP project and does not have a user-mandated ECS runtime. For MCP, rank veFaaS first, ECS second, and do not recommend VKE by default because this workflow needs session keeping.
• There are no complex in-band DB migrations, long-running workers, multi-service orchestration needs, unsupported event/task/trigger creation, custom system dependencies, or API Gateway blockers.
• The framework is likely supported by the volcengine-vefaas skill, such as FastAPI, Django, Flask, Express, Next.js, Nuxt, NestJS, Remix, Vite, Astro, Vitepress, Rspress, Create React App, or Angular.
• Low operational overhead and pay-by-use economics matter more than infrastructure control.

If the user chooses veFaaS, switch to/call the volcengine-vefaas skill. If it fails, return to the main deployment flow and let the user retry veFaaS or switch to ECS/VKE. Do not use the legacy ZIP/API flow in volcengine-deploy.

For MCP projects, use volcengine-vefaas/references/mcp-deployment.md after selecting veFaaS. VKE is only appropriate when the user explicitly asks for Kubernetes and already has a session-affinity plan.

Approximate cost: low-medium (function resources + API Gateway; plus dependency services if used).

Common warning signals

Mention these in the relevant option, but do not hide the option:

Suggested recommendation patterns

Go API with Redis, no Dockerfile

1. ECS

• Reason: compiled service can run directly under systemd; Redis can be managed or run via compose for quick validation.
• Tradeoff: single-VM operation unless expanded later.

2. VKE

• Reason: good if the user wants replicas, rolling rollout, or managed Redis wiring.
• Tradeoff: more resources and setup.

3. veFaaS

• Reason: low ops if the app is stateless.
• Warning: Redis and any migration/worker behavior must be confirmed.

Existing Dockerfile plus database migrations

1. VKE

• Reason: containerized app and migrations map cleanly to Deployment + Job.

2. ECS

• Reason: simpler if one VM is enough; run Docker or compose on ECS.

3. veFaaS

• Warning: migrations need a separate plan and framework support must be verified by volcengine-vefaas; failure should return to the main flow for retry or ECS/VKE selection.

FastAPI / Next.js with no external dependencies

1. veFaaS

• Reason: supported framework shape, low ops, pay-by-use.

2. ECS

• Reason: fastest predictable VM path with EIP.

3. VKE

• Reason: valid but heavier unless the user wants Kubernetes.

MCP project

1. veFaaS

• Reason: default MCP path for HTTP exposure and session keeping.

2. ECS

• Reason: fallback when veFaaS does not fit the runtime, dependency installation, or system-control needs.

3. VKE

• Warning: not a default MCP path; use only when the user explicitly asks for Kubernetes and already has a session-affinity plan.

Resource management recommendation

Recommend resource management, then ask the user to choose:

For China network conditions, include a note when Docker images are involved: Docker Hub and GHCR may be slow or blocked. Deployment should prefer Volcengine CR, user-provided registries, or an inspected domestic mirror/sync URL over direct public registry pulls.

User confirmation

After presenting the ranked list, ask only:

1. Deployment mode: defaults to the top-ranked option. Choose ECS / VKE / veFaaS (recorded as `ecs` / `vke` / `vefaas`).
2. Resource strategy: defaults to a new isolated project deploy-<repo> with new resources; you may also reuse existing resources.
3. Resource management: recommend <cli|iac>; confirm whether to use the CLI resource ledger or Terraform/IaC.

Mention the resource management recommendation, then ask for confirmation:

Resource management recommendation: choose Terraform/volcenginecc for VKE, managed dependencies, and team resources; choose the ve CLI fast path (record a resource ledger) for plain single-VM ECS, temporary validation, or when IaC is unavailable. Confirm `iac` or `cli`.