Skill Creator

Skill Creator

Create, evaluate, and iterate on high-quality agent skills. This skill guides the entire lifecycle: planning what the skill should do, writing SKILL.md and reference files, scoring quality against a rubric, and iterating until the skill meets production standards.

Philosophy: A great skill is not a long skill. It is a precise skill: exhaustive triggers, explicit defaults, clear steps with exit gates, deferred complexity via reference files, and a structured output template.

Core rule — always dynamic, never static: Skills MUST detect what tools, libraries, and auth are available at runtime and adapt their behavior accordingly. Never hardcode a single method. Always provide a detection flow with a decision tree and fallback paths. See references/dynamic-calling.md for the complete pattern catalog.

---

Step 1: Understand What the User Wants

Classify the request into one of these modes:

If ambiguous, ask: "Do you want to create a new skill, improve an existing one, or evaluate one?"

Gather Requirements (for Create mode)

Before writing anything, answer these questions (ask the user if unclear):

---

Step 2: Plan the Skill Architecture

Before writing SKILL.md, plan the structure. Read references/architecture-patterns.md for detailed guidance on each pattern.

Choose a Structural Pattern

Plan the Step Outline

Write out the step names before writing content. Every skill should have:

1. Detection flow (Step 1) -- dynamically detect available tools, auth state, and runtime environment; build a decision tree for which method to use 2. Core methodology (Steps 2-N) -- the actual work, with pass/fail gates; each step that calls an external tool should have method alternatives based on what Step 1 detected 3. Respond to user (Final step) -- structured output template

Target 5-9 steps total. More than 9 means the skill should be split or use a router pattern.

Plan the Detection Flow

Every skill that touches external tools MUST start with a runtime detection flow. Read references/dynamic-calling.md for all patterns. The detection flow answers:

The detection output feeds into a decision tree that the rest of the skill follows. Never assume — always check.

Plan Reference Files

Decide what goes in SKILL.md vs references/:

---

Step 3: Write the SKILL.md

Read references/writing-guide.md for detailed instructions on writing each section. Read references/frontmatter-guide.md for the complete YAML field reference.

Key Rules

1. Frontmatter first: name (lowercase-hyphenated, max 64 chars) and description (exhaustive trigger list, max 1024 chars) are required. Description needs 5+ triggers including sideways entry points.

2. Step 1 = detection flow: Use !command` with fallbacks to detect available tools, auth state, and runtime. Build a decision tree with multiple method paths (e.g., CLI preferred, Python fallback, built-in tools last resort). Never hardcode a single tool — always detect and adapt. See references/dynamic-calling.md`.

3. Core steps with method alternatives: Each step that calls an external tool should offer at least 2 paths based on what Step 1 detected. Use pattern: "If TOOL_A detected → Method 1, otherwise → Method 2." Each step gets ## Step N: [Verb] [Object], a decision table if routing, a pass/fail gate if evaluative, and a reference pointer for deep content.

4. Defaults table: Every parameter MUST have an explicit default. No skill should ever stall waiting for input.

5. Final step = output template: Number every output section. Specify exactly what data goes in each. Include a verdict/grade system if evaluative.

See references/skill-examples.md for annotated examples of each pattern.

---

Step 4: Write Reference Files

Read references/writing-guide.md for the full reference file authoring guide.

Key Rules

1. Naming: lowercase-hyphenated.md, one file per concept-cluster 2. Size: Quick lookup 50-150 lines, deep guide 150-400 lines, catalog 400-900 lines 3. Structure: H1 title, H2 sections, code blocks, tables, edge cases section at end 4. Linking: Use backtick paths in SKILL.md steps and a ## Reference Files section at the end

---

Step 5: Quality Check Before Delivery

Run the skill through the quality rubric in references/quality-rubric.md. Score each dimension.

Quick Checklist

• [ ] Frontmatter has name and description (both required)
• [ ] Description has 5+ distinct trigger phrases
• [ ] Description includes sideways entry points
• [ ] SKILL.md is under 300 lines (ideally under 250)
• [ ] Every parameter has an explicit default
• [ ] Steps are numbered (## Step N: ...)
• [ ] Each step has a clear exit condition or deliverable
• [ ] Final step specifies exact output structure with numbered sections
• [ ] Complex content is in reference files, not inline
• [ ] Reference file pointers use backtick paths
• [ ] Step 1 has a detection flow with !command` checks and fallbacks (|| echo "..."`)
• [ ] Detection flow produces a decision tree with 2+ method paths
• [ ] Core steps adapt behavior based on detection results (not hardcoded to one tool)
• [ ] Separate runtimes treated as separate environments (terminal vs execute_code)
• [ ] Legal/ethical disclaimers included where appropriate
• [ ] No hardcoded ticker lists, tool paths, or static data that will go stale

If any item fails, fix it before delivering to the user.

---

Step 6: Improve an Existing Skill

When the user asks to improve a skill:

6a: Read the Current Skill

Load the skill with skill_view(name) or read the SKILL.md directly. Also read all reference files.

6b: Score It Against the Rubric

Use the quality rubric from references/quality-rubric.md. Present the score breakdown to the user:

6c: Propose Specific Improvements

List concrete changes ranked by impact:

1. [Highest impact] Add defaults table with 8+ parameters 2. [High impact] Rewrite description with 10+ trigger phrases 3. [Medium impact] Add structured output template to final step 4. ...

6d: Apply Changes

After user approval, edit the skill. Use skill_manage(action='patch', ...) for targeted changes or skill_manage(action='edit', ...) for full rewrites.

---

Step 7: Evaluate a Skill

When the user asks to evaluate or score a skill:

7a: Load and Analyze

Read the full SKILL.md and all reference files. Count lines, steps, triggers, defaults, reference files.

7b: Score Against Rubric

Use the comprehensive rubric from references/quality-rubric.md. Score each of the 10 dimensions on a 1-10 scale.

7c: Present the Scorecard

## Skill Quality Scorecard: [skill-name]

| # | Dimension | Score | Notes |
|---|---|---|---|
| 1 | Trigger quality | 8/10 | 12 triggers, includes sideways entries |
| 2 | Defaults coverage | 9/10 | All 11 parameters have defaults |
| 3 | Step architecture | 8/10 | 5 clear steps with gates |
| 4 | Reference file strategy | 7/10 | 2 files, could use troubleshooting |
| 5 | Dynamic content | 10/10 | Dep check + live data injection |
| 6 | Output template | 9/10 | 5 numbered sections + verdict |
| 7 | Error handling | 6/10 | Missing data handling unclear |
| 8 | Code/formula quality | 8/10 | Working JS, copy-paste ready |
| 9 | SKILL.md conciseness | 7/10 | 196 lines, well within target |
| 10 | Domain accuracy | 9/10 | BS formulas correct, edge cases covered |

**Overall: 81/100** -- Production quality

### Top 3 Improvements
1. ...
2. ...
3. ...

Benchmark Reference

For context, here are scores for known high-quality skills in this repo:

---

Step 8: Respond to the User

For Create mode

Deliver: 1. The complete SKILL.md content 2. All reference files 3. A README.md for the skill directory 4. The quality scorecard (from Step 5) 5. Suggested next steps (test it, iterate, publish)

For Improve mode

Deliver: 1. Before/after quality scores 2. Summary of changes made 3. Remaining improvement opportunities

For Evaluate mode

Deliver: 1. The full quality scorecard 2. Comparison to benchmark skills 3. Prioritized improvement list

---

Reference Files

• references/dynamic-calling.md -- Core reference: Detection flows, decision trees, method fallbacks, runtime awareness, and multi-tool adaptation patterns with annotated examples from production skills
• references/writing-guide.md -- Detailed instructions for writing SKILL.md sections, environment checks, defaults tables, output templates, and reference files
• 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, benchmark scores, and score interpretation
• references/skill-examples.md -- Annotated excerpts from top skills showing why specific patterns work

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, step architecture, reference strategy, output template, etc.) with benchmark 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.

Core rule: Skills must always detect available tools at runtime and adapt with decision trees and fallback paths — never hardcode 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

# As a plugin (recommended)
npx plugins add himself65/finance-skills --plugin finance-skill-creator

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

See the main README 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, benchmark scores, 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, detection flows, defaults tables, and output templates

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: 5-7 numbered steps, executed in order.

Example: earnings-preview

Step 1: Check yfinance
Step 2: Fetch earnings data
Step 3: Analyze estimates vs history
Step 4: Assess analyst sentiment
Step 5: Respond with 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 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:

• The routing table MUST have 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 any gate stops the analysis.

Structure: 7-9 numbered steps, each with explicit pass/fail criteria.

Example: sepa-strategy

Step 1: Gather stock data
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: Position sizing & stop loss
Step 8: Market environment check
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:

• Every step MUST have a clear pass/fail gate or a grading system
• Failed gates must stop 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 ALL detailed criteria to reference files; SKILL.md shows the checklist, reference shows the rubric
• Always end with a verdict system (Strong Buy / Watch / Pass)
• The final step output template should mirror the step structure (9 steps → 8 output sections)

---

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 MUST have a defaults table covering every parameter (the skill should NEVER stall 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 must specify: controls, stats cards, chart axes, colors, tooltips
• The final step should be 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: 3-5 steps + heavy reference files (one per endpoint category).

Example: funda-data

Step 1: Check API key
Step 2: Identify what user needs (mega routing table)
Step 3: Make the API call
Step 4: Handle common patterns
Step 5: Respond to user

Strengths: Comprehensive API coverage, reference files serve as living documentation. Weaknesses: Step 2 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
• Always include a "common patterns" step for things like pagination, rate limits, error codes
• API keys should use required_environment_variables in frontmatter, not inline instructions

---

Choosing Between Patterns

Anti-Patterns to Avoid

The Wall of Text

A single massive step with 50+ lines of instructions. Fix: Split into multiple steps with clear boundaries.

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

Steps that always proceed regardless of result. Fix: Add "If X fails, stop here" at every decision point.

The Vague Output

"Summarize the results for the user." Fix: Number every output section, specify what data goes in each.

The Hardcoded Universe

Static ticker lists or data that will go stale. Fix: Build universes dynamically at runtime using screening APIs.

Dynamic Calling Patterns

Skills MUST detect what's available at runtime and adapt. Never hardcode a single tool or method. 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

## 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)

## 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)

` ` `
!`(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)

` ` `
!`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 "import lib; print('lib ' + lib.__version__)" 2>/dev/null || echo "LIB_NOT_INSTALLED"`

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

` ` `
!`python3 -c "import yfinance, pandas, numpy; print(f'yfinance={yfinance.__version__} pandas={pandas.__version__} numpy={numpy.__version__}')" 2>/dev/null || echo "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:

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: funda-data

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

If `KEY_NOT_SET`:
- Ask the user for their Funda API key
- Guide them to https://funda.ai/dashboard to get one
- Once provided, export it: `export FUNDA_API_KEY=<key>`

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

` ` `
!`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 "import yfinance as yf; print(f'PRICE={yf.Ticker(\"^GSPC\").fast_info[\"lastPrice\"]:.0f}')" 2>/dev/null || echo "PRICE_UNAVAILABLE"`

Real Example: options-payoff (current SPX price)

**Current SPX reference price:**
` ` `
!`python3 -c "import yfinance as yf; print(f'SPX ≈ {yf.Ticker(\"^GSPC\").fast_info[\"lastPrice\"]:.0f}')" 2>/dev/null || echo "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

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

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:

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

# 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

## 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

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

Rule: Test in the runtime you'll use

# 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

# 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

# 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

# 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

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

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

Detecting once, ignoring later

# 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

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

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.

description: >
  [What it does] Analyze stocks using the SEPA methodology.
  [Expert triggers] SEPA, Minervini, VCP, trend template, Stage 2, pivot point.
  [Beginner triggers] "should I buy this stock", "is this a good setup".
  [Context triggers] When user shares a chart, mentions swing trading criteria.

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 Funda AI API" 3. List 5+ explicit trigger phrases in quotes 4. Include 2+ sideways entry points (unexpected phrasings) 5. End with context triggers ("also when the user...")

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

Optional Fields

version

Semantic version for the skill. Useful for tracking changes.

version: 1.0.0

author

Creator name or handle.

author: himself65

license

License identifier.

license: MIT

platforms

Restrict to specific operating systems. Omit to load on all platforms (default).

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.

required_environment_variables:
  - name: FUNDA_API_KEY
    prompt: "Funda AI API key"
    help: "Get one at https://funda.ai/dashboard"
    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).

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.

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:

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

Config Settings

Non-secret settings stored in config.yaml:

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

Complete Frontmatter Example

---
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

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 80-90.

Dimension 1: Trigger Quality (Description Field)

How well does the description field capture the full range of user requests that should activate this skill?

Benchmark: sepa-strategy scores 9/10 (15+ triggers including "should I buy this stock")

Dimension 2: Defaults Coverage

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

Benchmark: options-payoff scores 9/10 (11 parameters with defaults, rationale for each)

Dimension 3: Step Architecture

Are steps numbered, well-bounded, and sequenced logically with clear exit gates?

Benchmark: sepa-strategy scores 9/10 (9 steps, each with explicit pass/fail, "stop here" gates)

Dimension 4: Reference File Strategy

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

Benchmark: sepa-strategy scores 9/10 (250 lines, 7 reference files totaling ~29KB)

Dimension 5: Dynamic Calling & Runtime Adaptation

Does the skill detect available tools at runtime and adapt its behavior with multiple method paths?

Benchmark: github-auth scores 10/10 (detects gh vs git, auth state, credential helper; 3 distinct method paths). options-payoff scores 8/10 (dep check + live SPX price injection with fallback). duckduckgo-search scores 9/10 (CLI vs Python vs built-in, runtime awareness, fallback_for_toolsets).

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 Template

Does the final step specify the exact output structure?

Benchmark: sepa-strategy scores 9/10 (8 numbered sections + verdict + disclaimer)

Dimension 7: Error Handling & Missing Data

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

Benchmark: sepa-strategy scores 8/10 ("proceed with what you have, flag RS as significant gap")

Dimension 8: Code / Formula Quality

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

Benchmark: stock-correlation scores 8/10 (full Python functions with imports, dropna, edge cases)

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

Dimension 9: SKILL.md Conciseness

Is the main SKILL.md file appropriately sized?

Benchmark: options-payoff scores 8/10 (196 lines, 2 reference files handle the depth)

Dimension 10: Domain Accuracy

Is the skill's domain knowledge correct and trustworthy?

Benchmark: options-payoff scores 9/10 (Black-Scholes correct, edge cases documented, disclaimer present)

---

Scoring Summary Table

Copy this template when scoring a skill:

| # | Dimension | Score | Notes |
|---|---|---|---|
| 1 | Trigger quality | /10 | |
| 2 | Defaults coverage | /10 | |
| 3 | Step architecture | /10 | |
| 4 | Reference file strategy | /10 | |
| 5 | Dynamic content | /10 | |
| 6 | Output template | /10 | |
| 7 | Error handling | /10 | |
| 8 | Code/formula quality | /10 | |
| 9 | SKILL.md conciseness | /10 | |
| 10 | Domain accuracy | /10 | |
| **Total** | | **/100** | |

Score Interpretation

Annotated Skill Examples

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

Example 1: Exhaustive Description (sepa-strategy)

description: >
  Analyze stocks using Mark Minervini's SEPA (Specific Entry Point Analysis) methodology.
  Use this skill whenever the user mentions SEPA, Minervini, superperformance, trend template,
  VCP (Volatility Contraction Pattern), Stage 2 uptrend, stage analysis, pivot point breakout,
  or asks about growth stock screening criteria. Also triggers when the user wants to evaluate
  whether a stock meets swing trading entry criteria, check moving average alignment (bullish
  stacking: price above 50MA above 150MA above 200MA), assess breakout quality with volume confirmation,
  calculate position sizing based on risk percentage, or identify consolidation patterns like
  cup-with-handle, flat base, bull flag, or high tight flag. Use this skill even when the user
  simply asks "should I buy this stock" or "is this a good setup" in the context of growth/momentum
  trading, or when they share a stock chart and want pattern analysis.

Why this works:

• Starts with the formal methodology name (expert trigger)
• Lists 8+ domain-specific terms (VCP, Stage 2, pivot point, bullish stacking)
• Describes behavioral triggers ("evaluate whether a stock meets...")
• Includes sideways entries ("should I buy this stock", "is this a good setup")
• Covers input modalities ("share a stock chart")

---

Example 2: Comprehensive Defaults Table (options-payoff)

| 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 (NOT strike) | middle strike |
| 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)
• Includes a critical warning: "spot price is NOT the strike"

---

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

## 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" — prevents wasted analysis on Stage 1/3/4 stocks
• The gate is explicit and non-negotiable, not a suggestion
• Saves tokens and produces more accurate results

---

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

## 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)

## 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
• Never assumes — always checks first

---

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

## 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)

## Step 1: Ensure Dependencies Are Available

**Current environment status:**

` ` `
!`python3 -c "import yfinance, pandas, numpy; print(f'yfinance={yfinance.__version__} pandas={pandas.__version__} numpy={numpy.__version__}')" 2>/dev/null || echo "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 — no guessing

---

Example 7: Structured Output Template (sepa-strategy, Step 9)

## 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. **Position Sizing**: Exact shares, stop price, targets, reward/risk ratio
7. **Market Environment**: Current assessment and sizing impact
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:

• 8 numbered sections — output is always structured identically
• Each section specifies exactly what data to include
• Verdict system with 3 clear options (not a spectrum, a decision)
• Mirrors the step structure (steps 2-8 → output sections 1-8)
• Ends with required disclaimer

---

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

## 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)

## 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

---

Anti-Example: Vague Output (avoid this)

## Respond to the User

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

Why this fails:

• "Clear and readable" means different things every time
• "Relevant metrics" — which ones? All of them? Top 3?
• No numbered sections → inconsistent output across runs
• No verdict → user must interpret everything themselves

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 the Frontmatter

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

---
name: skill-name-here
description: >
  [Line 1: What it does — concrete, specific]
  [Line 2-5: Exhaustive trigger list — include BOTH expert terminology AND beginner phrasing]
  [Line 6+: Edge case triggers — "also when user does X", "even if they only say Y"]
---

Description quality rules:

• Minimum 5 distinct trigger phrases
• Include at least 2 "sideways entry points" (unexpected phrasings that should still trigger)
• Name specific tools, methods, or APIs the skill uses
• Include example ticker symbols or entities if domain-specific

Writing Step 1: Detection Flow

Every skill that uses external tools MUST start with a detection flow — not just a single dep check, but a multi-dimensional probe that feeds a decision tree. See references/dynamic-calling.md for the complete pattern catalog.

Template: Detection flow with decision tree

## 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" — never let a check hang or error silently
• Detect multiple dimensions: tool existence + auth state + runtime environment
• Produce a decision tree: At least 2 distinct method paths, preferably 3+
• 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)

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 if applicable ("If condition fails, stop here and tell the user") 4. Reference pointer for deep content: "Read references/X.md for details." 5. Defaults table for any parameters the user might omit

Writing Parameter Defaults

Every skill MUST have explicit defaults for all parameters. Create a table:

| 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 MUST specify the exact output structure:

## Step N: Respond to the User

Present results with these sections:

1. **[Section name]**: [What to include]
2. **[Section name]**: [What to include]
...

### Caveats to include
- [Required disclaimer]
- [Data limitations]

Number every output section. Include a verdict/grade system if the skill is evaluative.

---

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

# [Topic Title]

[1-3 sentence introduction]

## [First Major Section]

### [Subsection]

[Tables, code blocks, formulas]

## Edge Cases

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

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:

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

Or as a reference section at the end:

## Reference Files

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