# FlyDocs Skills

> Authoritative guide for skill architecture, authoring, and structure.

---

## Skill Categories

### `flydocs-*` — Platform Skills

Owned and maintained by FlyDocs. May include executable scripts and premium
functionality gated via API relay.

| Skill              | Purpose                                                                      |
| ------------------ | ---------------------------------------------------------------------------- |
| `flydocs-workflow` | Unified skill — lifecycle, issues, projects, Figma, estimates, context graph |

All functionality consolidated into a single skill. Tier (local vs cloud) is
auto-detected from `.flydocs/config.json` — no separate mechanism skills.

### Unprefixed — Community Skills

Stack-detected or manually installed. Pure guidance (markdown only, no scripts).
Portable across projects and AI coding tools.

```bash
flydocs skills search typescript
flydocs skills add <repo>
flydocs skills list
```

Examples: `typescript-strict`, `testing-patterns`, `accessibility-patterns`,
`react-best-practices`, `convex-patterns`

Browse: [skills.sh](https://skills.sh/)

---

## Skill Authoring Standard

### Directory Structure

```
.claude/skills/{skill-name}/
├── SKILL.md             # Required — main skill file
├── cursor-rule.mdc      # Optional — condensed Cursor rule
├── scripts/             # Platform skills only — executable scripts
└── reference/           # Optional — supporting detail files
```

- **`skill-name`** uses kebab-case. Platform skills use the `flydocs-` prefix.
- **`SKILL.md`** is the entry point. Agents read this first.
- **`cursor-rule.mdc`** is a condensed version for Cursor IDE, installed by
  `flydocs skills add`. See Cursor Rules below. FlyDocs' own workflow rule is
  not authored here — it ships from `template/.cursor/rules/` with the rest of
  the Cursor tree (FLY-1275).
- **`scripts/`** contains executable scripts. Only `flydocs-*` platform skills include scripts.
- **`reference/`** holds detail files referenced by SKILL.md for progressive disclosure.

### SKILL.md Frontmatter

Every SKILL.md starts with YAML frontmatter:

```yaml
---
name: typescript-strict
description: >
  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.
triggers:
  - TypeScript
  - type error
  - any type
  - type guard
  - schema validation
---
```

**Required fields:**

| Field         | Type   | Purpose                                                                                                           |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `name`        | string | Skill identifier, matches directory name                                                                          |
| `description` | string | What the skill does and when to use it. Agents use this for auto-selection. Be specific about trigger conditions. |

**Optional fields:**

| Field      | Type     | Purpose                                                                                                                   |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `triggers` | string[] | Keywords/phrases for manifest indexing. Used by skill discovery to build the always-present index in CLAUDE.md/AGENTS.md. |
| `tools`    | string   | Comma-separated tools the skill uses (e.g., `WebFetch`, `Bash`)                                                           |

### SKILL.md Body

The body serves as a **compressed index** — not a documentation dump. Target ~100-150 lines.

**Structure pattern:**

```markdown
# Skill Name

Use this skill when performing [domain]-specific operations.
For general coding, skip this — just write code.

## Key Rules (always apply)

1. Rule one
2. Rule two

## Section Index

| Topic   | File                 | When to Read |
| ------- | -------------------- | ------------ |
| Topic A | reference/topic-a.md | When doing X |
| Topic B | reference/topic-b.md | When doing Y |

## Quick Reference (inline essentials)

[Most-referenced patterns, tables, or checklists that agents need
frequently enough to justify being in the index file]
```

**Principles:**

1. **Index, don't dump.** SKILL.md points to detail files. Agents read only what they need.
2. **Front-load rules.** Put golden rules and constraints at the top. Agents are more likely to follow instructions they encounter early.
3. **Concrete over abstract.** Use specific examples, code snippets, and file paths. Avoid vague guidance like "follow best practices."
4. **Trigger-aware descriptions.** The `description` field is how agents decide whether to load the skill. Include the exact scenarios and keywords that should trigger it.

### Progressive Disclosure

Skills use a three-level retrieval pattern (see ADR-004):

```
Level 1: Manifest in CLAUDE.md/AGENTS.md
          → Agent sees skill exists, knows triggers and entry point

Level 2: SKILL.md
          → Compressed index with key rules and section pointers

Level 3: reference/ files
          → Full detail, read only when needed for the specific task
```

This keeps context usage minimal while ensuring agents can always find relevant guidance.

**Line budgets:**

| File             | Target           | Max       |
| ---------------- | ---------------- | --------- |
| SKILL.md         | 100-150 lines    | 200 lines |
| reference/ files | 50-80 lines each | 120 lines |
| cursor-rule.mdc  | 30-50 lines      | 70 lines  |

### Cursor Rules (cursor-rule.mdc)

Optional. A condensed version of the skill for Cursor IDE, placed in
`.cursor/rules/` during install. Uses Cursor's frontmatter format:

```yaml
---
description: Short description of what this rule covers
globs: "*.ts,*.tsx"
alwaysApply: false
---
<!-- Condensed from SKILL.md — update both when changing patterns -->
```

**Frontmatter fields:**

| Field         | Type    | Notes                                                   |
| ------------- | ------- | ------------------------------------------------------- |
| `description` | string  | Required. What the rule covers.                         |
| `globs`       | string  | File patterns that trigger the rule. Comma-separated.   |
| `alwaysApply` | boolean | If `true`, rule loads for every prompt (use sparingly). |

Use `alwaysApply: true` only for workflow/process rules. Pattern skills should
use `globs` to activate only on relevant file types.

---

## Manifest System

When skills are installed, a compressed manifest is auto-generated in
CLAUDE.md and AGENTS.md between markers:

```markdown
<!-- flydocs:skills-manifest:start -->

## Skills Index

Consult the workflow skill for **issue operations and status transitions only**.
For general coding tasks, skip this — just write code.

| Skill             | Triggers                                      | Entry                                     |
| ----------------- | --------------------------------------------- | ----------------------------------------- |
| flydocs-workflow  | create issue, transition, assign, close issue | .claude/skills/flydocs-workflow/SKILL.md  |
| typescript-strict | TypeScript, type error, any type              | .claude/skills/typescript-strict/SKILL.md |

<!-- flydocs:skills-manifest:end -->
```

The manifest is generated from SKILL.md frontmatter (`name`, `triggers`).
It provides always-present discovery so agents don't need to guess which
skills exist. See ADR-004 for the full design rationale.

---

## Minimal Skill Template

Copy this to create a new community skill:

```
.claude/skills/my-skill/
├── SKILL.md
└── reference/           # optional
    └── patterns.md
```

**SKILL.md:**

```markdown
---
name: my-skill
description: >
  [What this skill teaches]. Use when [specific trigger conditions].
  [Technology/domain] patterns for [outcome].
triggers:
  - keyword1
  - keyword2
  - keyword3
---

# My Skill

## Key Rules

1. [Most important rule]
2. [Second most important rule]
3. [Third most important rule]

## Patterns

### [Pattern Name]

[Code example or guidance]

### [Pattern Name]

[Code example or guidance]

## Reference

For detailed patterns, see `reference/patterns.md`.
```

---

## Operation Model

Agents address operations by ID — `flydocs run issue.create`,
`flydocs run workspace.validate` — never by script path. IDs are stable; the
mapping to a script is internal and free to move.

| Domain       | Operations                                                    |
| ------------ | ------------------------------------------------------------- |
| `issue.*`    | create, get, list, transition, assign, update, comment, audit |
| `project.*`  | list, create, update, archive (plus `milestone.*`, `sprint.*`) |
| `workspace.*`| validate, labels, statuses, teams, config, identity           |
| `session.*`  | start-context, list-issues, wrap, project-update              |

Underneath, each maps to a grouped dispatcher script in
`flydocs-workflow/scripts/`. The unified client (`flydocs_api.py`) auto-detects
tier from `.flydocs/config.json` — nothing on this path checks tier directly.

---

## Platform Support

| Platform       | Skill Location        | Notes                                  |
| -------------- | --------------------- | -------------------------------------- |
| Claude Code    | `.claude/skills/`     | Native support                         |
| Cursor         | `.cursor/rules/*.mdc` | Shipped from `template/.cursor/rules/` |
| Codex / Others | `AGENTS.md`           | Universal layer via manifest           |

---

## Resources

- **Skills ecosystem:** [skills.sh](https://skills.sh/)
- **Agent Skills spec:** [agentskills.io](https://agentskills.io)
- **Discovery design:** `flydocs/knowledge/decisions/004-skill-discovery-and-indexing.md`