# Polish Skill > Polish Skill - Skill: `canonical/polish-skill` (Agent Skill) - Install (CLI): `npx skillmds@latest add canonical/polish-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/canonical/polish-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: canonical (https://skillmd.com/u/canonical) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/canonical/polish-skill --- # Polish Skill Your job is to take an existing skill (a `SKILL.md` file, optionally with companion files in `scripts/`, `references/`, `assets/`) and produce a polished version that is easier for a model to absorb, harder to mis-trigger, and structured for progressive disclosure when oversized — without altering any technical claim. The polish is **conservative on content** (preserve every rule, NEVER, workaround, and worked example verbatim wherever possible) and **opinionated on structure** (fix numbering, headings, indentation, forward references, and oversize). The goal is that a model loading the polished skill mid-task finds the right rule faster and applies it more reliably than it would with the original. ## When NOT to use this skill Do not use this skill to: - Author a *new* skill from scratch — that is a different workflow (description-driven design, eval loop, iteration). Use a skill-creator workflow instead. - Rewrite a skill's technical content. If a rule looks wrong or outdated, flag it and ask before changing it. Hard-won verification, transpiler, or domain knowledge in the original should be preserved even when it looks odd; the user almost certainly earned it through painful debugging. - Translate a skill between languages or harnesses. That is a port, not a polish. ## Workflow Follow these steps in order. Do not skip the audit step — most of the value of this skill is in catching specific failure modes that are hard to see when you're already writing the output. ### Step 1 — Read the entire file Use the `view` tool to read every line of the uploaded `SKILL.md`. If the file is large, view it in passes — but make sure you have seen every line before doing anything else. Skimming and pattern-matching to "looks like a standard skill" misses the specific issues that matter. If companion files exist in `references/`, `scripts/`, or `assets/`, list them but do not modify them unless the user explicitly asks. The polish targets `SKILL.md`. ### Step 2 — Audit against the failure-mode checklist Walk this list out loud (literally — write the findings to the user) before producing any output. Each item is a real failure mode that hurts skill reliability in practice: #### Frontmatter audit 1. Is `name` lowercase-with-hyphens, no spaces? Does it match the folder name? 2. Does `description` start by saying *what the skill does* (verb phrase), then *when to use it* (trigger conditions)? 3. Does the description undertrigger? A skill that only says "annotates Python code with contracts" will be skipped when a user asks "can you add invariants to my loop." Add the informal phrasings users actually use ("add contracts", "prove this correct", "make this verifiable"). 4. Does the description overtrigger? Vague triggers like "for any Python task" cause the skill to load for irrelevant requests and waste context. 5. Does the description make false claims about contents ("11+ examples" when there are exactly 11, "complete reference" when sections are missing)? Adjust to match reality. #### Structural audit 6. Is the numbering consistent? Watch for sequences like `1, 2, 3, 3b, 4` — these are signs that a section was retrofitted as a sub-item when it should be a top-level heading. 7. Are headings semantically grouped? A section titled "Code Generation Constraints" that contains both NEVERs and supported-feature notes is doing two jobs and confuses retrieval. 8. Are forward references resolved? If Example 9 says "see §7" and §7 appears *after* Example 9, the model has to re-read the file to find it. Move §7 above, or restructure. 9. Are cautionary examples mixed with canonical examples? If Examples 1–8 are templates to imitate but Examples 9–10 carry "ASPIRATIONAL / DO NOT IMITATE" warnings, separate them into clearly-labeled sections. Mixing them is actively misleading — the model copies whichever it pattern-matches first. #### Formatting audit 10. Are bullets indented consistently? Bullets at 5–7 spaces instead of 4 render as nested sub-items and break the visual hierarchy. 11. Are bullets concise enough to scan? A "NEVER" rule that runs 200 words loses its emphasis. Long rules belong as their own subsection with prose paragraphs, not as a bullet. 12. Is code fenced with language tags (` ```python `)? Untagged blocks render without syntax highlighting and are harder to scan. 13. Are inline references (`§7`, `Section 4`, `Example 6`) consistent throughout? Mixing `§3`, `section 3`, and `Sec. 3` makes search harder. #### Path and link audit 14. Do all internal file references point to files that exist *and* live in the standard layout? `references/foo.md` is conventional; `test-suite/foo.md` is not. 15. Are external URLs still valid? #### Size audit 16. Is the file under ~500 lines? Beyond that, the model's attention starts to degrade and rules get missed. If over, plan a split into `SKILL.md` plus `references/*.md`. 17. Is content that *could* be a reference still inline? Examples: detailed transpiler limits, edge-case tables, cautionary worked examples, low-frequency lookup tables. These belong in `references/`. ### Step 3 — Report findings and confirm depth Before writing any output, summarize what you found. Group findings by severity: surface (typos, indentation, dead paths) vs structural (heading reorganization, splits, forward-reference fixes). Then ask the user — **with the `ask_user_input_v0` tool, not as a prose question** — whether they want a light polish (surface only, keep single file) or a deep polish (everything including the split into references). Default to single-select with two options. Do not skip this step even if the file is obviously oversized; some users have hard constraints (e.g., they're shipping to a harness that does not load `references/` and want a single file regardless of length). ### Step 4 — Plan the split (deep polish only) If the user chose deep polish and the file warrants splitting: - The body of `SKILL.md` should keep: frontmatter, workflow steps, the canonical examples to imitate, the rules a model needs on every invocation. - Move to `references/` files: detailed constraint lists (transpiler limits, syntax forbidden lists), tables of patterns, cautionary examples, edge-case lookup data, anything the model only needs occasionally. - Group references by *when the model would need to load them*, not by topic similarity. A single `references/everything.md` defeats the purpose. Aim for 2–5 reference files, each scoped to a clear "I need this when…" trigger. - In the new `SKILL.md`, end with a "Reference files" section that lists each file with a one-sentence description of when to consult it. The model uses these descriptions to decide which file to read. Name reference files by what they contain, not by section number: `transpiler-limits.md`, `solver-heuristics.md`, `matrix-patterns.md` — not `section-5.md`, `appendix-a.md`. ### Step 5 — Write the polished files Use `create_file` to write each output file to `/mnt/user-data/outputs//`. Maintain the standard layout: ```text / ├── SKILL.md ├── references/ │ ├── .md │ ├── .md │ └── ... ├── scripts/ (if the original had one) └── assets/ (if the original had one) ``` If the original had `scripts/` or `assets/`, copy them through unchanged unless the user asks otherwise. ### Step 6 — Verify and bundle After writing all files: 1. Use `bash_tool` to `wc -l` each output file and confirm the line counts are in the expected ranges (`SKILL.md` ≤ ~500 lines for deep polish; references can be longer because they load on demand). 2. Use `bash_tool` to `zip -r` the entire folder into a single archive at `/mnt/user-data/outputs/.zip` so the user has both individual files and a bundle. 3. Use `present_files` to surface both the zip and the individual `.md` files. The zip goes first in the array — it's the primary deliverable; the individual files are for users who want to inspect one piece. ### Step 7 — Summarize the diff End with a short, honest summary of what changed. Explicitly call out: - What you fixed (frontmatter, headings, examples reorganized, bullets reformatted, dead references corrected, oversize split). - What you intentionally preserved (every technical claim verbatim). - Anything the user should double-check (e.g., "if I dropped a claim by accident, flag it and I'll restore the original wording"). Do not pad the summary with marketing language. The user just gave you a working artifact; respect that by being precise about what is different. ## Content-preservation rules These are absolute. Violating them turns a polish into a rewrite, which is not what the user asked for. - **Preserve every NEVER rule verbatim** — including any explanation of *why* the rule exists. The "because Alt-Ergo times out on nonlinear products" rationale is as important as the rule itself. - **Preserve every workaround verbatim** — the suggested fix ("introduce a `found` variable", "use `i = n` to force loop exit") is the actionable part. Do not paraphrase it. - **Preserve every worked example verbatim** in both input and output blocks. Re-fence with ` ```python ` if the original lacked language tags, but do not edit the code. - **Preserve cautionary warnings verbatim** ("ASPIRATIONAL ONLY", "CONTAINS FALSE INVARIANTS"). These are load-bearing; the user added them after the original failed in some specific way. - **Preserve technical terminology verbatim** even if it looks idiosyncratic. Domain-specific terms ("frame condition", "Hoare logic", "discharge a proof obligation") are not jargon to simplify away — they signal precision and the user's audience expects them. ### What you may change - Heading numbering, heading levels, and section ordering (when fixing forward references or moving cautionary examples out of the imitate-these block). - Bullet indentation, list markers, line wrapping. - Code fence language tags. - Internal references when you renumber sections (`§7` → `§3` if §7 became §3). - Prose around technical claims (transitions, framing sentences) — but not the claims themselves. ## Anti-patterns to avoid - **Don't rewrite the frontmatter description from scratch.** Edit the existing one. Wholesale rewrites tend to drop triggering phrases the user added on purpose. - **Don't merge similar NEVER rules** into a single combined rule even if they share structure. They were probably written as separate rules because they fail in subtly different ways and the user wants the model to see them as distinct. - **Don't add new examples.** The user has not asked for new content. Polish operates only on what is already there. - **Don't drop content silently.** If something genuinely doesn't fit anywhere in the new structure, surface it in the summary so the user can decide. - **Don't reorder the worked examples.** Examples 1–8 are usually ordered by complexity for a reason (each builds on patterns from earlier ones). - **Don't infer missing context.** If a section references "the schema" or "the format" without specifying, leave it ambiguous in the output and flag it for the user — do not guess what was meant. ## Output requirements The final response to the user should: 1. Briefly state what was done (1–2 sentences). 2. Show the final file structure with line counts. 3. Summarize what changed and what was preserved (the Step 7 diff). 4. Surface the zip and individual files via `present_files`. Do not write a long postamble. The user can read the files; they need access, not narration.