Covers asdf 0.16+ (the Go rewrite) for developers, CI/CD, and agents:
.tool-versions semantics, version resolution, shims, plugin sourcing,
CI/container recipes, troubleshooting, migration, and plugin authoring.
SKILL.md carries the mental model and the common path; six references
hold the depth (commands, setup, ci, troubleshooting, migration,
plugins) so only the relevant file is loaded per task.
Commands and flags were verified against internal/cli/cli.go and a live
0.18.0 binary rather than the docs, which are stale in places: 0.15-era
global/local/shell are documented as removed, and use_release_candidates
is noted as inert since it is commented out in the 0.16+ config struct.
Unique project names are global across the platform, not per wallet, so a
name another account holds fails as an opaque 5xx instead of a 409. The
wallet-scoped GET /agent/projects check cannot see it. Always append a
random suffix, and name that cause in the 5xx message.
Platform status "ready" precedes the container binding its port, so the
single endpoint probe raced the boot and reported a spurious 404. Probe
every ten seconds for up to two minutes, and treat a 404 that outlives
the window as the app's own answer rather than a failure.
The skill only had a TypeScript sample. Using it meant creating a
scratchpad, installing viem, and rewriting the sample before deploying.
The sample also hardcoded a two-file upload, so the file list had to be
written by hand.
Add deploy.mjs plus a pinned package.json, and fix the gaps found while
deploying a real Go project with this skill:
- Collect files with git ls-files instead of by hand. It honours
.gitignore, so build output and node_modules drop out with no list.
- Filter secrets. An untracked .env is not ignored by git, so it reached
the upload. That file usually holds the wallet key paying for the
deploy.
- Filter agent and editor tooling. In a six-file Go project, .agents/
added 39 files and grew the upload from 8 KB to 649 KB.
- Require --port. A wrong port only shows after payment: the deploy
reports ready and the endpoint answers nothing.
- Gate the payment behind --yes, and print the price first. The floor is
$0.50 but a real quote came to $1.81.
- Check the endpoint after ready, so a wrong port fails loudly.
- List existing projects, to name what a credit-sharing warning risks.
Docs: document the git collection step, port discovery, the price gate,
and that this gateway ignores createos.json. One Go project declared
node:20, reactjs-spa, and port 80 for a server listening on 8080.
Redeploying under an existing uniqueName stays an open question. It is
flagged as unverified rather than guessed, because names are validated
only after payment.
viem is pinned to 2.55.19, the current latest stable. Lock files stay
untracked: the exact pin already fixes the version, and a lock file only
creates churn when the skill is copied into a project.
* feat: add migration skill family; fix legacy .createos.io domain
Migration skill family (new):
- skills/vercel-to-createos — live, end-to-end tested against CreateOS
MCP. CreateProject (Pattern A: useBuildAI; Pattern B: explicit
commands) and CreateProjectEnvironment shapes verified.
- skills/{netlify,railway,heroku,render,flyio}-to-createos — reserved
stubs routing users to concierge migration until they ship.
- MIGRATIONS.md — category index at repo root (flat layout because the
skills CLI does not resolve nested category paths).
- README.md — adds vercel-to-createos row + migration section.
- skills/createos/SKILL.md — "See also" cross-link to migration family.
URL audit (existing skill):
- Replaced legacy .createos.io domain (DNS unreachable) with current
.createos.nodeops.network across createos/SKILL.md, references/
api-reference.md, references/deployment-patterns.md, and scripts/
quick-deploy.sh.
Known issues flagged in PR body:
- https://createos.nodeops.network/migrate currently 404s.
- Stray skills/SKILL.md (untracked, pre-existing) deliberately not
included in this commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(migrate): swap /migrate 404 URL for mailto:business@nodeops.xyz
The concierge migration URL referenced throughout the migration skill
family (https://createos.nodeops.network/migrate) currently 404s. Until
the landing page exists, route users to the business inbox instead.
Affects 15 references across 8 tracked files (vercel + 5 stubs, plus
MIGRATIONS.md and the createos See also section).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(createos): MCP endpoint path is /mcp not /sse in quick-deploy.sh
One-off inconsistency caught by @pratikbin in PR review. Every other
reference in the createos skill (SKILL.md, config.json,
deployment-patterns.md) already uses /mcp — this was the lone holdout.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Naman <naman307@Namans-MacBook-Pro.local>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Reduce SKILL.md from ~1230 to 336 lines (73% reduction)
- Fix hardcoded URLs - now extract from API responses
- Add allowed-tools to frontmatter
- Condense description to ~360 chars (from ~1015)
- Move detailed docs to references/core-skills.md
- Add references/troubleshooting.md for error handling
- Add tests/validate-skill.sh for skill validation
- Update scripts to parse actual URLs from API responses
Follows Anthropic's "Complete Guide to Building Skills for Claude":
- Progressive disclosure with 3-tier loading
- No content duplication between SKILL.md and references
- Imperative instruction style
- Scripts referenced for REST API usage
Co-authored-by: Naman <naman307@Namans-MacBook-Pro.local>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
pratikbin