Agent Skill Design

Use this skill to design agent skills as progressive behavioral interfaces. The goal is to turn repeated judgment, workflow, taste, or tool use into a skill that loads at the right time and changes agent behavior at the moment it matters.

Core thesis:

A skill is a progressive behavioral interface for agents: metadata controls invocation, the body carries judgment, references manage context depth, scripts provide deterministic substrate, and outputs preserve continuation context.

Design Axioms

• Invocation contract: name and description decide whether the skill is read at all. Put trigger conditions in metadata where they can influence loading.

• Behavioral kernel: the body should teach the agent what to judge, what to preserve, what to tighten, and how to act differently. Topic explanation usually belongs in reference material.

• Boundary design: add fixed contracts where reliability matters. Preserve flexible judgment where the work is interpretive, immature, or taste-dependent.

• Context economy: SKILL.md should contain what every invocation needs. references/ should hold optional depth. scripts/ should handle deterministic or fragile work. assets/ should contain output materials.

• Continuation surface: agent-facing scripts and CLIs should report the result and preserve enough state, ambiguity, paths, and next actions for the next agent step.