| name | one-cli |
| description | Use this skill for any task involving One CLI monorepo workspaces. Triggers include creating a new project / workspace ("create a new project", "scaffold a workspace", "建一个新项目", "新建 workspace", "搭脚手架"), adding projects ("add a backend", "add a frontend", "新增一个服务", "加一个前端应用"), fixing or diagnosing workspaces ("fix the workspace", "检查项目", "修一下", "manifest is out of sync"), and looking up exact command / JSON schema / error code information. The CLI is a Go binary called `one` distributed as a single static binary via curl installer / GitHub Releases. |
| license | MIT |
| metadata | {"author":"torchstellar-team","version":"0.1.0"} |
One CLI — Unified Skill
This skill covers every interaction with One CLI,
a Go-based scaffolding + governance tool for AI-Native monorepo workspaces.
Commands are minimal (create, add, templates, env,
container, dev, deploy, run, configure, serve, skills),
but each user intent has its own playbook in references/.
Quick Routing
Decide which mode applies, then read only that one file —
progressive disclosure keeps the context window tight.
| User wants to … | Read |
|---|
| Create a new workspace from scratch | references/bootstrap.md |
| Add a project from a template | references/add-feature.md |
| Install missing JS/Go dependencies before build/test/run | references/dependencies.md |
| Wire a service to consume env vars (Go / NestJS) | references/env-consumption.md |
| Look up a command / JSON schema / error code | references/REFERENCE.md |
If you're unsure, read references/INDEX.md for a decision tree, or
default to references/REFERENCE.md (passive lookup, no action).
Binary Prerequisite (READ BEFORE EVERY MODE)
Every workflow assumes the one binary is on PATH. Verify:
one --version
If this command fails, stop and tell the user:
One CLI 还没装。请用 curl 一键安装（macOS / Linux）：
curl -fsSL https://1cli.dev/install.sh | bash
或从 GitHub Releases 下载对应平台的归档：
https://github.com/1cli-team/one-cli/releases/latest
装完再回来重试这个请求。
Do not install the binary yourself, even with prior permission —
global binary installs are outside an agent's normal authority.
Hard Rules (apply to every mode)
1. Always use -o json / --output json for parseable output
Every command supports -o json / --output json; piped output auto-enables it
regardless. Pass it explicitly so behaviour is deterministic:
one templates -o json
one add nestjs-api --name user-api --yes -o json
2. Read error.code, never parse error.message
Errors flow as {schema: "one-cli/error/v1", error: {...}} envelopes.
error.code is stable; error.message is for humans and may change
with i18n. Branch on the code.
3. Use error.context instead of making redundant calls
Many errors include the data you'd otherwise need to fetch separately.
TEMPLATE_NOT_FOUND carries available_templates. Use those before
re-running probe commands.
4. Workspace root = one.manifest.json
A directory is a One workspace iff it carries one.manifest.json at
the root. Don't guess by layout. Walk upward from cwd to find the
nearest one.manifest.json; that ancestor is the workspace root.
5. Don't hand-edit generated agent docs in workspaces
AGENTS.md, CLAUDE.md, and .one/agents/** are generated from
one.manifest.json by one create / one add. AGENTS.md is the
canonical route entry and CLAUDE.md is only a pointer. If generated
docs are wrong, fix the manifest/template source and rerun the CLI. If
the CLI refuses (AI_GUIDE_EXISTS), surface that to the user — don't
paper over.
6. Read workspace state from one.manifest.json
The manifest at the workspace root is the source of truth for
projects, backends, and generated agent-doc routes. Read it directly when
you need to introspect state — there is no separate read-only status
command.
7. --yes for non-interactive flow
one create and one add prompt in TTY mode for missing inputs.
When you drive them, always pass --yes plus explicit values for
required fields. Pipes already disable prompts; explicit --yes is
unambiguous.
8. Bootstrap missing dependencies by toolchain
This skill is for coding agents. When you create, add, build, test, or run a
One workspace and dependencies are missing, install them automatically unless
the user explicitly asked not to.
Use the project type, not a single hard-coded command:
- JS / TS / Node projects: install from the workspace root with the
detected package manager (
pnpm install, npm install, or yarn install).
- Go projects: install module dependencies from the Go project directory
with
go mod download; use go mod tidy after changing imports or when
go.mod / go.sum needs repair.
Read references/dependencies.md before choosing commands in mixed JS + Go
workspaces.
Common Error Recovery
| Code | Recovery |
|---|
NOT_ONE_PROJECT | Run one create <dir> first, or cd into a workspace that has one.manifest.json. |
INVALID_NAME | Names must match ^[a-zA-Z0-9][a-zA-Z0-9_-]*$. |
TEMPLATE_NOT_FOUND | Read error.context.available_templates. |
TARGET_EXISTS | Project directory already exists. Pick a different name. |
EXISTING_TARGET_NOT_EMPTY | Target exists and is non-empty. Ask the user to pick a different directory, or to delete the existing one. create no longer overwrites. |
AI_GUIDE_EXISTS | AGENTS.md / CLAUDE.md is user-managed. Don't fight it. |
PROMPT_CANCELLED | User pressed Ctrl-C. Treat as graceful exit. |
UNKNOWN_COMMAND | Misspelled command. Read references/REFERENCE.md for the current command surface. |
INFISICAL_* | See references/REFERENCE.md for the full Infisical error matrix. |
For the complete code → recovery mapping see references/REFERENCE.md.
References
