Using Skills
Skills are composable workflows that guide your behavior for specific tasks.
Announce: "I'm checking available skills to determine the right approach."
Quick Reference
| Trigger |
Skill to Load |
| Bug, error, unexpected behavior |
systematic-debugging |
| New feature or behavior change |
openspec-check |
| Any code writing |
testing |
| Complex or vague request |
brainstorming |
| Dispatching subagent work |
subagent-workflow |
| Implementing approved change |
openspec-apply |
| Working through task list |
executing-tasks |
| Quick self-review |
code-review |
| Improve agent config |
config-tuning |
Skill Categories
Planning Skills (Interactive - ASK User)
Load these when you need to clarify, design, or get approval BEFORE implementation.
| Skill |
When to Load |
brainstorming |
Request is vague, complex, or needs design exploration |
openspec-check |
Before ANY implementation - check if specs exist |
openspec-propose |
New feature, behavioral change, or architecture modification |
task-planning |
Breaking approved work into implementable tasks |
config-tuning |
User notices a pattern that should be in config |
Key behavior: These skills ASK questions and WAIT for approval.
Execution Skills (Strict - FOLLOW Plan)
Load these when you have approved work to implement.
| Skill |
When to Load |
openspec-apply |
Implementing an approved OpenSpec change |
testing |
Writing ANY code (test first, always) |
executing-tasks |
Working through a task checklist |
Key behavior: These skills FOLLOW the plan exactly. No deviations.
Investigation Skills (Gather Info - REPORT)
Load these when you need to understand something before acting.
| Skill |
When to Load |
systematic-debugging |
Bug, test failure, unexpected behavior |
code-review |
After implementation, before commit |
Key behavior: These skills INVESTIGATE and REPORT. They don't fix.
Workflow Skills
Load these for orchestration patterns.
| Skill |
When to Load |
subagent-workflow |
Dispatching or recalling subagents |
knowledge-sync |
After major refactors, update skills with new patterns |
Domain Skills
Load these for project-specific patterns. They provide code examples and anti-patterns.
Foundation
| Skill |
When to Load |
database-first |
ANY database work - iron law: all logic in PostgreSQL |
codebase-conventions |
File structure, naming, constraints |
Database
| Skill |
When to Load |
postgres-vectors |
Embeddings, similarity search, pgvector operators |
postgis-spatial |
Geographic queries, ST_* functions, regions |
game-scoring |
Candidate scoring, confidence, softmax aggregation |
trait-learning |
Trait extraction, learning loop, LLM prompts |
Frontend
| Skill |
When to Load |
vue-composables |
useX patterns, Pinia stores, withLoadingState |
maplibre-camera |
Camera movements, flyTo, animations |
maplibre-layers |
GeoJSON sources, layer styling, events |
shadcn-vue |
UI components, forms, dialogs |
Edge Functions
| Skill |
When to Load |
edge-functions |
Deno patterns, LLM calls, embeddings |
Testing
| Skill |
When to Load |
gameplay-sql |
Test game via database tools (game_start, game_turn) |
gameplay-browser |
Test game via browser with Chrome DevTools |
How Skills Chain
Skills reference each other with REQUIRED SUB-SKILL: markers.
Example flow:
- User asks for feature -> load
openspec-check
- No spec exists ->
openspec-check says load openspec-propose
- Proposal approved -> load
task-planning
- Tasks ready -> load
openspec-apply + testing
- Implementation done -> load
code-review
Iron Law
ANNOUNCE WHICH SKILL YOU'RE USING BEFORE STARTING
Format: "I'm using [skill] to [what you're doing]."
Selecting Skills
Ask yourself:
- Am I planning or executing? -> Planning skills ask, execution skills follow
- Is this a new feature or existing behavior? -> New = check specs first
- Am I writing code? -> Always load
testing
- Am I investigating or fixing? -> Investigate first, then fix
- Does this involve database/frontend/edge? -> Load domain skill
When in doubt, load openspec-check first - it will guide you to the right path.
Domain Skill Selection Guide
| Task |
Primary Skill |
Also Consider |
| Vector similarity query |
postgres-vectors |
game-scoring |
| Geographic filtering |
postgis-spatial |
|
| Candidate ranking |
game-scoring |
postgres-vectors |
| New trait extraction |
trait-learning |
edge-functions |
| Map camera animation |
maplibre-camera |
|
| Map markers/layers |
maplibre-layers |
|
| Vue reactive state |
vue-composables |
|
| Pinia store |
vue-composables |
database-first |
| UI component |
shadcn-vue |
|
| LLM integration |
edge-functions |
trait-learning |
| Manual game testing |
gameplay-sql |
gameplay-browser |
1---2name: using-skills3description: Load at session start or when unsure which skill applies. Explains available skills and when to use each. Check this to understand the skill system.4---56# Using Skills78Skills are composable workflows that guide your behavior for specific tasks.910> **Announce:** "I'm checking available skills to determine the right approach."1112## Quick Reference1314| Trigger | Skill to Load |15|---------|---------------|16| Bug, error, unexpected behavior | `systematic-debugging` |17| New feature or behavior change | `openspec-check` |18| Any code writing | `testing` |19| Complex or vague request | `brainstorming` |20| Dispatching subagent work | `subagent-workflow` |21| Implementing approved change | `openspec-apply` |22| Working through task list | `executing-tasks` |23| Quick self-review | `code-review` |24| Improve agent config | `config-tuning` |2526## Skill Categories2728### Planning Skills (Interactive - ASK User)2930Load these when you need to clarify, design, or get approval BEFORE implementation.3132| Skill | When to Load |33|-------|--------------|34| `brainstorming` | Request is vague, complex, or needs design exploration |35| `openspec-check` | Before ANY implementation - check if specs exist |36| `openspec-propose` | New feature, behavioral change, or architecture modification |37| `task-planning` | Breaking approved work into implementable tasks |38| `config-tuning` | User notices a pattern that should be in config |3940**Key behavior:** These skills ASK questions and WAIT for approval.4142### Execution Skills (Strict - FOLLOW Plan)4344Load these when you have approved work to implement.4546| Skill | When to Load |47|-------|--------------|48| `openspec-apply` | Implementing an approved OpenSpec change |49| `testing` | Writing ANY code (test first, always) |50| `executing-tasks` | Working through a task checklist |5152**Key behavior:** These skills FOLLOW the plan exactly. No deviations.5354### Investigation Skills (Gather Info - REPORT)5556Load these when you need to understand something before acting.5758| Skill | When to Load |59|-------|--------------|60| `systematic-debugging` | Bug, test failure, unexpected behavior |61| `code-review` | After implementation, before commit |6263**Key behavior:** These skills INVESTIGATE and REPORT. They don't fix.6465### Workflow Skills6667Load these for orchestration patterns.6869| Skill | When to Load |70|-------|--------------|71| `subagent-workflow` | Dispatching or recalling subagents |72| `knowledge-sync` | After major refactors, update skills with new patterns |7374## Domain Skills7576Load these for project-specific patterns. They provide code examples and anti-patterns.7778### Foundation7980| Skill | When to Load |81|-------|--------------|82| `database-first` | ANY database work - iron law: all logic in PostgreSQL |83| `codebase-conventions` | File structure, naming, constraints |8485### Database8687| Skill | When to Load |88|-------|--------------|89| `postgres-vectors` | Embeddings, similarity search, pgvector operators |90| `postgis-spatial` | Geographic queries, ST_* functions, regions |91| `game-scoring` | Candidate scoring, confidence, softmax aggregation |92| `trait-learning` | Trait extraction, learning loop, LLM prompts |9394### Frontend9596| Skill | When to Load |97|-------|--------------|98| `vue-composables` | useX patterns, Pinia stores, withLoadingState |99| `maplibre-camera` | Camera movements, flyTo, animations |100| `maplibre-layers` | GeoJSON sources, layer styling, events |101| `shadcn-vue` | UI components, forms, dialogs |102103### Edge Functions104105| Skill | When to Load |106|-------|--------------|107| `edge-functions` | Deno patterns, LLM calls, embeddings |108109### Testing110111| Skill | When to Load |112|-------|--------------|113| `gameplay-sql` | Test game via database tools (game_start, game_turn) |114| `gameplay-browser` | Test game via browser with Chrome DevTools |115116## How Skills Chain117118Skills reference each other with `REQUIRED SUB-SKILL:` markers.119120Example flow:1211. User asks for feature -> load `openspec-check`1222. No spec exists -> `openspec-check` says load `openspec-propose`1233. Proposal approved -> load `task-planning`1244. Tasks ready -> load `openspec-apply` + `testing`1255. Implementation done -> load `code-review`126127## Iron Law128129```130ANNOUNCE WHICH SKILL YOU'RE USING BEFORE STARTING131```132133Format: "I'm using [skill] to [what you're doing]."134135## Selecting Skills136137Ask yourself:1381. Am I planning or executing? -> Planning skills ask, execution skills follow1392. Is this a new feature or existing behavior? -> New = check specs first1403. Am I writing code? -> Always load `testing`1414. Am I investigating or fixing? -> Investigate first, then fix1425. Does this involve database/frontend/edge? -> Load domain skill143144When in doubt, load `openspec-check` first - it will guide you to the right path.145146## Domain Skill Selection Guide147148| Task | Primary Skill | Also Consider |149|------|--------------|---------------|150| Vector similarity query | `postgres-vectors` | `game-scoring` |151| Geographic filtering | `postgis-spatial` | |152| Candidate ranking | `game-scoring` | `postgres-vectors` |153| New trait extraction | `trait-learning` | `edge-functions` |154| Map camera animation | `maplibre-camera` | |155| Map markers/layers | `maplibre-layers` | |156| Vue reactive state | `vue-composables` | |157| Pinia store | `vue-composables` | `database-first` |158| UI component | `shadcn-vue` | |159| LLM integration | `edge-functions` | `trait-learning` |160| Manual game testing | `gameplay-sql` | `gameplay-browser` |
Freddy-CHEN-ux