Agent Skills Overview

A skill is the unit of capability in Cremind. It is just a directory: a SKILL.md file plus, optionally, some scripts. When Cremind scans your skills directory it reads each SKILL.md and injects its content into the reasoning agent as context, so the agent learns — in plain language — what the skill does and how to drive it. The agent then runs the skill's scripts through the built-in terminal tool.

The shape of a skill

At minimum a skill is a folder with a SKILL.md whose YAML frontmatter declares a name and a description. That is genuinely all the scanner requires. Most useful skills also ship a small Python CLI and, when they react to the outside world, a long-running event listener.

A typical layout looks like this:

my-skill/
├── SKILL.md                  # frontmatter + Markdown instructions
├── events/<event_type>/      # markdown drop-zone for incoming events
└── scripts/
    ├── __main__.py           # an argparse CLI (the actions)
    ├── event_listener.py     # the long-running listener (optional)
    ├── .my-skill.json         # locally-stored tokens (never committed)
    └── app/                   # shared helper modules

The pieces:

• SKILL.md — the contract. Its frontmatter is parsed by the scanner; its Markdown body is the instruction manual the agent reads. See the SKILL.md Reference.
• scripts/__main__.py — an argparse-style CLI that exposes the skill's actions (list, send, create, …). The agent invokes subcommands and reads the JSON they print.
• scripts/event_listener.py — an optional persistent process declared via metadata.long_running_app. It subscribes to the Cremind Connect relay and drops markdown files into events/<event_type>/ when something changes. See Event Listeners.
• events/<event_type>/ — a watched drop-zone folder, one per event type the skill emits.

Scripts run via uv — no venv setup

Skill scripts run with uv and use PEP 723 inline metadata, so each script declares its own dependencies in a header comment. There is no virtual environment to create and no pip install step — uv run scripts/__main__.py <subcommand> resolves dependencies on the fly. This keeps a skill self-contained and portable: clone the folder, and it runs.

How skills get loaded

Cremind discovers and reloads skills automatically:

• The scanner (app/skills/scanner.py) walks a profile's skills directory, validates each SKILL.md, and produces an in-memory record for every valid skill.
• The sync layer (app/skills/sync.py) and a per-profile SkillsWatcher keep the on-disk skill set in lockstep with the agent's tool registry. Add, edit, or remove a SKILL.md and the change is hot-reloaded — no restart.
• Skills are per-profile. Each profile gets its own skills directory at <CREMIND_SYSTEM_DIR>/<profile>/skills/, so a work assistant and a home assistant never share credentials or context. The shipped built-in skills are copied into every profile and restored on boot if deleted; your own skills are left untouched.

Built-in skills

Cremind ships a starter set of skills you can use immediately or read as worked examples:

Where to go next