/agent-skills-creator

Skill Patterns

Four structural patterns. Pick one by what the skill has to do, then copy the shape of the named in-repo example rather than a generic skeleton: a real skill shows how the pattern actually holds up.

Contents

• Picking a pattern
• Simple/hub
• Workflow
• Rules-based
• Mixed
• Cross-cutting: failure decision tables

Picking a Pattern

Decision guide: auditing against a checklist is rules-based; guiding a process is workflow; dispatching by context is simple/hub. Unsure means workflow, the most flexible.

The problem a skill solves suggests its pattern. These are recommendations, not requirements: a runbook could be rules-based with categorized diagnostic checks.

Simple/Hub

Dispatch to focused files by track. SKILL.md is the tracks table plus whatever every track shares (boundary, output contract, gotchas); the substance lives in the track files, and a hub that starts teaching a track inline has stopped being a hub.

skills/<name>/
  SKILL.md
  <track-1>.md
  <track-2>.md

Root-level track files are exclusive to this pattern; every other pattern keeps supporting files in references/ or a rules folder.

Comprehensive-reference variant (canonical home for this guidance): for broad domains, the hub dispatches into a folder of small files, e.g. design-guidelines/ with 40 files (buttons.md, colors.md, forms.md), each 50-200 lines, mapped from an index.md. One concern per file, named after it; each stands alone with no cross-file reading order; files may run to roughly 450 lines when single-topic and TOC'd. Claude loads what the task needs instead of a 2000-line reference.

Workflow

A sequential process with references loaded per step. SKILL.md holds the steps and what every step needs; anything a single step needs goes in that step's reference.

skills/<name>/
  SKILL.md
  references/<detail>.md

Load-bearing parts, in the order they matter: a "Read when" table mapping each reference to its trigger condition, a copyable progress checklist, numbered steps, and a final step that produces evidence. agents-md is the reference implementation.

Rules-Based

An audit or lint against categorized rules. SKILL.md is the dispatch and the output contract; the rules folder is the content.

skills/<name>/
  SKILL.md
  rules/
    _sections.md          (categories: prefix, impact, why it matters)
    _template.md          (per-rule schema)
    <prefix>-<slug>.md    (one per rule)

SKILL.md carries a priority table (category, impact, prefix, rule count) so a truncated audit still surfaces the worst findings first, plus an output contract fixing the finding format. Rule counts in the description and the table must reconcile with the folder, which validate.sh checks. Folder mechanics are in rules-folder-structure.md.

Mixed

Workflow steps where one branch of references applies and the rest do not: platform-specific, framework-specific, or context-specific. The workflow determines context first, then loads only the matching reference. multi-tenant-architecture dispatches on Cloudflare versus Vercel this way.

Cross-Cutting: Failure Decision Tables

A compact symptom, cause, and recovery table helps with observed operational failures. Keep commands or error signatures that distinguish branches. Do not script rebuttals to a user who changes scope, declines an interview, or already authorized the next step.