{
  "markdown": "# Jetty — AI/ML Workflows for Any Agent\n\nBuild, run, and monitor AI/ML workflows on [Jetty](https://jetty.io) from any AI coding tool. Works with Claude Code, Cursor, VS Code Copilot, Windsurf, Zed, Gemini CLI, Codex CLI, and any MCP-compatible agent.\n\n## Quick Start (Claude Code)\n\n```bash\nclaude plugin marketplace add jettyio/jettyio-skills\nclaude plugin install jetty@jetty\n```\n\nThen run `/jetty-setup` to create an account, configure your API key, and run your first workflow in under 5 minutes.\n\n## Install in Your Tool\n\nJetty uses the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) to connect to your agent. Pick your tool below.\n\n### Claude Code\n\n**Plugin (recommended)** — includes guided setup wizard, workflow skills, and MCP tools:\n\n```bash\nclaude plugin marketplace add jettyio/jettyio-skills\nclaude plugin install jetty@jetty\n```\n\nThen run `/jetty-setup` to get started interactively.\n\n**MCP server only:**\n\n```bash\nclaude mcp add jetty -- npx -y jetty-mcp-server\n```\n\nOr add to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"jetty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"jetty-mcp-server\"],\n      \"env\": { \"JETTY_API_TOKEN\": \"mlc_your_token\" }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"jetty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"jetty-mcp-server\"],\n      \"env\": { \"JETTY_API_TOKEN\": \"mlc_your_token\" }\n    }\n  }\n}\n```\n\n### VS Code Copilot\n\nAdd to `.vscode/mcp.json` in your project root:\n\n```json\n{\n  \"servers\": {\n    \"jetty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"jetty-mcp-server\"],\n      \"env\": { \"JETTY_API_TOKEN\": \"mlc_your_token\" }\n    }\n  }\n}\n```\n\nOr run `MCP: Add Server` from the Command Palette.\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"jetty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"jetty-mcp-server\"],\n      \"env\": { \"JETTY_API_TOKEN\": \"mlc_your_token\" }\n    }\n  }\n}\n```\n\n### Zed\n\nAdd to your Zed settings (`~/.config/zed/settings.json`):\n\n```json\n{\n  \"context_servers\": {\n    \"jetty\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"jetty-mcp-server\"],\n        \"env\": { \"JETTY_API_TOKEN\": \"mlc_your_token\" }\n      }\n    }\n  }\n}\n```\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/jettyio/jettyio-skills\n```\n\nDuring installation, you'll be prompted for your Jetty API token. The extension registers the MCP server and loads context automatically.\n\nTo install from a local clone instead:\n\n```bash\ngemini extensions install --path /path/to/jettyio-skills\n```\n\n### Antigravity\n\nAntigravity (Google's agentic IDE) loads skills from `~/.gemini/antigravity/skills/` and reads MCP servers from `~/.gemini/antigravity/mcp_config.json`. It does **not** auto-install from any of the manifests in this repo — file-drop only.\n\n**Skills:** clone the repo and either symlink or copy each skill directory you want into Antigravity's skill path. For example:\n\n```bash\ngit clone https://github.com/jettyio/jettyio-skills.git\nmkdir -p ~/.gemini/antigravity/skills\nln -s \"$(pwd)/jettyio-skills/skills/jetty-setup\"     ~/.gemini/antigravity/skills/jetty-setup\nln -s \"$(pwd)/jettyio-skills/skills/create-runbook\"  ~/.gemini/antigravity/skills/create-runbook\nln -s \"$(pwd)/jettyio-skills/skills/optimize-runbook\" ~/.gemini/antigravity/skills/optimize-runbook\nln -s \"$(pwd)/jettyio-skills/skills/jetty\"           ~/.gemini/antigravity/skills/jetty\n```\n\n**MCP server:** add to `~/.gemini/antigravity/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"jetty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"jetty-mcp-server\"],\n      \"env\": { \"JETTY_API_TOKEN\": \"mlc_your_token\" }\n    }\n  }\n}\n```\n\nRestart Antigravity after editing the config. Skills trigger on natural language (slash commands aren't auto-discovered for skills) — say *\"set up Jetty\"* or *\"create a runbook for X\"* and the agent will pick the right skill via the description in its frontmatter.\n\n### Codex CLI\n\nAdd to `~/.codex/config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"jetty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"jetty-mcp-server\"],\n      \"env\": { \"JETTY_API_TOKEN\": \"mlc_your_token\" }\n    }\n  }\n}\n```\n\n### Any Other MCP Client\n\n```bash\nJETTY_API_TOKEN=mlc_your_token npx -y jetty-mcp-server\n```\n\nThe server communicates over stdio using the MCP protocol.\n\n---\n\n## Get Your API Token\n\n1. Sign up at [jetty.io](https://jetty.io/sign-up)\n2. Go to **Settings → API Tokens**\n3. Create a token (starts with `mlc_`)\n4. Add it to your tool's config as shown above\n\n---\n\n## First-Time Setup\n\nOnce connected, ask your agent to help you get started. This works in **any** MCP-connected tool — just paste the prompt below into your agent's chat:\n\n> Set up Jetty for me. List my collections, then deploy the cute-feline-detector demo workflow using the `create-task` tool with [this workflow JSON](skills/jetty/templates/cute-feline-detector-openai.json). Then run it with `run-workflow` using the prompt \"a fluffy orange tabby cat sitting in a sunbeam\". Poll `list-trajectories` until it completes, then show me the results with `get-trajectory`.\n\nBefore running the demo, store your AI provider key in your collection's environment variables. Ask your agent:\n\n> Use the Jetty `get-collection` tool to check my collection's environment variables. I need to add my OpenAI API key (or Gemini API key) so workflows can use it.\n\n**Claude Code users:** Just run `/jetty-setup` instead — the guided wizard handles all of this automatically.\n\n---\n\n## Available MCP Tools\n\nOnce connected, your agent has access to 16 tools:\n\n| Tool | Description |\n|------|-------------|\n| `list-collections` | List all collections (workspaces) |\n| `get-collection` | Get collection details and environment variable keys |\n| `list-tasks` | List tasks (workflows) in a collection |\n| `get-task` | Get task details and workflow definition |\n| `create-task` | Create a new task with a workflow |\n| `update-task` | Update a task's workflow or description |\n| `run-workflow` | Run a workflow asynchronously |\n| `run-workflow-sync` | Run a workflow synchronously (blocks until done) |\n| `list-trajectories` | List recent workflow runs |\n| `get-trajectory` | Get full run details with step outputs |\n| `get-stats` | Get execution statistics |\n| `add-label` | Label a trajectory (e.g., quality=high) |\n| `list-step-templates` | List available step templates |\n| `get-step-template` | Get template details and schema |\n| `check-secrets` | Check which env vars a collection has vs. what a runbook needs |\n| `set-environment-vars` | Set or delete environment variables on a collection |\n\n---\n\n## Claude Code Skills\n\nThe plugin adds three skills for richer Claude Code integration:\n\n### `/jetty-setup` — Guided Onboarding\nInteractive wizard that handles account creation, API key storage, provider selection (OpenAI or Gemini), and runs a demo workflow — all in under 5 minutes.\n\n### `/jetty` — Natural Language Workflow Management\n\n```\n/jetty list collections\n/jetty list tasks in my-project\n/jetty run my-project/my-task with prompt=\"Hello, world!\"\n/jetty show the last trajectory for my-project/my-task\n/jetty create a task called test-echo in my-project using text_echo\n/jetty add label quality=high to trajectory abc123 in my-project/my-task\n```\n\n### `/jetty create-runbook` — Guided Runbook Creator\n\nInteractive wizard that walks you through building a runbook step by step — choose an evaluation pattern, define parameters and secrets, and generate a complete runbook ready to run.\n\n---\n\n## Runbooks\n\nA **runbook** is a structured markdown document that tells a coding agent how to accomplish a complex, multi-step task with built-in evaluation loops and quality gates. Think of it as an executable playbook: your agent reads the runbook, executes each step, evaluates its own output, and iterates until quality criteria are met.\n\n### Key Features\n\n- **Outcome-oriented** — defines what must be true when done, not just procedure steps\n- **Self-evaluating** — built-in evaluate → refine → re-evaluate loops (max 3 rounds)\n- **Parameterized** — uses `{{param}}` template variables for reuse across inputs and environments\n- **Secrets-aware** — declares sensitive credentials in frontmatter, resolved securely at runtime\n- **Versioned** — carries a semantic version in YAML frontmatter for reproducibility\n\n### Evaluation Patterns\n\n| Pattern | Use Case | How It Works |\n|---------|----------|--------------|\n| **Programmatic** | Data pipelines, code generation, structured output | Validates against schema, API, or test suite — objective pass/fail |\n| **Rubric** | Creative content, analysis, complex reports | Scores across multiple criteria on a 1–5 scale — subjective quality |\n\n### Runbook Structure\n\nEvery runbook follows a mandatory structure:\n\n1. **Frontmatter** — version, evaluation type, secrets declarations\n2. **Objective** — what the runbook accomplishes (2–5 sentences)\n3. **Output Manifest** — files the agent must create\n4. **Parameters** — configurable inputs with defaults\n5. **Dependencies** — workflows, APIs, credentials, packages\n6. **Steps** — sequential processing (API calls, transformations, etc.)\n7. **Evaluation** — status table (programmatic) or rubric scoring\n8. **Iteration** — up to 3 refinement rounds with common-fix guidance\n9. **Validation Report** — standardized `validation_report.json`\n10. **Final Checklist** — verification script and exit gate\n\n### Getting Started with Runbooks\n\n**Claude Code users:** Run `/jetty create-runbook` for a guided wizard that generates a complete runbook from starter templates.\n\nFor full documentation, see [`docs/PRD-runbooks.md`](docs/PRD-runbooks.md).\n\n---\n\n## Secrets Management\n\nJetty provides secure handling of API keys and credentials so they never leak into logs, trajectories, or workflow outputs.\n\n### How Secrets Work\n\nSecrets are declared in runbook frontmatter and resolved at runtime through a 3-level fallback:\n\n1. **OS environment variable** matching the `env` field\n2. **`.env` file** in the runbook directory (should be `.gitignore`d)\n3. **Interactive prompt** (if `required: true` and not found above)\n\nWhen running on Jetty, secrets resolve from your **collection's environment variables** — set once, available to all workflows in that collection.\n\n### Declaring Secrets in a Runbook\n\n```yaml\nsecrets:\n  OPENAI_API_KEY:\n    env: OPENAI_API_KEY\n    description: \"OpenAI API key for LLM calls\"\n    required: true\n  LANGFUSE_SECRET_KEY:\n    env: LANGFUSE_SECRET_KEY\n    description: \"Langfuse API secret key\"\n    required: false\n```\n\nReference secrets in runbook steps as `{{secrets.OPENAI_API_KEY}}` — distinct from regular `{{params}}`.\n\n### MCP Tools for Secrets\n\n| Tool | Description |\n|------|-------------|\n| `check-secrets` | Verify which env vars a collection has vs. what a runbook needs — returns configured, missing, and ready status |\n| `set-environment-vars` | Set or delete environment variables on a collection (merge semantics, pass `null` to delete a key) |\n\n### Security Guarantees\n\n- Secrets are **never stored** in `init_params`, trajectories, or output files\n- The `secret_params` API field merges credentials into the runtime environment without persisting them\n- Collection environment variables are stored server-side. By default, `GET /api/v1/collections/{COLLECTION}/environment` returns values **in plain text** to the holder of a collection-owner token. Treat that token like a root credential. To make the endpoint redact specific keys, set the collection's `redacted_param_keys` (it defaults to `null`, i.e. no redaction)\n\n---\n\n## Workflow Templates\n\nReady-to-use templates are in [`skills/jetty/templates/`](skills/jetty/templates/):\n\n| Template | Description |\n|----------|-------------|\n| **cute-feline-detector-openai** | Prompt → DALL-E 3 image → GPT-4o cuteness judge |\n| **cute-feline-detector-gemini** | Prompt → Gemini image → Gemini Flash cuteness judge |\n| simple-chat | Basic LLM chat with system prompt |\n| model-comparison | Compare two LLM responses with an AI judge |\n| image-generation | Text-to-image with Replicate/FLUX |\n| batch-processor | Fan-out parallel processing |\n| document-summarizer | Configurable document summarization |\n\nUse the `create-task` MCP tool to deploy any template to your collection.\n\n---\n\n## Shell Functions (Standalone CLI)\n\nFor direct terminal usage without any AI tool:\n\n```bash\nexport JETTY_API_TOKEN=\"mlc_your_token_here\"\nsource path/to/skills/jetty/jetty-cli.sh\n\njetty_health                                    # Check connectivity\njetty_collections                               # List collections\njetty_run_sync my-project my-task '{\"prompt\": \"Hello\"}'  # Run a workflow\njetty_trajectories my-project my-task           # View execution history\njetty_help                                      # Full command reference\n```\n\n---\n\n## How It Works\n\nJetty runs AI/ML workflows defined as JSON pipelines. Each workflow has:\n- **init_params** — Input parameters (e.g., a prompt)\n- **step_configs** — Pipeline steps (e.g., LLM call → image generation → judge)\n- **steps** — Execution order\n\nResults are stored as **trajectories** with full step-by-step outputs, downloadable files, and labeling support.\n\n## Platform\n\n| Service | URL | Purpose |\n|---------|-----|---------|\n| Jetty API | `flows-api.jetty.io` | All operations: workflows, collections, tasks, datasets, trajectories, files |\n| Web UI | `jetty.io` | Dashboard and management |\n\n## Prerequisites\n\n- Node.js 18+ (for the MCP server via `npx`)\n- A Jetty API token ([get one here](https://jetty.io/sign-up))\n- An AI provider API key for workflow steps (OpenAI for DALL-E/GPT, or Google Gemini)\n- For runbooks: an agent runtime API key (Anthropic, OpenAI, or Google — see [agent reference](skills/jetty/references/agents-and-models.md))\n\n## Agent Compatibility\n\n| Agent CLI | MCP Tools | Skills (`/jetty`, `/jetty-setup`) | Runbook Execution | Notes |\n|-----------|-----------|-----------------------------------|-------------------|-------|\n| Claude Code | Full | Full | Full | Recommended — best experience |\n| Cursor | Full | N/A | Via API | MCP tools only |\n| VS Code Copilot | Full | N/A | Via API | MCP tools only |\n| Codex CLI | Full | N/A | Full | `codex` agent runtime |\n| Gemini CLI | Full | Partial | Full | `gemini-cli` agent runtime |\n| Windsurf | Full | N/A | Via API | MCP tools only |\n| Zed | Full | N/A | Via API | MCP tools only |\n\nFor agents without skill support, see [QUICKSTART.md](QUICKSTART.md).\n\n## Documentation\n\n- [AI Tool Integrations](docs/integrations.md)\n- [API Reference](docs/api-reference.md)\n- [Workflow Building Guide](docs/workflow-guide.md)\n- [Known Gotchas](docs/gotchas.md)\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| \"Invalid or expired token\" | Regenerate at jetty.io → Settings → API Tokens |\n| \"Access denied\" | Verify your token has access to the collection |\n| MCP tools not showing up | Restart your editor/agent after config changes |\n| Workflow fails | Use `get-trajectory` to inspect step-by-step outputs |\n| `/jetty-setup` not found | Claude Code only — reinstall: `claude plugin marketplace add jettyio/jettyio-skills && claude plugin install jetty@jetty` |\n\n## Releasing\n\nThe version number is hardcoded in several places. When cutting a release, bump all of them together:\n\n- `.claude-plugin/plugin.json`\n- `.claude-plugin/marketplace.json`\n- `.codex-plugin/plugin.json`\n- `.opencode-plugin/plugin.json`\n- `gemini-extension.json`\n- `skills/jetty-setup/scripts/jetty_simulate.py` (`CLIENT` string)\n- `skills/jetty/SKILL.md` (launch banner)\n- `skills/jetty-setup/SKILL.md` (launch banner)\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n",
  "bytes": 15732,
  "sha": "77bd3a03e8819bc14b1a67295dcde7284ce03207a0497e31f96251c1050fc16e",
  "repo_slug": "jettyio/jettyio-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_jettyio_jettyio_skills_jetty_7ed6f867/readme"
}