singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
singularity-forge/docs/user-docs/skills.md
Mikael Hugo 62fbc5d57b refactor: align agent resource overlays
2026-05-14 19:32:41 +02:00

9.7 KiB
Raw Blame History

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

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

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