Skip to main content

Onboard a repo with the UiGraph skill

Audience: Engineers onboarding a new service repo into UiGraph

Output: A repo wired to UiGraph, with the /uigraph skill installed, the MCP server connected, all artifacts generated under .uigraph/, and everything synced.

This is the fastest way to onboard a repo. The UiGraph skill drives artifact planning and generation for you inside Claude Code, Cursor, or any agent that supports skills, instead of pasting prompts by hand.

Onboarding without your own agent

uigraph-agents artifacts init does the same job as a single command, with no chat and no approval step. Use it when you want onboarding to run unattended, such as in CI. See Artifacts agent setup.

Overview​

  1. Install the skill. Add the uigraph skill to your agent.
  2. Connect the MCP server. Install @uigraph/mcp, set the server URL, and log in.
  3. Install the CLI. Install uigraph-cli for syncing.
  4. Generate artifacts. Run /uigraph and approve the plan.
  5. Sync. Push everything to UiGraph with the CLI.

Step 1: Install the UiGraph skill​

The skill lives in the uigraph-oss/skills repo. Install the uigraph skill into your agent:

npx skills add uigraph-oss/skills

Then invoke it from your agent's chat:

/uigraph

The skill plans which artifacts to create and generates them for you. It never writes anything until you approve the plan (see Step 4).

Step 2: Connect the MCP server​

Your agent connects to UiGraph through @uigraph/mcp. Install it globally:

npm i -g @uigraph/mcp

Then add it to your agent:

uigraph-mcp init

init picks your agent from a list, or pass it directly: uigraph-mcp init claude-code, uigraph-mcp init cursor. Supported: cursor, claude-code, claude-desktop, vscode, windsurf, gemini, opencode, codex.

The only value you need to set is UIGRAPH_MCP_SERVER_URL, pointing at your organization:

  • UiGraph Cloud: https://mcp.uigraph.app
  • Self-hosted: the URL of your own MCP server deployment

To configure it manually instead, add the server to your agent's MCP config:

{
  "mcpServers": {
    "uigraph": {
      "command": "uigraph-mcp",
      "env": {
        "UIGRAPH_MCP_SERVER_URL": "https://mcp.uigraph.app"
      }
    }
  }
}

See Connect your agent for the exact file path and format for every supported client.

Log in once​

uigraph-mcp auth login

Choose User Account to sign in through the browser, or Service Account to paste a uig_… token from UiGraph. For CI, set UIGRAPH_ACCESS_TOKEN instead of logging in. See Authentication for details.

Step 3: Install the CLI​

The skill generates the artifacts; uigraph-cli syncs them to UiGraph.

# Install the CLI
go install github.com/uigraph-oss/uigraph-cli@latest

# Make sure it's on your PATH, then check it runs
export PATH="$PATH:$HOME/go/bin"
uigraph-cli help

# Set your token from the UiGraph dashboard
export UIGRAPH_TOKEN="your-token-here"

Step 4: Generate artifacts with /uigraph​

Run the skill from your repo root:

/uigraph

The skill follows a fixed workflow:

  1. Discovers project evidence. API specs, route definitions, migrations, database schemas, docs, diagrams, tests, deployment config, service metadata, and calls out to other services.

  2. Asks what to generate. You pick the artifact categories: APIs, service dependencies, database schemas, architecture diagrams, docs, test packs, maps, and optional helper scripts. Cost tags and timeline are only offered when your repo has the evidence for them.

  3. Proposes a plan. The files it will create under .uigraph/, detected sources, assumptions, and validation steps.

  4. Waits for approval. Nothing is written until you reply with a message containing the word:

    Generate

    "generate", "generate now", and "ok generate the artifacts" all count. "go ahead", "sounds good", and "yes" do not, and it will ask you again.

  5. Generates. It writes the approved files and a .uigraph.yaml at the repo root, then validates the result.

You end up with a populated .uigraph/ directory and a ready-to-sync .uigraph.yaml. See the CLI overview for the full config format.

Step 5: Sync​

Preview, then push:

uigraph-cli sync --dry-run   # validate config and preview what will be synced
uigraph-cli sync             # push everything to UiGraph

Open the UiGraph dashboard to verify the service and its artifacts.

Keep it in sync​

To make agents update UiGraph diagrams automatically as they change code, add the CLAUDE.md, .cursor/rules, and .windsurfrules files from the manual onboarding guide, and run the CLI in CI. See CI/CD Setup.

Checklist​

  • uigraph skill installed with npx skills add
  • @uigraph/mcp installed and UIGRAPH_MCP_SERVER_URL set to your org's server
  • Logged in with uigraph-mcp auth login, or UIGRAPH_ACCESS_TOKEN set
  • uigraph-cli installed and UIGRAPH_TOKEN set
  • /uigraph run and plan approved with a reply containing Generate
  • uigraph-cli sync run and verified in the UiGraph dashboard
  • Agent rules and CI sync added to keep artifacts current

Next guides​