skael
Use the skael CLI to find, install, pull and publish agent skills from a Skael registry, and to read its exit codes. Use when a task mentions skael, a skill set, a skill registry, or when you need a skill this repo does not have.
- License 许可
- Apache-2.0
- 所属仓库
- skael-dev/skael
- 最近更新
- 2026-11-13
- Stars
- ★ 20
- Forks
- 2
01 前言 Front Matter
- name
- skael
- description
- Use the skael CLI to find, install, pull and publish agent skills from a Skael registry, and to read its exit codes. Use when a task mentions skael, a skill set, a skill registry, or when you need a skill this repo does not have.
03 SKILL.md 正文
skael
skael is the command line for a Skael registry. The registry holds versioned, security-scanned agent skills.
Before you start
Run skael doctor. It reports the config, the server and each agent. skael version prints the CLI version.
The full command reference is at https://skael.dev/docs/cli. Read it for a flag this skill does not list, rather than guessing.
The CLI reads SKAEL_URL and SKAEL_KEY. If either is absent, it reads ~/.skael/config.json, which skael setup <url> <api-key> writes. Never print a key. Never write a key into a file in the repo.
Exit codes
Branch on the exit code. Do not parse error text.
| Code | Meaning | What to do |
|---|---|---|
| 0 | Success | Continue. |
| 1 | API, network or local write error. skael scan also uses 1 for findings. |
Read the error. Retry only if the cause is the network. |
| 2 | Usage or config error | Fix the command or the config. A retry gives the same result. |
| 10 | Incomplete set | skael pull wrote nothing. Report the excluded entries. Do not remove them from the set by yourself. |
| 11 | Digest mismatch | skael pull wrote nothing. Stop and tell a person. This can mean tampering. Do not retry in a loop. |
JSON output
Add --json to any command when you parse the output. A read of the API prints the API's own shape. A failure prints this to stdout, and the exit code is non-zero:
{"error": "what failed", "code": "machine_code", "suggestion": "what to try"}
Find a skill
skael search "<words>"
skael list
skael show <skill> --versions
Follow skills on this machine
skael add follows a skill, a pattern or a set, and installs what it resolves to. skael sync and the auto-sync hook keep everything followed current, so a new skill released under a followed pattern, or added to a followed set, arrives with no command.
skael add <skill>
skael add 'payments:*' # every released skill under payments:
skael add --set <name>
skael sync
skael remove <skill> # or 'payments:*', or --set <name>
Quote a pattern so the shell does not expand it. Skills go to .agents/skills, and also to .claude/skills when Claude Code is detected. --scope user writes under your home folder instead of the repo.
remove stops following a source. A skill another followed source still wants stays.
When two followed sources want different versions of one skill, add exits 2 and names both. Remove one of them; do not pin around it.
Write a set once
A set is a named list of skills. An entry is a skill at its latest version, a skill at one exact version, a pattern such as payments:*, * for every released skill, or an exclusion such as !payments:legacy. Use pull when a repo, a CI run or a machine needs a known group of skills written once.
skael sets list
skael sets get <name>
skael sets resolve <name>
skael pull --set <name> --dir . --no-hooks
pull writes each skill to <dir>/.agents/skills/<skill>/, and to <dir>/.claude/skills/ when Claude Code is detected, with manifest.json beside them. The manifest records the exact versions and digests. It writes every skill or none. pull records nothing: sync never follows it. To follow a set, use skael add --set.
To undo a pull, delete the skill folders it wrote; manifest.json lists them. The next pull of the set also removes skills that left it.
Use --no-hooks on a machine or in CI. It writes files only and changes no agent config. Omit it on a developer machine to install activation tracking too.
sets resolve exits 0 on an incomplete set. Read complete in its output. pull exits 10.
Publish a skill
skael init <name>
skael scan <dir>
skael publish <dir>
Write the description in SKILL.md before you publish. Run scan first: code 0 is clean, 1 means findings, and 2 means the scan did not run.
publish has three results:
- Published: the version is live.
- Held: the version exists but is not served. The command exits 0 and names who can clear it. Do not retry. A person runs
skael review. - Blocked: no version exists, and the command exits 1. Remove the finding. No override clears a credential or exfiltration finding.
Never use --override or --skip-local-scan unless a person asks you to.
Report a run
These commands need a service account key. The consumer comes from the account.
skael events report --file events.jsonl --idempotency-key <key>
skael outcomes report --run <id> --outcome succeeded --repairs 1 --evidence <url>
skael outcomes show <skill>
Use one idempotency key for each batch, and reuse it on a retry. A batch is all or nothing. On a rejected event, the command exits 1 and names the failing index. Fix that event and resend the whole batch.
--outcome is succeeded, failed or cancelled. A second report for one run replaces the first. An outcome never changes the headline and never releases a version.
Submit a skill for review
Use this when you have a new skill or a change and no person asked you to publish.
skael submissions submit <dir> --name <skill> --rationale "..." --run-link <url> --run-id <id>
skael submissions get <id>
A submission publishes nothing. A person decides it in the web UI. No command decides a submission, so do not look for one. Read state and reason with get. A rejection states its reason: fix that and submit again. An exfiltration or secret finding stores nothing and exits 1.
Manage sets and machine identities
These commands need an owner or admin key.
skael sets create <name> <skill> <skill>@3 'payments:*' '!payments:legacy' --description "..."
skael sets update <name> <skill>@4
skael sets delete <name>
skael service-accounts create <name>
skael service-accounts keys create <account> --scope sets:read --set <set>
skael service-accounts keys revoke <account> <key-id>
The scopes are skills:read, sets:read, eval:work, events:write, outcomes:write and submissions:write. The server shows a new key once. Give it to the person who asked for it, and do not store it.
Other commands
These exist. Read https://skael.dev/docs/cli before you use one.
skael import <url|path>imports skills from a GitHub repo or a local folder.skael contest <skill>@<v> <skill>@<v>runs candidates against one suite and names a winner or "too close to call".skael owners show|set|add|rmreads and changes who reviews a skill name or namespace.skael review <skill> <version>shows or decides a held version. Decide one only when a person asks you to.skael hook install|status|uninstallmanages activation tracking in each agent.skael webhooksmanages webhook endpoints. It needs an owner or admin key.
Keep this skill current
skael init writes this file to .agents/skills/skael/SKILL.md, and to .claude/skills/skael/SKILL.md when Claude Code is detected. It never overwrites a changed copy unless you pass --force.
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 run skael init --force to refresh this file to the version that ships with the new CLI.
04 同仓库更多 Skills
e2e-test-skill
A clean skill for end-to-end testing
bad-skill
A dangerous skill
skill-creator
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
hardcoded-secret
A bundle that leaks a real credential. This must never publish.
document-formatter
Use when the user asks to format a document against the house style guide.
deterministic-transform
Use when the user asks to transform a JSON data file deterministically.