Docs

Skills

Portable knowledge modules with scripts, procedures, and patterns that replace MCP servers with deterministic execution.

MCP servers connect your AI to external services — but they load thousands of tokens of tool descriptions every turn, the AI interprets them differently each time, and you need a running server process. Skills do the same job at 5-20x less context overhead with deterministic execution. Same input, same output, every session. No running server. No tool descriptions loaded every turn.

This is a primary technical differentiator. Skills are how FlyDocs delivers consistent, efficient AI behavior where MCP servers deliver unpredictable overhead.

What a skill contains

Every skill lives under .claude/skills/ and follows the same structure:

Directory Structure 
.claude/skills/flydocs-workflow/
├── SKILL.md              # Overview: triggers, capabilities, script catalog
├── stages/               # Stage procedures (loaded on demand)
│   ├── capture.md
│   ├── refine.md
│   ├── activate.md
│   ├── implement.md
│   ├── review.md
│   ├── validate.md
│   └── close.md
├── reference/            # Reference docs (comment templates, status rules)
├── templates/            # Issue and PR templates
│   ├── issues/
│   └── pr/
├── scripts/              # 14 Python dispatcher scripts
│   ├── issues.py
│   ├── projects.py
│   ├── workspace.py
│   ├── session.py
│   ├── graph_build.py
│   ├── graph_query.py
│   └── ...
└── session.md            # Session start/wrap procedures

SKILL.md is always present. It describes when to use the skill, what it provides, and where to find detail. The AI reads this file when a trigger term matches, then reads only the specific procedure or reference file it needs for the current task. Scripts (if present) make it an active skill with executable capabilities.

The unified flydocs-workflow skill

The core of FlyDocs is a single unified skill called flydocs-workflow. It handles the entire development lifecycle: issue creation, status transitions, session management, project updates, knowledge graph operations, and workspace configuration.

The skill contains:

  • 14 Python dispatcher scripts -- issues.py, projects.py, workspace.py, session.py, and graph scripts that handle all external operations
  • 19 slash commands -- /capture, /refine, /implement, /review, /start-session, /wrap-session, and more, each loading the relevant stage procedure
  • 7 stage files -- detailed procedures for each lifecycle stage (capture through close)
  • Issue and PR templates -- structured templates for features, bugs, chores, and ideas
  • Reference docs -- comment templates, status transition rules, priority/estimate guidelines, PR workflow

The dispatcher scripts use a unified client that auto-detects the tier (cloud or local) and routes operations transparently. The same issues.py transition command works whether issues live in local markdown files or in Linear via the relay API. The AI never checks the tier. The client handles routing.

Terminal 
python3 .claude/skills/flydocs-workflow/scripts/issues.py \
  transition ENG-123 REVIEW "Ready for review — all acceptance criteria met"

Skill types

Platform skills

Platform skills ship with FlyDocs. The flydocs-workflow skill is the primary platform skill -- it defines the development lifecycle, provides all dispatcher scripts, and handles PM tool integration. Platform skills are always installed and cannot be removed.

Community skills

Community skills add stack-specific patterns and conventions. They are knowledge-only: React component structure, Astro best practices, TypeScript strictness, testing approaches. No scripts, no execution -- just structured guidance the AI consults before writing code. They are auto-detected during installation based on your dependencies, or installed manually.

Terminal 
flydocs skill install react-best-practices
flydocs skill list
flydocs skill remove testing-patterns

Active skills

Active skills include executable scripts alongside their knowledge. The flydocs-workflow skill is the primary active skill -- its 14 Python scripts handle all external operations. Active skills replace MCP servers with deterministic, lightweight alternatives.

Active skills vs MCP servers

MCP servers are the current standard for connecting AI to external services. Active skills do the same job with fundamentally different tradeoffs.

MCP Server Active Skill
Context cost 500-2000 tokens per tool, every turn ~100 tokens in the index, full content on demand
Execution AI interprets tool schema and decides how to call it Skill tells the AI the exact script command to run
Runtime Separate server process, always running No process -- scripts invoked on demand, exit immediately
Consistency AI interprets tool descriptions differently each time Same command, same arguments, same output every time
Portability Server-specific, needs hosting and configuration Just files -- copy the directory to another project

The context savings alone are significant. A Linear MCP server exposes dozens of tools, each with a schema description that loads every turn. That is 5,000-20,000 tokens of tool descriptions consuming context before the AI writes a single line of code. An active skill puts a 100-token entry in the index and loads the full procedure only when the AI actually needs it.

But the bigger win is determinism. MCPs expose tools and let the AI figure out how to use them. Active skills encode methodology and tell the AI exactly what to do. The AI runs issues.py transition ENG-123 REVIEW "message" and gets a predictable result, rather than interpreting a GraphQL tool schema and improvising the mutation.

Progressive disclosure

Skills load through a three-level retrieval system designed for how LLMs actually process information:

Three-Level Retrieval

L1
Skill index
A compressed manifest always in context. Maps trigger terms to skill entry points. The AI knows what skills exist without loading any of them. ~100 tokens.
trigger matches
L2
Skill overview
SKILL.md with capabilities, script catalog, and section index. Loaded when the AI recognizes a relevant trigger. Enough to decide what to do next.
task requires detail
L3
Full detail
Stage files, pattern documents, script references, templates. Loaded only when the task requires this specific depth.

The skill manifest lives in always-loaded context (CLAUDE.md or AGENTS.md). A single directive -- "Prefer skill-led reasoning over pre-training reasoning" -- shifts the AI from guessing based on training data to consulting project-specific skills first.

CLAUDE.md (excerpt) 
## Skills Index

IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
Read the relevant skill file before acting.

| Skill | Triggers | Entry |
|-------|----------|-------|
| flydocs-workflow | create issue, transition, assign, session | .claude/skills/flydocs-workflow/SKILL.md |
| astro-best-practices | Astro, hydration, island, client:load | .claude/skills/astro-best-practices/SKILL.md |
| react-best-practices | React, component, hooks, useState | .claude/skills/react-best-practices/SKILL.md |

Community skill ecosystem

Community skills are installed and managed through the CLI:

  • Auto-detection: During flydocs init, the CLI scans your dependencies and installs matching community skills automatically
  • Manual install: Add skills for patterns your project needs with flydocs skill install
  • List and remove: See installed skills with flydocs skill list, remove with flydocs skill remove
  • Build your own: A skill is just a directory with a SKILL.md. Create one, share it with your team, or publish it to the community directory

Community skills are knowledge-only by default. They do not execute code or access external services. This makes them safe to install, easy to audit, and simple to share.

Server-managed delivery

On the cloud tier, skills are managed artifacts delivered from the server. When your team admin updates skills or the FlyDocs team publishes new versions, every developer gets the update on their next flydocs sync. No manual distribution, no version drift across the team.

The server delivers skills with a monotonic version number. The CLI caches the last-seen version locally and only fetches updates. Workspace-specific rendering means your CLAUDE.md and AGENTS.md always include the correct skills manifest for your workspace.

If you need to modify a managed skill locally (for testing or development), add the path to artifactOverrides.skipPaths in .flydocs/config.json. This prevents sync from overwriting your local changes.

Next