Better Agent Skills

Reference

CLI reference

bas is the command agents run to record each use of a skill, with any problems they met. BAS can install it into ~/.local/bin. Where bas is not on the path, run ~/.bas/bin/bas with the same arguments: the app keeps that link to the copy it ships with each time it starts.

  • Every command prints one JSON object on one line to standard output.
  • A failure prints {"error":{"code":"…","message":"…"}} to standard error instead, and nothing to standard output.
  • record-usage sends each record straight to BAS, signed in with the session the app and the CLI share. It needs no running app.
  • There are no colours, prompts or spinners.

bas record-usage

Records one use of a skill: installed, one of your skills, or from GitHub. One record holds the use, the problems met, a line for the skill's owner, a summary and the structured result the skill asks for. The input is one JSON object, passed with --json or on standard input.

Usage
bas record-usage [--json <object>]
Example
bas record-usage --json '{"skill":"deploy-checklist","model":"claude-opus-5-5-low","summary":"Deployed the billing service to staging.","issues":[{"category":"outdated-command","severity":"medium","summary":"Step 3 uses deploy --prod, which was renamed to deploy --production"}]}'
Output
{"usageLogId":"8b0e…","target":{"kind":"version","skillId":"3f2a…","version":3},"success":true}
  • The CLI removes secrets, such as API keys, tokens, private keys and passwords in URLs, from every text field and the output before anything is saved or sent.
  • success is true when BAS took the record. It is false when the record waits in a queue in ~/.bas (for example offline, or nobody signed in), which the next successful call sends, and when nothing is sent or kept at all: for a skill of yours that was never published, a GitHub skill whose sharing with maintainers is off, or while usage sharing is off in the app.
  • To add to a record later, such as a problem found afterwards, send it again with its usageLogId. That updates the record and never counts a second use.

Exits 0 once the record is sent or queued, or when it is not to be sent; 1 for an unknown skill, an unknown usageLogId, a record BAS refused, or a file error; and 2 for input that does not match the schema.

Record fields

bas record-usage --help prints the same schema as JSON Schema.

skillrequired
The skill's folder name in the agent's skills folder. bas list prints the names.
modelrequired
The model that used the skill, e.g. claude-opus-5-5-low. At most 100 characters.
issues
Problems met while using the skill. At most 10, each an object with the issue fields below.
message
One line for the skill's owner. At most 200 characters.
summary
What the skill was used for and how it went. At most 4000 characters. No transcripts or file contents.
output
The structured result the skill's SKILL.md asks for. Any JSON object, at most 16 KiB as UTF-8 JSON.
usageLogId
Updates that earlier record instead of recording a new use. The usageLogId an earlier call printed. Fields you pass replace the record's, fields you leave out stay, and the use is not counted again.

Issue fields

Each entry of issues is one problem met while using the skill.

categoryrequired
What kind of problem it was.
  • wrong-instruction: the skill tells the agent to do the wrong thing.
  • missing-step: a step the task needs is not in the skill.
  • outdated-command: a command or script the skill names no longer works.
  • ambiguous: the agent could read an instruction more than one way.
  • conflicts-with-repo: the skill contradicts the repository it was used in.
  • other: anything else.
severityrequired
How much it got in the way. One of low, medium, high.
summaryrequired
One line naming the problem. At most 200 characters.
details
What happened, and where in the skill. At most 4000 characters. No transcripts or file contents.
suggestedFix
How the skill could be changed to avoid it. At most 4000 characters.

bas list

Lists every skill the CLI can record uses for, one entry per skill and agent: its name, kind (installed, mine or github), agent, the target a use would count against, and the install mode (auto, pinned or null). It reads only files on your Mac.

Usage
bas list
Output
{"skills":[{"name":"pdf-tools","kind":"installed","agent":"claude-code","target":{…},"mode":"auto"}]}

Exits 0, or 1 when an agent skills folder cannot be read.

bas whoami

Shows who is signed in, from the session the app and the CLI share. You sign in and out in the app; the CLI never opens it.

Usage
bas whoami
Output
{"user":{"id":"user_01…","email":"ada@example.com","name":"Ada Lovelace"}}

Prints {"signedOut":true} when nobody is signed in. Exits 0, or 1 when the session file cannot be read.

Help and version

bas --help lists the commands, bas <command> --help prints a command's input and output as JSON Schema, and bas --version prints {"version":"…"}. All three print JSON and exit 0.

Targets

A target says what a use counts against. The CLI works it out from the skill's link in the agent skills folder, so an agent never passes a version.

version
An installed version, or your published skill when its folder matches the latest version.
draft
Your published skill after you changed it; counted apart from every version.
github
The commit a GitHub skill was copied at.
local
Your skill that was never published; its records never leave your Mac.

Errors and exit codes

0
Success.
1
A command error: UNKNOWN_SKILL (no linked skill has that name), UNKNOWN_USAGE_LOG (BAS had no record with that usageLogId; the use is now recorded under it), INVALID_FILE, IO_ERROR or INTERNAL, which includes a record BAS refused, such as one for a skill you can no longer see. UNKNOWN_SKILL also lists, in skills, the names the CLI can record.
2
Bad usage: BAD_USAGE (input that does not match the schema, with the field in path, such as issues.0.summary) or UNKNOWN_COMMAND.

Environment

BAS_HOME
The BAS home folder, ~/.bas by default.
BAS_CLAUDE_SKILLS_DIR
The Claude Code skills folder, ~/.claude/skills by default.
BAS_CODEX_SKILLS_DIR
The Codex skills folder, ~/.codex/skills by default.
BAS_TOKEN
An access token used instead of the signed-in session, for CI, servers and sandboxes without the app.