Skip to content
Blopblop docs

Skills

Blop ships bundled SKILL.md files that teach the agent domain-specific patterns — for example, how to handle authentication flows, form validation, or multi-page checkouts. The blop skills command lets you list, view, validate, and improve them.

Commands

Section titled “Commands”

blop skills list

Section titled “blop skills list”

Print each bundled skill as name@version — description:

Terminal window
$ blop skills list
auth-flow@1.0.0 — Patterns for signing in and verifying authenticated sessions
form-validation@1.0.0 — Patterns for filling and validating forms
checkout@1.0.0 — Patterns for multi-step purchase flows

If no skills are found, prints No skills found.

blop skills view <name>

Section titled “blop skills view <name>”

Print the full content of a named skill:

Terminal window
$ blop skills view auth-flow

Exits non-zero if the skill name is unknown.

blop skills check

Section titled “blop skills check”

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

Terminal window
$ blop skills check

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

blop skills improve <name> [--write]

Section titled “blop skills improve <name> [--write]”

Distills learnings from .blop/skills journal entries into an improved skill version. Blop tracks recurring agent failures across runs and writes them to .blop/skills/ as journal entries. This command reads those entries and proposes an updated SKILL.md that incorporates the learnings.

Terminal window
$ blop skills improve auth-flow
auth-flow: 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:

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

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

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

How skills work

Section titled “How skills work”

Skills are Markdown files with YAML frontmatter (name, description, version) and a focused body of instructions. The agent receives relevant skill content as part of its prompt when running tests. The skill system has three layers:

Layer What it does
Registry Loads bundled SKILL.md files, validates them, and exposes list/get/check
Journal Records agent failure patterns to .blop/skills/ across runs
Evolution Distills journal entries into improved skill versions (improve)

Skill journal

Section titled “Skill journal”

The journal lives at .blop/skills/. Blop appends entries automatically when agents hit failure patterns. You don’t normally interact with it directly — blop skills improve reads it for you.

Add .blop/ to your .gitignore:

.blop/