Expedait Skills

Step-by-step guides for AI coding agents that use Expedait to manage project specifications.

📖 User docs: app.expedait.org/docs/skills

Expedait's spec model has four primitives: objectives (top-level goals that nest child deliverables), deliverables (the individual spec documents — formerly "pages"), context (the assembled LLM context for a deliverable), and review (scoring findings on a deliverable).

Quickstart

1. Install skills into your project

Claude Code plugin (recommended):

/plugin marketplace add Expedait/expedait-skills
/plugin install expedait-skills@expedait

Script installer (Claude Code, Cursor, OpenCode, Codex, Gemini CLI, Pi, Windsurf, GitHub Copilot, Cline, Zed, JetBrains Junie, Amp):

curl -fsSL https://raw.githubusercontent.com/Expedait/expedait-skills/main/install.sh | bash

The script installer auto-detects your agent and sets up the right config files. See Agent Setup for manual instructions.

2. Authenticate

The CLI's package is expedait-cli and its entrypoint is expedait, so run it via uvx as uvx --from expedait-cli expedait — no global install needed:

# Interactive login (browser SSO or email/password)
uvx --from expedait-cli expedait auth login

# Check auth status, tenant, and workspace
uvx --from expedait-cli expedait auth status

# Or set environment variables (for CI / agent environments)
export EXPEDAIT_TOKEN="your-jwt-token"
export EXPEDAIT_API_URL="https://your-instance.expedait.com"
export EXPEDAIT_TENANT_ID=1

Credentials are cached in ~/.expedait/config.json. Settings are resolved in order: CLI flag → environment variable → ~/.expedait/config.json. Pass the project per command (by ID, name, or interactively) — there is no separate init step.

Prefer the hosted MCP server? Add https://mcp.expedait.org to your AI client's connectors, sign in once, and pick a workspace — it exposes the same primitives (projects, deliverables, objectives, context, review, comments) and the same write surface as the CLI: author and edit deliverables (write_deliverable), design project-type processes (write_process), and manage owner roles (write_role). See Expedait's MCP docs.

3. Use a skill

Ask your agent to download specs, post comments, or review code — it knows the workflows.

> /expedait-download     # Claude Code
> @expedait-download     # Cursor (manual rule invocation)

Or just ask naturally: "Download the specs for project 1 and review my code against them."

Available Skills

Every skill works with either the CLI or the hosted MCP server. The write surface — authoring deliverables (write_deliverable), designing processes (write_process), and managing roles (write_role) — landed in expedait-cli 0.4.0, so the Author and Process Designer skills are CLI-first with an MCP-alternative section.

Staying up to date

Skills are static files, so they don't refresh themselves — but every skill runs a throttled version check in its preamble (one network call per day at most, silent when you're current or offline). When a newer release exists it points you to the Update Skills skill:

/expedait-update-skills

That skill compares your installed version against the latest GitHub release and runs the right update path — re-running install.sh for a script install, or /plugin for a Claude Code plugin install. You can also check any time with the installer directly:

./install.sh --check     # compares .expedait-skills-version against the latest release

Disable the automatic checks with export EXPEDAIT_SKILLS_UPDATE_CHECK=false (or touch ~/.expedait/no-update-check).

Agent Setup

Claude Code (Plugin)

Install as a Claude Code plugin — no manual file setup needed:

/plugin marketplace add Expedait/expedait-skills
/plugin install expedait-skills@expedait

This registers the marketplace and installs the skills as /expedait-download, /expedait-author, /expedait-process, /expedait-comment, and /expedait-review.

Teams can also auto-enable the plugin by adding to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "expedait": {
      "source": {
        "source": "github",
        "repo": "Expedait/expedait-skills"
      }
    }
  },
  "enabledPlugins": {
    "expedait-skills@expedait": true
  }
}

Claude Code (Script)

The installer creates skills as custom slash commands in .claude/skills/:

.claude/skills/
  expedait-download/SKILL.md
  expedait-author/SKILL.md
  expedait-process/SKILL.md
  expedait-comment/SKILL.md
  expedait-review/SKILL.md

These become available as /expedait-download, /expedait-author, /expedait-process, /expedait-comment, and /expedait-review.

Manual setup:

./install.sh --agent claude-code

Or add to your CLAUDE.md:

## Expedait Integration

Use `uvx --from expedait-cli expedait` (not `pip`) for all Expedait commands.
Run `uvx --from expedait-cli expedait auth login` once to authenticate.
See the skills in `.claude/skills/expedait-*` for workflows.

Cursor

The installer creates a rule file at .cursor/rules/expedait.mdc:

---
description: "Expedait spec management — download specs, post comments, review code"
alwaysApply: false
---

Cursor's agent will pick it up automatically when Expedait-related questions come up, or you can invoke it manually with @expedait.

Manual setup:

./install.sh --agent cursor

OpenCode

The installer creates commands in .opencode/commands/ using the native command format:

./install.sh --agent opencode

.opencode/commands/
  expedait-download.md
  expedait-author.md
  expedait-process.md
  expedait-comment.md
  expedait-review.md

These become available as /expedait-download, /expedait-author, /expedait-process, /expedait-comment, and /expedait-review.

Codex (OpenAI)

The installer creates skills in .codex/skills/ using the native SKILL.md format:

./install.sh --agent codex

.codex/skills/
  expedait-download/SKILL.md
  expedait-author/SKILL.md
  expedait-process/SKILL.md
  expedait-comment/SKILL.md
  expedait-review/SKILL.md

Gemini CLI

The installer creates custom commands in .gemini/commands/ using the native TOML format:

./install.sh --agent gemini

.gemini/commands/
  expedait-download.toml
  expedait-author.toml
  expedait-process.toml
  expedait-comment.toml
  expedait-review.toml

These become available as /expedait-download, /expedait-author, /expedait-process, /expedait-comment, and /expedait-review.

Pi (pi.dev)

The installer creates skills in .pi/skills/ using Pi's native Agent Skills standard (SKILL.md with name/description/allowed-tools frontmatter):

./install.sh --agent pi

.pi/skills/
  expedait-download/SKILL.md
  expedait-author/SKILL.md
  expedait-process/SKILL.md
  expedait-comment/SKILL.md
  expedait-review/SKILL.md

Invoke them explicitly with /skill:expedait-download (etc.), or let Pi auto-load the right skill when a request matches its description. $ARGUMENTS works natively.

Windsurf

The installer creates one rule file per skill in .windsurf/rules/, each with trigger: manual so it loads on demand rather than on every turn:

./install.sh --agent windsurf

.windsurf/rules/
  expedait-download.md
  expedait-author.md
  expedait-process.md
  expedait-comment.md
  expedait-review.md

Reference a rule in Cascade with @expedait-download (etc.). Windsurf rules don't substitute arguments, so $ARGUMENTS is rewritten to a prose reference.

GitHub Copilot

The installer creates prompt files in .github/prompts/ (mode: agent):

./install.sh --agent copilot

.github/prompts/
  expedait-download.prompt.md
  expedait-author.prompt.md
  expedait-process.prompt.md
  expedait-comment.prompt.md
  expedait-review.prompt.md

Run them in Copilot Chat as /expedait-download, /expedait-author, /expedait-process, /expedait-comment, and /expedait-review.

Cline

The installer creates workflows in .clinerules/workflows/:

./install.sh --agent cline

.clinerules/workflows/
  expedait-download.md
  expedait-author.md
  expedait-process.md
  expedait-comment.md
  expedait-review.md

Invoke a workflow by typing /expedait-download.md (etc.) in chat.

Zed

The installer creates Agent Skills in .agents/skills/ (the same SKILL.md standard as Claude Code, with name/description frontmatter):

./install.sh --agent zed

.agents/skills/
  expedait-download/SKILL.md
  expedait-author/SKILL.md
  expedait-process/SKILL.md
  expedait-comment/SKILL.md
  expedait-review/SKILL.md

Invoke a skill with /expedait-download or @expedait-download, or let Zed's agent auto-load the right one by description. $ARGUMENTS works natively.

JetBrains Junie

The installer creates custom slash commands in .junie/commands/ (works across all JetBrains IDEs — IntelliJ IDEA, PyCharm, WebStorm, GoLand, etc.):

./install.sh --agent junie

.junie/commands/
  expedait-download.md
  expedait-author.md
  expedait-process.md
  expedait-comment.md
  expedait-review.md

These become available as /expedait-download, /expedait-author, /expedait-process, /expedait-comment, and /expedait-review.

Amp (Sourcegraph)

The installer creates custom slash commands in .agents/commands/:

./install.sh --agent amp

.agents/commands/
  expedait-download.md
  expedait-author.md
  expedait-process.md
  expedait-comment.md
  expedait-review.md

These become available as /expedait-download, /expedait-author, /expedait-process, /expedait-comment, and /expedait-review.

All agents at once

./install.sh --all

What are Skills?

Skills are structured, agent-oriented guides that describe how to accomplish common workflows using the Expedait CLI. Each skill includes:

• When to use — the situation the skill addresses
• Prerequisites — what you need before starting
• Step-by-step instructions — CLI commands with example output
• Tips — best practices and edge cases

They are designed to be consumed by AI coding agents (Claude Code, Cursor, OpenCode, Codex, etc.) as part of their tool documentation, but are also useful as human reference.

Architecture

Skills are defined once in skills/*/SKILL.md (the single source of truth) and transformed into platform-specific formats by build.py:

skills/                        # canonical source (SKILL.md format)
  expedait-download/SKILL.md
  expedait-author/SKILL.md
  expedait-process/SKILL.md
  expedait-comment/SKILL.md
  expedait-review/SKILL.md

platforms/                     # generated — do not edit directly
  codex/skills/*/SKILL.md      # same format as Claude Code
  pi/skills/*/SKILL.md         # Pi Agent Skills standard
  opencode/commands/*.md       # OpenCode command format
  gemini/commands/*.toml       # Gemini CLI TOML format
  cursor/rules/*.mdc           # Cursor rule format
  windsurf/rules/*.md          # Windsurf manual-trigger rules
  copilot/prompts/*.prompt.md  # GitHub Copilot prompt files
  cline/workflows/*.md         # Cline workflows
  zed/skills/*/SKILL.md        # Zed Agent Skills standard
  junie/commands/*.md          # JetBrains Junie slash commands
  amp/commands/*.md            # Amp slash commands

Claude Code uses skills/ directly (native format). Other platforms use files from platforms/.

Testing

A local eval battery lives in evals/. It grades which expedait commands a skill leads the agent to run against a hermetic mock CLI — no auth, no network, no live backend. Two tiers:

python3 evals/lint.py                    # static frontmatter/body checks
uv run --with pytest pytest evals/       # agent-free unit tests
python3 evals/runner.py                  # full battery (needs the `claude` CLI)
python3 evals/runner.py --dry-run        # validate eval schema + wiring, no agent

Tier 1 (lint + unit tests) runs on every PR in CI; the agent battery and latency probe are local dev tools you run yourself. See evals/README.md for the eval schema and how to add cases.

Contributing

To add or modify a skill:

1. Edit the SKILL.md in skills/ (not in platforms/)
2. Run uv run build.py to regenerate platform files
3. Add the skill to the table in this README
4. Submit a pull request (CI checks that platforms/ is in sync)

See CONTRIBUTING.md for the full workflow and authoring guidelines, and SECURITY.md to report a vulnerability.

License

This project is licensed under the Apache License 2.0.