Skills

Skills are portable, composable knowledge modules. Each skill is a directory containing a SKILL.md overview, optional section files, and optional executable scripts. They encode methodology, coding patterns, and tool integrations into units the AI discovers on demand and loads through progressive disclosure.

Two Types of Skills

Skills come in two distinct types, and the distinction matters.

Passive skills are knowledge-only. Markdown patterns, coding standards, architectural guidance that the AI consults before writing code. Think TypeScript strictness rules, testing patterns, component conventions. They solve the knowledge problem: getting the right project context to the AI efficiently.

Active skills add executable scripts. They handle PM integration, issue tracking, status transitions, and any external service interaction. They solve the tool integration problem: replacing MCP servers with something lighter, faster, and more consistent.

Both types are discovered through the same compressed manifest and loaded through the same progressive disclosure pipeline. The AI does not treat them differently during discovery. It finds the skill, reads the overview, then either follows guidance (passive) or runs a script (active).

Passive Skill Example

# TypeScript Strict

TypeScript strict mode patterns and type safety. Use when writing
TypeScript code, reviewing types, or fixing type errors. Enforces
no-any policy with proper narrowing patterns.

## Patterns

| Pattern | When to Use | File |
|---------|-------------|------|
| Type guards | Narrowing unknown values | patterns/type-guards.md |
| Schema validation | Validating external data | patterns/schema-validation.md |

Active Skill Example

# FlyDocs Cloud

Connected issue management via Linear GraphQL API.

## Scripts

| Script | Purpose |
|--------|---------|
| create_issue.py | Create a new issue |
| transition.py | Move issue to a new status |
| comment.py | Add a comment to an issue |
| list_issues.py | List issues with filters |
| assign.py | Assign an issue to a team member |

When the AI needs to transition an issue, it runs the script directly:

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

Same command, same arguments, same output, every time. No schema interpretation, no improvisation. See how active skills replace MCP servers.

Skill Anatomy

Every skill lives in a directory under .claude/skills/:

.claude/skills/typescript-strict/
├── SKILL.md          # Overview: when to use, key patterns, triggers
├── patterns/         # Detailed pattern files (loaded on demand)
│   ├── type-guards.md
│   └── schema-validation.md
└── scripts/          # Executable utilities (active skills only)

The SKILL.md is always present. It describes when to use the skill, what it provides, and where to find detail. Section files break the content into focused chunks that the AI loads only when relevant. Scripts (if present) make it an active skill.

Skill Tiers

Skills are organized into tiers based on how they are installed and what they provide:

The Required tier includes both types: the workflow skill is passive (it defines methodology as knowledge), while the mechanism skill is active (it bundles the scripts for issue tracking, status transitions, and PM integration). Behavioral and stack-specific skills are typically passive. They encode patterns, not tool access. Community and premium skills can be either, depending on whether they provide knowledge, scripts, or both.

Intent / Mechanism Separation

The workflow skill (intent) defines the development lifecycle. It references scripts by name ("call transition.py to move to Review") without knowing or caring what transition.py does internally.

# Implement Stage

## Procedure
1. Read the issue spec and acceptance criteria
2. Create a branch from main
3. Build incrementally — commit at each milestone
4. Call `transition.py` to move to Review when done
5. Call `comment.py` to document what was built

The mechanism skill implements those scripts:

• flydocs-local (free): scripts move markdown files between status folders
• flydocs-cloud (paid): scripts call the FlyDocs relay API, which routes to Linear (Jira and GitHub Issues coming soon)

Both mechanisms expose the same interface: same script names, same arguments, same output format. Swapping from local to cloud requires changing one config value. The workflow does not change.

Progressive Disclosure

Skills are not dumped into context wholesale. They load through a three-level retrieval system designed for how LLMs actually process information:

The AI never loads all skills at once. It sees the compressed index, identifies which skill is relevant, reads the overview, then reads only the section it needs. Total context for a single task stays under 2KB, a fraction of what a single MCP tool description set consumes.

The Skill Manifest

The manifest is a compressed index that lives in always-loaded context (AGENTS.md or CLAUDE.md). It maps trigger terms to skill entry points:

## Skills Index

IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
Consult the relevant skill BEFORE writing code or making workflow decisions.

| Skill | Triggers | Entry |
|-------|----------|-------|
| flydocs-cloud | create issue, transition, comment, assign | .claude/skills/flydocs-cloud/SKILL.md |
| typescript-strict | TypeScript, types, strict mode, narrowing | .claude/skills/typescript-strict/SKILL.md |
| testing-patterns | test, coverage, vitest, testing library | .claude/skills/testing-patterns/SKILL.md |

A single instruction, "Prefer skill-led reasoning over pre-training reasoning," shifts the AI from guessing based on training data to consulting project-specific skills first. Simple to state, outsized impact.

Skills vs MCPs

MCP servers are the current standard way to connect AI to external services. Active skills do the same thing, without the running server, the context overhead, or the inconsistent execution.

The key difference: 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 a deterministic command and gets a predictable result, rather than interpreting a tool schema and improvising.

Deep dive: how active skills replace MCP servers.

Best Practices

1. One skill, one domain. A skill that covers TypeScript patterns and deployment workflows is doing too much. Split them.
2. Clear triggers. The manifest maps trigger terms to skills. If the triggers are vague, the AI will not find the skill when it matters.
3. Small section files. Each section file should be 30-80 lines. If a file exceeds 100 lines, break it into smaller sections. Progressive disclosure only works when the pieces are focused.
4. Document when to use, not just what it does. SKILL.md should make the decision to load the skill obvious. The AI needs to know when, not just what.

Related Concepts

• Rules: persistent AI guidance (advisory, not methodological)
• Hooks: deterministic enforcement that fires regardless of what the AI decides
• Active Skills Deep Dive: architecture and execution model
• Hooks & Guardrails: how hooks enforce what skills recommend