Skip to content

agent-skills-creation-reference.md

Latest commit

 

History

History
80 lines (48 loc) · 3.3 KB

agent-skills-creation-reference.md

File metadata and controls

80 lines (48 loc) · 3.3 KB
Raw

Agent Skills Creation Reference

This document defines the design standard for Agent Skills within the OMF repository.

Part 1: Agent Skills Fundamentals

The Core Model

A skill is a self-contained unit of domain-specific procedure.

  • Structure: folder $\rightarrow$ SKILL.md (instructions) + optional references/ (knowledge), scripts/ (logic), and assets/ (templates).
  • Loading: Progressive disclosure. Discovery (name/description) $\rightarrow$ Activation (SKILL.md) $\rightarrow$ On-demand (resources).

Description & Activation

Optimize for user intent, not keywords.

  • Goal-Oriented: Describe what the user is trying to accomplish and the expected outcome.
  • Concise: Keep activation text specific but brief.
  • Example: Prefer "Use when a user wants to document a computational model" over "Triggers: document model, generate ODD."

Output Contracts

Every skill must define a predictable contract:

  • Inputs/Outputs: Clear requirements and expected deliverables.
  • Success/Failure: Explicit criteria for a "complete" task and conditions that trigger failure.
  • Structure: Use structured outputs (JSON/YAML) when the result is consumed by downstream skills.

Evaluation

Quality is verified through comparative testing:

  • A/B Testing: Run identical realistic prompts with and without the skill.
  • Metrics: Compare correctness, efficiency (steps taken), and failure modes.
  • Concrete Triggers: Test with realistic user phrasing, including "near-miss" cases that should NOT trigger the skill.

Part 2: OMF Design Philosophy

The Golden Rule: Add Only What the Agent Lacks

Do not waste context on generic knowledge.

  • Encode: Expert workflows, community standards, non-obvious pitfalls, and methodological tradeoffs.
  • Exclude: General software engineering or common modeling advice that foundation models already handle reliably.
  • Mantra: If the agent would succeed without it, remove it.

Externalize Consequential Reasoning

Transparency is a requirement, not an option. Skills must prevent "silent" scientific decisions.

  • Provenance: Surface all consequential analytical choices (method selection, assumptions, priors).
  • Justification: Require the agent to explain why a specific path was taken based on encoded standards.
  • Intermediate Artifacts: Emit staging artifacts (e.g., inferred assumptions list) for user review before finalization.

Composability & Scope Discipline

Prefer many small, specialized skills over few comprehensive ones.

  • One Responsibility: Each skill owns a single methodological step.
  • Predictability: Minimal hidden state; clear input $\rightarrow$ clear output.
  • Routing over Expansion: Favor routing over expanding a skill's scope. If a concern belongs to another skill, route the user to it instead of duplicating guidance.

Architectural Rule: Favor Routing

Do not build "God-skills." When a workflow spans multiple domains:

  1. Identify the specialist skill for the sub-task.
  2. Instruct the current skill to delegate or route to that specialist.
  3. Maintain a clean boundary between orchestration and execution.

Design Mantra

Encode how experienced practitioners make, justify, document, and communicate consequential decisions while minimizing context cost.