Agent Skills

A coding agent writing a Wajub integration from memory gets the shape right and the details wrong: it reads event.type instead of event, it parses the body before verifying the signature, it sends an amount in minor units. Agent Skills ship those rules into your repository so the agent reads them instead of guessing.

You rarely need to run anything: from CLI 1.5.0, the first command you run after installing or upgrading the CLI copies the skills into the directories of the coding agents it finds on your machine, and says so. wajub login does the same. Then restart your coding agent: Claude Code, Codex and the others read their skills when a session starts, never during one.

wajub skills install --scope project

What gets installed

Ten skills, each one a SKILL.md with a reference document beside it. An agent loads the one whose description matches the task at hand, and ignores the rest.

The suite is pinned to an API version, currently 2026-08-01, so the guidance and the platform do not drift apart silently.

Where they land

Two directories per scope: .agents/skills, the open convention most agents read, and .claude/skills, the only one Claude Code reads.

Each agent reads its own subset. This is what each one loaded when we listed its skills, checked against their latest releases.

Both scopes write both directories: no single one reaches Claude Code and Codex, and an agent you install next week, or a teammate's, must find them too. Cursor and OpenCode read both; OpenCode keeps one copy of each skill and notes the duplicate name in its logs. --target agents or --target claude writes only one.

Project scope commits with your repository, so everyone on the team and every agent run gets the same rules. User scope follows you across repositories. Installing both is fine, and the project copy wins where an agent reads both.

$ wajub skills install --scope project --dry-run

Planned destinations (project):
  agents: /Users/you/code/shop/.agents/skills
  claude: /Users/you/code/shop/.claude/skills
  ✓ install  wajub-integrate (agents)
  ✓ install  wajub-payments (agents)
  ✓ install  wajub-webhooks (agents)
  …

Checking what you have

wajub doctor answers the question that matters, agent by agent: does it see the skills, and if not, what to run. wajub skills status reports every skill in every scope, with its integrity.

$ wajub skills status

Wajub Agent Skills 1.7.3 (API 2026-08-01)
  current   wajub-integrate      project/agents
  current   wajub-payments       project/agents
  modified  wajub-webhooks       project/agents
  absent    wajub-shield         project/agents
  …

modified means the directory no longer matches what the CLI installed, usually because someone edited a skill by hand. A plain install leaves those alone rather than overwriting your changes. --force replaces them.

Keeping them current

Skills ship inside the CLI package. The user scope updates itself on the first command after each CLI upgrade, and leaves alone any skill you edited. A project scope is part of your repository, so it changes only when you ask.

npm install -g @wajub/cli
wajub skills install --scope project

Nothing is installed automatically in CI (when CI is set), for a command run with --json, into a home that belongs to another user (sudo keeps HOME on macOS), or once you opted out. A failed installation is reported once and retried on the next command. An older CLI, such as a project's devDependency next to a newer global install, never puts its older skills back.

Removing them

wajub skills uninstall --scope project --dry-run
wajub skills uninstall --scope project --yes

Without --force, directories you modified are left in place, on the assumption that your edits are worth more than a clean removal.

Removing the user scope also turns the automatic installation off, so the next command does not put them back; wajub skills install --scope user turns it on again. WAJUB_NO_SKILLS=1 and wajub login --no-skills turn it off without removing anything.

When an agent does not see them

Run wajub doctor: it names each agent that misses the skills and the command that fixes it. The usual causes, in order:

• The agent was already running. Skills are read when a session starts. Restart it.
• The skills were never copied. CLI 1.4.0 and earlier only installed them during wajub login. Run wajub skills install --scope user.
• Gemini CLI and a project install. It reads project skills only in a folder it trusts, and only in the folder it starts in, not from a subdirectory of the repository. Trust the folder when it asks, and start it from the root, or rely on the user scope.
• CLAUDE_CONFIG_DIR is set. Claude Code then reads $CLAUDE_CONFIG_DIR/skills instead of ~/.claude/skills. Run wajub skills install --scope user from a shell where it is set.
• The skill exists but the agent does not use it. An agent loads a skill when its description matches the request. Name the task plainly: "verify the webhook signature" rather than "fix the endpoint".