foksa.dev

← Writing

·release

document-iteration-skill 6.0 rewrites the skill in positive terms

The skill now says what Claude should do instead of listing what it shouldn't, the slash commands became plain requests, and the repo went from about 7,700 lines to 850.

document-iteration-skill 6.0 is out. It's a Claude skill for editing documents with inline feedback. You write %% comments %% next to the text, and Claude edits the document and replies next to them with •%%> responses <%%•. The whole discussion stays in the file and in git.

I stopped working on it in January, but I kept using it, and it kept being useful. In the meantime, the way skills are written has changed quite a bit, so this release is mostly a rewrite.

Say what to do, not what to avoid

The old SKILL.md was full of rules like "NEVER remove user comments" and "NEVER use %% %% yourself", under headings like "MANDATORY RULES (NEVER SKIP)" and "NEVER DO THIS". It also showed examples of wrong output next to the right ones.

One thing I've learned since is that negations like these don't hold up well. As the context grows, the "never" fades and what's left is the thing you said not to do. The same goes for examples of wrong output: models tend to copy what they see.

So every rule now describes the behavior I want, with a short reason:

  • Before: "NEVER use %% %% for your own content."
  • Now: "Every piece of text you add as a remark goes inside •%%> … <%%•, including when you draft a brand-new document. Keeping the two voices distinct is what lets anyone reading the file see who said what."

The reason matters as much as the rule, because it lets Claude handle cases the rule doesn't mention. The examples now show only correct output. SKILL.md is shorter too, and the details moved into reference files that Claude reads only when it needs them.

No more slash commands

Version 5 came with six slash commands: /iterate, /iterate-ask, /feedback, /cleanup, /init-vscode and /init-obsidian. They're gone. The skill now picks the mode from a plain request:

text
> respond to the comments in docs/plan.md
> review docs/spec.md and add your feedback
> draft a proposal for dark mode
> clean up docs/plan.md
> set up Obsidian highlighting for the vault in docs/

The editor configs for VSCode and Obsidian now ship inside the skill, so Claude can set them up without a separate download.

A smaller repo

The repo had grown to about 7,700 lines of text for what is essentially one markdown file. There were five cleanup scripts doing the same thing in Python, JavaScript, Bash, PowerShell and Batch, plus four setup prompts, a devcontainer, and around 45 documentation pages in a separate repo.

Now it's about 850 lines: the skill, one Python cleanup script with tests, a four-page docs site, and one real example.

Other changes

  • Tokens update in place. When Claude rewrites highlighted text, it keeps the token: ==PostgreSQL(DB)== becomes ==SQLite(DB)==, so your %%(DB) comment still points at the right place.
  • Claude.ai support. The release now contains only the skill folder as document-iteration-skill.zip, ready to upload under Settings → Skills.

Upgrading

Delete .claude/skills/document-iteration-skill, along with any of the old command files you copied into .claude/commands/. Then install again:

bash
git clone --depth 1 https://github.com/foksa/document-iteration-skill.git /tmp/dis
cp -r /tmp/dis/document-iteration-skill .claude/skills/ && rm -rf /tmp/dis

The old starter-kit.zip download is gone. If you linked to it, switch to document-iteration-skill.zip.