18a0abbfe3
Update README and docs/ to cover new features and changes in v2.20.0: - commands.md: Added /gsd quick, /gsd mode, /gsd help, /gsd skill-health, /gsd hooks, /gsd run-hook, gsd --debug flag. Reorganized into Session Commands, Configuration & Diagnostics, Git, and Session Management. - skills.md: Added Skill Lifecycle Management section covering telemetry, health dashboard (/gsd skill-health), staleness detection, and heal-skill post-unit analysis. - remote-questions.md: Added Telegram as a third channel alongside Slack and Discord, with setup instructions and bot requirements. - configuration.md: Added skill_staleness_days preference. - README.md: Added skill_staleness_days to key settings table, new Agent Instructions section, and Debug Mode section.
126 lines
5 KiB
Markdown
126 lines
5 KiB
Markdown
# Skills
|
|
|
|
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.
|
|
|
|
## Bundled Skills
|
|
|
|
GSD ships with these skills, installed to `~/.gsd/agent/skills/`:
|
|
|
|
| Skill | Trigger | Description |
|
|
|-------|---------|-------------|
|
|
| `frontend-design` | Web UI work — components, pages, dashboards, styling | Production-grade frontend with high design quality |
|
|
| `swiftui` | macOS/iOS apps — SwiftUI, Xcode, App Store | Full lifecycle from creation to shipping |
|
|
| `debug-like-expert` | Complex debugging — after standard approaches fail | Methodical investigation with evidence gathering |
|
|
| `rust-core` | Rust code — ownership, lifetimes, traits, async | Idiomatic, safe, performant Rust patterns |
|
|
| `axum-web-framework` | Axum web apps — routing, middleware, extractors | Complete Axum development guide |
|
|
| `axum-tests` | Testing Axum apps — integration tests, mock state | Test patterns for Axum applications |
|
|
| `tauri` | Tauri v2 desktop apps — setup, plugins, bundling | Cross-platform desktop app development |
|
|
| `tauri-ipc-developer` | Tauri IPC — React-Rust type-safe communication | Command scaffolding and serialization |
|
|
| `tauri-devtools` | Tauri debugging — CrabNebula DevTools integration | Profiling and monitoring |
|
|
| `github-workflows` | GitHub Actions — CI/CD, workflow debugging | Live syntax, run monitoring, failure diagnosis |
|
|
| `security-audit` | Security auditing — dependency scanning, OWASP | Comprehensive security assessment |
|
|
| `security-review` | Code security review — injection, XSS, auth flaws | Vulnerability-focused code review |
|
|
| `security-docker` | Docker security — Dockerfile, runtime hardening | Container security best practices |
|
|
|
|
## Skill Discovery
|
|
|
|
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 |
|
|
|
|
## Skill Preferences
|
|
|
|
Control which skills are used via preferences:
|
|
|
|
```yaml
|
|
---
|
|
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 `~/.gsd/agent/skills/` and project skills
|
|
2. **Absolute path** — e.g., `/Users/you/.gsd/agent/skills/my-skill/SKILL.md`
|
|
3. **Directory path** — e.g., `~/custom-skills/my-skill` → looks for `SKILL.md` inside
|
|
|
|
User skills (`~/.gsd/agent/skills/`) take precedence over project skills.
|
|
|
|
## Custom Skills
|
|
|
|
Create your own skills by adding a directory with a `SKILL.md` file:
|
|
|
|
```
|
|
~/.gsd/agent/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:
|
|
|
|
```
|
|
.pi/agent/skills/my-project-skill/
|
|
SKILL.md
|
|
```
|
|
|
|
## Skill Lifecycle Management
|
|
|
|
GSD tracks skill performance across auto-mode sessions and surfaces health data to help you maintain skill quality.
|
|
|
|
### Skill Telemetry
|
|
|
|
Every auto-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 `/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 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, 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.
|