Oma Skill Creator

Skill Creator - SSL-lite Skill Authoring Specialist

Scheduling

Goal

Create, revise, and validate OMA skills using the SSL-lite Markdown structure derived from Scheduling-Structural-Logical skill representation while keeping the result readable, executable, and maintainable.

Intent signature

• User asks to create a new OMA skill, agent skill, specialist skill, or .agents/skills/*/SKILL.md.
• User asks to convert or normalize a skill into the project skill format.
• User asks whether a skill has enough scheduling, structural, logical, reference, or canonical execution detail.
• User mentions SSL-lite, Scheduling / Structural / Logical, skill format, skill template, or skill creator.

When to use

• Creating a new skill under .agents/skills/{name}/SKILL.md
• Updating an existing OMA skill to the SSL-lite format
• Adding Canonical command path or Canonical workflow path to an execution-heavy skill
• Auditing whether a skill is usable by routing, execution, validation, and recovery logic
• Deciding whether detailed examples belong inline or in resources/

When NOT to use

• Installing third-party skills into $CODEX_HOME/skills -> use Codex's built-in skill installer (external; not an OMA skill)
• Creating a Codex plugin bundle -> use Codex's plugin tooling (external; not an OMA skill)
• Writing a general project plan unrelated to skill authoring -> use PM Agent
• Editing product code, infrastructure, frontend, backend, or mobile implementation directly -> use the matching specialist skill

Expected inputs

• skill_name: target directory name, preferably oma-{domain}
• skill_goal: capability the skill should add
• trigger_intents: user prompts or domains that should activate the skill
• boundaries: when the skill should not be used and which skill should handle those cases
• execution_model: whether the skill is command-heavy, workflow-heavy, judgment-heavy, or reference-heavy
• Existing files, tools, commands, resources, or standards the skill must preserve

Expected outputs

• A complete SKILL.md using the SSL-lite top-level sections
• Optional resources/*.md, config/*.yaml, scripts/*, or assets/* only when progressive disclosure or deterministic execution requires them
• A validation report with structure checks, routing checks, execution checks, and unresolved assumptions

Dependencies

• Existing OMA skill conventions in .agents/skills/*/SKILL.md
• SSL-lite template in resources/ssl-lite-template.md
• Validation checklist in resources/validation-checklist.md
• Local filesystem and search tools for reading adjacent skills and checking output

Control-flow features

• Branches by new skill vs existing skill update
• Branches by command-heavy vs workflow-heavy vs reference-heavy skill type
• Reads and writes local skill files
• Must preserve user edits and avoid unrelated rewrites

Structural Flow

Entry

1. Identify whether the task is creating a new skill, updating an existing skill, or auditing a skill. 2. Read nearby or analogous OMA skills before choosing wording and structure. 3. Determine the skill type: command-heavy, workflow-heavy, judgment-heavy, or reference-heavy.

Scenes

1. PREPARE: Collect skill purpose, trigger intents, boundaries, inputs, outputs, dependencies, and risk/resource constraints. 2. ACQUIRE: Read analogous skills, existing resources, project conventions, and any user-provided source material. 3. REASON: Decide what belongs inline in SKILL.md and what belongs in resources/, config/, scripts/, or assets/. 4. ACT: Create or update the skill using the SSL-lite template. 5. VERIFY: Run structural, routing, execution, resource, and formatting checks. 6. FINALIZE: Report created/changed files, validation result, and any remaining assumptions.

Transitions

• If the skill performs fragile or repeated commands, include ### Canonical command path inline.
• If the skill is mostly human judgment or investigation, include ### Canonical workflow path inline.
• If detailed examples are long, variant-specific, or optional, move them to resources/ and reference them explicitly.
• If a skill already exists, preserve working content and normalize only what is needed for the target format.
• If the trigger description is too broad, narrow it before writing the skill.

Failure and recovery

Exit

• Success: the skill has the four SSL-lite top-level sections, a canonical path, clear routing boundaries, resource constraints, and validation evidence.
• Partial success: the structure is valid but missing commands, tools, source material, or user decisions are reported.
• Failure: no skill file is written or the blocking ambiguity is explicit.

Logical Operations

Actions

Tools and instruments

• rg, find, awk, sed, git diff --check
• apply_patch for manual file edits
• Existing OMA skills as examples
• resources/ssl-lite-template.md for the canonical section skeleton
• resources/validation-checklist.md for acceptance criteria

Canonical workflow path

1. Read 1-3 analogous existing skills before writing. 2. Classify the new skill as command-heavy, workflow-heavy, judgment-heavy, or reference-heavy. 3. Draft SKILL.md from resources/ssl-lite-template.md. 4. Add exactly one inline canonical path:

• ### Canonical command path for fragile or repeatable commands
• ### Canonical workflow path for decision, review, design, or research flow

5. Move long examples, provider-specific details, or optional protocols into resources/. 6. Validate top-level headings, canonical path presence, frontmatter, and whitespace.

Resource scope

Preconditions

• The target skill name and purpose are known or can be inferred safely.
• Adjacent skill overlap has been checked.
• The user has authorized changes under .agents/skills/ when project rules would otherwise protect .agents/.

Effects and side effects

• Creates or modifies files under .agents/skills/.
• May add resource files to support progressive disclosure.
• Does not stage or commit changes unless explicitly requested.

Guardrails

1. Keep the four top-level sections exactly: Scheduling, Structural Flow, Logical Operations, References. 2. Keep YAML frontmatter with clear name and description; routing depends on description quality. Run oma skills audit after editing description to confirm the new wording does not collide with adjacent skills (warn ≥ 60%, fail ≥ 75% TF-IDF cosine). 3. Include concrete When NOT to use boundaries and cross-routes to adjacent skills. 4. Include expected inputs, expected outputs, dependencies, and control-flow features. Prefer the structured outputs: block when artifacts can be globbed so oma verify can perform a closure check. 5. Include structural scenes using SSL scene vocabulary where practical: PREPARE, ACQUIRE, REASON, ACT, VERIFY, RECOVER, FINALIZE. 6. Include logical actions with SSL primitives such as READ, SELECT, VALIDATE, INFER, WRITE, CALL_TOOL, NOTIFY, and TERMINATE. 7. Include resource scope and resource targets for filesystem, codebase, process, credentials, network, user data, or memory. 8. Include effects and side effects, especially for commands, network calls, credentials, destructive actions, generated files, and long-running processes. 9. Add one canonical path inline so an agent can execute or reason without loading every resource file. 10. Put long variant-specific details in resources/, not in the main skill body. 11. Do not create extra README, changelog, or installation docs inside a skill. 12. Do not overwrite unrelated user edits.

References

• SSL-lite template: resources/ssl-lite-template.md
• Validation checklist: resources/validation-checklist.md
• Shared context loading: ../_shared/core/context-loading.md
• Shared quality principles: ../_shared/core/quality-principles.md
• Skill utility eval: when creating a new skill, consider adding held-out task fixtures under .agents/eval/<skill>/ so oma skills eval can measure whether the skill improves task outcomes. See web/docs/guide/skill-eval.md for the fixture schema and checker types.

SSL-lite Skill Template

Use this template for OMA skills. Replace placeholders; do not keep placeholder text in the final skill.

````markdown --- name: oma-{skill-name} description: > {One concise routing description. Include the task/domain and the phrases that should trigger this skill.} ---

{Skill Title}

Scheduling

Goal

{What capability this skill adds and the outcome it should produce.}

Intent signature

• {Prompt pattern, domain term, or situation that should activate this skill}
• {Another trigger}

When to use

• {Positive use case}
• {Positive use case}

When NOT to use

• {Boundary case} -> use {other skill/tool}
• {Boundary case} -> out of scope

Expected inputs

• {input_name}: {meaning}
• {input_name}: {meaning}

Expected outputs

Use freeform bullets when the skill has no machine-checkable artifacts:

• {Primary output}
• {Validation/reporting output}

Or declare a structured outputs: block when artifacts can be globbed. oma verify reads this block via parseExpectedOutputs and fails the closure check when any required: true artifact is missing after the agent reports completion.

outputs:
  - name: plan
    description: PM task breakdown
    artifact: ".agents/results/plan-*.json"
    required: true
  - name: tests
    description: regression tests
    artifact: "**/test_*.py"
    required: false

Field rules:

• name: short identifier, lowercase
• description: human-readable purpose
• artifact: glob relative to workspace root (supports **)
• required: defaults to false; only true blocks closure

Dependencies

• {Tools, files, standards, APIs, local resources}

Control-flow features

• {Branching, loops, tool calls, user clarification points, write behavior}

Structural Flow

Entry

1. {First thing the agent must establish} 2. {Second thing}

Scenes

1. PREPARE: {Setup, scope, assumptions} 2. ACQUIRE: {Read files, fetch docs, inspect inputs} 3. REASON: {Decide strategy} 4. ACT: {Make changes, run commands, produce artifact} 5. VERIFY: {Check result} 6. FINALIZE: {Report outcome}

Transitions

• If {condition}, {next action}.
• If {condition}, {next action}.

Failure and recovery

Exit

• Success: {observable success condition}
• Partial success: {what must be reported}
• Failure: {what must be reported}

Logical Operations

Actions

Tools and instruments

• {Tool, API, script, local command, reference file}

Canonical command path

{primary command}
{verification command}

Use ### Canonical workflow path instead when the skill is decision-heavy rather than command-heavy:

1. {Step} 2. {Step} 3. {Step}

Resource scope

Preconditions

• {Required condition before acting}

Effects and side effects

• {Files written, commands run, network calls, credentials touched, state changed}

Guardrails

1. {Safety or quality rule} 2. {Safety or quality rule}

References

• {Resource label}: resources/{file}.md
• {Shared reference}: ../_shared/core/{file}.md

````

Mapping To SSL

Inline vs Resource Rule

Keep inline:

• Routing description and boundaries
• Expected inputs and outputs
• Structural flow and recovery
• Logical actions, resource scope, preconditions, side effects, guardrails
• One canonical command or workflow path

Move to resources/:

• Long examples
• Provider-specific variants
• Detailed protocols
• Large checklists
• Reference material the agent should load only when needed

SSL-lite Skill Validation Checklist

Use this checklist after creating or updating a skill.

Required Structure

• YAML frontmatter exists.
• Frontmatter includes name.
• Frontmatter includes a routing-grade description.
• The only top-level ## headings outside code fences are exactly:
• ## Scheduling
• ## Structural Flow
• ## Logical Operations
• ## References
• The skill contains exactly one of:
• ### Canonical command path
• ### Canonical workflow path

Scheduling Checks

• Goal states the capability and outcome.
• Intent signature contains concrete user prompt patterns or domain triggers.
• When to use gives positive routing cases.
• When NOT to use names boundaries and cross-routes to adjacent skills.
• Expected inputs and Expected outputs are explicit. If the skill produces machine-checkable artifacts, prefer the structured outputs: YAML block over freeform bullets so oma verify can run a closure check.
• Dependencies names tools, files, standards, APIs, or resources.
• Control-flow features describes branching, tool calls, writes, and clarification points.

Cross-Skill Boundary Check

• Run oma skills audit (or oma doctor) after editing frontmatter description.
• Resolve any FAIL (≥ 75% similarity) pair by rewriting one description to highlight distinct triggers, domains, or boundaries.
• WARN (≥ 60%) pairs are acceptable when descriptions cover genuinely related domains; document the distinction in When NOT to use cross-routes.

Structural Checks

• Entry states what to verify before acting.
• Scenes use SSL-style scene vocabulary where practical.
• Transitions describe condition-to-action routing.
• Failure and recovery covers common failures.
• Exit defines success, partial success, and failure.

Logical Checks

• Actions map operations to SSL primitives.
• Tools and instruments names concrete tools, scripts, commands, APIs, or references.
• The canonical path is executable or operational enough for an agent to follow without extra context.
• Resource scope names affected resources such as CODEBASE, LOCAL_FS, PROCESS, CREDENTIALS, NETWORK, USER_DATA, or MEMORY.
• Preconditions are clear.
• Effects and side effects name writes, commands, network calls, generated artifacts, or state changes.
• Guardrails protect against unsafe, broad, or low-quality execution.

Reference Checks

• References points only to files that exist or are intentionally planned.
• Long examples and provider-specific variants are in resources/, not duplicated inline.
• Reference files are one hop from SKILL.md; avoid deep reference chains.

Suggested Commands

Check top-level headings and canonical path:

f=".agents/skills/{skill-name}/SKILL.md"
awk 'BEGIN{c=0} /^```/{c=!c; next} !c && /^## /{print $0}' "$f"
rg -n '^### Canonical (command|workflow) path$' "$f"

Check formatting whitespace:

git diff --check -- ".agents/skills/{skill-name}"