Skip to content
Linkworld Docs

Vibe coding

You don’t have to hand-write a Linkworld app. The scaffold ships everything an AI coding tool needs to understand the platform on its own: an AGENTS.md primer that the IDE picks up automatically and an MCP server it can query for live skill schemas. Describe what you want; the model writes the manifest, handlers, and eval scenarios; you iterate by re-prompting.

What you need

Section titled “What you need”
  • The Linkworld CLI (Install)
  • An AI coding tool that can run shell commands and edit files — Claude Code, Cursor, or Codex all respect AGENTS.md
  • A GitHub repo (only needed at deploy time)

1. Scaffold the empty app

Section titled “1. Scaffold the empty app”
Terminal window
linkworld init inbox-sweeper --lang python --github-owner you
cd inbox-sweeper

You get a working, deployable skeleton with the things the AI cares about:

  • linkworld.app.yaml — manifest with empty required_scopes
  • main.py — passing @app.on_install handler
  • linkworld.eval.yaml — passing eval suite to gate every iteration
  • AGENTS.md — the AI primer. Tells your IDE which Linkworld conventions exist (ctx.tools.call, ctx.commitments.add, lw-ui design tokens, CSP rules for the frontend bundle) and how to discover the rest via the MCP server (mcp.list_skills, mcp.get_skill_docs, mcp.search_examples).

Confirm the baseline is green before you hand it over:

Terminal window
linkworld eval

2. Connect your AI to the Linkworld MCP server

Section titled “2. Connect your AI to the Linkworld MCP server”

One-time setup per machine so your AI can call mcp.list_skills and mcp.get_skill_docs instead of guessing field names. See MCP setup for the per-IDE command.

Without MCP the AI still works from AGENTS.md alone — it just has to discover skill schemas the long way (eval failures). With MCP it gets them on first call.

3. Describe what you want

Section titled “3. Describe what you want”

Open the folder in your AI tool and type what your app should do. Concretely — the more specific the prompt, the less iteration.

Build out this app so when an email arrives you classify it as one of: customer-inquiry, newsletter, internal, other. Newsletters get moved to a “Newsletter” folder. Customer-inquiries get a one-line summary pushed to me in chat with a “Reply” button that drafts a polite acknowledgement. Add eval scenarios for each branch.

What the model does next:

  1. Reads AGENTS.md and calls mcp.list_skills(category="email") to find the right skills (here graph_email + assistant_chat).
  2. Calls mcp.get_skill_docs(...) for exact tool input/output schemas — no guessing field names.
  3. Edits linkworld.app.yaml to add the required scopes.
  4. Writes the @app.on_inbound handler with a branch per category.
  5. Extends linkworld.eval.yaml with one scenario per branch.
  6. Runs linkworld eval and fixes anything red.

4. Iterate via eval

Section titled “4. Iterate via eval”

Don’t trust the first draft. Re-prompt with concrete failure modes you see in the eval output or in local runs:

The newsletter branch fires on transactional emails like “Your receipt from Stripe”. Tighten the classifier — newsletter should mean marketing / digest only.

Each round: AI edits, you re-run linkworld eval. Green eval is your gate. Common follow-ups the scaffold handles out of the box:

  • “Add a frontend bundle showing the last 20 classifications.” → AI scaffolds web/index.html + app.js using lw-ui design tokens. AGENTS.md warns it about iframe CSP so it uses the bridge.callRoute / bridge.tools.call API instead of fetch.
  • “Add a daily 8am digest emailed to me.” → AI registers @app.on_schedule(cron="0 8 * * *") and writes the handler.

5. Run it locally

Section titled “5. Run it locally”
Terminal window
LINKWORLD_LOCAL=1 python main.py

Local mode boots a mock platform on localhost:8080 with stubbed tools. Ask your AI for a curl invocation that exercises the branch you care about — it has the mock API surface in AGENTS.md.

6. Deploy

Section titled “6. Deploy”
Terminal window
git init && git add . && git commit -m "init"
git remote add origin [email protected]:you/inbox-sweeper.git
git push -u origin main
git tag v0.1.0 && git push --tags

CI builds the image, pushes to GHCR, and runs linkworld deploy. First version live in ~3 minutes; see it on the dev console.

What’s next

Section titled “What’s next”
  • Concepts — what the manifest, handlers, ctx, and lifecycle actually do
  • MCP setup — wiring Claude Code / Cursor / Codex to the live skill catalog
  • Best practices — what to insist on before shipping
  • Quickstart — the hand-written path if you’d rather understand the bones first