skill-creator

# skill-creator

Create, evaluate, and iterate on high-quality agent skills with structured guidance, quality scoring, and best-practice enforcement.

## What it does

- **Create** new skills from scratch with step-by-step guidance through architecture planning, SKILL.md writing, reference file creation, and quality validation
- **Evaluate** existing skills against a 10-dimension quality rubric (trigger quality, defaults, instruction design, reference strategy, output contract, conciseness and register, etc.) with reference-skill comparisons
- **Improve** skills by scoring them, proposing ranked improvements, and applying targeted patches

The skill encodes patterns extracted from analyzing 20+ production finance skills and 120+ hermes-agent skills, distilling what separates top-tier skills (sepa-strategy, options-payoff) from mediocre ones. Its writing guidance targets current Claude models: descriptions that name intent categories instead of listing synonym phrasings, exact scripts only for fragile operations, goals and criteria for judgment work, output contracts instead of rigid templates, and constraints stated once, plainly, with their reasons.

**Core rule:** Skills that touch external tools detect what's available at runtime and adapt with decision trees and fallback paths, rather than hardcoding a single method.

## Triggers

- "create a skill", "make a new skill", "build a skill for", "write a skill that"
- "improve this skill", "optimize this skill", "this skill isn't working well"
- "evaluate this skill", "score this skill", "how good is this skill"
- "run evals on", "benchmark this skill", "test this skill's quality"
- "turn this into a skill", "I keep doing X manually", "can you remember how to do X"

## Platform

Works on **Claude Code** and other CLI-based agents. Also works on **Claude.ai** for evaluation and planning (skill file creation requires CLI).

## Setup

```bash
# Choose finance-skill-creator when prompted.
npx plugins add himself65/finance-skills

# Or install just this skill
npx skills add himself65/finance-skills --skill skill-creator
```

See the [main README](../../../../README.md) for more installation options.

## Reference files

- `references/dynamic-calling.md` -- **Core**: Detection flows, decision trees, method fallbacks, runtime awareness, 9 patterns from production skills
- `references/architecture-patterns.md` -- Linear, Router, Methodology, Widget, and API Wrapper patterns with examples and anti-patterns
- `references/frontmatter-guide.md` -- Complete YAML frontmatter field reference (name, description, platform, env vars, config, credentials)
- `references/quality-rubric.md` -- 10-dimension scoring rubric with 1-10 scales, reference-skill examples, and score interpretation
- `references/skill-examples.md` -- Annotated excerpts from top skills showing why specific patterns work
- `references/writing-guide.md` -- How to write each SKILL.md section for current Claude models: descriptions, detection flows, defaults tables, and output contracts

# Architecture Patterns for Skills

Choosing the right structural pattern is the most impactful decision in skill design. The wrong pattern creates friction; the right one makes the skill feel natural.

## Linear Pattern

**When to use:** The skill has a single workflow with no branching. User provides input, skill processes it sequentially, skill returns output.

**Structure:** A few numbered steps, executed in order.

**Example:** `earnings-preview`
```
Step 1: Check yfinance
Step 2: Fetch earnings, estimate, and sentiment data
Step 3: Build the preview (five content areas, one of them judgment)
Step 4: Respond with the briefing
```

**Strengths:** Simple to follow, easy to debug, low token cost.
**Weaknesses:** Cannot handle diverse user intents within the same domain.

**Design rules:**
- Each step should produce a concrete intermediate result
- Include an early exit if prerequisites fail (Step 1)
- Keep the total under about 7 steps; if you need more, consider Router or Methodology

---

## Router Pattern

**When to use:** The skill covers multiple related sub-tasks. The user's intent determines which path to take.

**Structure:** Step 1 (setup) + Step 2 (route) + Sub-Skill sections + Final step (respond).

**Example:** `stock-correlation`
```
Step 1: Check dependencies
Step 2: Route based on intent
  - Single ticker → Sub-Skill A: Co-movement Discovery
  - Two tickers → Sub-Skill B: Return Correlation
  - Group → Sub-Skill C: Sector Clustering
  - Time-varying → Sub-Skill D: Realized Correlation
Step 3: Respond to user
```

**Strengths:** Handles diverse intents cleanly, each sub-path stays focused.
**Weaknesses:** More complex to write, routing table must be exhaustive.

**Design rules:**
- Give the routing table a default for ambiguous requests
- Each sub-skill should be self-contained (A1, A2, A3 sub-steps)
- Shared defaults go in Step 1, sub-skill-specific defaults go in each sub-skill
- Limit to 4-6 sub-skills; more means the skill should be split into separate skills

---

## Methodology Pattern

**When to use:** The skill implements a known framework or methodology with sequential validation gates. Each step builds on the previous one, and failure at a real gate stops the analysis.

**Structure:** Ordered checks, each with the methodology's own pass/fail criteria or grade.

**Example:** `sepa-strategy`
```
Step 1: Gather stock data (computed in code)
Step 2: Stage analysis (STOP if not Stage 2)
Step 3: Trend template — 8 conditions (STOP if any fail)
Step 4: Fundamental check (grade A/B/C/D)
Step 5: Pattern recognition (VCP, cup-handle, etc.)
Step 6: Entry point analysis
Step 7: Market environment check (sets risk per trade)
Step 8: Position sizing & stop loss
Step 9: Respond with structured report
```

**Strengths:** Thorough, educational, produces high-quality analysis, prevents premature conclusions.
**Weaknesses:** Highest token cost, requires deep domain knowledge to write.

**Design rules:**
- Put a gate or grade wherever the methodology really has one, and order steps by their dependencies (the environment sets risk per trade, so it comes before sizing)
- A failed gate stops the analysis with a clear message ("Not Stage 2 — no further analysis needed")
- Use tables for checklists and criteria (the 8-condition trend template is the gold standard)
- Defer detailed criteria to reference files; SKILL.md shows the checklist, the reference shows the rubric
- End with a verdict system (Strong Buy Setup / Watch List / Pass)
- A scorecard-style methodology can mirror its step structure in the output; that fixed format earns its place because the user reads it as a checklist

---

## Widget Pattern

**When to use:** The skill generates an interactive HTML/SVG widget as output.

**Structure:** 4-5 steps: extract parameters → identify type → compute → render → explain.

**Example:** `options-payoff`
```
Step 1: Extract strategy from user input (with comprehensive defaults table)
Step 2: Identify strategy type (lookup matrix)
Step 3: Compute payoffs (mathematical formulas)
Step 4: Render the widget (UI spec + code template)
Step 5: Respond with brief explanation
```

**Strengths:** Produces tangible, interactive output.
**Weaknesses:** Requires detailed code templates, hard to test without rendering.

**Design rules:**
- Step 1 needs a defaults table covering every parameter, so the skill never stalls asking for info
- The extraction step needs "Where to find it" guidance for each field
- Include a code template skeleton in SKILL.md (not full implementation — that goes in references)
- The render step specifies controls, stats cards, chart axes, colors, and tooltips — a widget is format-sensitive, so exact specs belong here
- Keep the final step short — the chart speaks for itself

---

## API Wrapper Pattern

**When to use:** The skill wraps an external API with many endpoints. The user's request maps to one or more API calls.

**Structure:** Auth and lookup steps + an endpoint map + heavy reference files.

**Example:** `fintel-data`
```
Step 1: Resolve the API key (env var, local .env, repo-root .env)
Step 2: Resolve the security (ticker, CUSIP, ISIN, FIGI)
Step 3: Match the request to an endpoint (routing table)
Step 4: Call the API and handle errors
Step 5: MCP alternative
Step 6: Respond to user
```

**Strengths:** Comprehensive API coverage, reference files serve as living documentation.
**Weaknesses:** The routing table can become unwieldy, reference files need maintenance.

**Design rules:**
- The routing table in SKILL.md should be a high-level category map, not every endpoint
- Each reference file covers one endpoint category (market-data, fundamentals, options, etc.)
- Reference files should include: endpoint URL, parameters, example curl/code, response format
- Cover the common mechanics (pagination, rate limits, error codes, metered usage) in one place
- API keys should use `required_environment_variables` in frontmatter, not inline instructions

---

## Choosing Between Patterns

| Signal | Recommended Pattern |
|---|---|
| "Fetch X data and show it" | Linear |
| "It depends on what the user asks" | Router |
| "There's a formal framework with criteria" | Methodology |
| "Generate a chart/widget/visualization" | Widget |
| "Wrap this API's 20+ endpoints" | API Wrapper |
| Multiple signals | Combine: Router with Linear sub-skills, Methodology with Widget output |

## Anti-Patterns to Avoid

### The Wall of Text
A single massive step with 50+ lines of undifferentiated instructions. **Fix:** Split into steps with clear boundaries, and move reference material to `references/`.

### The Script for Judgment
Analysis or writing choreographed as "Step 3a: compute X. Step 3b: compare Y. Step 3c: write two sentences about Z." Current models plan this kind of work better than a hand-written script, and the script boxes them in. **Fix:** State the goal, the criteria, and the domain heuristics; keep numbered steps for work whose order really matters.

### The Shouting Skill
Capitalized MUST / NEVER / CRITICAL on several lines, repeated warnings, "double-check your answer". Current models over-apply this register and turn cautious. **Fix:** State each real constraint once, plainly, with its reason; delete instructions the model follows by default.

### The Gold Output
A single worked example — often with invented figures for a real company — that the model copies in length, structure, and phrasing. **Fix:** Describe what the output must contain; label any example as illustrative and keep it free of fabricated real-world numbers.

### The Synonym-List Description
A description that grows one quoted phrasing per missed trigger. **Fix:** Name the categories of intent and the distinctive vocabulary; point to sibling skills for neighboring requests.

### The Premature Reference
Linking to a reference file for 3 lines of content. **Fix:** Keep short content inline; references are for 50+ lines of depth.

### The Missing Exit Gate
A methodology that keeps analyzing after a disqualifying check fails. **Fix:** Add "If X fails, stop here and tell the user" at each point where failure really ends the analysis.

### The Vague Output
"Summarize the results for the user." **Fix:** State an output contract — what to lead with, what must be covered, which caveats apply, and the verdict scale if the skill is evaluative.

### The Hardcoded Universe
Static ticker lists or data that will go stale. **Fix:** Build universes dynamically at runtime using screening APIs, and date-stamp any snapshot data kept in references.

# Dynamic Calling Patterns

Skills that touch external tools should detect what's available at runtime and adapt, rather than hardcoding a single tool or method — environments differ, and a hardcoded tool fails for every user who lacks it. This reference catalogs every dynamic pattern used in production skills.

**Core principle:** The skill should work in as many environments as possible. A user with `gh` CLI gets the rich path. A user with only `git` gets the minimal path. A user with nothing gets clear install instructions. The skill never fails silently because a hardcoded tool is missing.

---

## Pattern 1: Detection Flow with Decision Tree

The foundational pattern. Every skill that touches external tools starts here.

### Structure

```markdown
## Step 1: Detection Flow

` ` `
!`(command -v tool_a && tool_a --version) 2>/dev/null || echo "TOOL_A_MISSING"`
` ` `

` ` `
!`(command -v tool_b && tool_b --version) 2>/dev/null || echo "TOOL_B_MISSING"`
` ` `

**Decision tree:**
1. If `tool_a` available and authenticated → use Method 1 (preferred)
2. If `tool_a` available but not authenticated → guide auth setup, then Method 1
3. If `tool_a` missing but `tool_b` available → use Method 2 (fallback)
4. If neither available → install `tool_a` (preferred) or `tool_b` (lighter)
```

### Real Example: github-auth (gh vs git)

```markdown
## Detection Flow

` ` `bash
git --version
gh --version 2>/dev/null || echo "gh not installed"
gh auth status 2>/dev/null || echo "gh not authenticated"
git config --global credential.helper 2>/dev/null || echo "no git credential helper"
` ` `

**Decision tree:**
1. If `gh auth status` shows authenticated → use `gh` for everything
2. If `gh` is installed but not authenticated → use "gh auth" method
3. If `gh` is not installed → use "git-only" method (no sudo needed)
```

**Why this works:**
- Detects 4 dimensions: git existence, gh existence, gh auth state, git credential state
- Three clear paths, each self-contained
- The skill works for everyone — from minimal git-only setups to full gh installations

---

## Pattern 2: Multi-Stage Detection (Install → Auth → Health)

For tools that need multiple checks before they're usable.

### Structure

```
!`(command -v tool && tool status 2>&1 | head -5 && echo "READY" || echo "SETUP_NEEDED") 2>/dev/null || echo "NOT_INSTALLED"`
```

This single command checks three things:
1. Is the tool installed? (`command -v tool`)
2. Can it run? (`tool status`)
3. Is it healthy? (output + `echo "READY"`)

### Real Example: discord-reader (opencli)

```markdown
` ` `
!`(command -v opencli && opencli discord-app status 2>&1 | head -5 && echo "READY" || echo "SETUP_NEEDED") 2>/dev/null || echo "NOT_INSTALLED"`
` ` `

If `READY`, skip to Step 2.
If `NOT_INSTALLED`, install first: `npm install -g @jackwener/opencli`
If `SETUP_NEEDED`, guide through CDP setup.
```

### Real Example: telegram-reader (tdl — two-stage)

```markdown
` ` `
!`command -v tdl 2>/dev/null && echo "TDL_INSTALLED" || echo "TDL_NOT_INSTALLED"`
` ` `

` ` `
!`tdl chat ls --limit 1 2>/dev/null && echo "TDL_AUTHENTICATED" || echo "TDL_NOT_AUTHENTICATED"`
` ` `

Decision tree:
1. Both OK → proceed to Step 2
2. Installed but not authenticated → run `tdl login`
3. Not installed → install via `go install` or binary download
```

**Why two-stage:** Some tools pass `--version` but fail on actual operations because auth is missing. Checking auth separately gives better error messages.

---

## Pattern 3: Library Version Detection with Fallback

For Python skills that need specific libraries.

### Structure

```
!`python3 -c "exec('try:\n import lib\n print(\'lib \' + lib.__version__)\nexcept Exception:\n print(\'LIB_NOT_INSTALLED\')')"`
```

### Real Example: stock-correlation (multi-package + algorithm fallback)

```markdown
` ` `
!`python3 -c "exec('try:\n import yfinance, pandas, numpy\n print(f\'yfinance={yfinance.__version__} pandas={pandas.__version__} numpy={numpy.__version__}\')\nexcept Exception:\n print(\'DEPS_MISSING\')')"`
` ` `

If `DEPS_MISSING`, install:
` ` `python
subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", "yfinance", "pandas", "numpy"])
` ` `
```

And later in the clustering step:
```markdown
Note: if `scipy` is not available, fall back to sorting by average correlation
instead of hierarchical clustering.
```

**Key insight:** The detection happens at Step 1, but the fallback logic is **also** in the core step that uses the optional dependency. Don't just detect — also provide alternatives at each usage point.

---

## Pattern 4: API Key Detection

For skills that wrap external APIs.

### Structure

```
!`echo $API_KEY | head -c 8 && echo "...KEY_SET" || echo "KEY_NOT_SET"`
```

### Real Example: fintel-data

```markdown
` ` `
!`echo $FINTEL_API_KEY | head -c 8 && echo "...KEY_SET" || echo "KEY_NOT_SET"`
` ` `

If `KEY_NOT_SET`:
- Ask the user for their Fintel API key
- Guide them to https://fintel.io/api to get one
- Once provided, export it: `export FINTEL_API_KEY=<key>`
```

### Real Example: finance-sentiment (multi-line Python check)

```markdown
` ` `
!`python3 -c "
import os
key = os.environ.get('ADANOS_API_KEY', '')
if key:
    print(f'KEY={key[:8]}...SET')
else:
    print('KEY_NOT_SET')
" 2>/dev/null || echo "PYTHON_UNAVAILABLE"`
` ` `
```

**Why show partial key:** Showing the first 8 characters lets the user verify they have the right key without exposing the full secret.

---

## Pattern 5: Live Data Injection

For skills that need current market data, not stale defaults.

### Structure

```
!`python3 -c "exec('try:\n import yfinance as yf\n p=yf.Ticker(\'^GSPC\').fast_info[\'lastPrice\']\n print(f\'PRICE={p:.0f}\')\nexcept Exception:\n print(\'PRICE_UNAVAILABLE\')')"`
```

### Real Example: options-payoff (current SPX price)

```markdown
**Current SPX reference price:**
` ` `
!`python3 -c "exec('try:\n import yfinance as yf\n p=yf.Ticker(\'^GSPC\').fast_info[\'lastPrice\']\n print(f\'SPX ≈ {p:.0f}\')\nexcept Exception:\n print(\'SPX price unavailable — check market data\')')"`
` ` `
```

**Why this matters for options:** A default spot price of "5000" becomes wrong within days. Live injection means the payoff chart is immediately useful without manual adjustment.

**Fallback design:** When live data fails, the skill still works — it just uses a static default and tells the user to check.

---

## Pattern 6: Frontmatter Conditional Activation

Skills can declare themselves as fallbacks or require specific tools at the YAML level.

### `fallback_for_toolsets` — Activate when primary is missing

```yaml
metadata:
  hermes:
    fallback_for_toolsets: [web]
```

**Real example:** duckduckgo-search only appears when the web toolset (with API keys) is NOT configured. Once the user sets up Firecrawl, the skill auto-hides.

### `requires_toolsets` — Only show when tools exist

```yaml
metadata:
  hermes:
    requires_toolsets: [terminal]
```

**Real example:** docker-management only appears when terminal tools are active — it makes no sense on Claude.ai.

### Combining with runtime detection

Frontmatter controls **whether the skill loads**. Runtime detection controls **how the skill behaves once loaded**. Use both:

```yaml
# Frontmatter: only load when terminal is available
metadata:
  hermes:
    requires_toolsets: [terminal]
```

```markdown
# Runtime: detect WHICH terminal tools are available
!`command -v gh && echo "GH_OK" || echo "GH_MISSING"`
```

---

## Pattern 7: Dual-Method Skills (CLI preferred, Python fallback)

The most common pattern for data-fetching skills.

### Structure

```markdown
## Step 2: Fetch Data

### If CLI detected (preferred)
` ` `bash
ddgs text -k "query" -m 5 -o json
` ` `

### If Python library available (fallback)
` ` `python
from ddgs import DDGS
with DDGS() as ddgs:
    results = list(ddgs.text("query", max_results=5))
` ` `

### If neither available
Install the CLI: `pip install ddgs`
```

### Real Example: duckduckgo-search decision tree

```markdown
1. If `ddgs` CLI is installed → prefer `terminal` + `ddgs` (fastest, simplest)
2. If `ddgs` CLI is missing → do not assume `execute_code` can import `ddgs`
3. If the user wants DuckDuckGo specifically → install `ddgs` first
4. Otherwise → fall back to built-in web/browser tools
```

**Critical runtime awareness:**
> Terminal and `execute_code` are separate runtimes. A successful shell install does not guarantee `execute_code` can import `ddgs`. Never assume third-party Python packages are preinstalled inside `execute_code`.

---

## Pattern 8: Runtime Environment Awareness

Different execution environments have different capabilities. Skills must not assume.

### Key distinctions

| Environment | Has shell | Has pip | Has browser | Has internet |
|---|---|---|---|---|
| Claude Code (CLI) | Yes | Yes | No (unless MCP) | Yes |
| Claude.ai (web) | Sandboxed | Limited | No | Restricted |
| Hermes Agent (terminal) | Yes | Yes | Configurable | Yes |
| execute_code sandbox | Isolated | Pre-installed only | No | Varies |

### Rule: Test in the runtime you'll use

```markdown
# WRONG — installs in terminal, uses in execute_code
` ` `bash
pip install ddgs
` ` `
` ` `python
# In execute_code — this might fail because it's a different runtime!
from ddgs import DDGS
` ` `

# RIGHT — verify in the runtime where you'll use it
` ` `python
# Check if available in this runtime
try:
    from ddgs import DDGS
    print("DDGS available")
except ImportError:
    import subprocess, sys
    subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", "ddgs"])
    from ddgs import DDGS
` ` `
```

---

## Pattern 9: Graceful Degradation Chain

When multiple tools can do the same job, prefer the richest and fall back gracefully.

### Structure

```
Preferred (richest) → Standard → Minimal → Manual instruction
```

### Example: Web search degradation

```
1. web_search tool (if available) → richest, API-backed
2. ddgs CLI (if installed) → free, no key needed
3. ddgs Python library (if importable) → same but in sandbox
4. curl + manual URL → always works but crudest
5. Ask user to search → last resort
```

### Example: GitHub operations degradation

```
1. gh CLI authenticated → full API (PRs, issues, reviews, CI)
2. gh CLI not authenticated → guide auth, then full API
3. git + curl + token → basic API (push, pull, simple operations)
4. git only (no token) → read-only operations on public repos
```

---

## Anti-Patterns to Avoid

### Hardcoded single tool

```markdown
# BAD — fails immediately if yfinance not installed
` ` `python
import yfinance as yf
data = yf.download("AAPL")
` ` `
```

**Fix:** Always detect first, then use.

### Assuming install means available

```markdown
# BAD — installs in shell, assumes execute_code has it
pip install ddgs
# ... later in execute_code ...
from ddgs import DDGS  # might fail!
```

**Fix:** Check in the same runtime where you'll use the library.

### Static tool paths

```markdown
# BAD — path differs across OS and installs
/usr/local/bin/gh auth status
```

**Fix:** Use `command -v gh` to find the tool wherever it is.

### No fallback on detection failure

```markdown
# BAD — no || fallback, command hangs or errors silently
!`tool_a --version`
```

**Fix:** Always use `|| echo "SENTINEL"` fallbacks.

### Detecting once, ignoring later

```markdown
# BAD — detects scipy in Step 1 but hardcodes scipy.cluster in Step 4
```

**Fix:** Every step that uses an optional tool should have inline fallback logic, not just the detection step.

---

## Quick Reference: Detection Commands

| What to detect | Command |
|---|---|
| CLI tool exists | `command -v tool 2>/dev/null` |
| CLI tool version | `tool --version 2>/dev/null` |
| Tool is authenticated | `tool auth status 2>/dev/null` |
| Python module available | `python3 -c "exec('try:\n import mod\n print(mod.__version__)\nexcept Exception:\n print(\'MOD_NOT_INSTALLED\')')"` |
| Env var is set | `echo $VAR \| head -c 8 && echo "...SET"` |
| File exists | `test -f ~/.config/tool/creds && echo "OK"` |
| API is reachable | `curl -sf endpoint \| head -c 100` |
| Runtime has internet | `curl -sf https://httpbin.org/get > /dev/null && echo "OK"` |

All commands should end with `|| echo "FALLBACK_SENTINEL"` for graceful handling.

# SKILL.md Frontmatter Reference

Complete field reference for the YAML frontmatter block that starts every SKILL.md file.

## Required Fields

### `name`
- **Type:** string
- **Max length:** 64 characters
- **Pattern:** `^[a-z0-9][a-z0-9._-]*$` (lowercase alphanumeric, hyphens, dots, underscores)
- **Purpose:** Unique identifier used in slash commands, file paths, and skill references

```yaml
name: my-skill-name
```

### `description`
- **Type:** string (multi-line with `>` recommended)
- **Max length:** 1024 characters
- **Purpose:** Controls when the skill activates. This is the most important field for skill quality.

```yaml
description: >
  [What it does] Analyze stocks using the SEPA methodology.
  [Intent categories + vocabulary] SEPA, Minervini, VCP, trend template, Stage 2, pivot point.
  [Scoped sideways entries] "should I buy this stock" about a growth or momentum name.
  [Context triggers] When user shares a chart, mentions swing trading criteria.
  [Boundaries] For X, use sibling-skill instead.
```

**Writing a high-quality description:**

1. Start with a concrete action verb: "Analyze", "Generate", "Fetch", "Evaluate" (not "Use" or "Handle")
2. Name specific tools/APIs: "via yfinance", "using the Fintel API"
3. Name every category of request the skill serves, with the distinctive terms users will use — both expert vocabulary and plain-language requests
4. Scope sideways entry points to their context ("should I buy this stock" about a growth name), so they don't fire everywhere
5. Point to sibling skills for neighboring requests, and state read-only limits where relevant

The description rides along in every request, so it is the one place where calibrated urgency ("use this skill whenever...") belongs. Keep behavioral instructions — how to do the work — in the body.

**Common mistakes:**
- Too short: "Analyze stocks" — won't trigger on specific requests
- Too generic: "Financial analysis tool" — triggers on everything, useful for nothing
- Missing beginner terms: Only expert jargon excludes most users
- Synonym lists: ten quoted phrasings of the same request cost tokens in every session and generalize worse than naming the category once
- Behavior in the description: "default to running all three methods" belongs in the body

## Optional Fields

### `version`
Semantic version for the skill. Useful for tracking changes.
```yaml
version: 1.0.0
```

### `author`
Creator name or handle.
```yaml
author: himself65
```

### `license`
License identifier.
```yaml
license: MIT
```

### `platforms`
Restrict to specific operating systems. Omit to load on all platforms (default).
```yaml
platforms: [macos, linux]   # Valid values: macos, linux, windows
```

### `required_environment_variables`
Declare API keys or tokens the skill needs. These are secrets stored in `~/.hermes/.env`.

```yaml
required_environment_variables:
  - name: FINTEL_API_KEY
    prompt: "Fintel API key"
    help: "Get one at https://fintel.io/api"
    required_for: "API access"
```

Fields per entry:
- `name` (required) — environment variable name
- `prompt` (optional) — text shown when asking the user
- `help` (optional) — URL or help text for obtaining the value
- `required_for` (optional) — which feature needs this variable

### `required_credential_files`
Declare file-based credentials (OAuth tokens, certificates).

```yaml
required_credential_files:
  - path: google_token.json
    description: Google OAuth2 token (created by setup script)
```

### `metadata.hermes`
Hermes-specific metadata for discovery, activation, and configuration.

```yaml
metadata:
  hermes:
    tags: [Finance, Market Analysis, Options]
    related_skills: [yfinance-data, earnings-preview]
    category: market-analysis
```

### Conditional Activation

Control when the skill appears in the system prompt:

```yaml
metadata:
  hermes:
    requires_toolsets: [web]              # Hide if web toolset NOT active
    requires_tools: [web_search]          # Hide if web_search NOT available
    fallback_for_toolsets: [browser]      # Hide if browser IS active
    fallback_for_tools: [browser_navigate] # Hide if browser_navigate IS available
```

| Field | Logic |
|---|---|
| `requires_toolsets` | Hidden when ANY listed toolset is unavailable |
| `requires_tools` | Hidden when ANY listed tool is unavailable |
| `fallback_for_toolsets` | Hidden when ANY listed toolset IS available |
| `fallback_for_tools` | Hidden when ANY listed tool IS available |

### Config Settings

Non-secret settings stored in `config.yaml`:

```yaml
metadata:
  hermes:
    config:
      - key: wiki.path
        description: Path to knowledge base directory
        default: "~/wiki"
        prompt: "Wiki directory path"
```

## Complete Frontmatter Example

```yaml
---
name: sepa-strategy
description: >
  Analyze stocks using Mark Minervini's SEPA methodology.
  Triggers: SEPA, Minervini, VCP, trend template, Stage 2, pivot point,
  superperformance, bullish stacking, breakout volume, cup-with-handle,
  "should I buy this stock", "is this a good setup", growth stock screening.
version: 1.0.0
author: himself65
license: MIT
metadata:
  hermes:
    tags: [Finance, Trading, Technical Analysis]
    related_skills: [yfinance-data, stock-correlation]
---
```

## Size Constraints Summary

| Field | Limit |
|---|---|
| `name` | 64 characters |
| `description` | 1024 characters |
| SKILL.md total content | 100,000 characters |
| Supporting files | 1 MiB each |
| Category name | 64 characters, single directory level |

# Skill Quality Rubric

Score each dimension on a 1-10 scale. A production-quality skill should score 70+ overall; the best skills in this repo score in the 80s and 90s.

## Dimension 1: Trigger Quality (Description Field)

Does the description route the right requests to this skill — and only those?

| Score | Criteria |
|---|---|
| 1-3 | Generic ("analyze stocks"); misses whole categories of requests, or so broad it fires on everything |
| 4-5 | Covers the main use case only; expert jargon only, or a long list of near-synonym phrasings standing in for categories |
| 6-7 | Names what the skill does and most intent categories, with the tools and data types it uses |
| 8-9 | Every intent category, the distinctive vocabulary users will use, scoped sideways entries, and pointers to sibling skills; well under 1024 characters |
| 10 | A trigger check routes varied real requests correctly, including near-misses that belong to a sibling skill |

**Example:** sepa-strategy names the methodology and its distinctive terms (VCP, trend template, Stage 2, pivot entries), then adds a scoped sideways entry — "should I buy this stock" about a growth or momentum name.

## Dimension 2: Defaults Coverage

Does every parameter have an explicit default so the skill never stalls waiting for input?

| Score | Criteria |
|---|---|
| 1-3 | No defaults table, skill frequently asks user for missing info |
| 4-5 | Some defaults mentioned in prose, incomplete coverage |
| 6-7 | Defaults table exists, covers main parameters, missing a few edge cases |
| 8-9 | Comprehensive defaults table with rationale column, covers all parameters |
| 10 | Every conceivable parameter has a default, skill always produces output |

**Example:** options-payoff has a field / where-to-find-it / default row for every input, including how to resolve spot when a screenshot omits it.

## Dimension 3: Instruction Design

Are instructions matched to the work — exact where operations are fragile, goal-oriented where the work is judgment?

| Score | Criteria |
|---|---|
| 1-3 | Wall of undifferentiated text, or a rigid script for everything including the analysis |
| 4-5 | Structure exists but order-independent judgment work is choreographed step by step, or fragile operations are left vague |
| 6-7 | Numbered steps where order matters; exact commands for setup and calls; judgment mostly stated as criteria |
| 8-9 | Specificity matched to fragility throughout; judgment stated as goals, criteria, and domain heuristics with reasons; gates only where a failed check really ends the analysis |
| 10 | A capable model could run it cold and produce expert-quality work without guessing at the mechanics or being boxed in on the judgment |

**Example:** sepa-strategy gates on stage and the trend template, where failure really ends the analysis; earnings-preview states what the briefing must cover and leaves the "what to watch" judgment to the model.

## Dimension 4: Reference File Strategy

Is complexity properly deferred to reference files? Is SKILL.md lean?

| Score | Criteria |
|---|---|
| 1-3 | Everything inline, SKILL.md is 500+ lines, no reference files |
| 4-5 | Some references exist but SKILL.md still bloated, or references are trivial |
| 6-7 | Good split — SKILL.md under 300 lines, 1-3 reference files for deep content |
| 8-9 | Clean architecture — SKILL.md under 250 lines, reference files covering all depth, dated datasets kept out of SKILL.md |
| 10 | Perfect split — SKILL.md is pure workflow and judgment, all detail in well-organized references |

**Example:** sepa-strategy keeps the checklist in SKILL.md and the full rubric for each stage of the methodology in seven reference files.

## Dimension 5: Dynamic Calling & Runtime Adaptation

Does the skill detect available tools at runtime and adapt its behavior?

| Score | Criteria |
|---|---|
| 1-3 | No detection, hardcodes a single tool/library, fails if not installed |
| 4-5 | Has a dependency check but no decision tree or fallback path |
| 6-7 | Detection flow with fallback messages; single method path after detection |
| 8-9 | Full detection flow → decision tree → a second method path where a real alternative exists; auth detection; graceful fallbacks |
| 10 | Multi-dimensional detection (tools + auth + runtime + live data), decision tree with 3+ paths, inline fallbacks at every usage point, frontmatter conditional activation |

**Examples:** github-auth detects gh vs git, auth state, and credential helper with three method paths. fintel-data resolves its API key from the environment, a local `.env`, or the repo-root `.env`. options-payoff injects a live SPX price with a fallback.

**Note:** Skills that are pure analysis (no external deps) can score 7+ by having a well-structured "Gather Data" step with data source alternatives (e.g., yfinance vs manual input).

## Dimension 6: Output Contract

Does the final step say what a good answer contains?

| Score | Criteria |
|---|---|
| 1-3 | "Summarize the results" — nothing specified |
| 4-5 | Lists topics, but not what to lead with, which caveats apply, or what verdict to give |
| 6-7 | Clear contract: what to lead with, the required content, the caveats |
| 8-9 | Contract plus a precisely defined verdict or grade scale; fixed templates only where format matters; length described qualitatively; examples labeled illustrative |
| 10 | Output is complete and useful across varied inputs — including thin data — without a rigid template, while format-sensitive parts (scorecards, widgets) are pinned exactly |

**Example:** sepa-strategy defines a three-way verdict (Strong Buy Setup / Watch List / Pass) and pins its trend-template scorecard; startup-analysis defines a verdict scale per lens and asks each section to scale to the evidence.

## Dimension 7: Error Handling & Missing Data

How does the skill handle missing data, failed API calls, or partial input?

| Score | Criteria |
|---|---|
| 1-3 | No mention of error cases, skill will break on missing data |
| 4-5 | Some error handling but gaps — certain failures cause silent wrong results |
| 6-7 | Handles main error cases, has "if unavailable" notes |
| 8-9 | Comprehensive: missing data noted and flagged, fallback approaches, user prompts |
| 10 | Graceful degradation at every step — always produces useful output even with partial data |

**Example:** sepa-strategy says to proceed with what's available and flag a missing RS rating as a significant gap.

## Dimension 8: Code / Formula Quality

Are code templates and formulas correct, complete, and copy-paste ready?

| Score | Criteria |
|---|---|
| 1-3 | No code provided, or pseudocode that won't run |
| 4-5 | Code snippets exist but incomplete — missing imports, undefined variables, or calls to APIs that no longer exist |
| 6-7 | Working code that needs minor adaptation |
| 8-9 | Copy-paste ready code with proper imports and error handling, checked against the current library version |
| 10 | Production-quality code templates in reference files + skeleton in SKILL.md, verified end to end |

**Example:** stock-correlation ships complete Python functions with imports, NaN handling, and edge cases.

**Note:** Not all skills need code. For pure analysis skills, score based on formula clarity and table quality.

## Dimension 9: Conciseness & Register

Is SKILL.md appropriately sized, and does every line earn its place?

| Score | Criteria |
|---|---|
| 1-3 | Over 500 lines, or dense with capitalized warnings, repeated rules, and instructions the model follows by default |
| 4-5 | 300-500 lines, or several MUST/NEVER/CRITICAL lines without reasons, generic virtues ("be thorough", "double-check"), maintainer notes, or history |
| 6-7 | 200-300 lines; mostly plain register with a few restated defaults or duplicated rules |
| 8-9 | 150-250 lines; each constraint stated once, plainly, with its reason; no boilerplate |
| 10 | Under 200 lines with comprehensive reference files; nothing a capable model would already do unprompted |

**Example:** options-payoff stays under 200 lines and leaves the depth to two reference files.

## Dimension 10: Domain Accuracy

Is the skill's domain knowledge correct and trustworthy?

| Score | Criteria |
|---|---|
| 1-3 | Factual errors, wrong formulas, misleading guidance |
| 4-5 | Mostly correct but some imprecise statements, outdated info, or undated figures that have gone stale |
| 6-7 | Accurate for main use cases, some edge cases not covered |
| 8-9 | Highly accurate, edge cases documented, dated data labeled, disclaimers appropriate |
| 10 | Expert-level accuracy — could be used as a reference by domain practitioners |

**Example:** options-payoff has correct Black-Scholes formulas, documented edge cases, and a disclaimer.

---

## Scoring Summary Table

Copy this template when scoring a skill:

```
| # | Dimension | Score | Notes |
|---|---|---|---|
| 1 | Trigger quality | /10 | |
| 2 | Defaults coverage | /10 | |
| 3 | Instruction design | /10 | |
| 4 | Reference file strategy | /10 | |
| 5 | Dynamic content | /10 | |
| 6 | Output contract | /10 | |
| 7 | Error handling | /10 | |
| 8 | Code/formula quality | /10 | |
| 9 | Conciseness & register | /10 | |
| 10 | Domain accuracy | /10 | |
| **Total** | | **/100** | |
```

## Score Interpretation

| Range | Quality | Action |
|---|---|---|
| 90-100 | Exceptional | Ship as-is, use as template for new skills |
| 80-89 | Production | Ready to use, minor polish opportunities |
| 70-79 | Good | Functional, 2-3 targeted improvements recommended |
| 60-69 | Needs work | Usable but will frustrate users, prioritize fixes |
| Below 60 | Draft | Not ready for use, needs structural rework |

# Annotated Skill Examples

Real excerpts from the best skills in this repo, with annotations explaining why specific patterns work.

## Example 1: Intent-Category Description (sepa-strategy)

```yaml
description: >
  Analyze stocks with Mark Minervini's SEPA (Specific Entry Point Analysis) methodology:
  stage analysis, the 8-condition trend template, fundamentals, VCP and other base
  patterns, pivot-point entries, market environment, and risk-based position sizing.
  Use this skill whenever the user mentions SEPA, Minervini, superperformance, the
  trend template, VCP (volatility contraction pattern), Stage 2, pivot or breakout
  entries, moving-average stacking (price above the 50/150/200-day MAs), breakout
  volume, position sizing from risk percentage, growth-stock screening criteria, or
  bases such as cup-with-handle, flat base, bull flag, or high tight flag. Also use it
  when the user asks "should I buy this stock" or "is this a good setup" about a
  growth or momentum name, or shares a chart for pattern analysis.
```

**Why this works:**
- Opens with what the skill does, in the methodology's own terms
- Names the distinctive vocabulary a user would actually use (VCP, trend template, Stage 2, pivot) rather than ten phrasings of the same request
- Adds sideways entries ("should I buy this stock") scoped to the context where they belong, so they don't fire on every stock question
- Covers input modalities ("shares a chart")

---

## Example 2: Comprehensive Defaults Table (options-payoff)

```markdown
| Field | Where to find it | Default if missing |
|---|---|---|
| Strategy type | Title bar / leg description | "custom" |
| Underlying | Ticker symbol | SPX |
| Strike(s) | K1, K2, K3... in title or leg table | nearest round number |
| Premium paid/received | Filled price or avg price | 5.00 |
| Quantity | Position size | 1 |
| Multiplier | 100 for equity options, 100 for SPX | 100 |
| Expiry | Date in title | 30 DTE |
| Spot price | Current underlying price shown in the screenshot or text | live quote (see below); middle strike only if no quote is available |
| IV | Shown in greeks panel, or estimate from vega | 20% |
| Risk-free rate | — | 4.3% |
```

**Why this works:**
- Three columns: Field, Where to find it (extraction guidance), Default
- Covers every parameter — the skill never stalls
- Defaults are reasonable (SPX is the most common underlying, 30 DTE is standard)
- The one tricky field, spot, gets a resolution order (screenshot → live quote → middle strike, flagged) instead of a bare prohibition

---

## Example 3: Pass/Fail Gate (sepa-strategy, Step 2)

```markdown
## Step 2: Stage Analysis — Identify the Current Stage

| Stage | Characteristics | Action |
|---|---|---|
| **Stage 1** — Basing | Price near 200MA, MA flat/declining | Do nothing, wait |
| **Stage 2** — Advancing | Higher highs/lows, bullish MA alignment | **Only stage to buy** |
| **Stage 3** — Topping | Wide swings at highs, false breakouts | Reduce, no new positions |
| **Stage 4** — Declining | Below all MAs, bearish alignment | Full cash, stay away |

If the stock is NOT in Stage 2, stop here and tell the user. No further analysis needed.
```

**Why this works:**
- Clear classification table (4 options, each with characteristics and action)
- **Hard gate**: "stop here" — the methodology itself says no other stage is buyable, so further analysis would be wasted
- The gate is explicit, not a suggestion
- Saves tokens and produces more accurate results

---

## Example 4: Router Pattern (stock-correlation, Step 2)

```markdown
## Step 2: Route to the Correct Sub-Skill

| User Request | Route To | Examples |
|---|---|---|
| Single ticker, wants related stocks | **Sub-Skill A** | "what correlates with NVDA" |
| Two+ tickers, wants relationship | **Sub-Skill B** | "correlation between AMD and NVDA" |
| Group, wants structure/grouping | **Sub-Skill C** | "correlation matrix for FAANG" |
| Time-varying or conditional | **Sub-Skill D** | "rolling correlation AMD NVDA" |

If ambiguous, default to **Sub-Skill A** for single tickers, **Sub-Skill B** for two tickers.
```

**Why this works:**
- Routing table with concrete examples for each path
- Default behavior for ambiguous cases — the skill never stalls
- Each sub-skill is self-contained with its own sub-steps (A1, A2, A3)

---

## Example 5: Detection Flow with Decision Tree (github-auth)

```markdown
## Detection Flow

` ` `bash
git --version
gh --version 2>/dev/null || echo "gh not installed"
gh auth status 2>/dev/null || echo "gh not authenticated"
git config --global credential.helper 2>/dev/null || echo "no git credential helper"
` ` `

**Decision tree:**
1. If `gh auth status` shows authenticated → use `gh` for everything
2. If `gh` is installed but not authenticated → use "gh auth" method
3. If `gh` is not installed → use "git-only" method (no sudo needed)
```

**Why this works:**
- Detects 4 dimensions in one block: git, gh, gh auth, credential helper
- Decision tree has 3 clear paths — skill works for everyone
- Each path leads to a self-contained method section
- Checks first instead of assuming

---

## Example 5b: Dual-Method with Runtime Awareness (duckduckgo-search)

```markdown
## Detection Flow

` ` `bash
command -v ddgs >/dev/null && echo "DDGS_CLI=installed" || echo "DDGS_CLI=missing"
` ` `

Decision tree:
1. If `ddgs` CLI is installed → prefer `terminal` + `ddgs`
2. If `ddgs` CLI is missing → do not assume `execute_code` can import `ddgs`
3. If the user wants DuckDuckGo specifically → install `ddgs` first
4. Otherwise → fall back to built-in web/browser tools

**Important runtime note:**
- Terminal and `execute_code` are separate runtimes
- A successful shell install does not guarantee `execute_code` can import `ddgs`
```

**Why this works:**
- Explicitly warns about the terminal vs execute_code runtime boundary
- 4-level degradation chain: CLI → Python → install → built-in fallback
- `fallback_for_toolsets: [web]` in frontmatter auto-hides when web toolset is configured
- Combines frontmatter-level activation control with runtime-level method selection

---

## Example 6: Runtime Dependency Check with Algorithm Fallback (stock-correlation)

```markdown
## Step 1: Ensure Dependencies Are Available

**Current environment status:**

` ` `
!`python3 -c "exec('try:\n import yfinance, pandas, numpy\n print(f\'yfinance={yfinance.__version__} pandas={pandas.__version__} numpy={numpy.__version__}\')\nexcept Exception:\n print(\'DEPS_MISSING\')')"`
` ` `

If `DEPS_MISSING`, install required packages before running any code:

` ` `python
import subprocess, sys
subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", "yfinance", "pandas", "numpy"])
` ` `

If all dependencies are already installed, skip the install step and proceed directly.
```

**Why this works:**
- Checks at runtime, not static instructions
- Reports actual versions (useful for debugging)
- Graceful fallback (`|| echo "DEPS_MISSING"`)
- Conditional action: only install if needed, skip otherwise
- Includes the exact install command — a fragile operation gets an exact script

---

## Example 7: Scorecard Output (sepa-strategy, Step 9)

```markdown
## Step 9: Respond to the User

Present a structured analysis report with these sections:

1. **Stock & Stage**: Ticker, current price, identified stage, base count
2. **Trend Template Scorecard**: 8-condition checklist with pass/fail and actual values
3. **Fundamental Grade**: A/B/C/D with EPS growth, acceleration, revenue, margins
4. **Pattern Identified**: Which pattern, key measurements
5. **Entry Assessment**: Pivot price, buy zone, breakout volume requirement
6. **Market Environment**: Current assessment and the risk per trade it implies
7. **Position Sizing**: Exact shares, stop price, targets, reward/risk ratio
8. **Overall Verdict**: Strong Buy Setup / Watch List / Pass

Always end with the disclaimer that this is educational analysis, not investment advice.
```

**Why this works:**
- A fixed structure fits here: the output is a methodology scorecard the user reads as a checklist, so consistency across runs is the point
- Each section names the data it carries
- Verdict system with 3 clear options (a decision, not a spectrum)
- Mirrors the step order, including environment before sizing
- Ends with the required disclaimer

For open-ended analysis, prefer an output contract instead (Example 10).

---

## Example 8: Reference File Pointer Pattern (sepa-strategy)

```markdown
## Reference Files

- `references/stage-analysis.md` — Four-stage theory, transition signals, base counting
- `references/trend-template.md` — Detailed 8-condition explanations and memory aids
- `references/fundamentals.md` — EPS, revenue, margins, institutional holdings, catalysts
- `references/patterns.md` — VCP 7 rules, cup-with-handle, flat base, flag, HTF
- `references/entry-rules.md` — Pivot point mechanics, buy zone, true vs false breakout
- `references/position-sizing.md` — Formula, stop loss evolution, pyramiding, loss handling
- `references/market-environment.md` — Bull/choppy/bear criteria and position adjustments
```

**Why this works:**
- Each reference file is listed with a one-line description
- Descriptions tell you what's in the file without opening it (saves tokens)
- Files are organized by concept-cluster, not by step
- 7 files is near the sweet spot for methodology-pattern skills

---

## Example 9: Edge Cases in Reference File (options-payoff, strategies.md)

```markdown
## Edge Cases

- **DTE = 0**: skip BS entirely, use intrinsic value only
- **IV = 0**: BS undefined (σ=0), use max(intrinsic, 0)
- **K1 > K2**: warn user, auto-sort strikes ascending
- **Negative theoretical value**: clip to 0 for display (arbitrage-free floor)
- **Calendar with IV skew**: use separate IV sliders for near vs far leg
```

**Why this works:**
- Specific conditions, not vague "handle errors"
- Each edge case has an exact resolution
- Placed in the reference file (not SKILL.md) to keep main instructions lean
- These are the cases that would cause bugs without explicit handling

---

## Example 10: Output Contract (earnings-preview, Steps 3-4)

```markdown
## Step 3: Build the Earnings Preview

The briefing should let the user see the setup at a glance. Cover these five areas;
if the data for one is missing, say so in a line rather than dropping it.

1. **Date and context** — company, ticker, sector and industry; the report date and
   whether it lands before the open or after the close; current price with 1-week
   and 1-month performance; market cap.
2. **Consensus estimates** — a table of this quarter's EPS and revenue consensus with
   low, high, analyst count, year-ago value, and expected growth. A high/low spread
   wider than about 20% of consensus signals unusual uncertainty; say so when you see it.
3. **Beat/miss track record** — ...
4. **Analyst sentiment** — ...
5. **What to watch** — the few things the market will focus on in this print, chosen
   for this company and sector ... This is the judgment part of the briefing.

## Step 4: Respond to the User

Open with the headline — the report date and a one-line read of the setup — then the
five areas above, using tables where they help. Close with a short read of the overall
setup, framed as what the street expects rather than a recommendation.
```

**Why this works:**
- Says what must be covered, not which headings to fill; missing data gets a line instead of a silent gap
- Carries the domain heuristic with its threshold (spread wider than ~20% of consensus)
- Marks the one judgment section and leaves the choice of what matters to the model
- Leads with the headline and describes length qualitatively ("a short read")
- Contains no invented figures for a real company for the model to copy

---

## Anti-Example: Vague Output (avoid this)

```markdown
## Respond to the User

Summarize the analysis results in a clear and readable format.
Include relevant metrics and insights.
```

**Why this fails:**
- Doesn't say what to lead with or which metrics matter for this skill
- No required caveats, so data limitations go unmentioned
- No verdict → user must interpret everything themselves

---

## Anti-Example: The Scripted, Shouting Step (avoid this)

```markdown
## Step 4: Respond to the User

IMPORTANT: You MUST show all 5 sections. Think step by step and double-check every number.

1. Lead with: "AAPL reports earnings on [date]. Here's what to expect."
2. Show all 5 sections with headers and tables
3. End with a 2-3 sentence summary

Example: "AAPL has beaten EPS estimates in 4 of the last 4 quarters by an average of 2.6%."
```

**Why this fails on current models:**
- Capitalized MUST/IMPORTANT and "double-check" lead to over-checking and rigid, padded output
- "Think step by step" is redundant with built-in thinking
- The sentence count caps the synthesis regardless of how much the data says
- The worked example carries invented figures for a real company, which the model copies in shape and can mistake for fact

# Writing SKILL.md and Reference Files

Detailed instructions for authoring each part of a skill. This is the reference companion to Steps 3-4 of the skill-creator workflow.

## Writing for Current Claude Models

Current Claude models follow instructions closely and literally, plan multi-step work on their own, and verify their own work without being asked. Skills written for earlier models often over-steer them. Apply one test to every line: **could the model already know this?** Re-run that test when a new model generation ships — a line that was load-bearing for one model can be dead weight for the next.

- **Keep what only the author knows.** The environment and tools, exact commands, API contracts and field names, defaults, the domain heuristics and thresholds, the quality bar, and the *reasons* behind each constraint. Context is never cruft, and a skill that gives too little context gets generic output.
- **Cut what the model does by default.** "Be thorough", "think step by step", "plan before acting", "double-check your answer", "don't be lazy". These don't improve the work; on current models they cause over-planning and over-verification.
- **Say it once, plainly, with the reason.** Capitalized MUST/NEVER/CRITICAL and repeated warnings made older models comply; current models over-apply them, and an anxious skill produces cautious, hedging output. Hedges cut the other way — "try to include X if possible" now reads as permission to skip X. State real requirements directly.
- **Match specificity to fragility.** Exact commands for narrow bridges (installs, auth, CLI flags, destructive operations, formulas that must be right). Goals, criteria, and heuristics for open ground (analysis, interpretation, writing), where a hand-written script is worse than the model's own plan.
- **Describe success rather than enumerating failures.** Keep a prohibition only when it encodes a real constraint (read-only access, compliance, privacy) or a failure you have actually seen — and give its reason.
- **Watch your examples.** A concrete example is the strongest signal in a skill: the model copies its length, tone, and structure. Label examples as illustrative, vary them when there are several, and don't invent figures for real companies.
- **Keep numbers out of length guidance.** "Two to three sentences" or "at most five bullets" starves the answer on hard cases; describe the length qualitatively ("a short read of the overall setup").
- **Leave history and maintenance out.** Past incidents, PR numbers, "this now works differently", and maintainer notes belong in the README or git history, not in text the model reads on every trigger.

## Writing the Frontmatter

Write the YAML frontmatter first. See `references/frontmatter-guide.md` for the complete field reference.

```yaml
---
name: skill-name-here
description: >
  [What it does — concrete, specific, with the tool or data source]
  [Use this skill whenever the user... — the categories of requests it serves,
   with the distinctive vocabulary users will use: methods, data types, entities]
  [Sideways entries — "also when the user asks X in context Y"]
  [Boundaries — "for Z, use sibling-skill instead"; read-only if relevant]
---
```

The description is routing text: it rides along in every request and decides whether the skill loads. Current skills tend to under-trigger, so calibrated urgency ("use this skill whenever...", "even if they only give a ticker") is fine here — this is the one place it belongs.

**Description quality rules:**
- Cover every category of request the skill serves, including sideways entries (a methodology skill should also catch "should I buy this stock" in its context)
- Name the specific tools, methods, or APIs the skill uses, and example entities (tickers, sites) where they help recognition
- Name categories instead of listing near-synonymous phrasings — ten ways to say "show me the price" cost tokens in every session and generalize worse than "current quotes and price history"
- Point to sibling skills for neighboring requests
- Keep behavior out of the description; the body is where the skill says how to do the work

## Writing Step 1: Detection Flow

Skills that use external tools should start with a detection flow — not just a single dependency check, but a probe of the dimensions that change what the skill does next, feeding a decision tree. See `references/dynamic-calling.md` for the complete pattern catalog.

### Template: Detection flow with decision tree

```markdown
## Step 1: Detection Flow

**Environment status:**
` ` `
!`(command -v tool_a && tool_a --version) 2>/dev/null || echo "TOOL_A_MISSING"`
` ` `

` ` `
!`(command -v tool_b && tool_b --version) 2>/dev/null || echo "TOOL_B_MISSING"`
` ` `

` ` `
!`echo $API_KEY | head -c 8 && echo "...KEY_SET" || echo "KEY_NOT_SET"`
` ` `

**Decision tree:**
1. If `tool_a` available and `KEY_SET` → **Method 1** (preferred, richest)
2. If `tool_a` available but `KEY_NOT_SET` → guide auth setup, then Method 1
3. If `tool_a` missing but `tool_b` available → **Method 2** (fallback)
4. If neither available → install `tool_a`, then Method 1
```

### Key rules for detection flows

- **Always use fallback sentinels:** `|| echo "SENTINEL"`, so a check never hangs or errors silently
- **Detect the dimensions that matter:** tool existence, auth state, runtime environment
- **Produce a decision tree:** give a second method path wherever a real alternative exists
- **Show partial keys:** `echo $KEY | head -c 8` lets users verify without exposing secrets
- **Treat runtimes as separate:** Terminal and execute_code are different — a shell install doesn't mean execute_code has the package
- **Keep checks fast:** Under 2 seconds — they run synchronously before the skill loads

For pure analysis skills (no external deps), use a "Gather Data" step that still detects data source availability (e.g., "if yfinance available, use it; otherwise accept manual input from user").

## Writing Core Steps (2 through N)

Number the steps whose order genuinely matters — fetch before compute, a gate before the analysis that depends on it. For each step:

1. **Clear heading**: `## Step N: [Verb] [Object]` (e.g., "Compute Correlations", "Identify Stage")
2. **Decision table** if the step involves routing or classification
3. **Pass/fail gate** where a failed check really ends the analysis ("If the stock is not in Stage 2, stop here and tell the user")
4. **Exact code or commands** for anything that must be computed or called precisely — put arithmetic in code rather than asking the model to estimate it
5. **Criteria and heuristics** for the judgment the step requires, with the reasons — what makes a range "wide", which signals matter for this kind of company
6. **Reference pointer** for deep content: "Read `references/X.md` for details."

Inside a step, describe the outcome rather than choreographing how to reach it. "Pick the few things the market will focus on in this print — revenue growth direction, margin trend, line items that moved sharply" leaves the model room to judge; "Step 3a: compute X. Step 3b: compare Y..." for judgment work does not.

## Writing Parameter Defaults

Give every parameter an explicit default so the skill works with partial input:

```markdown
| Parameter | Default if not provided | Rationale |
|---|---|---|
| Lookback period | 1y | Balances recency and statistical significance |
| Ticker | SPY | Most liquid, universally recognized |
| Risk per trade | 1% | Standard conservative sizing |
```

## Writing the Final Step: Respond to the User

The last step states the **output contract** — what a good answer contains — rather than a fill-in-the-blanks template:

```markdown
## Step N: Respond to the User

Open with [the headline the user needs first — the verdict, the number, the date],
then cover [the content areas, and which ones need tables]. Close with [the synthesis
or verdict on its defined scale].

Include the caveats that apply: [data limitations], [required disclaimer].
```

- **Lead with the answer.** Say what the first line should deliver.
- **List required content, not required headings.** Say what must be covered and let the model shape sections to the evidence — including saying briefly when data for an area is missing.
- **Define verdict and grade scales exactly** when the skill is evaluative (Strong Buy Setup / Watch List / Pass).
- **Pin the format only where format matters** — scorecards, checklists, widgets, anything a user or downstream tool parses.
- **Describe length qualitatively.**

---

## Writing Reference Files

### Naming Convention
- `lowercase-hyphenated.md` (never camelCase or underscores)
- Topic-focused: `quantization.md`, `position-sizing.md`
- One file per concept-cluster, not per section

### Reference File Structure

```markdown
# [Topic Title]

[1-3 sentence introduction]

## [First Major Section]

### [Subsection]

[Tables, code blocks, formulas]

## Edge Cases

- [Specific condition] -> [How to handle]
```

Dated data (benchmark tables, market snapshots) belongs in a reference file with an explicit "as of" date, so the SKILL.md stays stable and the model knows how fresh the numbers are.

### Size Guidelines
- **Quick lookup** (API tables, checklists): 50-150 lines
- **Deep guide** (technique, methodology): 150-400 lines
- **Comprehensive catalog** (visual effects, all endpoints): 400-900 lines

### How SKILL.md Should Reference Them

Use table pointers in the relevant step, not scattered inline links:

```markdown
Read `references/position-sizing.md` for the full formula, examples, and pyramiding rules.
```

Or as a reference section at the end:

```markdown
## Reference Files

- `references/api.md` -- Complete API endpoint reference
- `references/troubleshooting.md` -- Common errors and solutions
```