Better Agent Skills

CLI reference

bas is the command agents run to log each use of a skill and to report its problems. 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.
  • used and report need neither a network nor the app running, and finish in under 100 ms.
  • There are no colours, prompts or spinners.

bas used

bas used --skill <name>

Logs one use of a skill: installed, one of your skills, or from GitHub. It appends a line to ~/.bas/usage.jsonl, which the app turns into counts.

  • --skill <name> (required): the skill's folder name in the agent skills folder.
{"target":{"kind":"version","skillId":"3f2a…","version":3},"logged":true}

Exits 0 once logged, 1 for an unknown or not-managed skill or a file error, and 2 for bad usage.

bas report

bas report --skill <name> --category <category> --severity <low|medium|high> --summary <text> [--details <text>] [--suggested-fix <text>]

Files an issue report about a skill. Secrets are removed from the text, and the report is saved in ~/.bas/outbox/ for the app to send.

  • --skill <name> (required): the skill's folder name in the agent skills folder.
  • --category <category> (required): what kind of problem it is, one of:
    • 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.
  • --severity <low|medium|high> (required): how badly it gets in the way.
  • --summary <text> (required): one line describing the problem, at most 200 characters.
  • --details <text>: what happened, at most 4000 characters. No transcripts or file contents.
  • --suggested-fix <text>: how the skill should change, at most 4000 characters.
{"id":"6f1c…","target":{"kind":"version","skillId":"3f2a…","version":3},"queued":true,"localOnly":false}

localOnly is true for a skill of yours that was never published, or a GitHub skill whose sharing with maintainers is off: the report stays on your Mac. Exits 0 once the report is saved, 1 for an unknown or not-managed skill or a file error (nothing is saved), and 2 for bad usage, such as an unknown category or a summary that is too long.

bas list

bas list

Lists every skill the CLI can log for, one entry per skill and agent: its name, kind (installed, mine or github), agent, the target a use would count against (for a skill of yours, its published version or local, without checking for changes that would make a use a draft), and the install mode (auto, pinned or null).

{"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

bas whoami

Shows who is signed in to the app. It never opens the app.

{"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 lists a command's flags, and bas --version prints {"version":"…"}. All three print JSON and exit 0.

Targets

A target says what a use or report 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; it never leaves your Mac.

Errors and exit codes

  • 0: success.
  • 1, a command error: UNKNOWN_SKILL (no linked skill has that name), NOT_MANAGED (the folder is not managed by BAS, so it logs no uses or reports), INVALID_FILE, IO_ERROR or INTERNAL. The first two also list, in skills, the names the CLI can log for.
  • 2, bad usage: BAD_USAGE (a missing, unknown or invalid flag) 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.