Better Agent Skills

Agents and the footer line

BAS learns how a skill does from the agents that use it. It asks them with one line at the end of the skill's SKILL.md, and nothing else: no hooks, no extra skills, and no changes to Claude Code's or Codex's settings.

The footer line

For a skill named deploy-checklist, the last line of its SKILL.md reads:

After using this skill, log its use with `bas used --skill deploy-checklist` and any problem with `bas report --skill deploy-checklist` (Better Agent Skills; `~/.bas/bin/bas` if `bas` is missing).
  • BAS adds it to every installed skill, every one of your skills and every skill from GitHub. Skills BAS does not manage get no footer and log nothing.
  • On your own skills, BAS puts the line back if an edit removes it. The editor shows it like any other line.
  • Published versions never contain it: BAS leaves it out when you publish.
  • ~/.bas/bin/bas runs the same command where bas is not on the path: the app keeps that link to the copy it ships with each time it starts.

Logging a use

After using the skill, the agent runs:

bas used --skill deploy-checklist

The CLI works out which version the name points to at that moment (an installed version, a GitHub commit, or your own skill) and appends it with the time to ~/.bas/usage.jsonl. It needs no network and no running app. The app later sends only the number of uses per version and day, which turns report counts into report rates.

Counts are approximate: an agent that skips the footer is not counted. Every version is counted the same way, so their rates stay comparable.

Reporting a problem

When the skill got something wrong, the agent files a report:

bas report --skill deploy-checklist --category outdated-command --severity medium --summary "Step 3 uses deploy --prod, which was renamed to deploy --production"
  • A report has a category, a severity, a one-line summary and, optionally, details and a suggested fix. The CLI reference lists them all.
  • The CLI removes secrets from the text, such as API keys, tokens, private keys and passwords in URLs, and marks where it removed them, before anything is saved.
  • The report waits in ~/.bas/outbox/. By default the app shows you each report before it is sent, and you can edit, send or discard it. In Settings you can send reports automatically instead.
  • You can file reports the same way yourself, or ask your agent to.

What agents never send

No conversation, transcript, file contents or repository name leaves your Mac with a use or a report. See Privacy of reports and usage for exactly what is sent and who sees it.