Skill

A Skill is a reusable capability package that teaches an agent how to do one thing well. It bundles prompt instructions (a SKILL.md file) with optional scripts, reference documents, and assets.

Directory Layout

~/.nebflow/skills/<name>/
├── SKILL.md        # Required — frontmatter + instructions
├── scripts/        # Optional — executable code (Python, Bash, ...)
├── references/     # Optional — docs the agent reads on demand
└── assets/         # Optional — templates, fonts, output files

The directory name must match the name field in frontmatter.

SKILL.md Frontmatter

Only name and description are required. The description is the only text an agent sees in its skill catalog — it must explain both what the skill does and when to use it.

| Field | Required | Default | Description | |-------|----------|---------|-------------| | name | Yes | dir name | Skill identifier, must match directory name | | description | Yes | — | One-line summary shown in the agent's skill catalog | | when_to_use | No | — | Additional trigger context appended to the catalog entry | | language | No | — | Preferred response language (zh, en) | | audience | No | — | Team this skill belongs to — a real team name (e.g. nebflow-project), not a namespace | | user-invocable | No | true | Whether users can invoke it via a /<name> slash command | | disable-model-invocation | No | false | When true, hidden from agent catalogs (slash-command only) | | version | No | — | Semantic version string | | status | No | active | Lifecycle state: draft / active / deprecated | | replaced_by | No | — | Successor skill, shown when this one is deprecated | | allowed-tools | No | all | Comma-separated tool allowlist | | arguments | No | — | Argument names (YAML block list or comma-separated) |

Body Structure

The Markdown body is the instruction set the agent follows. A proven structure:

---
name: example
description: An example skill — copy this folder to create your own
language: en
---

# Example Skill

## Purpose
Describe what this skill does in one sentence.

## Steps
1. Step one
2. Step two

## Rules
- Rule one
- Rule two

## Output
Describe the expected output format.

Opt-in Subscription

Skills are not injected automatically. An agent only sees a skill catalog when it declares skills in its agent.json:

{
  "name": "Frontend",
  "skills": ["visual-report", "deploy-website"]
}

• Empty (or missing) skills array → no catalog at all, no global fallback
• The wildcard "*" subscribes to every skill in the library
• Skills marked disable-model-invocation: true stay out of catalogs even when declared
• The meta-skill skill-creator is always appended when a catalog is produced, so every subscribed agent can discover how to create new skills

Each catalog entry carries name, description, and when_to_use — enough for the agent to decide relevance without loading the full content.

How an Agent Uses a Skill

1. Catalog match — a task matches an entry in the agent's skill catalog
2. Read on demand — the agent reads that skill's SKILL.md in full
3. Bundled resources — the ${SKILL_DIR} variable in instructions is replaced with the skill's absolute directory path, so scripts and references can be invoked directly:

python ${SKILL_DIR}/scripts/analyze.py --input data.csv
cat ${SKILL_DIR}/references/spec.md

This is progressive disclosure: cheap catalog entries are always present; the full instruction set is loaded only when relevant.

Compatibility

Skill files also load from project-level .nebflow/skills/ and .claude/skills/ directories, and legacy single-file commands (.nebflow/commands/, .claude/commands/) are treated as skills — user-level skills take priority on name conflicts. This keeps Nebflow compatible with the Claude Code skills ecosystem.

Examples

The built-in library at ~/.nebflow/skills/ ships with real examples to copy from: _example (starter template) and skill-creator (the meta-skill for authoring skills).