Skills Commands

Use these commands to put capabilities in front of your agents: browse the app-shipped catalog, install skills into a company's library, attach the ones an agent should actually use, and keep installed skills in sync with their pinned origins. Skills are how you teach an agent a repeatable procedure (open a pull request, run a browser, follow a review checklist) without rewriting its prompt every time.

There are two command groups. The plural thinkingmach skills group is the one you reach for in practice — it understands catalog references, resolves skills by id/key/slug, and prints readable tables. The singular thinkingmach skill group is a thin, payload-driven wrapper over the same company-skill API endpoints; use it only when you need raw control over the request body in a script.

The three operations

thinkingmach skills spans three distinct things. Keeping them straight is the whole mental model:

Operation	Commands	What it changes
Company install	`skills install`, `import`, `create`, `scan-projects`	Adds or updates a skill in the company's library. Available to the whole company; does not attach it to any agent.
Agent attach	`skills agent sync`, `skills agent clear`	Changes an agent's desired company-skill set. `sync` takes a required `--mode` (`add`, `remove`, or `replace`) so you can grow, prune, or overwrite the set; `clear` empties it.
Adapter runtime sync	reported by `skills agent list`; triggered by `sync`/`clear`	The server-side adapter reconciles the desired set with files on disk and returns an `AgentSkillSnapshot`.

Note: skills agent sync now requires a --mode (add, remove, or replace), so you choose whether the named skills join, leave, or overwrite the desired set. skills agent clear empties the set outright (it uses replace internally with an empty list). Bundled ThinkingMach skills still live in the company library as read-only entries, but the server no longer force-attaches them to an agent.

Tip: Add --json to any command to print the raw API result for scripting. Every company-scoped command takes --company-id <company-id> (and respects your selected profile/context). See common options.

Catalog: browse before you install

The ThinkingMach app ships a curated catalog of skills. Catalog commands let you read it without writing anything to a company — there is no company context required to browse, search, or inspect.

thinkingmach skills browse --kind bundled --category github
thinkingmach skills search "pull request" --kind bundled
thinkingmach skills inspect github-pr-workflow

Command	Use
`browse`	List catalog skills, optionally filtered by `--kind`, `--category`, or `--query`.
`search <query>`	Same as `browse` but takes the search text as a positional argument.
`inspect <catalogRef>`	Show one catalog skill in full, including its file manifest (path, kind, size, sha256).

Browse/search filters:

Flag	Use
`--kind <kind>`	Filter by catalog kind: `bundled` or `optional`.
`--category <slug>`	Filter by catalog category slug.
`--query <text>`	Free-text search (`browse` only; `search` uses its positional argument).

A <catalogRef> is a catalog skill id, key, or a unique slug. Inspect a skill before installing it so you know exactly which files will land in the company library.

Catalog install into the company library

skills install materializes a catalog skill into a company-managed skill. This is a company install — it does not attach the skill to any agent.

thinkingmach skills install github-pr-workflow --company-id <company-id>
thinkingmach skills install github-pr-workflow --as review-prs --company-id <company-id>

Flag	Use
`--as <slug>`	Override the company skill slug.
`--force`	Replace a same-key catalog-managed skill when the server allows it. Never bypasses hard validation or hard-stop audit findings.

After install the command reminds you that nothing is attached yet. To make an agent use it, run an agent attach afterward.

Note: Catalog commands are for the app-shipped catalog only. GitHub, skills.sh, local-path, and plain-URL sources go through skills import instead.

Company library

These commands manage the skills that exist in a company, regardless of where they came from. All require a company context.

thinkingmach skills list --company-id <company-id>
thinkingmach skills show <skill-ref> --company-id <company-id>
thinkingmach skills file <skill-ref> --path SKILL.md --company-id <company-id>
thinkingmach skills import <source> --company-id <company-id>
thinkingmach skills create --name "Review PRs" --slug review-prs --body-file SKILL.md --company-id <company-id>
thinkingmach skills scan-projects --project-id <project-id> --company-id <company-id>

Command	Use
`list`	List every skill in the company library.
`show <skillRef>`	Show full detail for one company skill.
`file <skillRef>`	Print one skill file. Defaults to `SKILL.md`; pass `--path <path>` for another file. In human mode the raw content is written to stdout so you can pipe it.
`import <source>`	Import skills from a local path, GitHub, skills.sh, or a URL source. Prints the imported skills plus any warnings.
`create`	Create a managed local skill from flags and an optional markdown body.
`scan-projects`	Scan project workspaces for skills and import or update what it finds.

A <skillRef> resolves against the company library by id, canonical key, or unique slug. An ambiguous slug is rejected — use an id or key instead.

skills create options:

Flag	Use
`--name <name>`	Required. Skill name.
`--slug <slug>`	Optional explicit slug.
`--description <text>`	Optional description.
`--body-file <path>`	Markdown body file. Use `-` to read the body from stdin.

skills scan-projects options (each may be repeated):

Flag	Use
`--project-id <id>`	Project ID to scan; repeat for several.
`--workspace-id <id>`	Workspace ID to scan; repeat for several.

With no --project-id/--workspace-id the scan covers the company's projects and workspaces. The summary line reports projects/workspaces scanned plus discovered, imported, updated, skipped, conflicts, and warnings counts.

Maintenance loop: check, update, audit, reset

Catalog-installed skills are pinned to an origin. Over time the catalog moves on, or someone edits the installed bytes locally. These four commands are the maintenance loop. The skill reference is optional on check, update, and audit; omit it to operate over the whole library.

thinkingmach skills check --company-id <company-id>
thinkingmach skills update <skill-ref> --company-id <company-id>
thinkingmach skills update --all --company-id <company-id>
thinkingmach skills audit <skill-ref> --company-id <company-id>
thinkingmach skills reset <skill-ref> --yes --company-id <company-id>

Command	Use
`check [skillRef]`	Report update status: `supported`, `hasUpdate`, `currentRef`/`latestRef`, `installedHash`/`originHash`, any `updateHoldReason`, and the `auditVerdict`.
`update [skillRef]`	Install the pinned update for one skill.
`update --all`	Check every skill and update only those with `hasUpdate=true`; supported-but-current and unsupported skills are skipped with a reason.
`audit [skillRef]`	Re-scan installed bytes and report findings (severity, code, path, message) without executing anything.
`reset <skillRef>`	Reinstall a catalog-managed skill from its pinned origin, discarding local edits.

update and reset accept --force:

Flag	Use
`--all`	(`update` only) Update every skill that has an available update.
`--force`	Discard local-modification and soft-audit holds. Hard-stop audit findings still block the operation.
`--yes`	(`reset` only) Confirm without the interactive prompt. Required when not in a TTY.

Warning: Pass either a skill reference or --all to update, never both — the command rejects that combination.

Remove a skill

thinkingmach skills remove <skill-ref> --yes --company-id <company-id>

skills remove deletes a skill from the company library. It prompts for confirmation in an interactive terminal and requires --yes when run non-interactively.

Agent attach: desired skills

Once a skill is in the library, skills agent sync decides how the skills you name meet the agent's current desired set. That is what --mode is for, and it is required — you pick one of three behaviours:

add keeps everything the agent already has and unions in the skills you name (a skill already present is updated in place).
remove drops only the skills you name and leaves the rest of the set alone.
replace overwrites the complete desired set with exactly the skills you pass, detaching anything you omit. This is the old full-replacement behaviour.

The adapter then reconciles and the command returns an AgentSkillSnapshot.

thinkingmach skills agent list <agent-ref> --company-id <company-id>
thinkingmach skills agent sync <agent-ref> --skill review-prs --skill agent-browser --mode add --company-id <company-id>
thinkingmach skills agent clear <agent-ref> --yes --company-id <company-id>

Command	Use
`agent list <agentRef>`	Show the agent's runtime skill snapshot: adapter type, whether sync is `supported`, the `mode`, the desired count, and per-skill runtime entries (state, origin, managed flag).
`agent sync <agentRef>`	Add, remove, or replace the agent's desired company skills and sync runtime state. Requires at least one `--skill` and a `--mode`.
`agent clear <agentRef>`	Clear the desired set (empties it via an internal `replace` with an empty list). Prompts in a TTY; requires `--yes` otherwise.

Flag	Use
`--skill <skillRef>`	(`sync`) A desired company skill `id`, `key`, or `slug`. Repeat for several. At least one is required.
`--mode <mode>`	(`sync`) Required. Merge mode: `add` keeps other skills; `remove` deletes only named skills; `replace` destructively overwrites the complete set.
`--yes`	(`clear`) Confirm without the interactive prompt.

An <agentRef> is an agent id or shortname/url-key. With --mode replace you must list the complete desired set every time — anything you omit is detached — while --mode add and --mode remove only touch the skills you name. clear detaches everything.

The singular `skill` group

thinkingmach skill is a lower-level wrapper over the same company-skill API. It does not resolve key/slug references — every subcommand takes a literal <skillId> — and the create/import/scan/file-update operations are driven by a raw JSON payload. Reach for it only when you are scripting against a known skill ID and want direct control of the request body.

thinkingmach skill list -C <company-id>
thinkingmach skill get <skill-id> -C <company-id>
thinkingmach skill file <skill-id> --path SKILL.md -C <company-id>
thinkingmach skill file:update <skill-id> --payload-json '{"path":"SKILL.md","content":"..."}' -C <company-id>
thinkingmach skill update-status <skill-id> -C <company-id>
thinkingmach skill install-update <skill-id> -C <company-id>
thinkingmach skill delete <skill-id> -C <company-id>

Command	Use
`list`	List company skills (raw API output).
`get <skillId>`	Get one skill's detail by ID.
`file <skillId>`	Read a skill file; `--path` defaults to `SKILL.md`.
`file:update <skillId>`	Update a skill file. Requires `--payload-json` (a `CompanySkillFileUpdate` body).
`create`	Create a local skill. Requires `--payload-json`.
`import`	Import skills from a source. Requires `--payload-json`.
`scan-projects`	Scan project workspaces for skills. Requires `--payload-json`.
`update-status <skillId>`	Read the update status for one skill.
`install-update <skillId>`	Install the available update for one skill.
`delete <skillId>`	Delete a skill by ID.

Every skill subcommand takes -C, --company-id <id>. Prefer the plural skills group for everyday work — it gives you reference resolution, confirmation prompts, and readable output that the singular group does not.