Skills are specialized instruction sets that GSD 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 GSD-specific — they work with Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf, and 40+ other agents.
GSD reads skills from these locations:
| Location | Scope | Description |
|---|---|---|
~/.gsd/agent/skills/ |
Bundled | GSD-managed bundled skills synced during install/update |
~/.agents/skills/ |
Global | User-global skills shared across compatible agents |
.agents/skills/ (project root) |
Project | Project-specific skills, committable to version control |
~/.claude/skills/ |
Compat | Claude Code compatibility source, lower priority |
.claude/skills/ (project root) |
Compat | Project-local Claude Code compatibility source |
On name collisions project skills (.gsd/skills/, .agents/skills/) win over bundled GSD skills, and bundled GSD skills win over user-global (~/.agents/skills/) and Claude compatibility directories.
Project directories resolve against the session's current working directory. Only .agents/skills/ is discovered from ancestor directories (nearest first, up to the nearest enclosing directory containing a .git entry — or the filesystem root when there is none); .gsd/skills/ and .claude/skills/ are read from the working directory itself. Subagent children scan from the child's own working directory — see Skills In Child Sessions.
Bundled vs user skills: GSD bundled skills are managed in
~/.gsd/agent/skills/. Install your own shared skills into~/.agents/skills/, or commit project-specific skills under.agents/skills/.
GSD omits legacy gsd-* skills supplied by the separate
@opengsd/gsd-core v1 runtime. This applies to package checkouts and copied
installer layouts, including skills reached through symlinks. Unrelated skills
in the same location and independently authored gsd-* skills remain
available.
The managed gsd-browser skill is package-owned: on startup GSD installs it
from the installed @opengsd/gsd-browser package, including referenced support
files under docs/, scripts/, and gsd-browser-skill/. GSD refreshes stale
or incomplete copies in ~/.gsd/agent/skills/gsd-browser/, so do not edit that
managed directory directly.
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 updateDuring gsd init, GSD 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. If the project is already initialized, run gsd init again and choose Suggest & install skills from the "Already Initialized" menu.
The curated catalog is maintained in src/resources/extensions/gsd/skill-catalog.ts. Each entry maps a tech stack to a skills.sh repo and specific skill names.
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
The skill catalog lives in src/resources/extensions/gsd/skill-catalog.ts. To add or update a pack:
- Add a
SkillPackentry to theSKILL_CATALOGarray withrepo,skills, and matching criteria - For language-detection matching, use
matchLanguages(values fromdetection.tsLANGUAGE_MAP) - For Xcode platform matching, use
matchXcodePlatforms(e.g.,["iphoneos"]— parsed fromSDKROOTinproject.pbxproj) - For file-presence matching, use
matchFiles(checked againstPROJECT_FILESindetection.ts) - If the pack should appear in greenfield choices, add it to
GREENFIELD_STACKS - Packs sharing the same
repoare batched into a singlenpx skills addinvocation
The skill_discovery preference controls how GSD finds skills during auto mode:
| Mode | Behavior |
|---|---|
auto |
Skills are found and applied automatically |
suggest |
Skills are identified but require confirmation (default) |
off |
No skill discovery |
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]
---Skills can be referenced by:
- Bare name — e.g.,
frontend-design→ scans the skill directories above in priority order - Absolute path — e.g.,
/Users/you/.agents/skills/my-skill/SKILL.md - Directory path — e.g.,
~/custom-skills/my-skill→ looks forSKILL.mdinside
Project skills (.agents/skills/) take precedence over bundled skills (~/.gsd/agent/skills/), which take precedence over user-global (~/.agents/skills/) and Claude compatibility directories.
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.
SKILL.md frontmatter must be valid YAML. Quote description values that contain
YAML-sensitive characters such as : or use a folded block (description: >)
for longer trigger descriptions.
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.
GSD tracks skill performance across auto-mode sessions and surfaces health data to help you maintain skill quality.
Every auto-mode unit records which skills were available. This data is stored in metrics.json alongside existing token and cost tracking. The recorded skills list reflects catalog availability at dispatch, not verified per-skill reads, and it describes the parent unit — not any subagent child it delegated to.
View skill performance with /gsd skill-health:
/gsd skill-health # overview table: name, uses, success%, tokens, trend, last used
/gsd skill-health rust-core # detailed view for one skill
/gsd skill-health --stale 30 # skills unused for 30+ days
/gsd skill-health --declining # skills with falling success ratesThe 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
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.
When configured as a post-unit hook, GSD 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 .gsd/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.