Skills

Blop ships a standalone catalog of SKILL.md files for agent hosts. The blop skills command lets you list, view, validate, and improve them. The catalog is not automatically injected into active browser-check prompts.

Commands

blop skills list

Print each bundled skill as name@version — description:

$ blop skills list

The output contains the name, version, and frontmatter description of each bundled skill, including audit, reproduce-first, and verify-claims.

If no skills are found, prints No skills found.

blop skills view <name>

Print the full content of a named skill:

$ blop skills view auth-flow

Exits non-zero if the skill name is unknown.

blop skills check

Validates all bundled skills. Soft warnings are printed to stderr; hard errors cause a non-zero exit.

$ blop skills check

On success, prints OK — N skill(s) valid.

blop skills improve <name> [--write]

Distills learnings from .blop/skills journal entries into an improved skill version. A host must write those journal entries through the skills API; the browser runner does not record them automatically. This command reads existing entries and proposes an updated SKILL.md.

$ blop skills improve verify-claims
verify-claims: 1.0.0 → 1.0.1
  + Added guidance for OTP screens
  + Added timeout guidance for slow auth providers
(dry run — pass --write to apply)

Pass --write to save the improved version back to the skill file:

$ blop skills improve verify-claims --write
verify-claims: 1.0.0 → 1.0.1
  + Added guidance for OTP screens
  + Added timeout guidance for slow auth providers
Wrote skills/verify-claims/SKILL.md

If there aren’t enough recurring failures to distill (fewer than 2), prints:

No new learnings to distill for 'verify-claims' (need ≥2 recurring failures).

How skills work

Skills are Markdown files with YAML frontmatter (name, description, version) and a focused body of instructions. A host can opt into the registry and journal APIs; active checks do not consume them automatically. The skill system has three layers:

Layer	What it does
Registry	Loads bundled SKILL.md files, validates them, and exposes list/get/check
Journal	Stores outcome entries written by an integrating host under .blop/skills/
Evolution	Distills journal entries into improved skill versions (improve)

Skill journal

The journal lives at .blop/skills/. An integrating host writes entries; blop skills improve reads them. The browser runner does not append entries itself.

Add .blop/ to your .gitignore:

.blop/