Skill Discovery

Skill Discovery — Design & Development Meta-Skill

A systematic approach to discovering, designing, developing, and managing skills.

1. When to Create a Skill

Create a skill when you've done something 3+ times or it took 5+ tool calls and would benefit from being repeatable. Specifically:

2. Skill Discovery Process

When faced with any task, systematically check:

1. skills_list() — browse all existing skills by category
2. skill_view(name) — load relevant skills
3. session_search("topic") — check past conversations for learned lessons
4. memory — check persistent notes about user/workflow preferences

Discovery Heuristics

For ANY task the user asks about, ask:

• Is this a recurring workflow? (Git operations, Docker management, C++ builds)
• Does it have a standard procedure? (Setting up projects, debugging patterns)
• Were there pitfalls I should remember? (Encoding issues, UAC elevation, quoting)
• Did the user correct me? (That's a skill in waiting!)

Category Mapping

Skills map to categories based on domain:

docker/          — Docker, Compose, Swarm, Buildx, containers
software-development/  — PS modules, build tools, WSL2, Windows tools
networking/      — DNS, firewall, VPN
mlops/           — ML training, model serving
productivity/    — Office documents, PDFs, spreadsheets
creative/        — ASCII art, diagrams, video
research/        — ArXiv, web scraping, blog monitoring
note-taking/     — Obsidian, note management

3. Skill Anatomy

Every skill has two mandatory parts:

Frontmatter (YAML)

---
name: skill-name-here       # lowercase-hyphens, max 64 chars
description: "Use when <trigger>. <one-line behavior>."  # MAX 60 CHARS!
category: software-development   # single category
tags: [tag1, tag2, tag3]    # discoverability tags
---

Description Rules (CRITICAL)

Descriptions are truncated at 57 chars + "..." in the system prompt index. They MUST follow this exact pattern:

"Use when <trigger condition>. <what it does briefly>."

Examples:

• ✅ "Use when removing all Docker traces from Windows. 7-phase." (56 chars)
• ✅ "Use when building PS admin tools. BOM, UAC, PS5/7." (55 chars)
• ✅ "Use when managing container/image/volume/network lifecycles." (60 chars)
• ❌ "A production-grade, interactive PowerShell script for comprehensive Docker management..." (too long)

Body Structure

# Title
Brief intro paragraph.

## Section (commands, patterns, reference)
```command
Actual code here

Pitfalls

• Bullet list of gotchas
• Each one is a specific failure mode

## 4. Skill Design Principles

### 1. Trigger-First Naming
Name should immediately tell the agent when to load it:
- `docker-compose-patterns` → "Load when writing docker-compose.yml"
- `powershell-error-handling` → "Load when writing try/catch blocks"

### 2. Shallow But Wide
Cover the 80% case for each topic. Don't try to be a complete reference.
- Good: "Here are the 10 most common docker commands grouped by lifecycle"
- Bad: "Here is every Docker command and all 47 flags"

### 3. Exact Commands, Not Descriptions
Always provide copy-paste-ready code blocks:
- ✅ `docker stop $(docker ps -aq)` 
- ❌ "You should stop all containers using the docker stop command"

### 4. Pitfalls Section Is Mandatory
Every skill must end with `## Pitfalls` containing 3-10 bullet points.
These are the hard-won lessons that save time on the next attempt.

## 5. Writing Great Descriptions (≤60 chars)

The 60-char limit is strictly enforced. Use these patterns:

"Use when ." "Use when ." "Use when via ."

| Length | Description |
|--------|-------------|
| 60 | "Use when managing container/image/volume/network lifecycles." |
| 59 | "Use when orchestrating multi-service Docker environments." |
| 57 | "Use when removing all Docker traces from Windows. 7-phase." |
| 56 | "Use when debugging Docker network connectivity issues." |
| 53 | "Use when installing software via winget, choco, or scoop." |
| 50 | "Use when building C++ projects with CMake on Windows." |
| 48 | "Use when configuring Docker Desktop WSL2 backend on Windows." |

Check length before creating: `"Use when ...".Length`

## 6. Skill Lifecycle

DISCOVERY → DESIGN → CREATE → VALIDATE → USE → MAINTAIN → (UPDATE | MERGE | DELETE)

### CREATE
```powershell
skill_manage(action='create', name='my-skill', 
    content='# Full SKILL.md...', 
    category='software-development')

Or write directly:

New-Item -Path "$env:LOCALAPPDATA\hermes\skills\<category>\<name>\SKILL.md"

VALIDATE

After creating, verify:

1. skills_list() shows the skill with truncated description
2. skill_view(name='my-skill') loads the full content
3. The description starts with "Use when..." and is under 60 chars
4. The body has code examples and a pitfalls section

UPDATE (PATCH)

When a skill has stale info:

skill_manage(action='patch', name='my-skill',
    old_string='old wrong command',
    new_string='correct command')

MERGE

When two skills overlap:

1. Create umbrella skill with consolidated content
2. Delete original skills with absorbed_into='umbrella-skill'

DELETE

skill_manage(action='delete', name='stale-skill',
    absorbed_into='')  # empty = prune, no forwarding
# OR
skill_manage(action='delete', name='old-skill',  
    absorbed_into='umbrella-skill')  # consolidating

7. Skill Discovery Checklist

When given ANY user task, run this checklist:

[ ] 1. Scan skills_list() for matching categories
[ ] 2. Load relevant skills with skill_view()
[ ] 3. Did skill cover the task?
      YES → follow it exactly
      NO → continue
[ ] 4. Is this a 5+ call / recurring workflow?
      YES → plan to create a skill after completion
      NO → just complete the task
[ ] 5. After completing task:
      [ ] Were there pitfalls? → add to skill
      [ ] Is this new? → create skill
      [ ] Was existing skill wrong? → patch it
[ ] 6. Ask user: "Save this as a skill?"

8. Advanced: Skill Development Patterns

Mirroring the User's Workflow

If the user routinely does X, Y, Z together, wrap it in a skill:

"Use when setting up Docker + WSL2 + VS Code on a clean Windows machine."

Error-to-Skill Pipeline

Every error you fix is a potential skill:

1. Hit error → fix error → document fix → create skill
2. Hit error again → load skill → fix in seconds

Skill Chaining

Some tasks need multiple skills. Reference them:

See also: docker-wsl2-integration, docker-lifecycle-management

9. Testing Skills

After creating/updating a skill:

# Verify it loads
skill_view(name='my-skill')

# Verify it appears in list
skills_list() | Where-Object { $_.name -match 'my-skill' }

# Follow the skill yourself to verify steps work
# If steps fail, patch immediately

Pitfalls

• Descriptions over 60 chars are rejected by skill_manage
• No skills_list call before acting leads to duplicated effort
• No pitfalls section means the skill is incomplete
• Outdated commands (e.g., v1 docker-compose) slip in -- patch on discovery
• Overly detailed skills become reference docs, not quick-lookup procedures
• Skipping the "ask user" step creates skills nobody wants
• Not checking for existing skills before creating creates duplicates