# Skill Engineering > 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. - Skill: `paulpas/skill-engineering` (Agent Skill) - Install (CLI): `npx skillmds@latest add paulpas/skill-engineering` - Raw SKILL.md: https://api.skillmd.com/api/skills/paulpas/skill-engineering/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: paulpas (https://skillmd.com/u/paulpas) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/paulpas/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. ```yaml # ❌ 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:** ```yaml # 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. ```yaml # ❌ 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: ```python 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 | Skill | Purpose | |---|---| | `coding-code-review` | Review the generated skill for code quality within implementation patterns | | `agent-task-routing` | Understand how engineered skills integrate into the routing pipeline | | `coding-security-review` | Audit security-relevant aspects of trigger engineering (e.g., injection in user-provided triggers) | --- ## Appendix: Quick-Reference Trigger Quality Matrix Use this matrix during trigger calibration to evaluate each candidate term: | Score | Criteria | Action | |-------|----------|--------| | **Green** | Specific domain term, used naturally in conversation, matches a real user query pattern | ✅ Keep | | **Yellow** | Relevant but slightly broad (e.g., `monitoring` vs `Prometheus metrics scraping`) | ⚠️ Consider replacing with more specific variant | | **Red** | Ultra-generic single word (`code`, `data`, `risk`, `pattern`, `system`) | ❌ Replace immediately with domain-specific phrase | | **Red** | Internal jargon, class name, or file path that users never say naturally | ❌ Replace with externally documented terminology | **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](https://opencode.ai/docs) — Official OpenCode platform documentation on skill loading, routing, and configuration - [agent-skill-router Repository](https://github.com/anthropics/agent-skill-router) — Source repository for the skill router system with format specifications and examples - [MarkdownLint Configuration Guide](https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md) — Markdown linting rules applicable to SKILL.md quality enforcement - [YAML Schema Validation (JSON Schema)](https://json-schema.org/learn/getting-started-step-by-step) — JSON Schema patterns for validating YAML frontmatter in skill files - [AST Parsing for Markdown Files](https://remark.js.org/) — Remark.js documentation on programmatically parsing and validating Markdown structure