<overview>
SF-specific skill ecosystem details: directory conventions, discovery mechanics, telemetry, and health monitoring. Read this reference when creating or auditing skills within SF.
</overview>

<skill_directories>
SF discovers skills from two `.agents/` overlay roots:

**User-scope (global):**
- `~/.agents/skills/` — industry-standard ecosystem path (skills.sh and similar registries install here)
Available in every SF session regardless of working directory.

**Project-scope (local):**
- `<project>/.agents/skills/` — project-scoped industry-standard
Available only when SF runs inside the project directory. Use this only for
repo-specific overrides or additions.

Skills in both directories follow the same SKILL.md format and router pattern
conventions. SF does NOT use `~/.sf/agent/skills/`, `.pi/agent/skills/`, or
`.claude/skills/` for skill discovery.

Workflow-internal skills that are not meant to be modified or used directly
belong in bundled SF resources and should be locked there. Do not create
repo-local `.agents/skills/` entries for those paths unless the user explicitly
wants a repo override.
</skill_directories>

<skill_discovery>
SF auto-discovers skills at session start and during autonomous mode:

**Session start:** Skills in the `.agents/` overlay roots are enumerated and their names + descriptions are injected into the system prompt as `<available_skills>`.

**Autonomous mode discovery:** `skill-discovery.ts` takes a snapshot of the skills directories at autonomous mode start. On each unit boundary it diffs against the snapshot. Any new skills found are injected via a `<newly_discovered_skills>` XML block so the LLM sees them without requiring `/reload`.

**Manual reload:** Running `/reload` re-scans the `.agents/` overlay roots and updates the available skills list mid-session.
</skill_discovery>

<skill_validation>
Skill metadata has validation constraints:

- **name:** lowercase letters, numbers, and hyphens only. Maximum 64 characters. Must match directory name exactly. No reserved words ("anthropic", "claude").
- **description:** Non-empty, maximum 1024 characters. No XML tags. Third person voice. Must state what it does AND when to use it.
</skill_validation>

<skill_telemetry>
`skill-telemetry.ts` tracks per-skill usage:

- **Read count:** How often each skill is loaded
- **Last used timestamp:** When the skill was most recently invoked
- **Staleness detection:** Skills unused for 60+ days are flagged as stale
- **Pass/fail rates:** Derived from unit completion status when a skill is active

Telemetry data is stored per-project in `<project>/.sf/metrics.json` alongside other SF metrics.
</skill_telemetry>

<skill_health>
`skill-health.ts` aggregates telemetry into actionable health reports:

- **Success rate:** Units with this skill that completed without retry
- **Token trend:** Whether token usage per invocation is stable, rising, or declining
- **Staleness:** Days since last use, flagged at 60+ days
- **Flagging thresholds:**
  - Success rate below 70% → flagged for review
  - Rising token trend → flagged (may indicate skill drift or bloat)
  - 60+ days stale → flagged

The `/sf doctor` command surfaces skill health issues alongside other system diagnostics.
</skill_health>

<activation>
After creating or modifying a skill:

1. Run `/reload` to make it available in the current session
2. On next session start, auto-discovery picks it up automatically
3. In autonomous mode, new skills are detected at unit boundaries without any action needed
</activation>
