ms

name

ms

description

Create or directly edit Codex skill packages: SKILL.md, triggers, agents/openai.yaml, scripts, references, assets, and optional decision instrumentation. Use for explicit skill creation or direct skill surgery now; classify the skill as decision/execution/evidence/orchestration/mixed, and scaffold SKDC-v1 only when stable decision rules need future `$seq`/`$tune` observability. Use `$refine` instead for usage-backed existing-skill refinement.

ms

Mission

Create lean, composable skill packages.

For skills whose value lies in changing choices, make future decision evidence observable without turning every run into receipt ceremony.

Hard constraints

• Make the smallest sufficient change.
• Do not add README/INSTALL/CHANGELOG files inside a skill package.
• Default frontmatter to name and description.
• name is hyphen-case, at most 64 characters, and matches the folder.
• description is the trigger surface and remains under 1024 characters.
• Keep SKILL.md under 500 lines as the smallest operative kernel; move deeper knowledge into discoverable references/ loaded only when a live decision needs it.
• Keep agents/openai.yaml aligned.
• Record the agents/openai.yaml disposition.

Progressive disclosure gate

Before completion, prove:

• metadata carries every activation cue, while SKILL.md carries every always-required authority, safety, routing, and stopping rule;
• each deeper resource is linked directly from SKILL.md beside the condition that makes it relevant, without duplicating core rules;
• a common-path probe uses only the kernel and common resources, a conditional-path probe uses only resources whose conditions hold, and a near-miss probe does not activate.

Skill type

Classify:

decision
execution
evidence
orchestration
mixed

Examples:

• pattern-selection doctrine -> decision
• code implementer -> execution
• session miner -> evidence
• lifecycle controller -> orchestration
• review governor -> mixed

The classification guides observability. It does not belong in frontmatter unless the local convention supports it.

Decision instrumentation gate

Create:

references/decision-contract.json

only when all are true:

• the skill contains stable triggers and decision rules;
• future tuning would benefit from clause-level evidence;
• selected/rejected/no-action routes can be named;
• the contract is likely to survive wording changes.

Do not create a decision contract for a simple file transformer, narrow executor, or evidence fetcher unless it also makes consequential route decisions.

SKDC-v1

A decision contract contains stable:

trigger IDs
route IDs
clause IDs
required/prohibited routes
success/failure signals
required artifacts

Author the artifact as JSON conforming to SKDC-v1 and validate it through $tune's canonical skill-decision-contract Ledger definition. Do not emit a YAML decision-contract template.

Optional SDR-v1

A decision-oriented skill may specify an optional:

skill_decision_receipt / SDR-v1

Use only when the skill makes a real route decision that later tuning cannot otherwise recover.

Do not emit receipts for ordinary prose, every checklist step, or simple tool execution.

Create workflow

1. Search for an existing skill covering the intent.
2. Collect 2–3 realistic trigger prompts.
3. Write:
   • one-line problem statement;
   • success criteria;
   • non-trigger boundary.
4. Classify the skill type.
5. Map progressive disclosure: activation metadata, always-required kernel, common resources, and the live condition for each conditional resource.
6. Decide whether SKDC-v1 is justified.
7. Scaffold:

   uv run --with pyyaml -- python3 \
     codex/skills/.system/skill-creator/scripts/init_skill.py \
     <skill-name> --path codex/skills
   

8. Author procedural SKILL.md.
9. Create decision contract only if the gate passes.
10. Generate or update agents/openai.yaml.
11. Remove redundant doctrine and examples.

Update workflow

Use for direct user-authorized surgery without a $tune diagnosis.

1. Read the current package.
2. Preserve unrelated behavior.
3. If a decision contract exists:
   • preserve stable IDs;
   • update only affected clauses;
   • avoid silent contract drift.
4. If the skill is becoming decision-oriented, evaluate the instrumentation gate.
5. Update metadata.

Future tuneability check

Before completion, ask:

Can future evidence tell whether this skill was present?
Can it tell whether a consequential decision changed?
Can it tell which rule was exercised?
Can it distinguish compliance from success?

It is acceptable for the answer to be “not applicable.”

Do not add instrumentation merely to make every answer “yes.”

Seq feedback for ms

When refining ms itself, prefer:

tune_seq_definition="$(realpath "${CODEX_HOME:-$HOME/.codex}/skills/tune/definitions/seq/skill-decision-audit.json")"
seq observe \
  --definition "$tune_seq_definition" \
  --projection evidence \
  --root <sessions-root> \
  --last 30d \
  --param needle=ms \
  --format json

Tune classifies that evidence and validates any STE-v1 packet through its canonical Ledger definition. A missing evidence shape belongs in a passive observation definition or a genuinely generic Seq operator, never a new skill-specific command.

Final report

Skill:
- Action:
- Type:
- Progressive disclosure: pass | blocked — <probe evidence>
- Decision instrumentation: added | updated | not justified
- agents/openai.yaml:
- Remaining uncertainty: