Custom Skills Tutorial

Skills are focused knowledge bundles that teach an agent when and how to apply a specialized workflow. LumenFlow’s canonical skill directory is .lumenflow/skills/.

One canonical source

LumenFlow manages reserved skills only in .lumenflow/skills/. It does not project them into a particular agent tool’s directory or maintain tool-specific invocation syntax.

Create a skill

1. Create a directory using a stable, descriptive name:

   mkdir -p .lumenflow/skills/api-contract-review

2. Add .lumenflow/skills/api-contract-review/SKILL.md:

   ---
   name: api-contract-review
   description: Review API contract compatibility before implementation
   version: 1.0.0
   ---
   
   # API Contract Review
   
   Use this skill when a task changes a public request, response, event, or schema.
   
   ## Workflow
   
   1. Identify the current public contract and consumers.
   2. Classify the change as compatible or breaking.
   3. Add contract-level verification before implementation.
   4. Record migration and documentation impact.

3. Review the skill for portability.

4. Load it through the capability available in your current agent host before the work it governs.

Portability checklist

A canonical skill should:

• describe triggers and outcomes in plain language;
• use repository-relative paths;
• call LumenFlow CLI commands only for LumenFlow behavior;
• refer to delegation, file reading, or web research as host-native capabilities;
• avoid product filenames, proprietary slash commands, editor settings, and assumptions about a particular model;
• state any required external capability explicitly and provide a graceful fallback where possible.

Transposition

Prefer a host that can read the canonical SKILL.md directly. If another location or wrapper is required, the repository owns that transposition:

• wrappers should read the canonical file at invocation time;
• discovery adapters should include the canonical content digest and fail closed when the source is unavailable;
• symbolic links are a repository portability choice;
• copied skills are snapshots and must be updated by the repository owner.

LumenFlow install, upgrade, docs-sync, force, merge, and uninstall never modify the transposed artifact.

Reserved and project skills

LumenFlow refreshes only its reserved skill allowlist. A project-created skill with another name is left untouched. Use a project namespace when collision risk matters, and keep the skill’s name stable once other guidance refers to it.

The reserved browser-resource-etiquette skill applies whenever work uses a browser, preview, or browser-backed verification. It requires an isolated session and limits cleanup to browser resources owned by that session, so an agent never closes a user’s browser or another task’s processes.

Test a skill

Test the actual outcomes the skill promises:

1. give an agent a small representative task;
2. confirm the trigger description makes selection clear;
3. verify required sources and commands exist;
4. check that the result follows the workflow without depending on one host;
5. run repository docs and formatting gates.

For the universal ownership boundary, see Connect an AI Coding Assistant.