volcengine-prepare — Claude Code skill: deployment analysis
The volcengine-prepare Claude Code skill examines a project before deployment to Volcengine. It ranks viable options across ECS, VKE, and veFaaS.
MIT 119 installs ★ 37 updated 2026-11-16
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-prepare -a claude-codeWhat volcengine-prepare does
The skill inspects a local project or Git repository to identify a deployable target, such as a service or static site. It checks the language, framework, entry point, port, dependencies, migrations, and Docker packaging signals. A Dockerfile or build script alone does not establish that a project is ready to deploy.
Once it finds a concrete target, the skill compares suitable options among ECS, VKE, and veFaaS, then recommends CLI or IaC for resource management and asks for confirmation. If the target is unclear, it asks which service, directory, or command should be deployed. Path-specific tool checks happen after a deployment option is chosen.
Cloud identity checks are optional and run only when credentials are available. Git URLs are cloned into a temporary directory; .volcengine/ stores minimal state when work continues across steps.
What it helps with
- identify a repository component that can be deployed
- compare ECS, VKE, and veFaaS for a project
- choose CLI or IaC for resource management
- clarify the deployment target before selecting a path
Example prompts for the agent
- Analyze this repository and recommend a way to deploy it to Volcengine.
- Check whether this project is ready for Volcengine and compare ECS, VKE, and veFaaS.
- Which deployment mode fits this project?
How to install volcengine-prepare
1Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-prepare -a claude-code2Manually: put the files in place
~/.claude/skills/volcengine-prepare/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/volcengine-prepare/
1Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-prepare -a codex2Manually: put the files in place
.agents/skills/volcengine-prepare/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-prepare -a cursor2Manually: put the files in place
.cursor/skills/volcengine-prepare/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install volcengine/volcengine-agent-toolkit plugins/volcengine-service-support/skills/volcengine-prepare2Manually: put the files in place
.github/skills/volcengine-prepare/SKILL.md1Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-prepare -a gemini-cli2Platform CLI
gemini skills install https://github.com/volcengine/volcengine-agent-toolkit --path plugins/volcengine-service-support/skills/volcengine-prepareManually: put the files in place
.devin/skills/volcengine-prepare/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-prepare -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about volcengine-prepare
How do I install volcengine-prepare in Claude Code?
Run npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-prepare -a claude-code. The skill file is placed at ~/.claude/skills/volcengine-prepare/SKILL.md.
What does volcengine-prepare do?
It examines a project before a Volcengine deployment, identifies a concrete target, and ranks viable ECS, VKE, and veFaaS paths. It also recommends CLI or IaC for managing resources.
What does volcengine-prepare need to check a cloud account?
For the optional identity check, use ve login or provide VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY. VOLCENGINE_SESSION_TOKEN supports temporary credentials, and VOLCENGINE_REGION sets the region; repository analysis can continue without the identity check.
Source text
SKILL.md · MIT
---
name: volcengine-prepare
description: >-
Use when the user wants to deploy a local directory or GitHub repository to Volcengine and
needs the project analyzed, the app shape understood, and a ranked recommendation across
ECS, VKE, and veFaaS before choosing an execution path. Also trigger when the user asks
"what deploy mode should I use", "is this repo ready for Volcengine", or "check my repo
before deploying". This skill prepares the decision; `volcengine-deploy` skill performs the
chosen deployment, and `volcengine-iac` skill is used only when the user chooses Terraform/IaC
or the task already has an IaC workflow.
license: MIT
metadata:
openclaw:
envVars:
- name: VOLCENGINE_ACCESS_KEY
required: false
description: AccessKey for AK/SK auth path (alternative to `ve login`)
- name: VOLCENGINE_SECRET_KEY
required: false
description: SecretKey for AK/SK auth path
- name: VOLCENGINE_SESSION_TOKEN
required: false
description: Optional STS session token for temporary credentials
- name: VOLCENGINE_REGION
required: false
description: Default region; falls back to cn-beijing if unset
---
# 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 (`cli` or `iac`) per [`references/deploy-mode-heuristics.md`](./references/deploy-mode-heuristics.md), and ask the user to confirm.
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:
```text
.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.
```bash
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:
```bash
analysis=$(bash scripts/analyze-repo.sh "$repo_dir")
echo "$analysis" | jq .
```
Show the important findings in plain language:
```text
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
Verify identity by running the call directly. It is the credential check; do not print or list environment variables (`env`, `printenv`, `echo $VOLCENGINE_*`) to see whether credentials are set:
```bash
ve sts GetCallerIdentity
```
Do not read `~/.volcengine/config.json`; it may contain secrets. If the call fails for lack of credentials, 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:
```bash
services=$(bash 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:
```text
<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:
```text
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`](./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. Fill the resource management recommendation from [`references/deploy-mode-heuristics.md`](./references/deploy-mode-heuristics.md), but do not mention that internal reference path to the user:
```text
Resource management recommendation: <iac|cli>. Reason: <one short user-facing reason>. Confirm `iac` or `cli`.
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:
```text
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 per [`references/deploy-mode-heuristics.md`](./references/deploy-mode-heuristics.md), but do not turn it into a default. Ask the user to 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 [`references/deploy-mode-heuristics.md`](./references/deploy-mode-heuristics.md)
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:
```json
{
"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
```text
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>
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`
```
© volcengine · MIT · volcengine/volcengine-agent-toolkit