Skills System

Skill standard

The system uses Anthropic-style skills. A skill is a directory containing SKILL.md and optional scripts, templates, references, and examples.

~/.vibeflow/skills/        # shared skill catalog (machine-wide, source of truth)
.vibeflow/skills/          # project-local override/shadow layer (resolved first)
  <name>/
    SKILL.md             # required: frontmatter + instructions
    references/          # optional: linked reference docs
    scripts/             # optional: executable helpers
    assets/              # optional: templates, schemas, fixtures

Mirrors (regenerated from the canonical store by vf skills sync, see src/skills/sync.ts):

.claude/skills/          # Claude mirror (reads SKILL.md directly)
.agents/skills/          # Codex / cross-tool mirror
.github/skills/          # Copilot mirror
.opencode/skills/        # OpenCode mirror

SKILL.md must contain YAML frontmatter and follow the Anthropic skill-creator standard (see src/skills/ANTHROPIC_SKILL_STANDARD.md):

---
name: skill-name
description: Clear description of when this skill should be used
---

# Skill Name

Instructions...

Validation (`vf skills validate`)

VibeFlow validates skills against the official Agent Skills spec (https://agentskills.io/specification) — the enforced subset lives in src/skills/ANTHROPIC_SKILL_STANDARD.md. Rules:

name: required, lowercase kebab-case, 1–64 chars (error otherwise).
description: required, <= 1024 chars, no angle brackets </> (they corrupt XML tool-call parsing).
Standard frontmatter fields — name, description, license, allowed-tools, metadata, compatibility (<= 500 chars), owners (array of names/emails), changelog (block list with version/date/description), supersedes (replacement skill name for deprecation) — are recognized. Any other key is a warning (not an error), so legacy VibeFlow keys (status/version/triggers/requires) keep validating.
Optional dirs scripts/, references/, assets/ are emptiness-checked; the spec allows any additional top-level file or directory, so extras are not flagged (Anthropic’s own skill-creator ships agents/ and eval-viewer/).
Body must be actionable (>= 50 chars, not a TODO placeholder).

Skill metadata

Skill metadata lives in the SKILL.md YAML frontmatter. The orchestrator parses that frontmatter for deterministic capability matching — there is no separate metadata file.

Example:

---
name: xlsx-reader
version: 1.0.0
capabilities: ["read:xlsx", "extract:tables"]
triggers: ["xlsx", "spreadsheet", "excel"]
requires:
  filesystem: read
  network: false
  shell: false
status: verified
---

# XLSX Reader

Instructions...

`scope: common | organization | project | adapter` (#655)

The optional scope field classifies how reusable a skill is:

common (default when absent) — generic, applies to any project (e.g. “xlsx reader”).
organization — team/org conventions (e.g. “deploy to our staging env”).
project — repo-specific conventions. Contains hardcoded paths, branch names, or project IDs. MUST set project.id (e.g. project.id: my-org/my-repo).
adapter — tool-specific shim (e.g. a MCP wrapper for a CLI).

project.id is required when scope: project | adapter. extends declares skill names this skill inherits from (a flat list).

Security boundary: vf skills publish rejects scope: project skills targeting a common registry channel, and detects hardcoded absolute paths (/Users/…, C:\Users\…) in common-scoped content.

scope: project
project.id: my-org/my-repo
extends: [common-test-runner]

Adapter pattern (`extends:` — #656)

Adapter-scoped skills can declare extends: [<common-skill>@<version>] to inherit and override a base skill without duplicating its content.

Resolution (runs in discoverSkills):

Base skill loaded first from the same pool.
Frontmatter: adapter fields shallow-merge on top of base (adapter wins).
Body: H1/H2 sections from the adapter replace matching sections in the base. Sections not present in the base are appended. Non-heading content (text before the first heading) is replaced entirely.
Adapter’s dir/path remain unchanged → base skill source is never modified.
resolvedBody is set on the Skill object with the merged result.

Version pinning:

extends: [common-test-runner@1.2.3] — pins exact version. Warnings fire when installed base version differs.
extends: [common-test-runner] — no pin. A nudge warning suggests adding @<version> when the base declares one.

Missing base: produces an actionable warning; adapter body is used as-is. Invalid extends format: produces a warning and the entry is skipped.

Adapters are transparent to consumers: the merged body is what agents see, but the adapter file (SKILL.md) still holds only the delta.

`type: repo | knowledge` (always-on project law)

The optional type frontmatter field sets how a skill reaches the engine:

type: repo — always-on project law. Injected into EVERY dispatch as non-negotiable law, regardless of keyword match (e.g. “always run migrations in a transaction”, “never touch prod config”).
type: knowledge (default) — keyword-gated. Injected only when the unit text matches the skill’s triggers/capabilities (today’s behavior).
absent — treated as knowledge (back-compat).

vf skills validate warns if type is present but not repo/knowledge.

`mcp:` (executable skill bundles — #552)

A skill may declare ONE MCP server it needs. When the skill is present in the repo, VibeFlow provisions that server into every engine’s MCP config (reusing the same fan-out as vf config mcp, #548). Remove the skill and its server disappears on the next vf init / vf tools run.

mcp:
  name: playwright        # optional; defaults to the skill name
  transport: stdio        # stdio (default) | http | sse
  command: npx            # stdio only
  args: [@playwright/mcp] # stdio only
  url: https://…/mcp      # http/sse only
  headers: { Authorization: "Bearer ${TOKEN}" }  # http/sse only

One server per skill. (A multi-server block is not supported — declare separate skills.)
Server name = mcp.name if it’s valid lowercase-hyphen, else the skill name. The name is regex-validated (it becomes a TOML section / JSON key) so it can’t inject.
Precedence: an explicit vf config mcp server WINS over a skill’s server on a name clash.
Codex + SSE: codex has no SSE transport, so an sse skill server is skipped for codex with a warning (stdio/http still land).
Security: installing a skill now also wires a tool that runs code. VibeFlow prints one warning per skill-contributed server (naming the skill + command/url) so you SEE what got wired. Only install skills you trust; header values are never logged (use ${VAR}).
vf skills validate warns if the mcp block is malformed (stdio without command, or http/sse without url).

Skill categories

Source skills

Used to access project sources:

github-source-skill
gitlab-source-skill
google-drive-source-skill
confluence-source-skill
notion-source-skill
jira-source-skill
linear-source-skill
slack-source-skill
local-folder-source-skill
s3-source-skill

File processing skills

Used to read and normalize files:

markdown-reader-skill
docx-reader-skill
xlsx-reader-skill
pptx-reader-skill
pdf-reader-skill
image-ocr-skill
openapi-reader-skill
postman-reader-skill
drawio-reader-skill
mermaid-reader-skill

Workflow skills

Used to run AI SDLC processes:

repo-onboarding
instruction-generator
sdlc-agent-generator
copilot-task-dispatcher
claude-task-dispatcher
codex-task-dispatcher
diff-reviewer
skill-maintainer

Skill usage rule

Agents must use verified skills whenever a task matches an available skill capability.

If a matching verified skill exists but the agent does not use it, the task is not compliant.

Every agent output must include:

{
  "agent": "document-reader",
  "skills_considered": ["xlsx-reader"],
  "skill_used": "xlsx-reader",
  "skill_version": "1.0.0",
  "confidence": 0.91
}

Skill registry priority

Canonical order (kept in sync with MASTER_SPEC.md, SKILL_PROVIDERS.md, and SKILL_DISCOVERY_AND_EVOLUTION.md):

1. Local verified skills
2. Context7 HTTP API (skills and docs)
3. Official Anthropic skills/plugins
4. Vercel find-skills
5. Official vendor documentation
6. Trusted MCP registries
7. Community skills after review
8. npm packages only after security verification

Registry release proposals

Release fanout is opt-in. .vibeflow/REGISTRY_FANOUT.json is a committed, default-deny target allowlist. vf skills registry release-propose writes an immutable local snapshot under .vibeflow/registry-release-proposals/. There is no automatic fanout, webhook, discovery, or UI execution.

Proposal snapshots are exposed to the dashboard through two guarded, read-only HTTP endpoints: GET /api/skills/registries/releases (sanitized summary list) and GET /api/skills/registries/releases/<proposal-id> (sanitized detail; 404 for an unknown or malformed id). Both fail closed on a tampered snapshot and never expose an execution endpoint.

After approval runs in the CLI, each target’s sanitized verify evidence and, for pr-opened/existing-pr targets, the opened prUrl are persisted onto the snapshot next to the target status. These post-execution fields live OUTSIDE the immutable proposal-ID hash, so they never change the deterministic proposal id. The Registry tab renders a read-only review surface for these proposals — registry, version, abbreviated OIDs, state, per-target status, changelog, verify evidence, and a PR link for opened targets — plus a “Copy approval command” button (vf skills registry release approve <proposal-id> --yes). There is NO approve/execute/push control in the UI; approval happens only in the CLI.

Skill curator (findings → proposals)

The curator subsystem turns skill-catalog findings into reviewable work:

vf skills curator scan [--scope=local|repo] — scans the skill catalog for findings (duplicate patterns, stale anchors, scope violations, policy gaps). local (default) is private/offline; repo anchors the scan to a clean HEAD so findings are reproducible in CI.
--sync / --yes — with --scope=repo, previews then pushes shared finding markers via Git notes (refs/notes/vibeflow-curator) so multiple machines share one findings ledger.
Proposals — findings turn into configurable draft issues and PR proposals (vf skills curator issue [--dry-run], vf skills curator pr [--dry-run]).
CI — a scheduled curator report workflow runs in CI with issue deduplication (.github/workflows/skill-curator.yml).
UI — the web UI exposes curator settings, findings, and a registry-update preview under Settings.
Domain facts — vf skills impact lists affected skills; the UI shows a read-only domain-facts impact view.

Learning loop — turning runs into skills

VibeFlow self-improves by capturing what each run learns. Four mechanisms feed the loop, covering mistake / learn / knowledge / decision:

Dimension	Mechanism	Trigger
mistake / learn	auto-crystallize	Automatic at the end of `vf orchestrate` (and `vf verify --journal`). Reads the run log + `knowledge/log.md`, counts recurring commands / skills / failures. If patterns match an existing skill by name/domain/fact, prints a PATCH PROPOSAL (stdout only). Otherwise writes a DRAFT skill when threshold crossed.
learn (agent-driven)	`vf skills draft <name>`	An agent (or you) captures a reusable procedure or worked-around mistake on the spot. Scaffolds a `status: draft` SKILL.md with a Why/Evidence skeleton.
knowledge	`knowledge/log.md`	Append-only work journal (`## [YYYY-MM-DD] note
decision	`vf decision add`	Records a durable architecture/process decision in `knowledge/decisions.md` (ADR-lite), separate from the noisy journal.

Safety model — DRAFT, never auto-installed

Every captured skill lands as status: draft and is never installed into the engine mirrors automatically. A draft is an untracked file you review and git add if useful. This is deliberate: a wrong skill that auto-installed would poison every subsequent run. Promotion (draft → verified) is a human decision.

vf verify stays read-only by default — the auto-crystallize tail only runs on the opt-in --journal flag, so the gate an agent runs before “claiming done” never mutates the tree it audits.

Dispatched agents know the loop

The VF_WORKFLOW block injected into every engine’s context tells dispatched agents to draft skills and record decisions as they work — so the loop runs whether or not the deterministic auto-crystallize backstop fires.

No silent improvisation

Agents must not invent a manual process before checking available skills.

If no skill exists, the agent must report:

Missing capability:
Recommended skill:
Risk:
Safe fallback:
Validation plan: