skills

Skills

Flowbot ships with AI assistant skills that teach Claude Code, opencode, and other AI coding assistants how to use the flowbot CLI for daily tasks. Most skills correspond to a Flowbot capability: the skill name equals the capability ID (hub.CapabilityType / provider ID). Platform skills (for example workflow) are also generated and documented below. The skill body describes the CLI command tree (CLI domain names may differ from the capability ID, e.g. karakeep → flowbot bookmark).

Skills follow the SKILL.md convention. The AI assistant loads the skill's frontmatter (name + description) at startup, and only pulls the full SKILL.md body when the user's request matches the description. Additional files in the skill directory (for example reference.md or scripts/run.sh) can be loaded via read_skill with the path argument.

Available Skills

Platform skills (not capability IDs)

Also generated by go tool task skills (see platformSpecs / platformWorkflowSpec in cmd/composer/action/skills). Do not hand-edit the output; change the Go sources / testdata/workflow/*.yaml and regenerate.

Each skill file is in the corresponding subdirectory:

docs/skills/
├── karakeep/
│   ├── SKILL.md
│   └── references/cli.md
├── … (other capability skills)
├── workflow/
│   ├── SKILL.md
│   ├── examples/          # teaching YAMLs (copied from generator testdata)
│   └── references/
│       ├── cli.md
│       └── steps.md       # task action types, params, templates
└── README.md          (you are here)

Capabilities without a CLI tree (notify, agent, example) are not generated as skills. The devops skill is the multi-provider aggregator Cap ID.

How Skills Work with AI Assistants

1. An AI assistant (Claude Code, opencode, etc.) reads available_skills at startup, which includes every skill's name and description from the SKILL.md YAML frontmatter.

2. When the user sends a message that matches a skill's description (e.g. "save this URL to my bookmarks"), the assistant loads the full SKILL.md body into its context.

3. The SKILL.md body contains:

   • Setup (login, server URL, output format)
   • Common workflows (multi-step recipes)
   • Troubleshooting
   • A link to references/cli.md for the full command tree (loaded on demand)
   • For workflow: a step-type quick reference plus references/steps.md and examples/*.yaml for authoring task YAML

4. The assistant follows the instructions in the skill to compose the correct flowbot CLI commands and handle errors.

Enabling Skills in Your Environment

Skills files are already generated in docs/skills/. To use them with your AI assistant, configure the tool to scan this directory.

opencode: Add a --skill-dir or equivalent path pointing to this directory.

Claude Code: Place the skill directories under your global skills path. For example, to make them available project-wide:

# Symlink Flowbot skills into your project's .claude/skills/
mkdir -p .claude/skills/
ln -sf "$(pwd)/docs/skills/karakeep" .claude/skills/karakeep
ln -sf "$(pwd)/docs/skills/kanboard" .claude/skills/kanboard
ln -sf "$(pwd)/docs/skills/miniflux" .claude/skills/miniflux
ln -sf "$(pwd)/docs/skills/memos"    .claude/skills/memos
ln -sf "$(pwd)/docs/skills/trilium"  .claude/skills/trilium
ln -sf "$(pwd)/docs/skills/fireflyiii" .claude/skills/fireflyiii
ln -sf "$(pwd)/docs/skills/transmission" .claude/skills/transmission
ln -sf "$(pwd)/docs/skills/nocodb" .claude/skills/nocodb
ln -sf "$(pwd)/docs/skills/devops" .claude/skills/devops
ln -sf "$(pwd)/docs/skills/gitea"    .claude/skills/gitea
ln -sf "$(pwd)/docs/skills/github"   .claude/skills/github
ln -sf "$(pwd)/docs/skills/workflow" .claude/skills/workflow

For global availability:

# Symlink into the global Claude Code skills directory
mkdir -p ~/.claude/skills/
ln -sf "$(pwd)/docs/skills/karakeep" ~/.claude/skills/karakeep
ln -sf "$(pwd)/docs/skills/kanboard" ~/.claude/skills/kanboard
ln -sf "$(pwd)/docs/skills/miniflux" ~/.claude/skills/miniflux
ln -sf "$(pwd)/docs/skills/memos"    ~/.claude/skills/memos
ln -sf "$(pwd)/docs/skills/trilium"  ~/.claude/skills/trilium
ln -sf "$(pwd)/docs/skills/fireflyiii" ~/.claude/skills/fireflyiii
ln -sf "$(pwd)/docs/skills/transmission" ~/.claude/skills/transmission
ln -sf "$(pwd)/docs/skills/nocodb" ~/.claude/skills/nocodb
ln -sf "$(pwd)/docs/skills/devops" ~/.claude/skills/devops
ln -sf "$(pwd)/docs/skills/gitea"    ~/.claude/skills/gitea
ln -sf "$(pwd)/docs/skills/github"   ~/.claude/skills/github
ln -sf "$(pwd)/docs/skills/workflow" ~/.claude/skills/workflow

Generating Skills

Skills are generated from the live CLI command tree by the composer tool. This ensures the skill always matches the actual CLI interface. Capability skills and the platform workflow skill are both produced by the same command.

# Generate all SKILL.md files to docs/skills/
go tool task skills

When you add a new CLI command tree for a capability, register it in metaSpecs in cmd/composer/action/skills/skills.go (Name = capability ID) and re-run the generator. To change or add a platform skill (CLI recipes, step types, teaching examples), edit platformSpecs / workflow_skill.go and testdata/workflow/*.yaml, then regenerate.

Import into the database

The server binary embeds docs/skills (package skills) and upserts them into agent_skills / agent_skill_files on every startup (after DB migrate in cmd → server.newDatabaseAdapter). source is set to bundled. Existing enabled / disable_model_invocation values are preserved on update.

Flow:

1. go tool task skills — regenerate markdown under docs/skills/
2. Rebuild/restart the server (go tool task run) — auto-import into Postgres
3. Chat agent loads skills from DB via read_skill / system prompt

No manual Web UI paste or composer --sync-db step is required for bundled skills.

Adding a New Skill

1. Implement the CLI command tree in cmd/cli/command/ following existing conventions.

2. Register the capability in metaSpecs in cmd/composer/action/skills/skills.go. Name must equal the capability ID from pkg/hub (e.g. hub.CapKarakeep), not the CLI domain name. (hub.CapExample is shown only as a pattern — example has no CLI skill.)

   {
       Name:        string(hub.CapKarakeep),
       Title:       "Karakeep",
       CommandFn:   command.BookmarkCommand,
       Description: "Create, list, search, archive, and delete bookmarks via flowbot bookmark.",
       Keywords:    "bookmarks, karakeep, saved URLs",
       Workflows: []workflowSpec{
           {
               Title:       "Common task name",
               Description: "When the user wants to do X:",
               Steps: []workflowStep{
                   {Step: 1, Command: "flowbot bookmark list"},
                   {Step: 2, Command: "flowbot bookmark get <id>"},
               },
           },
       },
   },
   

3. Regenerate the skills:

   go tool task skills
   

   The new subdirectory and SKILL.md will appear under docs/skills/.

4. Add the skill directory to your AI assistant's skills path as shown above.

Skill File Anatomy

Each capability skill directory follows Agent Skills progressive disclosure:

{capability-id}/
├── SKILL.md              # frontmatter + setup + workflows (lean)
└── references/
    └── cli.md            # full CLI command/flag reference (on demand)

The platform workflow skill adds references/steps.md and examples/*.yaml.

---
name: karakeep
description: >-
  Create, list, search, archive, and delete bookmarks via flowbot bookmark.
  Use when the user mentions bookmarks, karakeep, ...
compatibility: Requires flowbot CLI, network access to a Flowbot server
metadata:
  capability: karakeep
  cli_root: bookmark
---

# Karakeep

## Setup

## Workflows

## Troubleshooting

• Frontmatter: name equals capability ID and directory name; description is WHAT + WHEN (≤1024 chars); metadata.capability mirrors the Cap ID (platform skills use metadata.platform instead).
• SKILL.md body: Imperative setup, workflows, and troubleshooting only.
• references/cli.md: Auto-generated command tree from cobra (loaded only when needed).
• references/steps.md (workflow only): Task action types, params, templates.
• Workflows: Hand-written multi-step recipes for common tasks (in generator source).

References

• Composer skills code — Capability skill generator.
• Workflow platform skill — Platform workflow skill + step type docs.
• Capability types — Canonical capability IDs.
• CLI commands — The CLI command tree implementations.
• Skill Cap ID migration — Rename homelab-* agent_skills rows to Cap IDs after upgrade.

Migrating from homelab-* names

Skill name and directory now equal the capability ID. If you previously stored skills as homelab-bookmark / homelab-kanban / homelab-reader:

1. Run docs/migrations/2026-07-agent-skills-cap-id.sql.
2. Update pipeline / subagent allowlists to Cap IDs (karakeep, kanboard, miniflux). Runtime still resolves the old names this release.
3. Point Claude/opencode skill symlinks at docs/skills/{cap}/.