ywc-skill-author

name: ywc-skill-author description: >- (ywc) Use when creating a new ywc-* skill, restructuring an existing one's frontmatter/body sections/references/agents metadata, or auditing existing ywc-* skills against the canonical rule set. Triggers: "ywc skill 생성", "create ywc skill", "ywc skill 만들어줘", "ywc skill 개선", "new ywc skill", "ywc skill upgrade", "ywcスキル作成", "ywc skill audit", "ywc skill 룰 점검". Do not use for editing skill content during normal task execution, for non-ywc-* skills, or for renaming/moving skills (use git mv directly).

ywc-skill-author

Announce at start: "I'm using the ywc-skill-author skill to apply the canonical ywc-* skill rules."

This skill captures the conventions that every ywc-* skill must follow, derived from the synchronized Claude Code, Codex, and Pi skill bundles. Use it whenever authoring or restructuring a ywc-* skill so that new work matches the established quality bar without manual cross-referencing of sibling skills.

Rationalization Defense

When tempted to bypass a rule, check this table first:

Violating the letter of these rules is violating the spirit. Inconsistent ywc-* skills degrade the activation accuracy of every other ywc-* skill.

Mandatory Rules

These rules apply to every ywc-* skill without exception.

Frontmatter

Body

Filesystem

Rationalization Defense rows must cover the skill's concrete failure modes, including guessing missing context, adjacent cleanup, overbuilding abstractions, and declaring completion without goal-specific verification. Acceptable: "This migration task only mentions one table; I can also normalize neighboring tables" -> Adjacent schema cleanup changes review scope and belongs in a separate task unless the spec names it. Unacceptable: "Do not hallucinate" -> Be careful.

Progressive Disclosure (3-Tier Loading Model)

Every ywc-* skill is consumed by the agent in three tiers, each with different load semantics and different cost profiles. Skill design must respect what loads when:

The cost asymmetry is the entire reason for the model. Tier 1 cost is paid every turn, so descriptions must stay trigger-focused (anti-pattern: workflow summary). Tier 2 cost is paid once per activation, so workflow steps and rules belong here. Tier 3 cost is paid only when a deep dive is genuinely needed, so the per-language tool matrices, full classification rubrics, and templates go here.

Decision tree (inline vs. extract to Tier 3) — see references/progressive-disclosure.md for the full version with worked examples from ywc-refactor-clean, ywc-onboard-repo, and ywc-code-gen. Quick form:

Is the section >30 lines of static content (lookup table / decision tree / template)?
├─ YES → extract to references/<topic>.md with one-line pointer in SKILL.md body
└─ NO → keep inline
     │
     └─ Is the content workflow / step / rule prose?
        ├─ YES → MUST stay inline regardless of length (the agent needs it
        │        on activation to execute the skill correctly)
        └─ NO → keep inline if <30 lines, extract otherwise

The Workflow / Rationalization Defense / Validation Checklist sections are Tier 2 by definition — never extract them to Tier 3, even when they grow. The agent must read them on activation, not on demand.

Recommended Rules

These improve quality but are not strictly required.

Format Conventions

Anti-patterns (Never Do These)

Workflow (Adapted from superpowers:writing-skills)

Treat skill authoring as TDD applied to documentation: RED → GREEN → REFACTOR.

Step 1: RED — Baseline Behavior

Before writing or restructuring the skill, run a representative scenario without the skill present (or with the current version) and document:

• What did the agent do incorrectly?
• What rationalizations did the agent use verbatim?
• Which mandatory rule would have prevented the failure?

This step ensures the skill addresses real gaps, not hypothetical ones.

Step 2: GREEN — Minimal Skill

Draft the skill addressing exactly the failures identified in RED. Do not pre-emptively cover hypothetical cases.

Use references/skill-template.md as the starting structure.

For a new bundle skill in this repository, place it at codex/skills/<skill-name>/ unless the user explicitly asks for an installed local skill. For an installed local skill outside this bundle, ask for the destination and default to ${CODEX_HOME:-$HOME/.codex}/skills so Codex can discover it automatically.

Step 3: REFACTOR — Close Loopholes

Re-run the scenario with the new skill. Document any new rationalizations the agent invented to bypass the new rules. Add those to the Rationalization Defense table.

Repeat until the agent cannot find a loophole.

Resource and Metadata Pass

After drafting SKILL.md, add only the resources that directly support execution:

• agents/openai.yaml: write deterministic interface.display_name, interface.short_description, and interface.default_prompt from the final SKILL.md. Include optional fields such as icons or brand color only when explicitly provided.
• references/: move long static rules, lookup tables, rubrics, and templates here, then add an explicit pointer from SKILL.md.
• scripts/: add scripts only when repeated manual code would be fragile or deterministic reliability matters. Run each new script, or a representative sample for similar scripts, before completion.
• assets/: add files that the skill uses as output material, not documentation to load into context.

Delete placeholder files and do not create empty resource directories.

Forward-testing

Use subagents to forward-test substantial or tricky skill changes when available and when doing so will not require risky approvals or long-running work.

Prompt subagents as if they are solving a real task, for example:

Use $ywc-<skill-name> at <path/to/skill> to solve <realistic user request>.

Do not ask them to "review the skill" unless the user explicitly requested a review. Pass raw artifacts and the task-local request, not the intended answer, suspected bug, or planned fix. Review their outputs for generalization failures, then tighten SKILL.md or references and retest if needed.

Templates and References

Validation Checklist

Run the bundled mechanical gate first — it enforces the deterministic subset of the checklist below (name/description shape, announce line, 500-line cap, README locale set, no @ywc- force-loads, reference pointers + min-length) for a single skill and exits non-zero on any failure:

VALIDATE_SKILL_SCRIPT="${CODEX_HOME:-$HOME/.codex}/skills/ywc-skill-author/scripts/validate-skill.sh"
[ -f "$VALIDATE_SKILL_SCRIPT" ] || VALIDATE_SKILL_SCRIPT="codex/skills/ywc-skill-author/scripts/validate-skill.sh"
bash "$VALIDATE_SKILL_SCRIPT" <skill-dir>

Then verify the judgment-based items the script cannot check, before merging a new or modified ywc-* skill:

Frontmatter

• name starts with ywc-
• description starts with (ywc) Use when...
• description ends with Do not use for... anti-triggers
• description includes Korean / English / Japanese triggers (if user-facing)
• No frontmatter keys other than name and description

Body

• First content line is **Announce at start:** "..."
• ## Rationalization Defense has ≥5 domain-specific rows
• No @ cross-references
• No vague language without threshold
• Body ≤500 lines (wc -l SKILL.md)
• Empty sections use N/A — <reason> rather than being omitted

Filesystem

• Full README locale set: .md, .en.md, .ja.md, .ko.md
• agents/openai.yaml exists and matches the current SKILL.md purpose and invocation
• Long sections (>30 lines of static content) extracted to references/ (Tier 3 — A14)
• evals/evals.json exists if outputs are objectively verifiable
• No auxiliary docs such as per-skill CHANGELOG.md, INSTALLATION_GUIDE.md, or QUICK_REFERENCE.md
• New scripts were run, or a representative sample was run when many similar scripts were added

Progressive Disclosure (Tier compliance)

• Description (Tier 1) contains trigger conditions only — no workflow summary
• Workflow / Rationalization Defense / Validation Checklist / Common Mistakes are in SKILL.md body (Tier 2), not in references/
• Every references/*.md file has at least one explicit pointer from the SKILL.md body
• No references/*.md file is <30 lines (over-extraction)

Catalog Sync

• Relevant bundle catalog or root distribution docs updated when the repository has one for the affected bundle
• Relevant routing guide updated if the bundle has one and the skill is user-facing
• If skill is part of a pipeline, the 표준 개발 Pipeline diagram updated

Cross-Skill Etiquette

• If skill A's purpose overlaps with skill B's responsibility, document the relationship in ## Integration and add (use ywc-B) to A's Do not use for... line.
• For shared conventions across multiple skills (e.g., Advisor Pattern), extract to the bundle-level references/<topic>.md rather than duplicating.
• New skill that supersedes an existing one: do not silently delete the old skill in the same PR. Add a deprecation note pointing to the successor, then delete in a later PR after a soak period.

Common Mistakes

• Skipping the RED step because "the gap is obvious" — gaps that look obvious to the author are often not the gap the agent actually has. Always observe baseline behavior.
• Copying a sibling's Rationalization Defense table verbatim — tables must be domain-specific to be effective. Adapt every excuse to the new skill's actual failure modes.
• Adding everything inline because "references is overhead" — this scales poorly. The 500-line cap exists because skills are loaded into context whenever activated.
• Forgetting to update skills/README.md catalog — invisible skills do not get discovered.