Skill Engineering

Skill Engineering Framework

Designs high-fidelity OpenCode AI skills with precision trigger engineering, stub-free validation frameworks, and domain-specific constraint patterns. When loaded, this skill makes the model act as a senior skill architect — reviewing, creating, or refining SKILL.md files to meet the zero-tolerance quality standards of the agent-skill-router system.

TL;DR Checklist

• Verify YAML frontmatter: all required fields present, name matches directory kebab-case exactly
• Check description starts with active verb, includes 1–2 domain terms, stays under ~200 characters
• Validate triggers: 5–8 terms blending technical precision (e.g., stop loss, PromQL) with conversational discovery (e.g., how do i limit losses)
• Confirm file is ≥ 3,000 bytes and contains zero instances of the stub sentinel phrase
• Ensure Core Workflow has numbered steps with Checkpoint: notes — no generic "identify → apply → validate" patterns
• Include at least 2 real code blocks with actual implementations (not placeholders like # TODO)
• Provide BAD vs GOOD comparison pair(s) relevant to the domain
• Add MUST DO / MUST NOT DO constraints that are actionable and specific (no "follow best practices")

When to Use

Use this skill when:

• Designing a new SKILL.md from scratch for any domain (agent, cncf, coding, trading, go, linux, programming)
• Reviewing an existing SKILL.md that failed automated validation (stub detection, size checks, trigger quality)
• Refining trigger sets that are too broad (matching irrelevant conversations) or too narrow (missing natural phrasings)
• Crafting descriptions that read like topic labels instead of action-oriented capability statements
• Auditing skills for the zero-tolerance stub policy — checking for placeholder code, thin content, or generic workflows
• Adding new skills to the router index and needing to update README.md catalog generation

When NOT to Use

Avoid this skill for:

• Implementing domain logic inside a skill (use coding-* or domain-specific implementation skills instead) — this skill designs the SKILL.md wrapper, not the runtime code
• Writing user-facing documentation, blog posts, or README files — use writing-technical-documentation or similar
• Debugging runtime agent behavior that is unrelated to skill metadata or trigger matching — use agent-runtime-log-analyzer
• Creating skills with fewer than 3 meaningful triggers or for topics too narrow to warrant a separate skill entry

Core Workflow

1. Parse the Target or Brief — Determine whether you are creating from scratch, reviewing an existing file, or refining specific sections. Read the full SKILL.md content and AGENTS.md quality checklist. Checkpoint: Identify the domain (agent, cncf, coding, trading, etc.) and confirm the directory name matches the intended name field exactly in kebab-case.

2. Engineer the YAML Frontmatter — Construct or audit all required frontmatter fields:

   • Verify name matches the directory topic name exactly (case-sensitive, kebab-case)
   • Rewrite description with an active verb and domain-specific terms if generic
   • Build the trigger set using the Two-Tier Trigger Strategy (see Implementation Patterns)
   • Set metadata.role, scope, and output-format to values that match the skill's actual behavior, not defaults Checkpoint: All required fields present. No typos in enum values (implementation not implemention). Triggers between 5–8 terms.

3. Craft the H1 Title and Purpose Paragraph — Write a human-readable title (not kebab-case) and a 1–3 sentence role description from the model's perspective. The purpose paragraph must state what loading this skill makes the model do, not what the topic is about. Checkpoint: Title is readable English, not risk-stop-loss. Purpose paragraph contains an action verb and describes model behavior.

4. Build the Core Workflow with Domain-Specific Steps — Write 4–6 numbered steps. Each step must name a concrete action (e.g., "Calculate ATR-based stop level" not "Apply pattern") and end with a Checkpoint: line specifying what to verify before proceeding. Checkpoint: No generic step names. Every step has domain-specific detail. Every step ends with a Checkpoint.

5. Create Implementation Patterns / Reference Guide — Add 2+ patterns as subsections. Each pattern must include:

   • A descriptive name (e.g., "ATR-Based Stop Calculation", not "Pattern 1")
   • A brief explanation of when and why to use it
   • A real code block with typed signatures, docstrings, and guard clauses
   • At least one BAD vs GOOD comparison somewhere in this section Checkpoint: Code blocks contain actual implementations — no pass bodies, no return {}, no # TODO: add implementation.

6. Define Constraints (MUST DO / MUST NOT DO) — Write 5–8 actionable rules per subsection. Each constraint must be a specific behavior, not an abstract principle. Reference code-philosophy laws where data flow or constraint architecture applies. Checkpoint: No constraints read like "follow best practices" or "ensure quality." Each is testable against the actual skill file.

7. Run Validation Against Stub Policy — Apply the zero-tolerance checks:

   • File size ≥ 3,000 bytes (excluding frontmatter)
   • Zero occurrences of the stub sentinel phrase
   • ≥ 2 real code blocks with working implementations
   • Core Workflow steps are domain-specific with Checkpoints
   • Triggers avoid ultra-generic single words Checkpoint: All checks pass. If any fail, iterate and fix before considering the skill complete.

┌─────────────────────────────────────────────────────────────────────────────────┐
│                         SKILL LIFECYCLE: DESIGN → VALIDATE → DEPLOY                │
└─────────────────────────────────────────────────────────────────────────────────┘

  ┌──────────────┐
  │  Idea / Brief │
  └───────┬──────┘
          │
          ▼
  ┌──────────────────────────────────────────────────────────────────────────────┐
  │                        STEP 1: FRONTMATTER ENGINEERING                         │
  │                                                                                │
  │   • name = directory kebab-case (exact match)                                  │
  │   • description = active verb + domain terms (<200 chars)                      │
  │   • triggers = 5-8 terms, two-tier strategy (technical + conversational)       │
  │   • role/scope/output-format match actual behavior                             │
  └────────────────────────┬───────────────────────────────────────────────────────┘
                           │
                           ▼
  ┌──────────────────────────────────────────────────────────────────────────────┐
  │                      STEP 2: CONTENT ARCHITECTURE                              │
  │                                                                                │
  │   • H1 title: human-readable English (NOT kebab-case)                          │
  │   • Purpose paragraph: what the model DOES (not what the topic IS)             │
  │   • TL;DR Checklist: 5-7 concrete checkbox items                               │
  │   • When to Use / NOT to Use: specific situations                              │
  └────────────────────────┬───────────────────────────────────────────────────────┘
                           │
                           ▼
  ┌──────────────────────────────────────────────────────────────────────────────┐
  │                    STEP 3: DOMAIN-SPECIFIC WORKFLOW                            │
  │                                                                                │
  │   • 4-6 numbered steps, each with **Checkpoint:**                              │
  │   • No generic "identify → apply → validate" patterns                          │
  │   • Steps describe concrete actions in the domain (e.g., trading formulas)     │
  └────────────────────────┬───────────────────────────────────────────────────────┘
                           │
                           ▼
  ┌──────────────────────────────────────────────────────────────────────────────┐
  │                  STEP 4: IMPLEMENTATION PATTERNS (CODE)                        │
  │                                                                                │
  │   • 2+ patterns with real code blocks                                          │
  │   • Typed signatures, docstrings, guard clauses                                │
  │   • BAD vs GOOD comparison pairs                                               │
  │   • No placeholders: pass bodies, # TODO, return {}                            │
  └────────────────────────┬───────────────────────────────────────────────────────┘
                           │
                           ▼
  ┌──────────────────────────────────────────────────────────────────────────────┐
  │                  STEP 5: CONSTRAINTS & VALIDATION                              │
  │                                                                                │
  │   • MUST DO: 5-8 actionable, specific rules                                    │
  │   • MUST NOT DO: 4-6 concrete anti-patterns                                    │
  │   • Stub policy checks: size ≥ 3KB, no sentinels, ≥ 2 real code blocks        │
  │   • Reference code-philosophy for constraint design                            │
  └────────────────────────┬───────────────────────────────────────────────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │ PASS? ──Yes──► Deploy to router index  │
                    │ No ──► Fix and re-validate             │
                    └─────────────┘

Implementation Patterns / Reference Guide

Pattern 1: Trigger Engineering — Two-Tier Strategy

The most impactful design decision in any skill is its trigger set. Triggers drive auto-discovery; poor triggers mean the skill exists but never fires. Use the Two-Tier Trigger Strategy: blend technical precision terms with conversational discovery phrases that non-expert users or business stakeholders would naturally search for.

Tier 1 — Technical Terms: Exact domain vocabulary used by practitioners, documentation, and official product names. Tier 2 — Conversational Variants: Natural language questions, business terminology, and everyday problem descriptions.

# ❌ BAD: Only technical terms — misses 60%+ of natural user searches
triggers: stop-loss, trailing-stop, atr-based, volatility-adjusted

# ❌ BAD: Too broad — fires on nearly every trading conversation  
triggers: risk, trading, loss, price, money

# ❌ GOOD: Two-tier blend — captures both experts and business users
triggers: >-
  stop loss, trailing stop, ATR stop, position protection,
  emergency stop, how do i limit losses, capital protection

Domain-specific trigger construction templates:

# CNCF Skills (Kubernetes example)
triggers: >-
  kubernetes, k8s, container orchestration, managing containers,
  deploying applications, scaling apps, helm chart management

# Trading Skills (VWAP execution example)  
triggers: >-
  vwap, volume-weighted average price, execution algorithm,
  order execution strategy, how do i execute large orders, minimal market impact, institutional trading

# Coding Skills (Code review example)
triggers: >-
  code review, pull request review, PR quality check, security audit,
  OWASP guidelines, architectural review, peer review process

Calibration heuristic for each trigger term: Ask "If someone says this word/phrase in a conversation, would they plausibly need this skill?" If no → exclude or make more specific.

Pattern 2: Description Writing — Active Verb + Domain Specificity

A description tells the router what capability this skill provides. It must start with an active verb and include domain-specific terms. Never write it as a topic label.

# ❌ BAD: Topic label, no action verb
description: Stop loss strategies for trading

# ❌ BAD: Too vague, missing domain context
description: Implements risk management patterns

# ✅ GOOD: Active verb + specific strategies + domain context
description: >-
  Implements stop-loss strategies (fixed percentage, ATR-based, trailing, 
  support/resistance levels) to protect position capital in algorithmic 
  trading systems under volatile market conditions

# ❌ BAD: Describes the skill itself, not what it makes the model do
description: This skill covers trigger engineering and stub detection rules

# ✅ GOOD: States model behavior + scope
description: >-
  Designs high-fidelity OpenCode AI skills with precision trigger engineering, 
  stub-free validation frameworks, and domain-specific constraint patterns for 
  the agent-skill-router system

Description formula: [Active verb] [what it does] ([specific variants/methods]) to [purpose/outcome] in [domain context].

Pattern 3: Stub Detection — The Five Prohibited Patterns

The zero-tolerance stub policy rejects skills exhibiting any of these five patterns. Build defenses against each during design:

def validate_stub_resistance(skill_content: str) -> dict:
    """Apply the five zero-tolerance stub detection checks.
    
    Returns validation result with pass/fail per check and actionable fixes.
    Implements Fail Fast (Law 4) — halts on first critical violation.
    """
    violations = []
    
    # Check 1: Stub sentinel phrase
    # Sentinel to detect: "Implementing" + "this specific pattern or feature"
    sentinel_marker = "Implementing" + " this specific pattern or feature"
    if sentinel_marker in skill_content:
        violations.append({
            "rule": "stub-sentinel",
            "severity": "fatal",
            "fix": "Remove the sentinel phrase and replace with domain-specific implementation details"
        })
    
    # Check 2: File size (excluding frontmatter)
    content_without_fmatter = skill_content.split("---\n", 2)[-1] if "---" in skill_content else skill_content
    if len(content_without_fmatter.encode("utf-8")) < 3000:
        violations.append({
            "rule": "file-size",
            "severity": "fatal",
            "fix": f"Expand content from {len(content_without_fmatter)} bytes to at least 3,000 bytes with real examples"
        })
    
    # Check 3: Generic workflow steps
    generic_patterns = [
        r"\bidentify\s+.*\s*→\s*apply\b",
        r"\bidentify.*analyze.*implement.*validate\b", 
        r"Step \d+: [A-Z][a-z]+\s+\-\s+(Identify|Apply|Implement|Validate)"
    ]
    import re
    for pattern in generic_patterns:
        if re.search(pattern, skill_content):
            violations.append({
                "rule": "generic-workflow", 
                "severity": "fatal",
                "fix": "Replace generic step names with domain-specific actions (e.g., 'Calculate ATR-based stop' not 'Apply pattern')"
            })
    
    # Check 4: Missing real code blocks (implementation skills)
    code_blocks = skill_content.split("```")
    real_code_count = sum(1 for i, block in enumerate(code_blocks) 
                         if i % 2 == 1 and "pass" not in block.lower() 
                         and "# TODO" not in block and "return {}" not in block)
    
    # Check 5: Triggers too broad
    triggers_raw = ""
    for line in skill_content.split("\n"):
        if line.startswith("triggers:") or line.startswith("  triggers:"):
            triggers_raw = line.split(":", 1)[1].strip()
    trigger_terms = [t.strip().lower() for t in triggers_raw.replace(">", "").replace("'", "").replace('"', "").split(",")]
    generic_triggers = {
        "code", "data", "risk", "pattern", "system", "management", 
        "implementation", "development", "testing", "quality"
    }
    overly_generic = [t for t in trigger_terms if t in generic_triggers and len(t) < 6]
    
    return {
        "violations": violations,
        "overall_pass": len(violations) == 0,
        "checks": {
            "stub_sentinel": len([v for v in violations if v["rule"] == "stub-sentinel"]) == 0,
            "file_size": len([v for v in violations if v["rule"] == "file-size"]) == 0,
            "generic_workflow": len([v for v in violations if v["rule"] == "generic-workflow"]) == 0,
            "real_code_blocks": real_code_count >= 2,
            "trigger_quality": len(overly_generic) == 0
        }
    }

# Usage: validate_stub_resistance(skill_md_content)

Pattern 4: Core Workflow Design — Domain-Specific Checkpoints

Generic workflows read like: "1. Identify the pattern. 2. Apply the solution. 3. Validate the result." This is a stub signature — it teaches nothing domain-specific. Every step must name a concrete action and end with a checkpoint.

# ❌ BAD: Generic workflow (stub pattern)
1. **Identify the use case** — Determine what kind of problem the user has.
2. **Apply the pattern** — Use the appropriate design pattern for the situation.
3. **Validate the implementation** — Make sure the code follows best practices.

# ✅ GOOD: Domain-specific workflow with checkpoints (trading domain)
1. **Assess Market Regime** — Determine if the current market is trending, 
   ranging, or high-volatility using ATR and ADX indicators.
   **Checkpoint:** If ADX < 20 and ATR ratio < 1.5, classify as ranging regime.

2. **Select Stop Type** — Map the identified regime to the appropriate stop strategy:
   - Trending → Trailing stop with ATR-based distance
   - Ranging → Support/resistance level stop with 2% buffer
   - High-volatility → Volatility-adjusted stop (3x ATR) + hard emergency stop
   **Checkpoint:** If no suitable regime matches, default to volatility-adjusted with emergency layer.

3. **Calculate Stop Level** — Apply the formula for the selected stop type.
   For ATR-based: `stop_price = current_price - (atr_value * multiplier)` where 
   multiplier is 2.0 for normal conditions and 3.0 during earnings events.
   **Checkpoint:** Verify calculated stop price does not exceed maximum risk per trade.

4. **Layer Emergency Protection** — Overlay a hard emergency stop at the portfolio 
   level that triggers if total position loss exceeds N% regardless of individual 
   stop placement.
   **Checkpoint:** Emergency stop must be independent of individual position stops.

The checkpoint rule: Every workflow step MUST end with **Checkpoint:** followed by a specific verification condition — a concrete test the model can apply to confirm the step completed correctly before proceeding.

Pattern 5: Constraint Writing — Actionable, Not Abstract

Constraints translate abstract principles into testable rules. Each constraint must be something you could verify by reading the file without additional context.

# ❌ BAD: Abstract constraints (unverifiable)
### MUST DO
- Follow best practices
- Ensure quality code
- Make it maintainable

### MUST NOT DO  
- Write bad code
- Be inefficient
- Ignore edge cases

# ✅ GOOD: Specific, testable constraints
### MUST DO
- Parse all user inputs at the boundary with explicit type checking (Law 2)
- Return early on missing or invalid parameters before any domain logic executes (Law 1)  
- Never mutate input dictionaries; construct and return new objects instead (Law 3)
- Fail immediately with a descriptive error message containing the parameter name and expected format (Law 4)
- Include typed function signatures with docstrings for every public API function
- Reference `code-philosophy` laws in comments explaining constraint design decisions

### MUST NOT DO
- Use bare except clauses — always catch specific exception types
- Hard-code market parameters (ATR multipliers, risk percentages); make them configurable function arguments
- Skip input validation on external data sources (API responses, file reads, environment variables)
- Return None implicitly; either return a well-typed value or raise an explicit error
- Write docstrings that repeat the function signature instead of explaining purpose, edge cases, and examples

Constraints

MUST DO

• Validate all YAML frontmatter fields against the format spec before considering a skill complete
• Ensure name field is an exact case-sensitive match to the directory topic name (kebab-case)
• Build trigger sets using the Two-Tier Strategy: technical precision + conversational discovery phrases
• Write Core Workflow steps that describe concrete domain actions with Checkpoint: verification points
• Include at least 2 real code blocks with typed signatures, guard clauses, and working implementations
• Provide at least one BAD vs GOOD comparison pair relevant to the skill's domain
• Write constraints as testable rules (verifiable by inspection), never abstract principles like "follow best practices"
• Reference code-philosophy (5 Laws of Elegant Defense) in constraint design and code comment patterns
• Include a TL;DR Checklist with 5–7 specific checkbox items the model can verify before delivering output
• Keep descriptions under ~200 characters, starting with an active verb, including 1–2 domain-specific terms

MUST NOT DO

• Use the exact stub sentinel phrase (the one starting with "Implementing..." and referencing a "specific pattern or feature") anywhere in the file
• Write workflow steps with generic names like "Identify," "Apply," "Analyze," or "Validate" as standalone actions
• Include placeholder code: pass bodies, return {}, # TODO: add implementation, ...
• Set triggers to single ultra-generic words (code, data, risk, pattern, system)
• Write a description that reads as a topic label instead of stating what the model does (e.g., "Stop loss for trading")
• Use an H1 title equal to the kebab-case directory name (e.g., # risk-stop-loss)
• Set metadata.role/scope/output-format to default values without verifying they match actual skill behavior
• List more than 4 related skills (dilutes focus) or fewer than 2 when complementary skills exist
• Skip the "When NOT to Use" section for any skill with non-obvious applicability boundaries

Output Template

When applying this skill, produce outputs following this structure:

1. File Audit Summary — List of all frontmatter fields with pass/fail status, trigger set analysis (tier breakdown), and file size verification
2. Corrected Frontmatter — Complete YAML block ready for insertion, with any fixes applied and rationale for changes
3. Trigger Set Analysis — Before/after comparison showing old triggers, why they failed the calibration heuristic, and new triggers mapped to technical vs conversational tiers
4. Workflow Step Review — Each existing step evaluated against the domain-specificity rule, with rewritten steps where generic patterns were detected
5. Code Block Audit — Count of code blocks, classification of each as "real" or "placeholder", and rewritten versions for any stubs found
6. Constraint Rewrite — MUST DO / MUST NOT DO sections replaced with testable rules derived from the zero-tolerance policy
7. Validation Pass Report — Full results from all five stub detection checks with byte count, sentinel scan, generic workflow scan, code block validation, and trigger quality assessment

Related Skills

Appendix: Quick-Reference Trigger Quality Matrix

Use this matrix during trigger calibration to evaluate each candidate term:

Example calibration walk-through for a trading skill:

Candidate: "stop loss" → Green (core concept, natural language)
Candidate: "trailing stop" → Green (specific variant used in conversations)
Candidate: "ATR stop" → Green (technical term + abbreviation, practitioners say this)
Candidate: "position protection" → Green (conversational/business phrasing for the same need)
Candidate: "how do i limit losses" → Green (Tier 2 conversational variant)
Candidate: "emergency stop" → Green (specific operational scenario)
Candidate: "risk management" → Yellow (too broad — applies to position sizing, portfolio allocation too)
Candidate: "trading" → Red (ultra-generic single word)

Result: Keep 6 terms. Drop "risk management" and "trading". Final set: 6 triggers, balanced between
technical precision and conversational discovery.

Live References

Authoritative documentation links for this domain. The model follows markdown links at load time to resolve external references and inline content.

• OpenCode Documentation — Official OpenCode platform documentation on skill loading, routing, and configuration
• agent-skill-router Repository — Source repository for the skill router system with format specifications and examples
• MarkdownLint Configuration Guide — Markdown linting rules applicable to SKILL.md quality enforcement
• YAML Schema Validation (JSON Schema) — JSON Schema patterns for validating YAML frontmatter in skill files
• AST Parsing for Markdown Files — Remark.js documentation on programmatically parsing and validating Markdown structure