# Crewd — Complete Documentation for LLMs & AI Agents > The Package Manager for Prompt-Defined AI Agents, Skills, and Teams. > Website: https://crewd.dev > Source Code: https://github.com/crewdhq/crewd-cli --- ## 1. What is Crewd? Crewd is an open-source package manager and registry designed specifically for prompt-defined AI agents, specialized skills, and multi-agent squads. ### Core Problems Crewd Solves: 1. **Agent Copy-Paste Sprawl**: Teams copy massive prompt files between repositories, losing updates, versions, and bug fixes. 2. **Multi-Host Incompatibility**: Developers use multiple AI tools (Claude Code, Cursor, Gemini CLI, OpenAI Codex CLI). Crewd compiles a single agent manifest into the native format required by each active tool in the workspace. 3. **Deterministic Versioning**: With `crewd.json` (manifest) and `crewd.lock` (lockfile), every developer and CI runner has the exact same AI agent setup. 4. **Durable Local Learning**: When you customize an agent's memory or teach it repo-specific conventions, Crewd preserves your local learnings through upgrades using `crewd promote`. --- ## 2. Terminology & Package Types Crewd defines three core package primitives: ### A. Agents (`type: agent`) An autonomous AI persona defined by a system prompt, role triggers (`when:`), allowed tools, and required skills. Examples: `@crewd/code-reviewer`, `@crewd/backend-engineer`, `@crewd/api-designer`, `@crewd/test-writer`. ### B. Skills (`type: skill`) Modular, focused instructional modules or cheatsheets that teach an agent specific domain expertise (e.g. `@crewd/pr-template`, `@crewd/conventional-commits`, `@crewd/owasp-top10`). Skills can be attached to any agent via `crewd teach` or required in `agent.yaml`. ### C. Teams / Squads (`type: team`) Composed multi-agent squads that bundle multiple agents and skills into a coordinated workflow. Examples: `@crewd/backend-squad` (bundles Backend Engineer, API Designer, DB Architect, and Test Writer), `@crewd/pr-review-squad` (bundles Code Reviewer, Security Auditor, and Test Writer). --- ## 3. Installation ### macOS / Linux via Homebrew: ```bash brew tap crewdhq/tap brew install crewd ``` ### Standalone Shell Installer: ```bash curl -fsSL https://crewd.dev/install.sh | sh ``` ### Go Install: ```bash go install github.com/crewdhq/crewd-cli/cmd/crewd@latest ``` ### Verify Installation: ```bash crewd --version crewd doctor ``` --- ## 4. Quickstart Workflow ```bash # 1. Initialize repository with auto-detected AI hosts crewd init # 2. Inspect package dossier before hiring crewd interview @crewd/code-reviewer # 3. Hire an individual agent crewd hire @crewd/code-reviewer # 4. Hire a full multi-agent squad crewd hire team @crewd/backend-squad # 5. View your active roster crewd roster # 6. Teach an installed agent a project-specific skill crewd teach @crewd/code-reviewer @crewd/pr-template # 7. Check health and adapter compilation crewd doctor ``` --- ## 5. CLI Command Reference ### `crewd init [--hosts=]` Initializes a new `crewd.json` in the current workspace. Automatically detects active AI editors (Claude Code, Cursor, Gemini CLI, OpenAI Codex CLI) and writes `.gitignore` rules for generated cache files. ### `crewd hire [@range]` / `crewd hire team ` Installs an agent, skill, or squad into your workspace. - Resolves all transitive dependencies. - Downloads content-addressed tarball archive and validates SHA-256 integrity against registry. - Updates `crewd.json` and `crewd.lock`. - Compiles agent instructions into your workspace's active AI host config files. Options: - `--hosts `: Explicitly target specific hosts (e.g. `--hosts claude-code,cursor`). - `--dry-run`: Preview dependency resolution and files without writing changes. ### `crewd fire ` / `crewd fire team ` Removes an agent, skill, or team from `crewd.json` and deletes its generated host adapter files. Memory files in `.crewd/memory/` are deliberately preserved. ### `crewd promote [package[@version]]` Upgrades installed packages to their latest matching release while strictly preserving all repo-local memories, learnings, and taught skills stored in `.crewd/memory/`. ### `crewd teach ` Attaches an additional repo-local skill to an installed agent without modifying upstream packages. Saved in `crewd.json` under `teach` and re-applied on subsequent compiles and upgrades. ### `crewd forget ` Detaches a taught skill from an agent and recompiles host configurations. ### `crewd install [--frozen]` Restores all agents and skills exactly as defined in `crewd.lock`. - Use `--frozen` in CI/CD pipelines to fail with exit code 4 if the lockfile is out of sync with `crewd.json`. ### `crewd search ` Queries the public Crewd registry for agents, skills, and squads matching keywords or tags. ### `crewd interview ` Fetches and displays the package dossier prior to hiring: system prompt, tool permissions, dependency graph, host compatibility, and any included helper files. ### `crewd roster [--json]` Displays all installed agents, their pinned versions, attached skills, and target host configurations. Supports `--json` for automated scripting. ### `crewd doctor` Runs diagnostic checks: - Verifies lockfile integrity and SHA-256 checksums. - Validates host file synchronization across active editors. - Checks network connectivity to the Crewd registry. ### `crewd mcp` Launches the built-in Model Context Protocol (MCP) server over standard I/O (stdio) so AI agents can query the registry and manage crew members dynamically. ### `crewd completion [bash|zsh|fish]` Generates shell autocompletion scripts for faster terminal workflows. --- ## 6. Supported AI Hosts & Compilation Targets Crewd natively adapts packages into each tool's supported format: | AI Host / Editor | Compiled File / Directory | Native Format & Behavior | | :--- | :--- | :--- | | **Claude Code** | `.claude/agents/.md`
`.claude/skills//SKILL.md` | Frontmatter tool configurations, subagent triggers, and linked memory instructions. | | **Cursor** | `.cursor/rules/crewd-.mdc` | Glob patterns, rule descriptions, and referenced skills. | | **Gemini CLI / Antigravity** | `GEMINI.md` / `AGENTS.md`
`.gemini/skills/` / `.agents/skills/` | Marker-delimited blocks (``). User content outside markers is preserved. | | **OpenAI Codex CLI** | `CODEX.md` / `AGENTS.md`
`.codex/skills//SKILL.md` | Marker-delimited blocks with automatic host detection. | --- ## 7. Package Specifications & Schemas ### `agent.yaml` (Agent Specification) ```yaml schema: https://crewd.dev/schema/agent/v1 type: agent name: "@crewd/code-reviewer" version: 1.0.0 description: "Comprehensive code & PR reviewer subagent" role: title: "Lead Code Reviewer" when: "Use when a diff, commit, or PR requires code review." hosts: - claude-code - cursor - gemini-cli - codex tools: allow: [read, grep, glob, bash] deny: [write, edit] skills: - "@crewd/pr-template@^1.0.0" prompt: prompt.md ``` ### `skill.yaml` (Skill Specification) ```yaml schema: https://crewd.dev/schema/skill/v1 type: skill name: "@crewd/pr-template" version: 1.0.0 description: "Structure pull request descriptions so reviewers can understand and verify a change quickly." hosts: - claude-code - cursor - gemini-cli - codex entry: SKILL.md files: - references/template.md requires: - git - bash ``` ### `team.yaml` (Team Specification) ```yaml schema: https://crewd.dev/schema/team/v1 type: team name: "@crewd/backend-squad" version: 1.0.0 description: "Four coordinated AI agents covering full backend development" members: - agent: "@crewd/backend-engineer@^1.0.0" role: "Lead" - agent: "@crewd/api-designer@^1.0.0" role: "API design" - agent: "@crewd/db-architect@^1.0.0" role: "Data model" - agent: "@crewd/test-writer@^1.0.0" role: "Tests" ``` ### `crewd.json` (Workspace Manifest) ```json { "$schema": "https://crewd.dev/schema/crewd.json", "version": "1.0", "hosts": ["claude-code", "cursor", "gemini-cli", "codex"], "dependencies": { "@crewd/code-reviewer": "^1.0.0", "@crewd/backend-squad": { "team": "^1.0.0" } }, "teach": { "@crewd/code-reviewer": ["@crewd/pr-template@^1.0.0"] } } ``` --- ## 8. Model Context Protocol (MCP) Server Connect your AI assistant directly to Crewd so it can search and hire agents autonomously within your active editor. ### Setup in Claude Desktop, Cursor, Gemini CLI, or Codex (`claude_desktop_config.json`): ```json { "mcpServers": { "crewd": { "command": "npx", "args": ["-y", "@crewdhq/crewd-mcp"] } } } ``` ### Exposed MCP Tools: 1. `search_packages(query: string, type?: string, host?: string)`: Finds packages in the registry. 2. `inspect_package(name: string, version?: string)`: Read-only inspection of prompts, role specifications, tool permissions, and file previews. 3. `plan_hire(name: string, targets?: string[])`: Dry-run resolution returning exact files to be created/changed, SHA-256 hashes, and a single-use `confirm_token`. WRITES NOTHING TO DISK. 4. `hire(name: string, confirm_token: string, targets?: string[])`: Installs package after explicit user confirmation using the `confirm_token`. 5. `check_upgrades()`: Compares repository lockfile against registry for updates. --- ## 9. Public REST API Reference All endpoints return standard JSON. No API key required for public reading. - **Search**: `GET https://crewd.dev/api/v1/search?q={query}` - Query parameters: `q` (string), `type` (optional: `agent`, `skill`, `team`), `host` (optional). - **Package Details**: `GET https://crewd.dev/api/v1/packages/{namespace}/{name}` - **Version Details**: `GET https://crewd.dev/api/v1/packages/{namespace}/{name}/{version}` - **Tarball Archive**: `GET https://crewd.dev/api/v1/tarballs/{namespace}/{name}/{version}` - **Resolve Graph**: `POST https://crewd.dev/api/v1/resolve` - Body: `{"packages": [{"name": "@crewd/code-reviewer", "range": "latest"}]}` --- ## 10. Security & Sandboxing - **Zero Install-Time Script Execution**: Unlike npm or pip, Crewd never executes post-install hooks, build scripts, or lifecycle code during hire, install, or dependency resolution. Packages cannot execute code upon installation. - **Inert File Placement**: Skills containing helper scripts (e.g. `.sh` or `scripts/`) are installed strictly as inert source files. Neither the CLI nor MCP server executes package scripts. - **Pre-Hire Dossier Inspection**: Developers can run `crewd interview ` to inspect prompts, tool permissions, and file scripts before hiring. MCP agents use `inspect_package` and `plan_hire` requiring user confirmation. - **Integrity Verification**: Every version artifact has an immutable SHA-256 integrity hash (`sha256-...`) verified in `crewd.lock` before compilation. - **Deterministic Archiving**: All package tarballs are built with normalized timestamps (epoch 2026-01-01) for repeatable checksum verification. - **Reserved Namespaces**: Brand namespaces (e.g. `@anthropic`, `@cursor`, `@openai`, `@google`) are protected against namespace squatting.