# Skills

Skills are specialized instruction sets that SF loads when the task matches. They provide domain-specific guidance for the LLM — coding patterns, framework idioms, testing strategies, and tool usage.

Skills follow the open [Agent Skills standard](https://agentskills.io/) and are **not SF-specific** — they work with Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf, and 40+ other agents.

## Skill Directories

SF has three user skill layers:

| Layer | Location | Scope | Description |
|---|---|---|---|
| Bundled user-visible | `src/resources/skills/` | SF product | Built into SF releases. Only `create-skill` is listed as a default user skill. |
| Global | `~/.agents/skills/` | User | Shared across projects and compatible agents. |
| Project | `.agents/skills/` | Repo | Optional project-specific user skills and overrides, committable to version control. |

At runtime, SF resolves user/project skills over bundled defaults when names
collide. This mirrors Copilot-style project skills: `.agents/skills/` is a
repo-owned customization layer, not where SF built-ins live.

For default releases, the only bundled skill shown to users is `create-skill`.
Internal automatic workflow guidance is modeled as hidden system pattern skills
under `src/resources/workflow-skills/`. That directory is intentionally small:
core workflow constraints, SF runtime/planning/state patterns, and automatic
workflow helpers such as `sf-repo-orientation`, `sf-debug-forensics`,
`sf-metric-optimization`, `sf-human-writing`, and `sf-vcs-hygiene`. They use the
`SKILL.md` shape so SF can test and evolve them like Hermes-style pattern
packages, but they are not listed in the user skill catalog.

SF reads user and project skills from these portable locations:

| Location                          | Scope   | Description                                              |
|-----------------------------------|---------|----------------------------------------------------------|
| `~/.agents/skills/`              | Global  | Shared across all projects and all compatible agents     |
| `.agents/skills/` (project root) | Project | Project-specific skills, committable to version control  |

Global/project skills take precedence over bundled skills when names collide.

> **Migration from `~/.sf/agent/skills/`:** On first launch after upgrading, SF automatically copies skills from the legacy `~/.sf/agent/skills/` directory to `~/.agents/skills/`. The old directory is preserved for backward compatibility.

## Installing Skills

Skills are installed via the [skills.sh CLI](https://skills.sh):

```bash
# Interactive — choose skills and target agents
npx skills add dpearson2699/swift-ios-skills

# Install specific skills non-interactively
npx skills add dpearson2699/swift-ios-skills --skill swift-concurrency --skill swiftui-patterns -y

# Install all skills from a repo
npx skills add dpearson2699/swift-ios-skills --all

# Check for updates
npx skills check

# Update installed skills
npx skills update
```

### Onboarding Catalog

During `sf init`, SF detects the project's tech stack and recommends relevant skill packs. For brownfield projects, detection is automatic; for greenfield projects, the user picks a tech stack.

The curated catalog is maintained in `src/resources/extensions/sf/skill-catalog.ts`. Each entry maps a tech stack to a skills.sh repo and specific skill names.

#### Available Skill Packs

**Swift (any Swift project — `Package.swift` or `.xcodeproj` detected):**
- **SwiftUI** — layout, navigation, animations, gestures, Liquid Glass
- **Swift Core** — Swift language, concurrency, Codable, Charts, Testing, SwiftData

**iOS (only when `.xcodeproj` targets `iphoneos` via SDKROOT):**
- **iOS App Frameworks** — App Intents, Widgets, StoreKit, MapKit, Live Activities
- **iOS Data Frameworks** — CloudKit, HealthKit, MusicKit, WeatherKit, Contacts
- **iOS AI & ML** — Core ML, Vision, on-device AI, speech recognition
- **iOS Engineering** — networking, security, accessibility, localization, Instruments
- **iOS Hardware** — Bluetooth, CoreMotion, NFC, PencilKit, RealityKit
- **iOS Platform** — CallKit, EnergyKit, HomeKit, SharePlay, PermissionKit

**Web:**
- **React & Web Frontend** — React best practices, web design, composition patterns
- **React Native** — cross-platform mobile patterns
- **Frontend Design & UX** — frontend design, accessibility

**Languages:**
- **Rust** — Rust patterns and best practices
- **Python** — Python patterns and best practices
- **Go** — Go patterns and best practices

**General:**
- **Document Handling** — PDF, DOCX, XLSX, PPTX creation and manipulation

### Maintaining the Catalog

The skill catalog lives in [`src/resources/extensions/sf/skill-catalog.ts`](../src/resources/extensions/sf/skill-catalog.ts). To add or update a pack:

1. Add a `SkillPack` entry to the `SKILL_CATALOG` array with `repo`, `skills`, and matching criteria
2. For language-detection matching, use `matchLanguages` (values from `detection.ts` `LANGUAGE_MAP`)
3. For Xcode platform matching, use `matchXcodePlatforms` (e.g., `["iphoneos"]` — parsed from `SDKROOT` in `project.pbxproj`)
4. For file-presence matching, use `matchFiles` (checked against `PROJECT_FILES` in `detection.ts`)
5. If the pack should appear in greenfield choices, add it to `GREENFIELD_STACKS`
6. Packs sharing the same `repo` are batched into a single `npx skills add` invocation

## Skill Discovery

The `skill_discovery` preference controls how SF finds skills during autonomous mode:

| Mode | Behavior |
|------|----------|
| `auto` | Skills are found and applied automatically |
| `suggest` | Skills are identified but require confirmation (default) |
| `off` | No skill discovery |

## Skill Preferences

Control which skills are used via preferences:

```yaml
---
version: 1
always_use_skills:
  - my-debug-skill
prefer_skills:
  - my-frontend-skill
avoid_skills:
  - security-docker
skill_rules:
  - when: task involves Clerk authentication
    use: [clerk]
  - when: frontend styling work
    prefer: [my-frontend-skill]
---
```

### Resolution Order

Skills can be referenced by:
1. **Bare name** — e.g., `my-frontend-skill` → scans `~/.agents/skills/` and project `.agents/skills/`
2. **Absolute path** — e.g., `/Users/you/.agents/skills/my-skill/SKILL.md`
3. **Directory path** — e.g., `~/custom-skills/my-skill` → looks for `SKILL.md` inside

Project skills (`.agents/skills/`) take precedence over global skills
(`~/.agents/skills/`) for the same name. Global skills take precedence over
non-locked bundled defaults.

## Custom Skills

Create your own skills by adding a directory with a `SKILL.md` file:

```
~/.agents/skills/my-skill/
  SKILL.md           — instructions for the LLM
  references/        — optional reference files
```

The `SKILL.md` file contains instructions the LLM follows when the skill is active. Reference files can be loaded by the skill instructions as needed.

### Project-Local Skills

Place skills in your project for project-specific guidance:

```
.agents/skills/my-project-skill/
  SKILL.md
```

Project-local skills can be committed to version control so team members share
the same skill set. Do not put SF product-owned workflow guidance here;
product-wide defaults belong in `src/resources/workflow-skills/`. A repo may
still add a same-name `.agents/skills/<name>/SKILL.md` file to override a
non-locked system pattern for that repo.

### Learning and Overrides

SF self-learning is per repo. Runtime evidence, traces, and candidate variants
belong in `.sf` / SQLite first. Reviewed repo-specific improvements are proposed
as `.agents/` overrides. Bundled defaults under `src/resources/` are changed
only when the improvement is generally useful across projects.

### `SKILL.md` and `skill.yaml`

`SKILL.md` is the canonical skill payload. It contains the frontmatter and
Markdown instructions that compatible agents load.

Some projection tools also use `skill.yaml` for resolver metadata such as
activation mode, interface, requirements, or contracts. In SF, that file is
optional compatibility metadata. It should point at `SKILL.md` when present and
must not duplicate or replace the model-facing instructions.

## Skill Lifecycle Management

SF tracks skill performance across autonomous mode sessions and surfaces health data to help you maintain skill quality.

### Skill Telemetry

Every autonomous mode unit records which skills were available and actively loaded. This data is stored in `metrics.json` alongside existing token and cost tracking.

### Skill Health Dashboard

View skill performance with `/skill-health`:

```
/skill-health              # overview table: name, uses, success%, tokens, trend, last used
/skill-health rust-core    # detailed view for one skill
/skill-health --stale 30   # skills unused for 30+ days
/skill-health --declining  # skills with falling success rates
```

The dashboard flags skills that may need attention:
- **Success rate below 70%** over the last 10 uses
- **Token usage rising 20%+** compared to the previous window
- **Stale skills** unused beyond the configured threshold

### Staleness Detection

Skills unused for a configurable number of days are flagged as stale and can be automatically deprioritized:

```yaml
---
skill_staleness_days: 60   # default: 60, set to 0 to disable
---
```

Stale skills are excluded from automatic matching but remain invokable explicitly via `read`.

### Heal-Skill (Post-Unit Analysis)

When configured as a post-unit hook, SF can analyze whether the agent deviated from a skill's instructions during execution. If significant drift is detected (outdated API patterns, incorrect guidance), it writes proposed fixes to `.sf/skill-review-queue.md` for human review.

Key design principle: skills are **never auto-modified**. Research shows curated skills outperform auto-generated ones significantly, so the human review step is critical.
