Quickstart

From a clean machine: install the CLI, sign in to Cursor, Claude Code, or Codex, then run skillgate check. Exit 0 when green. Exit 1 when red. Exit 2 when no agent is available, you are not signed in, or no decision model is selected (unless you pass --no-judge). No Skill Gate account.

0. Install

Install the CLI first. Follow the Install page: confirm python3 --version is 3.11 or newer, then install skillgate-ai==0.7.9. Come back when skillgate version prints 0.7.9.

1. Workspace and example datasets

shell
skillgate init
skillgate examples install

skillgate init creates skills/ and gitignores .skillgate/. skillgate examples install copies six skills into that folder. Files already there stay as they are. A second install prints Left N existing file(s) in place. List them with skillgate examples list. Install one with skillgate examples install json-response.

json-response flattens a JSON API body. json-response-sabotaged uses the same cases and fails them. readme-writer, log-summarizer, sql-writer, and receipt-extractor are the other datasets. Read them on Examples. The PDF pack is still skillgate example pdf --dest skills/pdf.

2. Sign in to an agent

Checks run through Cursor Agent CLI, Codex CLI, or Claude Code, using your agent subscription and its quota. Sign in with that agent's official login:

shell
skillgate login cursor
# or: skillgate login claude
# or: skillgate login codex
skillgate login --status

Omit the agent name to sign in any installed agent that is still missing. Pick one per run with --harness claude (or cursor-agent, codex). Details are on Agents. Vault keys are optional; see Keys if you need them for CI.

3. Run a pass and a fail

shell
skillgate check skills/json-response
echo $?   # 0 when the live run is green; 2 when no agent is available or you are not signed in
skillgate check skills/json-response-sabotaged
echo $?   # 1 when the JSON checks fail. The unrelated check can pass.
skillgate check skills/json-response-sabotaged --expect-fail
echo $?   # 0 only when that live run is red

json-response has three pinned cases. json-response-sabotaged keeps those cases and writes a snack list instead of the JSON, so the trigger cases fail. The unrelated check can still pass.

Checks use your signed-in agent subscription and that quota. A live check also needs a decision model. Pick one on Judge, then run skillgate judge test. Without an agent, when you are not signed in, or when no decision model is selected, the process exits 2 unless you pass --no-judge.

shell
skillgate check skills/json-response --no-judge

Try one check with --case <check-id>. List ids first:

shell
skillgate case list skills/json-response
skillgate check skills/json-response --case <check-id>

4. Deploy after green (optional)

shell
skillgate check skills/pdf
skillgate deploy skills/pdf --targets cursor,claude,codex

Deploy copies skill files only (not evals/) and refuses unless this pack already has a passing check. It replaces an existing skill with the same name in ~/.cursor/skills, ~/.codex/skills, or ~/.claude/skills.

The same steps in the local UI

shell
skillgate ui

Run from your workspace root so skills/ resolves. If the page does not load, an older skillgate ui may still be holding the default port. Stop that process, or pass --port.

  1. Click Skills. The page title is Skill Repository.
  2. Click Examples, then Install. Existing files stay as they are.
  3. Open json-response. Click Evaluate this skill.
  4. Click Run. With the three cases loaded, the label is Run 3 cases. Until you sign in or add a key, the line above the button is Next: sign in or add a key in Settings, then press Run.
  5. Open json-response-sabotaged and press Run again. The JSON checks fail. The unrelated check can pass.