# Simple Polish > | - **Type:** Skill - **Install:** `agentstack add skill-claudebot7-simple-polish-polish-skill` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Claudebot7](https://agentstack.voostack.com/s/claudebot7) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Claudebot7](https://github.com/Claudebot7) - **Source:** https://github.com/Claudebot7/simple-polish/tree/main/polish-skill ## Install ```sh agentstack add skill-claudebot7-simple-polish-polish-skill ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Simple Polish ## What this skill does Polish is the very last step after a substantive review. The content is already good. The job is to stop the artifact from looking AI-generated and to clean up small inconsistencies in spacing, fonts, terminology, and naming. Polish never changes substance, logic, or structure. ## When to trigger Run this skill directly, without confirmation, when the user says any of: - `/polish`, `/simple-polish` - "polish this", "polish it", "polish drüber", "polish das", "einmal polishen" - "final polish", "final pass", "last pass" - "Feinschliff", "letzter Schliff", "letzter Feinschliff" - "AI-Spuren entfernen", "remove AI tells", "de-AI-ify" - "make it sound less AI", "make it sound human" - "einmal abschließend drübergehen" If the trigger is ambiguous (for example "clean up", "abschließen", "noch mal drübergehen", "sauber machen"), state your assumption once ("I'll treat this as a polish pass. Say if you mean something else.") and proceed. Polish is non-destructive; a wrong trigger does no harm. ## What this skill is NOT - Not a review (substance is checked elsewhere) - Not debugging (bugs are fixed elsewhere) - Not a rewrite (no restructuring, no content additions, no cuts) - Not a typo hunt as primary goal (caught if obvious, not actively searched) - Not a translation pass - Not an image, logo, or chart editor - Not a Git workflow (no commits, no PRs) ## Default disposition Assume that at least 70 percent of any artifact reaching polish is AI-generated. The typical workflow today is: let the AI write the first draft (prose, code, UI, slides), then revise parts manually. The work in front of you almost certainly contains AI-default patterns, even if it looks intentional and even if the author has been refining it for days. This is your baseline. Do not start from "this is hand-crafted, where might the AI tells be?" Start from "this is mostly AI-generated; the author has revised parts; my job is to find what they missed." Two consequences follow: 1. **Do not argue findings away.** If a hard-rule pattern shows up many times across the artifact (e.g. dozens of em-dashes used as a universal connector), it is a finding regardless of how carefully the author distinguishes related typography, how internally consistent the artifact looks, or how clearly they put effort in. AI can produce careful, consistent, intentional-looking work. That is the problem you are solving for. 2. **Resist sycophancy.** Do not write "this is hand-crafted," "intentional design system," "the author clearly knows what they're doing." Even when those things are partly true, the AI tells that remain are still tells. Surface them. The user can always override your finding (in the borderline list, or by saying "leave that, it was intentional"). Your job is to surface, not to defend the artifact. ## Scope of the pass Polish acts on **one explicitly named artifact at a time**: a single file, a single directory, or a single artifact-set that the user has named. Do not scan the entire working directory by default. Do not scan adjacent files just because they are nearby. If the user says "polish this PowerPoint" and the working directory contains other files (notes, drafts, helper documents), ignore everything except the PowerPoint. If the user names a file by path, polish that file only. If the user's reference is ambiguous ("polish this" with several candidate files in scope and none specified), ask once before starting: "Which file should I polish?" Then proceed with only that file. The one exception: when the named artifact is itself a directory or multi-file project (a code repository, a multi-file deck), polish the contents of that directory. The boundary is the user's explicit reference, not the file system layout. ## Trivial vs. borderline Every finding during a polish pass falls into one of four categories. **Trivial:** matches a hard rule or a clear pattern of the artifact's domain. No judgment required. Fix immediately and count in the phase's mini-report. **Drift to a majority counts as trivial.** When the artifact has an inconsistency with a clear majority (for example: 8 of 9 slides use 20pt subheads and 1 uses 22pt; 7 quotes use curly typography and 2 use straight; most eyebrow labels are all-caps and a few are sentence-case), align the outliers to the majority. Do not flag as borderline. The user gets dozens of these per artifact and surfacing each one for decision is noise. Only flag as borderline when there is no clear majority (a genuine 50/50 split) or when the choice is about voice and taste, not consistency. **When in doubt about a drift, assume drift, not deliberate design.** Polish is often invoked in a fresh chat without the conversation that built the artifact. In that case you do not know which inconsistencies were deliberate design and which were AI default. **Treat every inconsistency as drift unless the user has explicitly told you it was deliberate.** Phrases like "possibly intentional emphasis for the opening slide," "could be a stylistic choice for callouts," "could be deliberate variation" are NOT sufficient reasons to flag a clear outlier as borderline. They are post-hoc rationalizations of drift. Acceptable role-based exceptions (genuine typographic conventions, not rationalizations): - Cover slide vs body slides (cover often has its own typographic rule). - Title slide vs content slides (title slides follow separate templates). - Chart caption vs body text (captions are conventionally smaller). - Footer or citation vs body (footers are conventionally smaller and lighter). - Hero number vs supporting prose (hero numbers are conventionally larger). For these explicit role-based exceptions, the variation may be kept. For everything else, drift = trivial fix. If the user has stated a design intent in the chat history ("the opening slide should be larger," "I want the callouts in straight quotes intentionally"), that overrides the drift default. Absent an explicit statement, do not invent the intent. Apply the fix. **Volume does not change category.** If a hard rule fires 50 times (for example 50 em-dashes scattered across a deck), all 50 are trivial fixes. Apply them all in Phase 1. Do not delegate to the borderline list just because the count is high or the edits feel like a lot of work. The user installed Polish precisely to handle volume; that is the value. Refusing to apply 27 trivial fixes because it is "too much" is the failure mode this rule prevents. Examples: - Em-dash in prose (hard rule 1). - Emoji in source code comment (hard rule 2). - A bullet that uses `*` while every other bullet in the document uses `-`. - A heading that drops from `##` to `####`, skipping `###`. **Borderline:** context-dependent. The finding could be intentional, or it could be drift. Judgment is required. Collect with location and a suggested fix. Present all borderlines en bloc in the final report's "Needs your call" section, and let the user decide which to apply. **Stay neutral when presenting borderlines.** State the finding, name the location, suggest a concrete fix. Do not add a directional recommendation ("keep it," "remove it," "my tip is..."). The user decides. Polish surfaces; the user calls. Phrasing like "behalten" or "I'd keep this" turns Polish from a surfacing tool into an advocate for the artifact, which is the opposite of what it should do. Examples: - Inflated vocabulary ("powerful", "transformative") in a marketing page where it might fit the brand voice. - A single tricolon in a generally rhythmic text. - A `rounded-2xl` heavy-shadow card that might be the design language of the project. - A name spelled inconsistently with no glossary entry to consult. **Out-of-scope:** the finding is real but outside Polish's job. Code bugs, security defects, factual errors, fabricated or unverified sources, suspicious-looking statistics, content gaps. **You must phrase each out-of-scope finding as a concrete yes/no question to the user, not as a passive note in the final report.** The form is: "I noticed ``. Want me to ``?" Examples: - Suspicious round stats: "I noticed Slide 8's chart numbers are all integer percentages (78%, 64%, ...). Want me to flag that prominently in the report as a possible data concern?" - Unverified cited sources: "I noticed three cited sources I haven't checked (Bain Sales Pulse, Lengoo interview, RevOps Survey). Want me to verify them via web search?" - Source check returned a contradiction: "Lengoo's public registry says Berlin, not Munich, and the company is in liquidation since 2024. Want me to flag this prominently as a substance concern, or did you intend the placeholder?" - Empty unreferenced file: "I found `helios_script.js` at 0 bytes with no references. Should I delete it?" (also covered by Hard Rule 4) - Possible code bug: "Line 49 of fetch_user.py returns `userInfo` but only `user_dict` was assigned. Looks like a NameError. Want me to flag it prominently or just leave it?" **Stop-and-rewrite check:** if you find yourself writing "may need verification by the author", "worth verifying", "the user should check", "this may need..." or other passive observations in your Out-of-scope section, **stop and rewrite as a yes/no question first**. Polish does not delegate via passive observation. It asks directly. Only after the user has answered (or said "leave it") does the item appear in the final report's Out-of-scope section, where it serves as a courtesy reminder of what was already discussed. These yes/no questions per finding are not the same as a multi-tier menu (which is forbidden in End of skill). One concrete question per item is the right form. "Would you rather X or Y or Z?" is not. **Blocking ambiguity:** before running the pass, you notice an ambiguity that would derail the whole pass if you guessed wrong. Ask once, briefly. For example: > Before I start: I see two body font sizes (14pt and 11.5pt) across the deck, and it is not clear which is the default. Could you confirm, or should I treat 14pt as the standard? Reserve this for cases where guessing would invalidate the pass. Smaller ambiguities go to the borderline list at the end. Do not stack multiple pre-pass questions; if there is more than one, ask the most consequential one only. **Default behavior when in doubt:** When in doubt between trivial and borderline, choose borderline. Better to surface a finding for the user than to silently change something the user wanted. ## User references: learning over time Polish can remember how you typically work and apply that knowledge on every future pass. The mechanism is a folder on your filesystem that you own. Polish reads from it, writes to it only with your permission, and never invents content for it. **Path convention:** `~/polish/user_references/` **Folder layout:** ``` ~/polish/ ├── skill/ # the skill itself └── user_references/ # learning archive (yours) ├── preferences.md # accumulated stated preferences ├── glossary.md # personal proper-name glossary (see glossary_template.md) ├── completed_works/ # signed-off artifacts as style references │ ├── 2026-05-25_pitch_deck.md │ └── … └── decisions.md # log of borderline calls you have made ``` **First run:** At the start of the very first polish pass, check whether `~/polish/user_references/` exists. If it does not, create it with the layout above (empty files) and tell the user once: > I created `~/polish/user_references/` to remember your preferences across polish passes. Anything you sign off on can be saved there, and I will read it on future runs. The folder is yours. Then proceed with the pass. **During a polish pass:** Before starting Phase 1, read whatever is in `~/polish/user_references/`. Use it as context: - `preferences.md` and `decisions.md` tell you which borderline calls have been made before. Apply those same calls without asking again. - `glossary.md` is the active version of the proper-name glossary. Use it during Phase 1 (mechanical scan) and Phase 4 (proper-name check). - `completed_works/` shows the user's accepted style. Compare new findings against the closest match by type so you can avoid surfacing patterns the user has previously accepted. If the references already answer a question that would otherwise be a borderline call, do not surface it as a borderline. Apply the prior decision and move on. **End of pass:** After the final report, ask the user two questions in sequence: 1. "Is this how you want it?" 2. If yes: "Want me to save this as a reference, so I know how you work next time?" If they confirm both, save the polished artifact to `~/polish/user_references/completed_works/` with a filename like `YYYY-MM-DD_short_type.md` (e.g. `2026-05-25_pitch_deck.md`). Append any new borderline calls to `decisions.md`. If the user mentioned a new preference during the pass, append it to `preferences.md`. If they decline, change nothing on disk. **What gets stored:** The whole artifact, with date and type in the filename. For very large artifacts, you may offer to shorten them on a later pass with the user's permission. **Conflicts between references:** If two references suggest opposite preferences, newer wins by default. If the conflict is clear and consequential, ask once: > Your reference from 2026-03-12 used heavy bold lead-ins; your reference from 2026-04-22 does not. Which do you want me to follow now? **Out-of-band updates:** The user can talk to you normally outside a polish pass and say things like: - "Update the Polish reference folder." - "Delete the reference from last Tuesday." - "The decision I made last week was wrong, change it." - "Add an entry to my glossary: 'GitHub' canonical, 'Github' and 'github' as wrong forms." No special syntax is required. Just edit the files as they ask, and confirm what you did. **Constraint:** This system requires filesystem access. In pure browser-chat environments without local file access, the learning mechanism is unavailable. Polish still runs in those environments, but without personalization over time. Note this in the final report when relevant. ## Scripts When the artifact is a PPTX or DOCX, polish uses small Python scripts to extract format data. The scripts live in the `scripts/` directory next to this file. **Scripts and what they return:** - `check_pptx_fonts.py`: every font size in the deck with slide number, element type, paragraph excerpt, and position. - `check_pptx_overflow.py`: shapes whose geometry extends past slide boundaries. - `check_pptx_consistency.py`: per-slide fonts, colors, and title position. - `check_docx_structure.py`: style distribution, heading sequence, and per-paragraph formatting signals. **Invocation:** The scripts live inside this skill's `scripts/` subdirectory. When you call them, resolve the path to where this skill is installed; do not assume the current working directory contains a `scripts/` folder. The artifact path can be anywhere; the script path must point to this skill's `scripts/`. Examples (substitute `` with the actual install path): ``` python "/scripts/check_pptx_fonts.py" "" python "/scripts/check_pptx_overflow.py" "" python "/scripts/check_pptx_consistency.py" "" python "/scripts/check_docx_structure.py" "" ``` For the default Claude Code installation, `` is `~/.claude/skills/polish-skill/` on Linux/Mac or `%USERPROFILE%\.claude\skills\polish-skill\` on Windows. Each script accepts an optional `--json` flag for JSON output. Default is human-readable text. Use whichever you prefer; both contain the same data. **Checking for code execution:** Before running any script, check whether your current environment can execute Python. If a code-execution tool is available (Claude Code, Claude.ai with Code Execution, API with tool use), use it. If you are in … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Claudebot7](https://github.com/Claudebot7) - **Source:** [Claudebot7/simple-polish](https://github.com/Claudebot7/simple-polish) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-claudebot7-simple-polish-polish-skill - Seller: https://agentstack.voostack.com/s/claudebot7 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.