skill-forge

name	skill-forge
description	Meta-skill and design compass for creating new skills and upgrading existing ones with a deliberate push toward being maximally technological, creative, and aesthetically disciplined. Use when the user wants to create a skill from scratch, reshape an existing skill, make a skill more reliable/technological, more creative/varied, or more visually polished — or when a skill feels templated, generic, or mechanically weak. Trigger on phrases like "создай скил", "новый скил", "улучши скил", "сделай скил креативнее", "эстетичный скил", "технологичный скил", "скилл выглядит шаблонно", "перепиши SKILL.md", even if the user does not say the word "skill" explicitly. Also use when reviewing a skill before release.
license	MIT
metadata	{"version":"1.0.0"}
when_to_use	Use to create or upgrade skills: 'create a skill', 'new skill', 'improve skill', 'make skill creative', 'rewrite SKILL.md', 'создай скил', 'новый скил', 'улучши скил', 'перепиши SKILL.md'. Example: 'Make a skill for PDF reports' / 'Создай скилл для презентаций'.

skill-forge

A compass, not a dictator. This skill helps you design skills that are maximally technological (engineered, reliable, composable), creative (generative, varied, distinctive), and aesthetically disciplined (intentional, not templated). It separates the obligatory base — rules you must not break — from accents — amplifiers you choose per task.

Russian triggers: создай скил, новый скил, улучши скил, сделай скил креативнее, эстетичный скил, технологичный скил, скилл шаблонный, перепиши SKILL.md, мета-скилл, проверь скилл перед релизом.

Level 0 — Hard rules (the base, never break these)

These come from the official Agent Skills specification (agentskills.io) plus our own working gates. They are non-negotiable.

• Frontmatter: name (≤64 chars, a-z 0-9 -, no double hyphens, MUST match the folder name) and description (≤1024 chars, MUST state what the skill does AND when to use it). Put all "when to use" info in description, never in the body. Make triggers a little "pushy" to fight undertriggering — list synonyms and casual phrasings.
• Progressive disclosure: keep SKILL.md under 500 lines. Bundle code in scripts/ (deterministic, repetitive tasks), docs in references/ (loaded as needed; add a TOC if >300 lines), outputs in assets/. Reference files one level deep only.
• Voice: write in the imperative. Explain the why instead of heaped MUST/ ALWAYS/NEVER — all-caps rigidity is a yellow flag. The model is smart; reason with it.
• Principle of Lack of Surprise: no malware, no deceptive or malicious content. A skill's intent must match its description.
• Single data contract: one spec file (e.g. deck.json) is the source of truth; every stage reads/writes it so artifacts are regenerable.
• Mandatory gates: nothing is "done" until automated checks PASS. At minimum: structural/format validation, content QA, and — for any visual output — a real-browser or render gate. Require EVIDENCE, not assertion: the skill must show the command it ran, its output, and the exit status. Use SCOPED CLAIMS — separate failures the change caused from pre-existing ones ("3 pre-existing failures, my change introduced none"). For unattended runs, back the gate with a deterministic Stop hook or a /goal evaluator so a turn cannot end on a false "done".
• Reproducibility: deterministic seed so the same input yields the same output on another day.
• Anti-template baseline (our enforcement, mechanical): ≤2 typefaces, ≤4 accent roles (keep 60-30-10), WCAG contrast (text ≥4.5:1, large/non-text ≥3:1), zero raw hex outside :root (every color is a token), one mood per artifact, one idea per slide, assertion headlines (full sentence with a verb), words-per-slide budget.

Level 1 — Accent: Technological

Pick this when the skill must be engineered. It is an amplifier, not required.

• Modular base + pluggable patterns — never a monolithic template. Each artifact assembles from base + only the patterns it uses, so no two outputs share a prebuilt shell.
• Composable pipeline: small single-purpose scripts, one command per stage, everything inspectable and debuggable.
• Real verification: for any UI/visual output, a Playwright/Chromium gate is mandatory (geometry, overflow, clipping, keyboard nav).
• Fixed contract constants (lesson from the official pptx skill): pin the canvas (e.g. 1600×900), the safe font (e.g. Arial — LibreOffice substitutes matter), and exempt decorative elements from bounds checks by naming convention (ghost*, decor*, chrome-*).
• Binary-format safety: when generating OOXML/PDF, follow the hard rules — no #/8-digit hex (corrupts files), parse with defusedxml (round-tripping through ElementTree rewrites namespaces and corrupts), run the validator after generating and fix in the generator, never hand-edit packed XML.

Level 2 — Accent: Creative

Pick this when the skill must vary and surprise (in a good way).

• Generative composition from a seed: synthesize layout/parameters deterministically from a deck seed (title + date + index) so rebuilding on another day yields a different but reproducible mix.
• Variety across artifacts: different outputs should carry different visual "handwriting" — not one shared base. Multiple base styles, each deck picks its own.
• Signature element: one memorable, brief-true motif per artifact (NOT a color bar or accent stripe — those read as AI filler).
• Avoid the three AI-default looks: (1) cream #F4F1EA + high-contrast serif
  • terracotta; (2) near-black + single acid-green/vermilion accent; (3) broadsheet hairline rules, zero radius, newspaper columns. Where the brief leaves an axis free, don't spend that freedom on a default.

Level 3 — Accent: Aesthetic

Pick this when the skill must look intentional.

• Mood system: swiss | editorial | flat | glass | dark drives the regime; one mood per artifact, one radius/stroke language.
• Token system (4 parts): palette as 4–6 named hex; type as 2+ roles (characterful display used with restraint + complementary body + utility face); layout as one-sentence prose + ASCII wireframes; signature as the single unique element.
• Assertion headlines: full sentences with a verb — a conclusion, not a topic.
• Typography floor: body text readable at projection scale (≥17px cards, labels ≥17px, metric values 30–48px); re-check overflow after any font change.
• Restraint: spend your boldness in one place — let the signature be the one memorable thing, keep everything else quiet. Chanel's rule: before shipping, remove one accessory. Match complexity to the vision; elegance is executing the chosen vision well.
• Structural honesty: numbering/eyebrows/dividers should encode something true about the content, not decorate it (numbered markers only if it's actually a sequence).

Process — the build loop

Adapted from the official skill-creator flow, with an accent pass added:

1. Capture intent — what should the skill enable? when should it trigger? what's the output format? do we need test cases (objective outputs do; subjective ones often don't)?
2. Draft SKILL.md — follow Level 0; choose accents from Levels 1–3 that fit the task.
3. Test prompts — 2–3 realistic user phrasings; save to evals/evals.json.
4. Parallel runs — with-skill vs baseline subagents in the same turn; capture total_tokens / duration_ms to timing.json (only chance to get them).
5. Grade — objective assertions with text / passed / evidence, no partial credit; superficial pass = fail. Subjective quality → human judgment.
6. Accent pass (added) — on each iteration ask: did we keep it technological, creative, and aesthetically disciplined? Did it slip into a default look or a monolith?
7. Improve — generalize from feedback; keep the prompt lean; explain the why; if all test runs wrote the same helper, bundle it into scripts/.
8. Optimize description — generate ~20 trigger queries (mix should/should-not, include near-misses and casual typos), split 60/40 train/test, iterate up to 5× to get best_description by test score.
9. Package — package_skill → .skill file; preserve the original name.

Release checklist

• Level 0 hard rules all satisfied (frontmatter, <500 lines, gates green)?
• Chosen accents actually amplified, not just "it works"?
• Escaped the three AI-default looks (Level 2)?
• Token system coherent: one mood, ≤2 typefaces, ≤4 accent roles, zero raw hex?
• Signature element present and brief-true (not a stripe/bar)?
• Description triggers reliably, including casual/near-miss phrasings?

A skill that passes Level 0 and at least one accent is shippable. A skill that passes all three accents is exceptional.