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

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

Scenes

• PREPARE: Collect skill purpose, trigger intents, boundaries, inputs, outputs, dependencies, and risk/resource constraints.
• ACQUIRE: Read analogous skills, existing resources, project conventions, and any user-provided source material.
• REASON: Decide what belongs inline in SKILL.md and what belongs in resources/, config/, scripts/, or assets/.
• ACT: Create or update the skill using the SSL-lite template.
• VERIFY: Run oma skills lint --skill {name}, then the remaining routing, execution, resource, utility-content, and formatting checks.
• 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

| Failure | Recovery |

|---------|----------|

| Skill scope overlaps heavily with another skill | Add a clear When NOT to use boundary and cross-route |

| Execution path is vague | Add canonical command or workflow path inline |

| SKILL.md becomes too long | Move detailed examples to resources/ and keep navigation in References |

| oma skills lint is unavailable (CLI not installed) | Fall back to structural grep/awk checks and manual checklist validation |

| User input is underspecified | Make conservative assumptions and list them, unless the target behavior would be unsafe |

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

| Action | SSL primitive | Evidence |

|--------|---------------|----------|

| Read analogous skills | READ | Existing .agents/skills/*/SKILL.md |

| Select skill type | SELECT | Command/workflow/judgment/reference-heavy classification |

| Infer boundaries | INFER | Trigger intents and adjacent skill overlap |

| Write skill file | WRITE | New or updated SKILL.md |

| Add resources | WRITE | resources/, config/, scripts/, or assets/ |

| Validate structure | VALIDATE | oma skills lint smell report; heading and canonical-path checks |

| Report result | NOTIFY | Changed files and validation summary |

Tools and instruments

• oma skills lint --skill <id> for automated smell detection (frontmatter, structure, canonical path, broken references, boundaries)
• rg, find, awk, sed, git diff --check
• The runtime's native file-edit tool for manual 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

• Read 1-3 analogous existing skills before writing.
• Classify the new skill as command-heavy, workflow-heavy, judgment-heavy, or reference-heavy.
• Draft SKILL.md from resources/ssl-lite-template.md.
• Add exactly one inline canonical path:
• ### Canonical command path for fragile or repeatable commands
• ### Canonical workflow path for decision, review, design, or research flow
• Move long examples, provider-specific details, or optional protocols into resources/.
• Validate with oma skills lint --skill <name> (frontmatter, headings, canonical path, broken references, boundaries), then git diff --check for whitespace. If the CLI is unavailable, fall back to the structural grep/awk checks in resources/validation-checklist.md.

Resource scope

| Scope | Resource target |

|-------|-----------------|

| CODEBASE | .agents/skills/*/SKILL.md, adjacent resources, project skill conventions |

| LOCAL_FS | New skill directories and resource files |

| PROCESS | Validation commands and optional generator/check scripts |

| MEMORY | User requirements, assumptions, and validation notes |

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

• Keep the four top-level sections exactly: Scheduling, Structural Flow, Logical Operations, References.
• 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).
• Include concrete When NOT to use boundaries and cross-routes to adjacent skills.
• 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.
• Include structural scenes using SSL scene vocabulary where practical: PREPARE, ACQUIRE, REASON, ACT, VERIFY, RECOVER, FINALIZE.
• Include logical actions with SSL primitives such as READ, SELECT, VALIDATE, INFER, WRITE, CALL_TOOL, NOTIFY, and TERMINATE.
• Include resource scope and resource targets for filesystem, codebase, process, credentials, network, user data, or memory.
• Include effects and side effects, especially for commands, network calls, credentials, destructive actions, generated files, and long-running processes.
• 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. Keep the SKILL.md body under 500 lines; oma skills lint warns as body-too-long past that.

10a. Write examples only when the output format is a contract someone parses — a CLI's result block, a schema, a LAW-validated document. Worked input/output pairs that merely show "what a good report looks like" narrow the model's exploration space to the example's shape, so state the requirement instead and let the model choose the form. Per-task shape belongs in the task, not the skill.

10b. Do not add instructions to double-check, re-verify, or self-review before answering — current models already do this, and the instruction compounds into over-verification. Deterministic validators the skill can actually run (oma verify, a lint script, a schema check) are the exception and should stay: they are feedback loops, not re-reading.

11. Do not create extra README, changelog, or installation docs inside a skill.

12. Do not overwrite unrelated user edits.

13. Enforce the three utility-predictive content dimensions — failure mechanism encoding, actionable specificity, high-risk action blacklist — per the Utility Content Checks in resources/validation-checklist.md (SkillLens, arXiv:2605.23899).

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.
• Skill optimization: once eval fixtures exist, oma skills opt --skill <id> proposes SKILL.md edits and keeps only those that improve measured held-out utility lift — use it after authoring instead of hand-tuning prose.