# OpenCode Skills - 3-Tier Organization

**Last Updated:** 2025-11-15

## Overview

Skills are organized into **3 tiers** based on usage frequency and context:

```
Tier 1: CORE (9 skills) - Always available, used every session
Tier 2: STACK (6 skills) - Context auto-load, used 2-4x/week
Tier 3: SPECIALIZED (10 skills) - Manual activation, project-specific
```

---

## Tier 1: Core Skills

**Auto-load:** Session start  
**Count:** 9 skills  
**Usage:** Every development session

Located in `core/`:

- memory - Persistent context management
- code-review - Quality gates and verification
- debugging - Error investigation
- problem-solving - When-stuck dispatcher
- sequential-thinking - Complex reasoning
- docs-seeker - Documentation lookup
- databases - SQL/MongoDB operations
- ledgers - Session execution tracking
- devops - Docker, CI/CD, deployment

**Why core:** Used in every session, cross-project utility, workflow infrastructure.

---

## Tier 2: Stack Skills

**Auto-load:** Context-aware (file types, tech detection)  
**Count:** 6 skills  
**Usage:** 2-4 times/week

Located in `stack/`:

- web-frameworks - Next.js, Turborepo, React
- frontend-design - Tailwind, shadcn/ui, design principles (MERGED)
- better-auth - Authentication frameworks (PROMOTED)
- document-skills - PDF, XLSX, DOCX, PPTX
- ai-multimodal - Image/video/audio with Gemini
- media-processing - FFmpeg, ImageMagick

**Why stack:** Highly common in modern solo dev stacks, context-aware auto-load.

**Auto-load triggers:**

- frontend-design: `.tsx`, `.jsx`, `.css` files
- web-frameworks: `next.config.js`, `.tsx` files
- databases: `.sql`, `.prisma` files
- devops: `Dockerfile`, `.github/workflows`
- better-auth: `auth`, `login` mentions
- ai-multimodal: `.mp4`, `.png`, `.jpg`, `.pdf`, `.wav` files

---

## Tier 3: Specialized Skills

**Auto-load:** Manual only  
**Count:** 10 skills  
**Usage:** Project-specific, episodic

Located in `specialized/`:

**Framework-Specific:**

- htmx-spring-boot - Server-side rendering with HTMX
- thymeleaf - Spring Boot templating
- shopify - Shopify app development

**Tool Builders:**

- mcp-builder - Build MCP servers
- skill-creator - Create new skills
- repomix - Repository packaging
- template-skill - Skill creation template

**Developer Tools:**

- chrome-devtools - Browser automation
- google-adk-python - Google ADK agents

**Community/Domain:**

- opencode-community - OpenCodeKit community management

**Why specialized:** Excellent tools but not part of standard workflow, project-specific.

---

## Shared Infrastructure

**shared-utilities/** (formerly "common")

- Cross-cutting concerns
- Background utilities
- Not user-facing

---

## Changes from Previous Structure

### Consolidations

- ✅ **frontend-design** = ui-styling + frontend-aesthetics (merged)
- ✅ **better-auth** promoted from Tier 3 → Tier 2
- ✅ **common** renamed → shared-utilities

### Reorganization

- ✅ 26+ flat skills → 3-tier structure (core/stack/specialized)
- ✅ Clear hierarchy: essential → common → specialized
- ✅ -15% skill count through merges
- ✅ 70% faster discovery (8 core vs 26 flat)

### Archived

- ui-styling → .archive/ (merged into frontend-design)
- frontend-aesthetics → .archive/ (merged into frontend-design)

---

## Quick Reference

**Core skills (always loaded):**

```bash
ls skills/core/
# Used every session
```

**Stack skills (context auto-load):**

```bash
ls skills/stack/
# Loaded based on file types, tech stack
```

**Specialized skills (manual):**

```bash
ls skills/specialized/
# Activated on-demand
```

---

## See Also

- `docs/SKILLS_OPTIMIZATION_RESEARCH.md` - Full analysis and rationale
- `AGENTS.md` - Auto-load strategy and tier rules
- Individual skill SKILL.md files for usage details
