> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skill Commands

> Author, import, and assign skills to agents from the CLI.

# crewship skill

Skills are reusable instruction playbooks that get injected into an agent's
system prompt as a `[SKILLS AVAILABLE]` block and materialised on disk in
each CLI's discovery convention (`.claude/skills/`, `.opencode/skills/`,
`.factory/skills/`, `.agents/skills/`, `.cursor/rules/`). The CLI is the
canonical authoring + iteration path; the web UI is a surface over the
same API.

```bash theme={null}
crewship skill <subcommand> [flags]
```

## Subcommands at a glance

| Command            | What it does                                                        |
| ------------------ | ------------------------------------------------------------------- |
| `init`             | Generate a SKILL.md scaffold on disk (offline; no API call).        |
| `list`             | List skills in the workspace, with optional filters.                |
| `get`              | Show skill metadata.                                                |
| `export`           | Recover a previously-imported SKILL.md from the workspace registry. |
| `import`           | Upload a SKILL.md (single URL/file) or walk a whole git repo.       |
| `create`           | LLM-author a SKILL.md via Anthropic Messages (requires API key).    |
| `delete`           | Remove a skill from the workspace registry.                         |
| `assign`           | Attach a skill to one agent, several agents, or a whole crew.       |
| `unassign`         | Detach the same way.                                                |
| `proposed list`    | List skills auto-promoted from memory awaiting operator approval.   |
| `proposed approve` | Import a staged proposal via the canonical importer.                |
| `proposed reject`  | Discard a staged proposal (deletes the `.proposed/` file).          |

***

## The CLI authoring loop

The intended flow for a custom skill is:

```bash theme={null}
# 1. Scaffold a starter SKILL.md
crewship skill init pdf-cleanup --category DEVOPS \
  --description "Use when the user asks to strip metadata from a PDF."

# 2. Edit the scaffold — fill in Steps, Output format, Guardrails
$EDITOR ./pdf-cleanup/SKILL.md

# 3. Upload it
crewship skill import --file ./pdf-cleanup/SKILL.md

# 4. Assign to one or more agents
crewship skill assign pdf-cleanup --to-crew engineering

# 5. Iterate: pull the current version back, edit, re-upload
crewship skill export pdf-cleanup --output ./
$EDITOR ./pdf-cleanup.md
crewship skill import --file ./pdf-cleanup.md
```

<Tip>
  `init` is intentionally offline — it doesn't talk to the server, so it
  works for users who only have a Claude Code OAuth token and cannot reach
  the Anthropic Messages API directly (the path `crewship skill create`
  needs).
</Tip>

***

## `crewship skill init`

Write a SKILL.md scaffold to disk so you can edit it locally and upload.

```bash theme={null}
crewship skill init <slug> [flags]
```

| Flag            | Default     | Notes                                                                                                                                                                                                                                                                           |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--category`    | `CUSTOM`    | One of `CODING DATA DEVOPS WRITING RESEARCH PM DESIGN SUPPORT SECURITY FINANCE OPS AUTOMATION SALES CUSTOM`.                                                                                                                                                                    |
| `--description` | *(empty)*   | One-line trigger; should start with `Use when...`, `Useful for...`, or `To <verb>...`. When omitted, the scaffold writes a `TODO:` placeholder into the frontmatter `description:` field — fill it in before `crewship skill import`, which validates the SKILL.md server-side. |
| `--license`     | `MIT`       | SPDX identifier — must be on the allowlist below for `skill import` to accept it later.                                                                                                                                                                                         |
| `--output`      | `./<slug>/` | Output directory for `<dir>/SKILL.md`.                                                                                                                                                                                                                                          |
| `--force`       | `false`     | Overwrite an existing SKILL.md at the destination.                                                                                                                                                                                                                              |

The scaffold writes the canonical body sections (`When to use`, `Steps`,
`Output format`, `Guardrails`, optional `Verification`) and frontmatter
fields the parser accepts.

***

## `crewship skill list`

```bash theme={null}
crewship skill list [flags]
```

| Flag                      | Notes                                                  |
| ------------------------- | ------------------------------------------------------ |
| `--category`              | Filter by category.                                    |
| `--source`                | One of `BUNDLED CUSTOM GENERATED MARKETPLACE MANAGED`. |
| `--vendor`                | Vendor namespace (e.g. `anthropic`, `community`).      |
| `--maturity`              | One of `OFFICIAL CURATED COMMUNITY EXPERIMENTAL`.      |
| `--runtime`               | One of `INSTRUCTIONS SCRIPT MCP HYBRID`.               |
| `--search`                | Substring match on name / display\_name / description. |
| `--installed`             | Only skills with at least one `agent_skills` row.      |
| `--installed-for=<agent>` | Only skills assigned to a specific agent.              |

Examples:

```bash theme={null}
crewship skill list --maturity OFFICIAL
crewship skill list --vendor anthropic --category DESIGN
crewship skill list --installed-for viktor
crewship skill list --search pdf
```

***

## `crewship skill get`

Show metadata for one skill — name, slug, category, version, source, author, tool count, created-at. The markdown `description` body renders below the metadata block via `glamour` for human formats; JSON / YAML / quiet outputs include it raw inside the serialized struct.

```bash theme={null}
crewship skill get <slug-or-id>
crewship skill get pdf-cleanup --format json | jq '.tool_count'
```

Backed by `GET /api/v1/skills/{id}` after resolving `<slug-or-id>` to the skill's id.

***

## `crewship skill export`

Recover the SKILL.md body from the workspace and write it to disk or stdout.

```bash theme={null}
crewship skill export <slug-or-id> [--output PATH]
```

Without `--output`, prints to stdout (pipe-friendly). With `--output` set
to a directory, writes `<slug>.md` inside it.

```bash theme={null}
# Print to stdout
crewship skill export pdf-cleanup

# Write to a directory
crewship skill export pdf-cleanup --output ./
```

***

## `crewship skill import`

Import a single SKILL.md (URL or file) or walk a whole git repo.

```bash theme={null}
# Single SKILL.md from a URL or local file
crewship skill import https://raw.githubusercontent.com/owner/repo/main/skills/my-skill/SKILL.md
crewship skill import --file ./SKILL.md

# Whole git repo (--depth 1, walks for **/SKILL.md, license-gated)
crewship skill import --repo https://github.com/anthropics/skills
crewship skill import --repo https://github.com/owner/skills --paths 'skills/*' --dry-run
crewship skill import --repo https://github.com/owner/skills --unsafe-license
```

| Flag               | Notes                                                |
| ------------------ | ---------------------------------------------------- |
| `--file`           | Path to a local SKILL.md (single skill).             |
| `--repo`           | Git URL — switches to bulk mode.                     |
| `--ref`            | Git ref (branch/tag); only with `--repo`.            |
| `--paths`          | Glob filters relative to repo root, e.g. `skills/*`. |
| `--vendor`         | Override vendor namespace (defaults to `community`). |
| `--unsafe-license` | Skip the SPDX license allowlist (use with caution).  |
| `--dry-run`        | Walk + parse, don't write.                           |

### What runs on every import

1. **SSRF check** — URL/host must be public; private IPs blocked (single + bulk).
2. **License gate** — frontmatter `license:` is matched against the SPDX allowlist below.
3. **Prompt-injection scanner** — body scanned for "ignore previous instructions", role hijack, large base64 blobs, etc. Status stored in `scan_status` (`CLEAN` / `FLAGGED`).
4. **Size cap** — single fetch ≤ 512 KB; bulk per-file same; bulk total ≤ 500 SKILL.md files.
5. **BUNDLED protection** — re-importing a slug already owned by a `BUNDLED` skill is refused.

### SPDX allowlist

`MIT`, `Apache-2.0`, `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `CC0-1.0`,
`MPL-2.0`, `Unlicense`, `0BSD`. Pass `--unsafe-license` to bypass for one
batch (audited via the `license` column).

***

## `crewship skill create`

LLM-authored SKILL.md via Anthropic Messages.

```bash theme={null}
crewship skill create --slug pdf-cleanup \
  --prompt "Help users sanitise PDFs: strip metadata, remove embedded JS, flatten forms"
```

<Note>
  **Requires** an active Anthropic credential of type `API_KEY` in the
  workspace (Settings → Credentials). An OAuth token from `claude /login`
  is **not** sufficient (it's a Bearer for claude.ai, not the Messages API).
  Users without an API key should reach for `skill init` instead.
</Note>

| Flag       | Default             | Notes                                                  |
| ---------- | ------------------- | ------------------------------------------------------ |
| `--slug`   | *required*          | Kebab-case identifier.                                 |
| `--prompt` | *required*          | Free-form description of the skill's behaviour.        |
| `--model`  | `claude-sonnet-4-6` | LLM model override.                                    |
| `--print`  | `false`             | Print generated SKILL.md to stdout instead of summary. |

***

## `crewship skill delete`

Remove a skill from the workspace registry. Cascades to `agent_skills`.

```bash theme={null}
crewship skill delete <slug-or-id>          # interactive confirm
crewship skill delete <slug-or-id> --yes    # skip confirm (--force also accepted)
crewship skill rm <slug-or-id>              # alias
```

<Warning>
  Cascades to `agent_skills` — every agent loses the skill. `BUNDLED` skills
  cannot be deleted (they re-seed on every server start).
</Warning>

***

## `crewship skill assign`

```bash theme={null}
# One agent (positional)
crewship skill assign my-skill viktor

# Multiple agents
crewship skill assign my-skill --to-agents viktor,nela,martin

# Whole crew
crewship skill assign my-skill --to-crew engineering
```

The fan-out variant is idempotent: agents that already have the skill are
treated as success, and per-agent failures are reported but don't abort
the rest.

***

## `crewship skill unassign`

Same target shapes as `assign`:

```bash theme={null}
crewship skill unassign my-skill viktor
crewship skill unassign my-skill --to-agents viktor,nela
crewship skill unassign my-skill --to-crew engineering
```

After `unassign`, the next time the agent runs, the orchestrator prunes
the skill folder from the agent's container (`.claude/skills/<slug>/`,
`.cursor/rules/<slug>.mdc`, etc.) so a CLI auto-discovery walker can no
longer pick it up.

***

## `crewship skill proposed`

Operator-side HITL surface for the memory→Skills bridge. When the consolidator sees a learned rule with sustained recall (default ≥ 10 recall events, composite score ≥ 0.85) it stages an Anthropic-format `SKILL.md` under `.memory/{crew-slug}/topics/.proposed/skill-<slug>.md`. These three verbs let an operator inspect and decide.

<Note>
  Each `proposed` verb requires `OWNER`, `ADMIN`, or `MANAGER` role.
</Note>

### `crewship skill proposed list`

```bash theme={null}
crewship skill proposed list --crew <crew-id>
crewship skill proposed list --crew <crew-id> --format json
```

| Flag       | Required | Description                                                                                                                          |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--crew`   | yes      | Crew id whose `.proposed/` dir to scan. The CLI URL-encodes this value so any future id-scheme change with special chars stays safe. |
| `--format` | no       | `text` (default) or `json`.                                                                                                          |

**Output columns:** FILE, NAME, CATEGORY, DESCRIPTION (truncated to 60 chars), QUALITY (`ok` when the server didn't flag it).

Backed by `GET /api/v1/skills/proposed?crew_id=<id>`.

### `crewship skill proposed approve`

Run the staged file through the canonical skill importer — same path as URL-based imports, so the SPDX license check and prompt-injection scan apply. On success the staging file is deleted and an `EntryMemorySkillApproved` journal entry fires.

```bash theme={null}
crewship skill proposed approve --crew <crew-id> --file skill-deploy-friday.md
```

| Flag     | Required | Description                                                 |
| -------- | -------- | ----------------------------------------------------------- |
| `--crew` | yes      | Crew id.                                                    |
| `--file` | yes      | Staged file name as listed (e.g. `skill-deploy-friday.md`). |

Backed by `POST /api/v1/skills/proposed/approve`. Output: `approved <file> -> skill <id> (<slug>, created|updated)`.

### `crewship skill proposed reject`

Discard the staging file without importing. **Idempotent** — rejecting an already-deleted file returns success, and an `EntryMemorySkillRejected` journal entry fires either way.

```bash theme={null}
crewship skill proposed reject --crew <crew-id> --file skill-noise.md
```

| Flag     | Required | Description       |
| -------- | -------- | ----------------- |
| `--crew` | yes      | Crew id.          |
| `--file` | yes      | Staged file name. |

Backed by `POST /api/v1/skills/proposed/reject`.

***

## Per-CLI filesystem materialisation

When a skill is assigned, the orchestrator writes its SKILL.md into the
discovery convention each adapter knows. This way the same skill works
for whatever CLI the agent is configured with:

| CLI                         | Path inside container                   |
| --------------------------- | --------------------------------------- |
| Claude Code                 | `.claude/skills/<slug>/SKILL.md`        |
| OpenAI Codex CLI            | `.agents/skills/<slug>/SKILL.md`        |
| OpenCode                    | `.opencode/skills/<slug>/SKILL.md`      |
| Factory Droid               | `.factory/skills/<slug>/SKILL.md`       |
| Cursor                      | `.cursor/rules/<slug>.mdc` (flat .mdc)  |
| Gemini CLI / other adapters | `[SKILLS AVAILABLE]` block only (no FS) |

The system-prompt block is the authoritative surface — filesystem layout
is the bonus discovery path for adapters that walk it natively.