Better Agent Skills

Getting started

Better Agent Skills is a registry for agent skills, like npm for packages. You publish a skill once, your team installs it in Claude Code or Codex, and the agents that use it tell you when it goes wrong. It has two parts, both called BAS: the desktop app for macOS, where people find, install, edit, publish and audit skills, and the bas command, which agents run to log each use and report problems.

Install BAS

  1. Download BAS for Apple silicon or Intel. It needs macOS 13 or later.
  2. Open it from your Applications folder.
  3. Sign in. BAS opens this website in your browser and returns to the app once you are signed in. You need an account to publish skills and to see your organization's and teams' skills.

Your library

The library shows every skill in your agents' skills folders, grouped by kind:

  • My skills: skills you write and keep in BAS, under ~/.bas/skills/. You edit them in the app and publish them as versions.
  • Installed: published skills from the registry, including your organization's and teams' kits. They are read-only and update from their owner.
  • From GitHub: a skill folder in a GitHub repository, copied at one commit. BAS tells you when the repository changes and updates when you click Update.
  • Not managed: anything else in a skills folder. You can edit it in place; BAS never moves or deletes it, and Manage with BAS turns a folder into one of your skills.

Install a skill

Find a skill in Browse, which lists public skills and your organization and team kits, or open a share link someone sent you, such as https://better-agent-skills.com/s/3f2a…, and choose Open in BAS.

  1. Pick the agents to install it for: Claude Code (~/.claude/skills), Codex (~/.codex/skills) or both.
  2. BAS downloads the version and links <skills folder>/<skill name> to it. It never overwrites a folder that is already there; you rename the install or cancel.
  3. Choose a mode. Auto-update, the default, follows the skill's current version. Pinned stays on its version and shows when an update is available.

Publish a skill

  1. Choose New skill. BAS creates ~/.bas/skills/<name>/SKILL.md and links it into your agents.
  2. Edit its files in the editor. Saving writes straight to disk, so your agents see the change at once.
  3. Publish. The first publish asks for a visibility: public, private, one of your organizations or one of your teams. Each publish is a new numbered version (v1, v2, v3) that never changes.
  4. Copy the share link from the editor and send it to the people who should install it.

You can roll back to an earlier version or mark a version bad at any time; installs in auto-update mode follow the current version.

Add a skill from GitHub

Choose Add from GitHub and paste a link to a skill folder: a repository, a tree link to a folder, or a blob link to its SKILL.md. Public repositories need nothing; for a private one, add a GitHub personal access token in Settings. It stays in your Mac's keychain and is sent only to GitHub.

See how each version does

Every installed skill, skill of yours and skill from GitHub ends with one line asking the agent to log its use with bas used and any problem with bas report. The audit dashboard turns those into reports per 100 uses for each version, flags a version that made the skill worse, and groups the reports by problem.

Read next