Skills

Skills are task-specific instruction packages and scripts. They let AgentOS load relevant guidance only when a task needs it, instead of putting every possible instruction into every prompt.

Skills are separate from memory. Memory stores facts; skills describe repeatable ways to work.

What Skills Are For#

Use skills for repeatable work patterns such as:

• deep research;
• summarization;
• GitHub and PR workflows;
• document generation;
• spreadsheet, slide, PDF, and DOCX work;
• web search;
• weather lookup;
• terminal or tmux monitoring;
• subagent delegation;
• skill creation and review.

Discover Installed Skills#

List skills available in the current install:

agentos skills list

View one skill:

agentos skills view <skill-name>

Search community sources:

agentos skills search pdf

Some skills may be ineligible when optional dependencies are missing or when the skill is intentionally demo-only. skills list is the source of truth for your current install.

Where Search Results Come From#

skills search fans out to every configured source and merges the results. The Bankr source covers both places Bankr publishes: skills in the BankrBot/skills repository, and skills published from bankr.bot, which live under their author's wallet address (https://bankr.bot/skills/<wallet>/<slug>) and are served with their body inline rather than as a repository directory. Both install the same way:

agentos skills install https://bankr.bot/skills/<wallet>/<slug> --source bankr

Each half carries a fixed allowlist, because neither has an index that can be crawled without tripping a rate limit — and because the source a skill arrives through is recorded as its provenance, so it must not be able to pull an arbitrary repository or another author's skill under Bankr's name. A skill published from a wallet is credited to its author, not to Bankr: it lists the author's handle and resolves to no recognized publisher, so it renders unbranded rather than sitting in the Partners group.

The Aeon source reads aeonfun/aeon, which unlike the others publishes a real machine-readable index — one catalog/skills.json describing all 75 of its skills, so browsing costs a single request rather than one per skill. Its allowlist therefore exists for a different reason: not because the catalog cannot be crawled, but because most of what Aeon publishes does not belong in an interactive runtime. Aeon skills are prompts written for scheduled GitHub Actions runs, and dozens of them either operate an Aeon instance (aeon-doctor, memory-flush, aeon-update) or read Aeon's durable memory/ directory as their actual input.

The allowlisted ones are adapted on install. Their frontmatter declares requires as a plain list, which AgentOS reads only as a mapping and would otherwise discard — so it is rewritten into the requires.env form, and the Aeon category is remapped onto a real browse bucket. A short note is inserted ahead of the skill's own text saying that memory/, ./secretcurl, and ./notify are absent here and what to do instead. The prose itself is left alone, so the installed file still reads as Aeon wrote it.

Some Aeon skills want an API key you supply yourself, and a few want a paid plan; each catalog card lists what it needs under its setup steps.

How a Skill Is Described#

Four separate facts describe an installed skill. They are easy to confuse, and using one to answer another is the usual cause of a confusing Skills screen.

Acquisition is what the Web UI groups by, and what agentos skills list --json reports under acquisition. A shipped skill came with AgentOS. A hub skill was fetched by agentos skills install and has a lockfile entry recording its source, identifier, version, and install time. A local skill is a directory you put in a skills folder yourself.

The same block carries removable and updatable. These are answers, not guesses from the layer: if a hub-installed skill's recorded path no longer matches the configured skills.managed_dir, removable is false — AgentOS will not delete files it cannot prove it owns — while updatable stays true, because an update re-fetches by identifier into the current managed directory.

Publisher is allowlisted inside AgentOS. A skill manifest can only select a recognized publisher by id; it can never describe one. A third-party skill that writes a partner's name, URL, and logo into its own frontmatter renders as an ordinary unbranded skill, because none of those fields are read.

Selecting an id is also restricted by where the skill lives. Only a bundled manifest — one that ships inside the release — may name its own publisher; a directory you (or anything else) drop into a writable skills path gets no brand from its own frontmatter, so a look-alike cannot sit in the Partners group. An installed partner skill is branded by the hub catalog row that installed it, recorded in the lockfile, not by its own text. This is why a partner's skills sit under one heading whether they shipped with AgentOS or you installed them from that partner's hub.

Layer is only about file location and name-collision precedence (later overrides earlier): extra (config dirs) → bundled (shipped) → managed (~/.agentos/skills, where installs land) → personal (~/.agents/skills) → project (<workspace>/.agents/skills) → workspace (<workspace>/skills). It is shown as a detail on each card and it decides which skills are sacrificed first if the prompt budget is exceeded, but it does not tell you where a skill came from.

The two .agents/skills layers are shared with other agents on the machine — Codex, Cursor, and anything else following that convention install there too. AgentOS treats them as ordinary layers: a skill another tool writes appears on the next turn, and one it removes stops being offered, without a restart and without going through agentos skills. The directories are also honoured when they do not exist yet, so the first cross-agent install on a fresh machine does not need one either. Note the precedence that follows from the order above: a skill in .agents/skills overrides a bundled or hub-installed skill of the same name.

Provenance (origin, license, upstream_url) is separate from all four: it records where the text came from and under what licence. A skill can be AgentOS-original text published by a partner, or upstream text with no publisher at all.

Category (metadata.agentos.category) is subject matter, not trust — what a skill is about, where capabilities says what it can reach. The Web UI reads one value from it: a shipped skill declaring category: crypto is split out of "AgentOS Normal Skills" into its own AgentOS Crypto Skills heading. The split is gated on acquisition exactly the way publishers are, so a directory dropped into a writable skills path cannot claim a heading carrying the AgentOS name just by writing a category into its own frontmatter.

Cards in that group carry a mark instead of the generic glyph. The nine bundled GMGN skills (gmgn-token, gmgn-market, gmgn-portfolio, gmgn-track, gmgn-holder-analysis, gmgn-wallet-analysis, gmgn-wallet-score, gmgn-swap, gmgn-cooking) wear the GMGN mark — chosen on provenance.origin: gmgn-mit, badged with each skill's own metadata.agentos.emoji so nine siblings stay tellable apart — and the rest of the group wears the AgentOS mark. Every mark ships with the client; no manifest field points the UI at an image, remote or local.

Declaring the Variables a Skill Reads#

metadata.agentos.requires.env (or metadata.platform.requires.env) lists the environment variables a skill's scripts read. Each entry carries a description and a url so the Environment page and agentos env list can say what the variable is for and where to obtain it, and secret when the name-based heuristic would guess wrong. required defaults to true; set it to false for a variable that unlocks part of the skill rather than gating all of it -- the multi-search-engine skill declares every engine key that way, so it stays offered on DuckDuckGo alone and grows engines as keys appear. A required variable that is missing hides the skill and is reported by agentos skills doctor; an optional one only shows as unset on the Environment page.

Declared variables are also the ones forwarded into the execute_code sandbox when the skill is viewed, which is how a script running there can read its own key. AgentOS's own provider credentials are refused to hub and local skills; a bundled skill may declare them.

How a Skill Reaches Its Own Scripts#

A SKILL.md is written before anyone knows where it will be installed or which Python will be running, so it names both through placeholders that the tool layer fills in when the body is handed to the agent (skill_view):

So a script invocation in a skill body is written as:

{python} {baseDir}/scripts/run.py --flag value

and an entrypoint.command in frontmatter as "{python} {baseDir}/scripts/run.py" (quoted — YAML would otherwise read the leading { as a mapping). agentos skills init --with-script scaffolds it that way. The expanded text also leads with [Skill directory: …] and [Skill interpreter: …] lines, so a third-party skill that still says python3 script.py can be steered onto the right interpreter too.

Expansion happens only on the copy the agent reads. The file on disk keeps the placeholders, which is what lets skill_edit write it back without baking a machine-specific path into it, and what lets the same skill directory move between machines.

Whether the Agent Is Offered a Skill#

Installed, eligible, and offered are three different states. A skill can be installed and fully eligible and still not reach the agent on a given turn.

The gateway reports this as availability on every skill row, and the agent's own skill listing prints a [not offered] line with the same explanation:

Every reason above appears in a skills.list row except not_retrieved. Retrieval ranks skills against the wording of one message, so there is no query to answer it with outside a turn — it reaches the decision log, never the Skills page. The other six, prompt_budget included, are answerable from the installed set plus the configured budget, so the page can show them before you send anything.

agentos skills list --json does not carry availability. A CLI process has no chat session and no tool surface, so it cannot answer honestly; an absent key means "not computed", never "not offered".

Install, Update, and Remove Skills#

Install a managed skill:

agentos skills install <skill-name>

Update one skill or all managed skills:

agentos skills update <skill-name>
agentos skills update --all

Remove a managed skill:

agentos skills uninstall <skill-name>

Install Security#

A hub skill is someone else's instructions and scripts, so an install passes three checks before anything reaches the managed layer. The bundle is staged in ~/.agentos/quarantine while they run and deleted if any of them refuses.

Registry verdict. ClawHub scans what it hosts with ClawScan and publishes the result. AgentOS reads it on install, refuses on suspicious or malicious, and records it in the lockfile as registry_verdict. Search results carry it too, along with upstream_scanners — third-party scanner statuses the registry relays (Snyk, Socket and others). Those are shown but never refused on: they are another party's opinion of another party's copy. Other sources publish no verdict, so the field is empty for them.

Install policy. For a real review, point AgentOS at a scanner of your own. It is off by default:

[skills.install_policy]
enabled = true
command = "/absolute/path/to/clawscan"
args = ["openclaw-install-policy"]
pass_env = ["PATH", "DOCKER_HOST"]
timeout_seconds = 300

The command is run once per install and per update, after the built-in scan and before the move. It reads one JSON request on stdin — the quarantined directory as sourcePath, the skill name, the source and the requested identifier — and writes one JSON response on stdout:

{"protocolVersion": 1, "decision": "block", "reason": "reads ~/.ssh/id_rsa"}

decision is allow, warn or block; reason and a findings list are optional. This is the OpenClaw security.installPolicy protocol, version 1, so clawscan openclaw-install-policy works unchanged and can front SkillSpector, Tencent AIG, Cisco's scanner or Snyk. Any executable that speaks the protocol will do.

The policy fails closed. A command that is missing, is not an absolute path, exits nonzero, times out, or prints anything other than a valid response blocks the install, and so does enabled = true with no command. The command inherits only the variables named in pass_env, not the gateway's environment, and it runs outside the tool sandbox as a trusted local process — point it at a binary you control.

The policy covers agentos skills install and agentos skills update, the Skills page, and the agent's skill_install_community tool. It does not cover skills you write yourself or copy into a skill directory by hand.

Manage Skill Sources#

Custom source repositories are called taps:

agentos skills tap list
agentos skills tap add <owner/repo>
agentos skills tap remove <owner/repo>

Use taps when your team maintains its own skill catalog.

What a Skill Can Put in the Chat#

Besides text, a skill hands files to the surface with publish_artifact. Most arrive in Web UI chat as a download chip, but some mimes render inline instead:

Nothing has to be registered for this: the mime a skill publishes decides how its output is drawn, so any skill can render a chart without a frontend change.

Artifacts and Media carries the payload shape, the workspace rule publish_artifact enforces, and the two mistakes that produce no error and no chart — omitting the mime, and writing the file outside the workspace.

Publish and Inspect#

Publish a skill directory:

agentos skills publish <path-to-skill>

For ordinary skill content, use:

agentos skills view <skill-name>

How to Ask for a Skill#

Ask for the outcome:

Create a PowerPoint deck summarizing this report.

Better than:

Load the pptx skill and run its script.

AgentOS can choose eligible skills from the current catalog when the task matches their description and triggers.

Bundled Skill Families#

Troubleshooting#

If a skill is not used, start by finding out whether the agent was ever offered it. Guessing from the layer or from "it says ready" is what makes this hard.

1. Confirm it appears in the installed catalog:

   Copy

   agentos skills list
   

2. Open the skill on the Skills screen, or ask the agent to list its skills. Either surface names the reason it is being withheld. Match it below.

3. "Needs setup" / ineligible. The reason names the missing binary or environment variable. Install the binary, or set the variable:

   Copy

   agentos env set <NAME> --stdin
   

   The value applies to the running gateway — no restart — and the skill becomes eligible on the next turn.

4. "Skills section is full" / prompt_budget. The skill is ready and was dropped only because the injected skills block hit its character budget. Raise it:

   Copy

   agentos config get skills.max_skills_prompt_chars     # default 24000
   agentos config set skills.max_skills_prompt_chars 32000
   agentos gateway restart
   

   The gateway also logs skills_filter.budget_truncated with the names it dropped and the budget it hit. Truncation goes lowest-precedence layer first — extra directories, then bundled — so the symptom is usually shipped skills quietly disappearing while what you installed into managed, personal, project, or workspace survives.

5. The agent ignores skills, but nothing reports prompt_budget. The block fits, so no skill was dropped — but the budget was tight enough that the descriptions were shortened, or replaced by names alone. A name is rarely enough for the model to tell that a skill applies, so the symptom is an agent that answers from general knowledge with every skill still listed as offered. Check the render mode:

   Copy

   grep skills_render_mode ~/.agentos/logs/decisions-*.jsonl | tail -1
   

   Anything other than full means the budget cost the model description text, and the gateway logged skills_filter.budget_degraded when it happened. Raise skills.max_skills_prompt_chars, or turn on skills.filter_enabled so only the skills relevant to each message are injected.

6. not_retrieved. Only reachable when skills.filter_enabled = true, which is off by default. Raise skills.filter_top_k or reword the request; the answer depends on the wording of that one message.

7. tool_gate or fallback_superseded. These are about the session's tools, not the skill. The first means a tool the skill needs is not enabled; the second means AgentOS already has a native tool that does the job better.

8. model_invocation_disabled. Working as declared. The skill opted out of model invocation and is for you to run, not the agent.

9. If none of the above applies, ask for the outcome in normal language. Skill names can help, but user intent should still be clear.