singularity-forge/docs/user-docs/skills.md

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 and are not SF-specific — they work with Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf, and 40+ other agents.

Skill Directories

SF reads skills from two locations, in priority order:

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 skills take precedence over project 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:

# 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. 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:

---
version: 1
always_use_skills:
  - debug-like-expert
prefer_skills:
  - frontend-design
avoid_skills:
  - security-docker
skill_rules:
  - when: task involves Clerk authentication
    use: [clerk]
  - when: frontend styling work
    prefer: [frontend-design]
---

Resolution Order

Skills can be referenced by:

1. Bare name — e.g., frontend-design → 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

Global skills (~/.agents/skills/) take precedence over project skills (.agents/skills/).

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.

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:

---
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.