Skip to content

CLI reference

All commands accept --json for scriptable output and --no-color to disable styled output (the NO_COLOR env var works too).

Every skael command uses these codes. They are stable, so a script can branch on the code and ignore the text.

CodeMeaning
0Success
1API or network error, or a local write that failed
2Usage or config error: an unknown command or flag, a bad argument, or a missing or invalid config
10Incomplete set: skael pull wrote nothing
11Digest mismatch: skael pull or skael add wrote nothing

With --json, a failure prints this envelope to stdout, and the exit code is not zero. suggestion is present only when the CLI has one. Some failures add fields, such as excluded on code 10 and decision on a blocked publish.

{"error": "not configured", "code": "not_configured", "suggestion": "skael setup <url> <api-key>"}

A held publish is not a failure. The version exists, so skael publish exits 0.

skael sync and skael import exit 1 if any one skill fails. With --json, the counts are under result in the envelope.

skael scan also uses 1 for findings, and 2 when the scan cannot run. skael doctor exits 2 when the config check fails and 1 when another check fails. These two print their full report first.

One-command onboarding: validates the key, writes ~/.skael/config.json, detects installed agents, and installs activation-tracking and auto-sync hooks.

FlagDefaultDescription
--scope project|userprojectDefault skill placement scope saved to config
--skip-syncfalseSkip the initial sync
--skip-hooksfalseSkip hook installation
--no-auto-syncfalseSkip auto-sync hook installation

skael add <skill | pattern> | --set <name>

Section titled “skael add <skill | pattern> | --set <name>”

Follows a skill, every released skill under a pattern, or a set, and installs what it resolves to. It records the followed source in ~/.skael/config.json, and skael sync and the auto-sync hook keep it current. A new skill released under a followed pattern, or added to a followed set, arrives with no command.

Terminal window
skael add code-review
skael add 'payments:*'
skael add --set payments

A pattern is a prefix ending in *, such as payments:*, or * for every released skill. Quote it so the shell does not expand it. Any member can follow a pattern; it creates nothing on the server and reaches only released skills the member can already read.

When two followed sources want different versions of one skill, add exits 2, names both sources, and records nothing.

FlagDefaultDescription
--set <name>noneFollow a set
--scope project|userconfig defaultOverride placement scope for this source

skael remove <skill | pattern> | --set <name>

Section titled “skael remove <skill | pattern> | --set <name>”

Stops following a source and removes each skill that no other followed source still wants. A skill you also follow by name, or through another pattern or set, stays.

Resolves every followed source in ~/.skael/config.json and installs what changed: new and updated skills, skills added to a followed set, and skills released under a followed pattern. It removes skills no source wants any more. Only changed skills are downloaded. Supports --dry-run.

FlagDefaultDescription
--scope project|userconfig or projectOverride skill placement scope for this run
--agent <name>both foldersclaude-code writes only .claude/skills; any other agent writes only .agents/skills
--dry-runfalseShow what would happen without making changes
--quietfalseSuppress non-error output

Sync removes an installed version that a rescan withdrew, and prints the reason. It prints the reason with --quiet too, because the reason names a finding such as a secret. If an older released version exists, sync installs it in the same run. With --json, the output lists each removal under withdrawn.

With no argument, init writes two skills to .agents/skills/ in the current directory, and to .claude/skills/ when Claude Code is detected. The binary carries both:

  • skael tells an agent how to use the CLI.

  • skael-evals tells an agent how to write an eval suite that skael eval check reports at the full tier. It holds templates, a sheet of good and bad expectations, and a complete suite for examples/code-review.

  • A second run changes nothing and exits 0.

  • If a file differs from the skill in the binary, init refuses and exits 2. Pass --force to overwrite it.

  • With --json, init prints the path and status of the skael SKILL.md, and a files map of every file to created, unchanged or overwritten.

With a name, init scaffolds a spec-compliant skill directory. Creates <name>/ in the current directory and writes a SKILL.md with name, an empty description, and a metadata block (author, tags, version) ready to fill in.

The name must match ^[a-z0-9]([a-z0-9:.-]*[a-z0-9])?$ — lowercase letters, digits, colons, dots and hyphens, starting and ending on a letter or digit. Colons namespace a skill (payments:invoices). Anything else is rejected and nothing is created.

The directory is named after the skill. If it already exists, init fails and writes nothing — it never merges into or overwrites an existing directory.

Resolves a set to exact versions, downloads its bundle, and writes the skills under <dir>/.agents/skills/, and under <dir>/.claude/skills/ when Claude Code is detected. It works on a clean machine with only SKAEL_URL and SKAEL_KEY set.

Pull writes once. It records nothing, and skael sync never follows it. To follow a set on a developer machine, use skael add --set <name>. To undo a pull, delete the skill folders that manifest.json lists.

FlagDefaultDescription
--set <name>requiredThe set to pull
--dir <path>current directoryThe directory that receives .agents/skills/
--no-hooksfalseWrite files only. Change no agent config and write nothing to ~/.skael

Pull runs these steps in order:

  1. It resolves the set. If an entry is excluded, it prints the excluded entries and exits 10.
  2. It downloads the bundle for that exact resolution.
  3. It checks the SHA-256 of each skill archive and the manifest against the resolve result. A mismatch or a missing archive exits 11.
  4. It unpacks each verified archive, not the bundle’s unpacked tree, into a temporary directory beside the target. It refuses path traversal, links and special files, and it removes setuid bits.
  5. It renames the temporary directory into place. A failure before this step leaves the target unchanged.
  6. Without --no-hooks, it installs the activation hook for each detected agent. It does not install the auto-sync hook, because skael sync manages a different list of skills.

The target directory holds manifest.json and one directory per skill. Other entries in the target stay, such as the skill from skael init. A skill that the previous manifest named and this set does not name is removed.

manifest.json has the set name, the resolution id, and the name, version and SHA-256 of each skill. Its archive field names a path inside the bundle. Pull does not write the archives to disk.

Reads and manages named sets of skills. --json prints the API response unchanged. delete has no API body, so it prints {"deleted": true, "name": "..."}.

CommandWhoDescription
skael sets listany key with sets:readList sets. A set-limited key sees its own set
skael sets get <name>any key with sets:readShow the entries and the last callers
skael sets resolve <name>any key with sets:readShow exact versions, digests and excluded entries
skael sets create <name> [entry...]owner or adminCreate a set. --description sets its description
skael sets update <name> [entry...]owner or adminReplace all entries, or change --description. What you omit stays
skael sets delete <name>owner or adminDelete a set

Write an entry as name or name@latest to follow the latest version, or as name@3 to pin one version. A pattern such as 'payments:*' follows every released skill under it, and '*' follows every released skill. An exclusion such as '!payments:legacy' leaves skills out after every include. A skill a pattern matches with nothing released is skipped and the set stays complete. Saving refuses an exact entry that an exclusion also covers.

skael sets resolve exits 0 on an incomplete set, because that is a valid answer. Read complete in the output. Use skael pull to get exit code 10.

Manages machine identities and their scoped keys. Every command needs an owner or admin. <account> is a name or an id. --json prints the API response unchanged. delete and revoke have no API body, so they print a small object that says what changed.

CommandDescription
skael service-accounts listList service accounts
skael service-accounts create <name>Create a service account
skael service-accounts delete <account>Delete an account and revoke its keys
skael service-accounts keys list <account>List an account’s keys
skael service-accounts keys create <account>Create a key and show it once
skael service-accounts keys revoke <account> <key-id>Revoke a key

keys create takes these flags:

FlagDefaultDescription
--scope <scope>requiredA scope the key holds. Repeat it for more. The scopes are skills:read, sets:read, eval:work, events:write, outcomes:write and submissions:write
--set <name>noneLimit the key to one set. The key needs sets:read
--name <label>defaultA label for the key

Manages webhook endpoints and their deliveries. Every command needs an owner or admin. <endpoint> is a name or an id. If two endpoints share a name, use the id, because the name exits 2. --json prints the API response unchanged. delete, test and redeliver have no API body, so they print {"deleted": true, ...} or {"queued": true, ...}.

CommandDescription
skael webhooks listList endpoints
skael webhooks get <endpoint>Show an endpoint
skael webhooks createRegister an endpoint and show its secret once
skael webhooks update <endpoint>Change an endpoint. What you omit stays
skael webhooks delete <endpoint>Delete an endpoint and its delivery log
skael webhooks rotate <endpoint>Replace the secret and show the new one once
skael webhooks test <endpoint>Queue a test event
skael webhooks deliveries <endpoint>List the newest 50 deliveries and their attempts
skael webhooks redeliver <delivery-id>Send a delivery again with the same event id

create and update take these flags. create needs --name, --url and --event.

FlagDescription
--name <name>A label for the endpoint
--url <url>The address that receives deliveries
--event <type>An event type. Repeat it for more. On update, the list replaces the current list
--set <name>Limit set.changed to this set. Repeat it for more. On update, the list replaces the current list

update also takes these flags.

FlagDescription
--enableSend deliveries to the endpoint again
--disableStop deliveries. The endpoint and its log stay
--all-setsRemove the set limit, so set.changed fires for every set. Cannot be used with --set

rotate takes --window-hours <n>, from 0 to 168. The old secret stays valid for that window, and the default is 24 hours.

A refused address or an unknown event type is a server 422, so it exits 1. A missing flag exits 2.

Sends a batch of run events to POST /api/events/batch. It needs a service account key with events:write. The consumer comes from the account.

FlagDefaultDescription
--file <path>requiredJSON Lines with one event on each line, a JSON array of events, or an object with an events array
--idempotency-key <key>noneA repeat with this key returns the first result and stores nothing

Each event has skill, version, agent, role, external_run_id and time, and it can have set and resolution_id. A batch holds at most 1,000 events.

A batch is all or nothing. If the server rejects an event, the command prints the failing index and exits 1. With --json, the envelope has index and the code invalid_event. A file that cannot be read or parsed exits 2.

CommandWhoDescription
skael outcomes report --run <id> --outcome <outcome>service account key with outcomes:writeReport how a run ended
skael outcomes show <skill>any key with skills:readShow the outcomes of the runs that loaded each version

outcomes report takes these flags:

FlagDefaultDescription
--run <id>requiredYour id for the run
--outcome <outcome>requiredsucceeded, failed or cancelled
--repairs <n>0How many repairs the run needed
--verdict <text>noneThe verdict of the review of the run
--evidence <url>noneAn http or https link to the evidence
--set <name>noneThe set the run used
--resolution <id>noneThe resolution the run used

A second report for one run replaces the first, including any field you omit. The audit log keeps the old value.

outcomes show gives rates only when a version has at least 20 runs. It states a difference between versions and no cause.

An outcome never changes the headline and never releases a version.

Sends a skill for human review and reads the decision. No command publishes or decides a submission. A person decides in the web UI. An approved submission then goes through the normal publish gate.

CommandWhoDescription
skael submissions submit <dir> --name <name> --rationale <text>key with submissions:writePack the directory and send it. --run-link <url> and --run-id <id> link the run that produced it
skael submissions lista person’s keyList submissions. --state takes pending, approved or rejected
skael submissions get <id>a person’s key, or the consumer that sent itShow the state and the reason

A directory with no SKILL.md exits 2. An exfiltration or secret finding stores nothing and exits 1. With --json, the envelope has the code submission_blocked and the decision.

Validates, security-scans, packs, and uploads a skill directory.

evals/ in the directory is the skill’s eval suite. The server stores it as the suite and leaves it out of the version, so installers never receive it. The local scan skips it. Only an owner of the skill or an admin can change the suite: for anyone else, the publish stores the version and prints why it skipped the suite. A publish has one of three outcomes:

  • created: a new version exists.
  • unchanged: the skill and its suite are the same as before.
  • suite updated: only evals/ changed. The server stores the suite and queues an eval of the latest version, and creates no version.

An eval queued by a publish runs at the deepest tier the stored suite reaches. A suite below the smoke tier queues no eval, and the publish prints why, for example suite below smoke tier: 3 scorable evals, needs 5.

With --json, the output adds outcome, suite (ref, updated, skipped) and job_id.

A bundle with blocking findings meets one of two different fates, and the difference matters:

  • Refused. Credential-theft and data-exfiltration findings — the secret and exfiltration classes at critical or high severity — are unappealable. The server returns 422, no version row is created at all, and nothing clears them: no evaluation, no approval, no --override. Fix the bundle.
  • Held. Every other blocking finding (execution, injection, heuristic) holds the version for review instead. The version is created — it has a number and an archive — but it is not served to any client until it clears. A verified evaluation or a human approval releases it. See publish gate.

Findings below high are advisory: they are reported and the version publishes normally.

The local pre-scan runs the same decision function the server does, so it aborts before upload only on a refusal. Anything the server would merely hold is uploaded, held, and reported back as held with the exact findings and what would clear each one.

A publish can also be held because you are not a skill owner of the name you are publishing to. That is a separate hold from a scan finding — clearing one does not clear the other, and a version held for both stays held until both are cleared.

FlagDefaultDescription
--skip-local-scanfalseSkip the local security scan and let the server decide (the server still scans independently)
--overridefalsePublish despite findings that would otherwise hold the version — instance admin required; recorded server-side
--forcefalseDeprecated alias for --skip-local-scan

--override clears a scan hold and nothing else. It does not clear an ownership hold: publish to a name you don’t own with --override and the version is still held, now on ownership alone. It also does not get an unappealable finding past the server — that is still a 422.

Runs the security scan locally without publishing.

Exit codes:

CodeMeaning
0No findings
1Findings detected (warn or critical)
2Scan could not run (missing SKILL.md, I/O error)

Scans a published version again on the server and prints the report. The server uses the same steps as a publish: the built-in rules, the external scanner when one is set, and relative paths in the report. Without @version, the command rescans the newest version, held or released. Only an owner of the skill or an instance admin can rescan.

The server stores the new report. The result depends on the version:

  • A released version with a new exfiltration or secret finding becomes withdrawn. The server stops serving it, and skael sync removes it from each machine. Only a new version releases the skill again.
  • A released version with any other new finding stays released. The findings show as new since release.
  • A held version has its scan hold reason decided again. An ownership hold reason stays.

skael scan <dir> stays the local scan before a publish.

Exit codes:

CodeMeaning
0The version has no blocking finding
1The version has a blocking finding, or the request failed
2Usage error

Validates the suite in <dir>/evals/ locally and names the deepest tier it reaches. It needs no server.

It loads evals/evals.json and evals/triggers.json, validates every eval and every check, and plans each tier. It prints each void eval with its reason, ✓ or ✗ for each tier with the reason, and tier: <name>.

TierEvals that can be scoredShould triggerShould not trigger
smoke500
full1033
deep1688
FlagDefaultDescription
--tier <tier>—Exit 1 unless the suite reaches this tier: smoke, full or deep

Exit codes:

CodeMeaning
0Every eval can be scored, and the suite reaches at least --tier
1A file does not load, an eval is void, the suite reaches no tier, or it is below --tier
2Usage error, such as an unknown tier

With --json, it prints evals, checks, void, should_trigger, should_not_trigger, tiers and reached.

Queues an eval of a published skill on the server. Without @version, it evaluates the latest released version. A worker runs the eval against the skill’s stored suite. With no stored suite, the worker derives one from the skill’s SKILL.md. It needs an owner or admin key.

FlagDefaultDescription
--tier <tier>the deepest the suite reachesTier to run: smoke, full or deep. A tier the suite cannot reach is refused with the reason. A skill with no stored suite runs full.
--waitfalsePrint each job event until the job ends, then the headline and the lift
--set <name>—Install every skill of the set beside the skill. See Eval with a set.
--resolution <id>the set’s current resolutionPin a stored resolution of --set, so a re-run installs the same versions
Terminal window
skael eval run review:all --set review-split --wait

With --set, the command prints the resolution the job pinned. With --wait, it also prints the share of prompts each member took and each rule the skill keeps alone and loses with the set.

Without --wait, it prints the job id and exits 0. With --wait, it exits 0 when the job finishes and 1 when the job fails or is cancelled, with the job’s last error. With --json and --wait, it prints the job id and the version’s quality record.

Full-text search across the registry (with fuzzy matching on names).

Lists all skills on the platform. Use --installed to show only locally installed skills with their scope and version.

Details for one skill: name and latest version, author, license, spec compliance, description, tags, when it was last published, and 30-day activation counts with a per-agent breakdown.

FlagDefaultDescription
--versionsfalseList every version, newest first, with its age and changelog

--json always includes the full version list, whether or not --versions was given.

Diagnostic health check: config, connectivity, agent detection, hook status. It exits 2 when the config check fails, and 1 when another check fails. A warning does not change the exit code.

Standalone management of activation-tracking and auto-sync hooks.

  • install — register the hooks with every detected agent (activation tracking + auto-sync)
  • uninstall — remove the hooks from every detected agent
  • status — show which agents have current hooks. A hook that names an old script or another skael binary shows as out of date.

Each hook runs the skael binary itself, so the same hooks work on macOS, Linux and Windows with no bash, jq or curl:

  • skael hook report --agent <name> reads the agent’s hook payload on stdin and reports a skill load. It returns at once and posts the event from a background process.
  • skael hook autosync starts skael sync --quiet in the background when the last sync is 30 minutes old.

Agents call these commands. You do not run them. Both print nothing and exit 0 on every error, so a hook never blocks or breaks an agent session.

The hook names the skael on your PATH when that is the running binary, so a Homebrew or Scoop upgrade keeps the path. Every skael command checks the hooks you installed and rewrites one that names an old script or a moved binary.

AgentActivation trackingAuto-sync
Claude Code~/.claude/settings.json, on each Skill tool callon each prompt
Codex~/.codex/config.toml, a PreToolUse hookbefore a tool call
Cursor~/.cursor/hooks.json, on each read of a SKILL.md in .agents, .cursor, .claude or .codex /skills/<name>/on session start
OpenCode~/.config/opencode/plugins/skael-tracking.ts, on each skill tool callskael-autosync.ts, on each new session
pi~/.pi/agent/extensions/skael-tracking.ts, on each read of a SKILL.md in .agents, .pi or .pi/agent /skills/<name>/, and each /skill:nameskael-autosync.ts, on session start

Auto-sync runs skael sync --quiet in the background, at most once in 30 minutes. uninstall removes only the files and entries that Skael wrote.

Imports skills into the registry from a GitHub repository, a subpath within one (e.g. .../tree/main/skills/docx), or a local directory. Each imported skill goes through the same scan and the same publish gate as skael publish — an imported skill can be rejected or held for review exactly like a published one.

FlagDefaultDescription
--allfalseImport everything discovered without prompting
--dry-runfalsePreview what would be imported, without importing

Setting GITHUB_TOKEN on the server raises GitHub’s API rate limit for repository imports.

Approves or rejects a version the publish gate is holding for review.

FlagDefaultDescription
--approvefalseApprove the targeted reason
--rejectfalseReject the version
--reason <text>—Required. Written justification, recorded on the version
--reason-kind scan|ownershipinferredWhich held reason this decision targets

Exactly one of --approve/--reject is required, and --reason is always required. Both are checked locally before any request is made.

--reason and --reason-kind are different things. --reason is the written justification a human types and the server records. --reason-kind is which of the version’s holds the decision is about. They are separate flags on purpose: every already-deployed skael review --approve --reason "..." keeps working exactly as it did.

--reason-kind is required when more than one reason is outstanding, and inferred when exactly one is. Naming a reason the version is not actually held for is rejected, as is any value other than scan or ownership.

Who may clear which reason:

Reason kindWho can clear it
scanAn instance admin, and only an instance admin
ownershipA skill owner of that name, or an instance admin

A scan finding is an instance-level decision. If a self-managed namespace could clear one, the security gate would only ever be as strong as the least careful namespace on the instance.

Three things can come back:

  • Rejected. --reject is terminal for the whole version, whichever reason it named — there is no partial reject and no way back. The command confirms the rejection and stops.
  • Approved and released. The reason cleared was the last one outstanding. The command confirms the version is now served to clients.
  • Approved, still held. One reason cleared but another is still outstanding — only possible when you passed --reason-kind explicitly. The command prints a warning naming the reason that cleared and stating the version is still held, then one Outstanding line per remaining reason with who can clear it. It will not say “released”, because that would be a lie about a version nobody can download.

Shows what a held version actually changed, before you decide on it.

Takes one or two arguments. With a version, it targets that exact held version. Without one, it picks the highest-numbered held version of that skill, and errors if no version of it is held.

It prints, in order:

  • a unified diff of SKILL.md against the version currently being served, or SKILL.md unchanged
  • a status list of every other file that differs — added, removed, or modified
  • an Outstanding: block naming each unresolved reason and who clears it, omitted when nothing is outstanding

--json emits:

{
"diff": {
"against": 3,
"skill_md": "<unified diff>",
"files": [{ "path": "scripts/setup.sh", "status": "added" }]
},
"hold_reasons": ["scan", "ownership"],
"outstanding": ["ownership"]
}

against is the served version the diff was computed against; 0 means there is no baseline yet because this is the skill’s first version. hold_reasons is every reason the version was ever held for; outstanding is the subset with no decision recorded yet. The two differ once one reason clears and the version stays held on another.

skael contest [<skill>[@version] …] [--set <name> …]

Section titled “skael contest [<skill>[@version] …] [--set <name> …]”

Runs two or more candidates against one eval suite, in one job, on one panel, at the same time, and prints which won each task. A candidate is a skill version or a set.

FlagDefaultDescription
--suite <ref>—A stored eval suite; omitted, one is derived from every candidate
--tier <tier>fullEval tier
--attempts <n>3Attempts per task per candidate
--waittrueWait for the verdict
--set <name>—Enter a set as one candidate. Repeat the flag for more sets.
Terminal window
skael contest payments:deploy@3 platform:deploy@7
skael contest review:all@3 --set review-split

A version left off means the skill’s released version. The candidates need not be the same skill. A set candidate installs every skill of the set’s current resolution. The command prints the median tokens per run of each candidate. When a set competes, it also prints the skills that fired on each task.

The verdict is one of three things: a named winner, too close to call, or a statement that too few tasks separated the candidates for any verdict to be possible. Each comes with the split — 6-0 with 6 ties, p = 0.031 — so a reader who distrusts a single number reads the task table instead.

Two things surprise people. A 7–2 split is not a winner: an exact sign test puts it at p = 0.18, and at twelve tasks you need 8–1. And below six decided tasks no verdict exists at all, because even a clean sweep of five is inside what a coin does — when that happens the problem is the suite, and the command says so.

A contest is advisory. It releases nothing, holds nothing, and clears no hold. See Quality scoring.

Manages who reviews changes to a skill name. Ownership decides who can clear an ownership hold on a publish — it never gates reads and never re-gates an already-released version. See ownership for how a name resolves to a rule.

A pattern is one of exactly three shapes. No mid-string globs, no character classes.

PatternMatches
payments:invoicesthat one exact skill name
payments:*every name under the payments: namespace
*every skill name on the instance
CommandWhat it does
owners listEvery rule and its members
owners show <skill-name>Resolves that name, printing the rule that matched and its members — or that the name is unowned when none matches
owners set <pattern> <email>...Replaces the rule’s member list wholesale with exactly the emails given, creating the rule if there isn’t one
owners add <pattern> <email>...Adds members, keeping the existing ones
owners rm <pattern> <email>...Removes members, keeping the rest
owners delete <pattern>Deletes the rule entirely

add and rm are not separate endpoints. Both read the current rule, compute the new member list on the client, and write it back through the same upsert set uses — so two people editing one rule at the same moment is last-write-wins.

Emails are resolved to user IDs before anything is written. Each address is looked up through the user-search API and must match a real account exactly (case-insensitively, on the whole address). One address that doesn’t match aborts the entire command — including the addresses that would have resolved fine — and prints the near matches the search returned. Nothing is written. A rule that looks like it has an owner but doesn’t is worse than a command that refuses to run.

owners rm down to zero members is refused server-side with a 422: a rule with no members claims a namespace nobody can review. Use owners delete to remove the rule instead.

A pattern you are not allowed to manage returns 403. You may manage one if you are an instance admin, a member of that rule, or a member of a strictly-containing rule — so a payments:* namespace owner can create payments:invoices, but never the reverse. Delegation only ever narrows.

owners add on a pattern with no rule yet creates it. owners rm and owners delete on a pattern with no rule report that no rule was found and make no write.

Prints the version, git commit, and build date injected at build time.

A binary built with go install or go run has none of those injected and reports dev for the version (with none for the commit and unknown for the date). Only release builds print real values.

At most once a day, a command reads the server’s version from /api/capabilities and compares it with the CLI’s. When they differ, it prints one line to stderr after the command’s own output:

  • An older CLI says so and shows how to update it. It keeps working; only newer features need the update.
  • A newer CLI says the server needs upgrading for its newer features.

The notice never changes an exit code or stdout. It stays silent with --json or --quiet, on a dev build, and when the server does not answer within 2 seconds. It asks your own server only, never an outside service. skael doctor always shows both versions.

To update the CLI, run the install script again (curl -fsSL https://skael.dev/install | sh, or irm https://skael.dev/install.ps1 | iex on Windows), brew upgrade --cask skael-dev/skael/skael, or scoop update skael, then skael init --force in each repo to refresh the skael and skael-evals skills.

Every installed skill lives at one of two scopes:

  • user — installed under your home directory. Follows you across every project.
  • project — installed inside the repo, under version control alongside your code. Follows the repo — everyone who checks it out gets it too.

Each skill installs into a folder named its canonical name. Windows does not allow : in a file name, so on Windows a prefixed skill such as payments:refunds installs into payments_refunds. The agent still sees the name in the skill’s frontmatter, and activations still report payments:refunds. A repo that commits a payments:refunds folder from macOS or Linux does not check out on Windows. Commit project-scope skills from Windows, or have each developer run skael sync.

The default is project. Scope is resolved with this precedence: a command’s --scope flag, then the scope value saved in ~/.skael/config.json, then the default.

  • skael setup --scope user sets the default saved to your config.
  • skael add <name> --scope user overrides the scope for just that one skill, and that choice is remembered for it.
  • skael sync --scope ... overrides scope for that run only — but if a skill already has its own recorded scope, that wins over the sync flag.

The project root is the nearest ancestor directory containing a .git folder, walking up from your current directory. If none is found, it falls back to the current directory.

Skael writes to two folders at each scope:

Folderuser scopeproject scopeRead by
Shared~/.agents/skills/<name><project>/.agents/skills/<name>Codex, Cursor, OpenCode, pi
Claude Code, when detected~/.claude/skills/<name><project>/.claude/skills/<name>Claude Code

Claude Code reads only .claude/skills, so Skael writes a second copy there when it detects Claude Code. A skill that an older version placed in .cursor/skills, .opencode/skills or .codex/skills moves on the next skael sync.