name	using-skills
description	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.

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`

using-skills

Install Skill

SKILL.md