copy-editing

Files (1)

• SKILL.md

SKILL.md (first lines)

# Copy Editing Skill

Good copy editing isn't about rewriting — it's about enhancing. Each sweep focuses on one quality dimension, catching issues that get missed when you try to fix everything at once.

> **Scope:** This skill edits prose and Markdown structure only. It does not write, suggest, or modify code of any kind.

---

## The Seven Sweeps

Run these in order. Complete each sweep fully before moving to the next.

---

### Sweep 1 — Clarity

**Goal:** Every sentence should be understood on the first read.

Look for:
- Sentences that require re-reading to parse
- Passive voice hiding who does what ("the file is loaded" → "load the file")
- Buried lead — the most important point is halfway through a paragraph
- Assumed knowledge — jargon or acronyms not defined for the intended audience
- Double negatives and hedge stacks ("it may not be unlikely that...")

**Common clarity killers in technical docs:**
| Weak | Stronger |
|------|----------|
| "Leverage the functionality" | "Use the feature" |
| "It should be noted that" | [delete — just say the thing] |
| "In order to" | "To" |
| "At this point in time" | "Now" |
| "Utilize" | "Use" |

**Checklist:**
- [ ] Each sentence makes one point
- [ ] Subject comes before verb in most sentences
- [ ] Acronyms defined on first use
- [ ] No sentence needs to be read twice

---

### Sweep 2 — Voice and Tone

**Goal:** The document sounds like a knowledgeable colleague, not a corporate manual or an AI summary.

This library's voice is:
- **Direct** — say what you mean, skip the preamble
- **Technically confident** — don't over-explain basics, but don't assume expert depth
- **Action-oriented** — favor imperative constructions ("Open the file", "Paste this into...")
- **Unpretentious** — no inflated language to sound more authoritative

Look for:
- Overly formal phrases that create distance ("Please be advised...", "It is recommended that...")
- Enthusiasm inflation ("incredibly powerful", "seamlessly integrates", "game-changing")
- Hedging that undermines confidence ("might possibly", "could potentially")
- Inconsistent person — don't switch between "you", "the user", and "one" in the same doc

**Checklist:**
- [ ] Tone is consistent start to finish
- [ ] No corporate or marketing filler language
- [ ] Reads like a person wrote it, not a template was filled in
- [ ] Consistent second-person address ("you") throughout

---

### Sweep 3 — So What

**Goal:** Every section should answer "why does this matter to me?"

The most common failure in technical documentation: describing *what* something is without explaining *why someone would use it* or *what problem it solves*.

Look for:
- Feature descriptions with no benefit statement
- Steps that don't explain what the step accomplishes
- Introductions that describe the document instead of its value ("This README covers...")
- Skill descriptions that say what the skill contains instead of what it does for the user

**Pattern to fix:**
```
Before: "This skill includes four post type templates."
After:  "Four post type templates mean you always start with the right structure — no blank page."
```

**Checklist:**
- [ ] The opening of every major section answers "why does this exist"
- [ ] Each feature or capability is paired with a user benefit
- [ ] The document's opening paragraph tells the reader what they'll be able to do, not just what the doc covers

---

### Sweep 4 — Prove It

**Goal:** Claims are backed by examples, not just asserted.

Look for:
- Assertions without illustration ("This skill produces better results")
- Vague capability statements with no concrete example ("Works for any goal")
- Instructions that tell but don't show ("Describe what you want and the skill handles the rest")

Fix by adding:
- A concrete example for any claim that could be doubted
- A "for example" or sample input/output where a step is abstract
- Specific scenarios in skill descriptions (the frontmatter `description` field is the main place agents use to decide whether to invoke a skill — make it concrete)

**Checklist:**
- [ ] Every "this does X" statement has an example of X
- [ ] Skill frontmatter descriptions include at least one concrete trigger or use case
- [ ] Abstract instructions have a "for example" companion

---

### Sweep 5 — Specificity

**Goal:** Replace vague language with precise language wherever precision is possible.

Look for:
- Quantity vagueness ("several", "a few", "many" → use actual numbers when known)
- Scope vagueness ("various features", "different options" → name them)

From zrosenfield/sharepoint-ai-skills, MIT.

More from zrosenfield/sharepoint-ai-skills