skills.rest
mpsuesser
mpsuesserCOMMUNITY
Explore all skills by this author →
GitHub

skill-design

Structure opencode agent skills with SKILL.md routing and progressive reference loading.

Updated Mar 12, 2026
Search Tags:#token efficiency#progressive loading#skill architecture#decision trees#agent prompting#reference organization
One-click install
npx skills add https://github.com/mpsuesser/workspace --skill skill-design-mpsuesser
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: skill-design
Source: https://github.com/mpsuesser/workspace/tree/main/dotconfig/opencode/skills/skill-design
Command: npx skills add https://github.com/mpsuesser/workspace --skill skill-design-mpsuesser

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you structure opencode skills so agents can reliably trigger them and load the right level of detail without wasting context window tokens.

Core Features & Use Cases

  • Skill architecture guidance: Choose between minimal, standard, and comprehensive skill tiers based on domain complexity.
  • Progressive loading strategy: Put routing logic in SKILL.md and load reference files only when needed to reduce token cost.
  • Decision-tree task routing: Encode “judgment” so the agent makes good choices between alternatives, not just follows instructions.
  • Reference organization patterns: Use a consistent reference-file layout (e.g., README/api/configuration/patterns/gotchas) to support partial loads and maintainability.
  • Debugging gotchas: Diagnose why skills fail to trigger, load wrong files, or exceed size limits, then fix routing and descriptions.

Quick Start

Use the skill-design skill when creating or refactoring an opencode skill so its SKILL.md description triggers correctly and its routing loads the right reference files on demand.

Frequently Asked Questions about skill-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure agent skills for progressive loading and token efficiency?▼

Agent skills achieve progressive loading by placing routing logic in SKILL.md and loading reference files on demand. This reduces token cost by ensuring agents load only relevant context when triggered.

What is the best way to organize reference files for on-demand agent loading?▼

Organize reference files using a consistent layout like README, api, configuration, patterns, and gotchas directories. This structure supports partial loads and maintainability while controlling file sizes.

Why does my agent skill fail to trigger or load the wrong reference files?▼

Skills fail to trigger when frontmatter descriptions lack proper trigger conditions or SKILL.md routing logic is misconfigured. Debug by diagnosing routing decision trees and ensuring reference file purposes are clearly defined.

When should I choose minimal versus comprehensive skill architecture for my domain?▼

Choose skill architecture tiers based on domain complexity: minimal for single-domain tasks, standard for moderate complexity, and comprehensive for platform-scale coverage requiring extensive decision trees and reference organization.

How do decision trees in SKILL.md improve agent task routing?▼

Decision trees in SKILL.md encode judgment logic so agents make good choices between alternatives rather than blindly following instructions. This ensures reliable triggering and appropriate context loading for complex tasks.

Can I refactor existing opencode skills to support progressive loading?▼

Yes, existing skills can be refactored by restructuring SKILL.md routing, reorganizing reference files into consistent directories, and adding trigger conditions to frontmatter descriptions to enable on-demand loading.

Related Skills

Explore More Software Engineering Skills→
benjaminshafiibenjaminshafii
10

self-improve

Update OpenCode skill documentation and extend capabilities based on learnings.

Community
Basic
pproencapproenca
193

skill-authoring

Guide AI agent skill design with metadata, structure, and trigger best practices.

Community
Advanced
anilcan-karaanilcan-kara

nozich-agent-skill-authoring

Standardize and verify SKILL.md frontmatter for Nozich Skill units.

Community
Intermediate
jezwebjezweb
961

skill-creator

Design Claude Code skills with progressive disclosure and YAML frontmatter constraints.

Community
Basic