Skip to main content
skill CX Codex

corezoid-init — Claude Code skill: setup and installation

corezoid-init connects a working directory to Corezoid, handles sign-in, and pulls a selected stage. Use it when starting a Corezoid project.

MIT ★ 74 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add corezoid/corezoid-ai-plugin
/plugin install corezoid@corezoid
Open on GitHub

What corezoid-init does

This skill sets up a Corezoid environment through the Corezoid MCP server. It starts with login, collects the Account URL, runs OAuth2, and guides workspace, project, and stage selection. With interactive elicitation, those choices appear as forms. Without it, the agent lists each set of options and waits for the user’s choice.

Once setup succeeds, the skill calls pull-folder to pull the selected stage. Auth state is stored in ~/.corezoid/config.json, while the stage marker is created in the workspace. API-key authentication is supported through api_login and api_secret passed to login. The workflow depends on access to the Corezoid MCP server.

What it helps with

  • connect a working directory to Corezoid
  • complete OAuth2 sign-in
  • choose a workspace, project, and stage
  • pull the selected stage with pull-folder
  • configure API-key authentication

Example prompts for the agent

  • Connect this working directory to Corezoid and set up the environment.
  • Sign in to Corezoid, show me the workspace list, and wait for my choice.
  • Use the provided api_login and api_secret, then pull the selected stage.

How to install corezoid-init

1Plugin marketplace

/plugin marketplace add corezoid/corezoid-ai-plugin
/plugin install corezoid@corezoid

This installs the whole corezoid plugin with all its skills

2Skills CLI (Vercel)

npx skills add corezoid/corezoid-ai-plugin --skill corezoid-init -a claude-code

3Manually: put the files in place

~/.claude/skills/corezoid-init/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/corezoid-init/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about corezoid-init

How do I install corezoid-init in Claude Code?

Run /plugin marketplace add corezoid/corezoid-ai-plugin, then run /plugin install corezoid@corezoid.

What does corezoid-init do?

It configures a Corezoid connection, stores authentication details, guides workspace and stage selection, and calls pull-folder after setup completes.

Can I use an API key instead of OAuth2?

Yes. Pass api_login and api_secret to login. The skill uses them for authentication and saves them for the current working directory.

Source text

SKILL.md · MIT
---
name: corezoid-init
description: >
  Corezoid environment setup specialist. Use when the user wants to connect to
  Corezoid, set up credentials, authenticate, pull a project, configure the
  environment, or start working with a Corezoid project for the first time.
  Activate when the user says "init", "setup", "connect to corezoid", "login",
  "pull workspace", "configure environment", or "get started".
---

# Initialize Corezoid Environment

You are a specialist in setting up the Corezoid working environment using the `corezoid` MCP server.

## Step 1 — Call `login`

Call MCP tool **`login`** with no arguments — an empty argument object `{}`. All its parameters are optional; do not invent a placeholder argument. It will guide setup in one of two modes depending on whether the client supports MCP elicitation.

---

## Mode A — Elicitation supported (interactive forms)

The `login` tool handles everything automatically in sequence:

1. **Account URL prompt** — interactive form asking for `account_url`
2. **OAuth2** — browser window opens for authentication; the token is saved to `~/.corezoid/config.json` (`access_token` field on the current Folder)
3. **Workspace picker** — fetches available workspaces and shows a dropdown; saves `workspace_id`
4. **Stage picker** — lists projects then stages for selection; the chosen stage is materialized on disk as `<id>_<name>.stage/<id>_<name>.stage.json` (the marker file — NOT stored in `config.json`)

### Interpreting the `login` response

- **`"Setup complete! ... Stage <N> selected."`** → stage was picked and pulled. Proceed to **Step 2**.
- **`"Setup incomplete: stage not selected. ..."`** → elicitation was cancelled or returned no stage. Follow the instructions in the message (usually: run `cz-structure {"action": "list-stages", …}` + call `login(stage_id=…)` again). Do **not** fall back to Mode B — the token and workspace are already saved.

---

## Mode B — Elicitation not supported (chat-based collection)

When elicitation is unavailable, drive the setup yourself using explicit tool calls. Follow this sequence **exactly** — never pick a workspace, project, or stage on behalf of the user. Always present the full list and wait for the user's explicit choice.

### B1 — Collect Account URL

→ Ask the user: **"What is your Corezoid Account URL? (e.g. https://account.corezoid.com)"**

→ Call `login(account_url=<value>)`

The tool opens a browser for OAuth2 authentication and saves the token to the current Folder in `~/.corezoid/config.json`.

### B2 — Select Workspace

→ Call **`cz-structure {"action": "list-workspaces"}`**

→ Show the full workspace list to the user. **Ask the user to choose** — do not select automatically.

→ Wait for the user's answer before proceeding.

### B3 — Select Project

→ Call **`cz-structure {"action": "list-projects", "args": {"company_id": <workspace_id>}}`** using the workspace the user chose.

→ Show the full project list to the user. **Ask the user to choose** — do not select automatically.

→ Wait for the user's answer before proceeding.

### B4 — Select Stage

→ Call **`cz-structure {"action": "list-stages", "args": {"project_id": <id>, "company_id": <workspace_id>}}`** using the project the user chose.

→ Show the full stage list to the user. **Ask the user to choose** — do not select automatically.

→ Wait for the user's answer before proceeding.

### B5 — Commit selection

→ Call `login(workspace_id=<workspace_id>, stage_id=<stage_id>)`

When `login` returns "Setup complete", proceed to **Step 2**.

---

## Step 2 — Pull the project

After `login` returns "Setup complete", call MCP tool **`pull-folder`** with no arguments — the MCP server pulls the stage selected during `login`. You do **not** need to know or pass `stage_id`. If the workspace has no stage selected ("No Project" mode), pass `folder_id=0` to pull the workspace root.

Do not proceed until the tool returns successfully.

---

## Exception: user provides values directly

If the user pastes values (account URL, workspace ID, stage ID, or API key credentials), pass them to `login` as arguments — do **not** edit `~/.corezoid/config.json` by hand:

```
login(
  account_url=<value>,
  workspace_id=<value>,
  stage_id=<value>
)
```

`login` will persist them to the current Folder and only prompt for what's still missing.

---

## Exception: API key auth (login + secret)

When the user provides an **API key login and secret** instead of OAuth credentials, use API key auth. This is common on private/on-prem Corezoid instances where browser OAuth is not available.

**How to recognise:** user says something like "use login 12345 secret abc..." or "connect with API key".

**Exact steps — call `login` with `api_login` and `api_secret` as arguments:**

```
login(
  account_url=<host>,
  workspace_id=<company_id>,
  stage_id=<stage_id>,
  api_login=<login_id>,
  api_secret=<secret>
)
```

⚠️ **Critical:** pass `api_login` and `api_secret` **as arguments to the `login` tool** — do NOT edit `~/.corezoid/config.json` by hand. The tool writes them to the current Folder with the correct field names (`api_login`, `api_secret`). Hand-editing under wrong field names will break authentication.

The login tool will:
1. Skip the OAuth2 browser flow
2. Save `api_login` and `api_secret` to the current Folder in `~/.corezoid/config.json`
3. Set `corezoid_url` from `account_url` if not already set
4. Complete workspace/stage selection normally

---


## Credential and config file locations

All credentials and per-workspace auth state live in a user-level file. Stage identity (and normally project identity too) lives in the workspace itself, in an on-disk marker file:

| File | Contents | Notes |
|------|----------|-------|
| `~/.corezoid/config.json` | Array of Folders — one per working directory. Each Folder holds auth state: `account_url`, `corezoid_url`, `workspace_id`, `access_token`, `expires_at`, `api_login`, `api_secret`, `git_url`, `git_stage_path`, and a cached `project_id` used as a fallback when the marker's `parent_id` is missing. | Mode `0600`; never in git; secrets never leave the user's home directory. |
| `<workspace>/<stage_id>_<name>.stage.json` | Stage marker at the workspace root. Contains `obj_id` (stage_id) and `parent_id` (project_id). Materialized automatically by the stage's zip during `pull-folder`/auto-pull; parsed by every tool that needs stage/project identity. | Checked into the workspace repo; safe to share. |

The MCP server chooses which Folder to use by matching the current working directory (or `$COREZOID_WORK_DIR`, set by Claude Code / Codex / Kiro) against each `root_path` and picking the longest-prefix match. This means sub-agents launched from any subdirectory of the workspace pick up the right credentials automatically.

---

## `corezoid_url` format

⚠️ `corezoid_url` must be the **base URL only** — no path suffix:

```
✅ "corezoid_url": "https://your-corezoid-host.example.com"
❌ "corezoid_url": "https://your-corezoid-host.example.com/api/2/json"
```

The server appends `/api/2/json` or `/api/2/download` automatically.

---

## Fields reference

Every field below lives in the current Folder inside `~/.corezoid/config.json`. All are managed by the `login` tool — you should not hand-edit them unless a documented exception applies.

| Field | Set during |
|---|---|
| `account_url` | login step 1 — account URL prompt |
| `corezoid_url` | login step 2.5 — derived from account clients API (or fallback to `account_url` in API-key mode) |
| `access_token` / `expires_at` | login step 2 — OAuth2 (or manually for on-prem workaround) |
| `workspace_id` | login step 3 — workspace selection |
| `api_login` / `api_secret` | login arguments (API-key auth mode) |
| `project_id` | cached on first pull-folder / push-process |
| `git_url` / `git_stage_path` | cached on the first `git-pull-context` action |
| `ws_url` | never set automatically — hand-set exception for self-hosted installs whose Git Call build / deploy WebSocket is not at `ws.<domain>` or the API host (`wss://<host>/api/1/sock_json`); overridden by `COREZOID_WS_URL` |

`COREZOID_OAUTH_CLIENT_ID` remains an environment variable (not a Folder field) — pre-login only, on-prem deployments with a custom authorization server. Cloud users do not need it.

---

## Environment fallback (headless / CI)

Every field above can also come from the environment when the config file has nothing for it. Use this only where the interactive login cannot run — CI jobs, containers, the Streamable HTTP transport:

| Variable | Field |
|---|---|
| `COREZOID_ACCOUNT_URL` | `account_url` |
| `COREZOID_API_URL` | `corezoid_url` |
| `COREZOID_APIGW_URL` | `apigw_url` |
| `COREZOID_WORKSPACE_ID` | `workspace_id` |
| `COREZOID_PROJECT_ID` | `project_id` |
| `COREZOID_STAGE_ID` | `stage_id` |
| `COREZOID_ACCESS_TOKEN` | `access_token` |
| `COREZOID_TOKEN_EXPIRES_AT` | `expires_at` (RFC 3339) |
| `COREZOID_API_LOGIN` | `api_login` |
| `COREZOID_API_SECRET` | `api_secret` |
| `COREZOID_GIT_URL` | `git_url` |
| `COREZOID_GIT_STAGE_PATH` | `git_stage_path` |

Rules to keep in mind when diagnosing auth state:

- The **config file wins field by field**; a variable applies only where the matching Folder leaves that field empty, or when no Folder matches the cwd.
- **Credential pairs are the exception to that** — `COREZOID_API_LOGIN`/`COREZOID_API_SECRET` come from one source or neither, as do `COREZOID_ACCESS_TOKEN`/`COREZOID_TOKEN_EXPIRES_AT`. A login and a secret from different sources cannot authenticate, so the half-pair is refused instead of being sent.
- An **expired** stored `access_token` counts as missing, so `COREZOID_ACCESS_TOKEN` takes over.
- If a variable was **set and rejected** (malformed `*_ID`, half an API-key pair), the auth error names it. Read that before concluding the user never configured anything — re-running `login` will not help in a headless environment.
- Environment values are **never persisted** — they are used in memory only. Derived caches (`project_id`, `git_url`, `git_stage_path`) are still written as usual.
- `logout` removes the Folder but cannot unset variables; the server stays authenticated until they are removed from the environment. The `logout` response says so when this is the case.
- Minimal set: `COREZOID_ACCOUNT_URL` + `COREZOID_STAGE_ID` + (`COREZOID_ACCESS_TOKEN` or `COREZOID_API_LOGIN`/`COREZOID_API_SECRET`).
- `COREZOID_API_URL` is optional: it is **derived on the first authenticated operation** — from the account's clients endpoint with a token, or from `COREZOID_ACCOUNT_URL` with API-key credentials. If that lookup fails the error says so and names the variable; do not read it as "not logged in".

Do **not** propose this path for a normal desktop setup — `login` is better there (it discovers `corezoid_url`, lists workspaces/stages, and refreshes the token).

© Corezoid · MIT · corezoid/corezoid-ai-plugin

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set30

The whole set →
corezoid-state-diagram-edit corezoid-state-diagram-edit — a skill for updating Corezoid state diagrams in .conv.json files. Adjusts states, transition paths, and transition side effects. CX Codex +1 ★ 74repo stars corezoid-node-layout corezoid-node-layout arranges Corezoid process nodes into a readable top-to-bottom flow and moves error handling to the right. Use it before pushing a new process or after a layout request. CX Codex +1 ★ 74repo stars corezoid-access corezoid-access — a skill for managing access to processes, folders and projects in Corezoid. Share objects with users and groups, create API keys, invite external users, and audit who has access. CX Codex +1 ★ 74repo stars corezoid-project-review corezoid-project-review audits entire Corezoid projects or folders, finding circular calls, duplicate code logic, and shared hardcoded secrets. CX Codex +1 ★ 74repo stars release Walks through six release phases: compares your code to the last tag, suggests a version number, updates seven manifest files, and creates a git tag. CX Codex +1 ★ 74repo stars corezoid-state-diagram-create corezoid-state-diagram-create designs Corezoid state diagrams with conv_type: state, sets up entity lifecycles, and generates valid diagram JSON files. CX Codex +1 ★ 74repo stars corezoid-process-optimizer corezoid-process-optimizer reviews Corezoid process JSON and proposes or applies changes such as merging nodes, cleaning data, and filling missing titles. CX Codex +1 ★ 74repo stars corezoid-connector-create corezoid-connector-create — a skill that generates a Corezoid process calling a single endpoint of any HTTP API (Stripe, OpenWeather, banks, CRM, or your own service). CX Codex +1 ★ 74repo stars

Project sponsors

Companies that keep this analytics open