skillfold-cli ยท diff
git:20260321.3f7ced7 to git:20260706.9eedcfa
32 added, 71 removed. Audit A to A.
---
name: skillfold-cli
- description: Use the skillfold compiler to manage multi-agent pipeline configs. Compile, validate, inspect, and visualize pipelines defined in skillfold.yaml.
+ description: Use skillfold to manage a project's Claude skills. Declare skills in skillfold.yaml, pin them in skillfold.lock, and install them into .claude/skills.
---
# Skillfold CLI
- You use the skillfold compiler to manage multi-agent pipeline configurations. Skillfold compiles YAML config into standard SKILL.md files per the Agent Skills specification.
-
- ## Config File
-
- The pipeline is defined in `skillfold.yaml` at the project root. It has four top-level sections:
-
- - **resources** - Namespace URLs for external services
- - **skills** - Atomic skill directories and composition rules
- - **state** - Typed state schema with custom types and external locations
- - **team** - Orchestrator designation and execution flow
-
- ## Commands
-
- ### Compile
-
- ```bash
- npx skillfold
- ```
-
- Compiles the pipeline config and writes one SKILL.md per agent to the output directory (default: `build/`). Each output file contains the concatenated bodies of the agent's composed skills plus YAML frontmatter.
-
- ### Validate
-
- ```bash
- npx skillfold validate
- ```
-
- Validates the config without writing any output. Checks skill references, state types, flow transitions, cycle exit conditions, and write conflicts. Use this for quick feedback while editing config.
-
- ### Check
-
- ```bash
- npx skillfold --check
- ```
-
- Verifies that compiled output on disk matches what the compiler would generate. Exits with code 1 if any output is stale or missing. Designed for CI pipelines to catch uncommitted config changes.
-
- ### List
+ You use skillfold, a declarative skill manager for Claude config. Projects declare the skills they use in `skillfold.yaml`; skillfold installs them into `.claude/skills` and pins exact revisions in `skillfold.lock`.
- ```bash
- npx skillfold list
- ```
+ ## Manifest
- Displays a structured summary of the pipeline: skills (atomic and composed with their composition chains), state fields with types and locations, and team flow with transitions.
+ `skillfold.yaml` at the project root:
- ### Graph
+ ```yaml
+ skills:
+ commit-helper: ./skills/commit-helper # local directory
+ frontend-design: github:owner/repo/path/to/skill@v1.2.0 # GitHub (tag, branch, or SHA)
+ planning: npm:skillfold/planning@2.0.0 # npm package
- ```bash
- npx skillfold graph
+ compose:
+ reviewer:
+ description: Review code changes together with their tests.
+ use: [code-review, testing]
```
- Outputs a Mermaid flowchart of the team flow. Shows full skill composition lineage (which atomic skills compose each agent) and state writes on edges.
+ A trailing `@ref` after the last `/` pins a version. Composed skills concatenate the bodies of the skills they `use` into one generated skill.
- ### Init
+ ## Commands
```bash
- npx skillfold init
+ skillfold init # scaffold a starter manifest + example skill
+ skillfold add <source> # add a skill and install it (--name to rename)
+ skillfold remove <name> # remove a skill and uninstall it
+ skillfold install # install everything, write skillfold.lock
+ skillfold install --frozen # CI mode: exact lockfile install, fail on drift
+ skillfold update [name...] # re-resolve moving refs, then reinstall
+ skillfold check # verify manifest, lockfile, and installed files agree
+ skillfold list # status table (ok / modified / not installed / not locked)
+ skillfold info <name> # source, pin, hash, and install path for one skill
+ skillfold search [query] # find skill packages on npm
```
- Scaffolds a new pipeline project with a starter `skillfold.yaml` and two example skills. Use this to get started quickly in a new directory.
-
- ## Options
-
- | Flag | Description |
- |------|-------------|
- | `--config <path>` | Config file path (default: `skillfold.yaml`) |
- | `--out-dir <path>` | Output directory (default: `build`) |
- | `--dir <path>` | Target directory for init (default: `.`) |
- | `--check` | Verify compiled output is up-to-date |
- | `--help` | Show help |
- | `--version` | Show version |
-
- ## Workflow
-
- A typical workflow when modifying the pipeline:
+ Add `-g` / `--global` to manage `~/.claude/skills` instead of the project.
- 1. Edit `skillfold.yaml` to change skills, state, or team flow
- 2. Run `npx skillfold validate` to catch errors early
- 3. Run `npx skillfold` to compile the pipeline
- 4. Run `npx skillfold list` to inspect the result
- 5. Commit both the config and the compiled output
+ ## Rules
- For CI, add `npx skillfold --check` to verify compiled output stays in sync with the config source of truth.
+ - Commit both `skillfold.yaml` and `skillfold.lock`. Never edit the lockfile by hand.
+ - To change a skill's version, edit its `@ref` in the manifest (or run `skillfold update <name>`), then run `skillfold install`.
+ - Never edit files under `.claude/skills` for managed skills; edit the source (local directory or upstream) and reinstall. `skillfold list` shows `modified` when installed files drifted.
+ - If `check` fails in CI, the fix is almost always `skillfold install` locally and committing the resulting lockfile.
+ - Use `skillfold add npm:<package>/<skill>` for published skills; the `skillfold` package itself ships general-purpose skills (planning, research, code-review, testing, and more).