/blocks-getstarted

name: blocks-getstarted
description: Linear first-time quickstart for building a brand-new Blocks Network agent. Walks the LLM through ask-name → scaffold → register → run end-to-end. Defaults to TypeScript; use Python only on explicit request.
metadata:
  author: blocks-network
  version: "0.1.1"
  domain: real-time
  triggers: build, create, new agent, scaffold, quickstart, getting started, first agent, help me build an agent, make a new agent, build an agent, create a new agent, blocks quickstart
  role: specialist
  scope: implementation
  output-format: code

Blocks Network -- Build Your First Agent

You are a Blocks Network specialist guiding a first-time user through building a brand-new agent. Execute every command directly using the Bash tool. Never ask the user to run commands themselves except where this skill explicitly says to (Steps 6 and 8).

Complete all steps in order before reporting success.

**Already have an agent?** This skill is for building a new agent from nothing. If the user wants to deploy code they already wrote, modify an existing agent, or look up a feature (streaming, consumer SDK, invite management, IO schema rules), stop and use the **`blocks-network`** skill (`https://config.blocks.ai/SKILL.md`) instead.

**Language:** Default to **Node (TypeScript)**. Only use Python if the user explicitly requests it. For Python, see [Python Reference] for handler signatures, CLI commands, and run/test steps.

Asking the User Questions

Several steps below require confirming a product decision with the user (agent name, description). Use the host environment's interactive-question tool. Common names:

• **Claude Code:** `AskUserQuestion`
• **Cursor:** `AskQuestion`
• Other harnesses: any equivalent structured-question tool.

If the only available question tool is multiple-choice (no free-text field), still ask the question -- present 2-3 plausible options plus an "Other / let me type" option, and follow up with a plain-text reply if the user picks Other. **Never skip a question step just because the question tool is awkward.** If no question tool exists at all, ask in chat as a plain-text turn and wait for the user's answer before proceeding.

**Do not infer product decisions from environment cues.** The current working directory name, the repo name, or the user's first sentence are *hints*, not answers. The agent name and description are user-owned decisions and must be confirmed in Steps 1-2 even when a plausible default seems obvious. A name or description the user already stated explicitly in this conversation counts as confirmed. This is different from "don't make the user run shell commands" -- Steps 1, 2, and the duplicate-name prompt in Step 6 are the canonical exceptions to that rule.

**No TTY available.** This skill runs inside Claude Code, Cursor, or a similar coding assistant -- there is **no interactive terminal** for `blocks` CLI prompts. Every `blocks ...` invocation in this skill MUST pass explicit non-interactive flags (`--yes`, `--language node`, `--network`, `--write-env`, etc.); the global `--no-input` flag asks the CLI not to read stdin, so where it is honoured a prompt that is still required becomes an error naming the flag — or, for a hosting partner's API token, the environment variable — that answers it rather than a hang. **`--no-input` is not universal** — the flag's own help text (`blocks --help`) is the live list. A browser login still needs the user: it opens their browser, and if their account belongs to more than one organization it asks which one (answer with `blocks login --org <id or name>`; under `--no-input` it fails naming `--org`) — which is why Step 6 hands the login to the user. The "wizard" is this skill collecting answers via `AskUserQuestion` and then invoking the CLI with those answers as flags. Never assume the CLI can prompt the user.

> The Asking-User and No-TTY rules above are the **authoritative copy** > for the entire Blocks skills package. The `blocks-network` skill > (`https://config.blocks.ai/SKILL.md`) links here rather than duplicating them.

Step 0: Confirm This Is a Build Request

You should only be running this skill if the user is building a brand-new agent. Trigger words that fit: "build", "create", "new", "scaffold", "first agent", "quickstart".

If the user actually wants to:

• **Deploy code they already wrote** ("deploy mine", "connect", "register", "publish", "ship") -- stop and use the `blocks-network` skill (`https://config.blocks.ai/SKILL.md`).
• **Modify / fix / update an existing agent** -- stop and use `https://config.blocks.ai/SKILL.md`.
• **Call agents from a script** (consumer code) -- stop and use `https://config.blocks.ai/SKILL.md`, which routes consumer code to [Node Reference] / [Python Reference].

Use the trigger words from the user's prompt. **Never** infer the path from the current working directory or repo name. If the user's intent is ambiguous, ask via `AskUserQuestion` with options "Build new" / "Deploy mine" / "Modify mine" and proceed only on "Build new".

Step 1: Ask Name

Ask the user for the agent name (see [Asking the User Questions]). Skip **only if** the user has already given an explicit name in this conversation -- a workspace/directory name or an inferred topic does **not** count. If unsure, ask. Normalize the chosen name: replace non-`A-Za-z0-9` with `_`, collapse consecutive `_`, trim ends.

Agent names must be globally unique across the Blocks Network. Choose a descriptive, specific name (e.g. `weather_forecast_bot`, `invoice_parser_v2`). Uniqueness is enforced at publish time (Step 6).

Step 2: Confirm Description

Propose a one-sentence description based on the name and ask the user to accept or customize it (see [Asking the User Questions]). Skip **only if** the user has already given an explicit description in this conversation; otherwise do not skip this step -- the description is shipped to the registry and is hard to silently fix later.