refine-write-article-skill

Refine Write Article Skill

Compares what the AI generated against what you actually kept, analyzes the pattern of changes, and updates the write-article skill so future articles need fewer corrections.

---

File Locations

Original snapshots:  skill-out/YYYY-MM/slug/original.mdx   ← gitignored, read directly
Live articles:       src/pages/YYYY-MM/slug/index.mdx

Skill files to update:
  .agents/skills/write-article/SKILL.md
  .agents/skills/write-article/references/components.md

Copies to keep in sync:
  .github/skills/write-article/SKILL.md
  .github/skills/write-article/references/components.md
  .claude/skills/write-article/SKILL.md
  .claude/skills/write-article/references/components.md

---

Workflow

Step 1 — Identify the article

Determine which article to analyze:

1. If an article path was passed as an argument, use it.
2. Otherwise, use the currently open file (should be an index.mdx).
3. Confirm the file is inside src/pages/ before proceeding.

Step 2 — Load the original and current versions

Derive the snapshot path from the article path. Given an article at:

src/pages/YYYY-MM/article-slug/index.mdx

The original AI-generated snapshot lives at:

skill-out/YYYY-MM/article-slug/original.mdx

Important: The skill-out/ directory is listed in .gitignore and will not appear in any git-aware file listing. Use the read_file tool directly with the absolute path — do not use git commands, git diff, or any tool that filters gitignored files. The file is present on disk even though git ignores it.

Read both files in full. If original.mdx does not exist, tell the user it was not saved when the article was generated and stop — there is nothing to compare against. Do not fall back to git.

Step 3 — Categorize every change

Read the diff line by line and bucket each change into one or more of these categories. A single edit can belong to multiple categories.

Ignore pure factual/technical corrections (category 8) — those are article-specific and do not teach the skill anything reusable.

Step 4 — Extract reusable rules

For each non-technical change, ask: "If the AI had known this rule upfront, would it have written this correctly the first time?"

If yes, it is a candidate for a new or updated rule.

Group candidates by category and write them as actionable directives, not observations. Examples:

• Observation (bad): "Kyle removed 'It is worth noting that' three times."

• Rule (good): Add "It is worth noting that..." to the banned phrases list with the correction → just say the thing directly.

• Observation (bad): "Kyle restructured the intro."

• Rule (good): "The intro should state the problem and its cost in the first sentence. Do not lead with historical context or background."

Step 5 — Evaluate impact

Before writing anything, score each candidate rule:

• High impact: Appeared more than once in this diff, OR is a pattern that matches other known AI tendencies
• Low impact: One-off phrasing preference that may not generalize

Only add high impact rules to the skill. Low impact observations can be noted as a comment to the user but should not clutter the skill.

Step 6 — Update the skill files

Edit the appropriate files based on what was learned:

For voice, tone, structure, and anti-pattern rules → SKILL.md

Add new banned phrases to the "Banned words and phrases" list. Add new structural rules to the relevant section. If a pattern contradicts an existing rule, update the existing rule rather than adding a duplicate.

For component rules → references/components.md

If changes reveal a preference for when to use inline HTML vs a component, or a specific structural pattern, add it to the relevant section.

For frontmatter rules → SKILL.md frontmatter section

If the title, description, or tags were systematically wrong, refine those guidelines.

Step 7 — Sync skill copies

After updating the canonical skill files, copy them to the .github and .claude locations:

cp .agents/skills/write-article/SKILL.md .github/skills/write-article/SKILL.md
cp .agents/skills/write-article/SKILL.md .claude/skills/write-article/SKILL.md
cp .agents/skills/write-article/references/components.md .github/skills/write-article/references/components.md
cp .agents/skills/write-article/references/components.md .claude/skills/write-article/references/components.md

Step 8 — Report back

Summarize what was learned in a short report using this format:

## Skill Update Report

**Article analyzed:** src/pages/YYYY-MM/slug/index.mdx
**Original snapshot:** skill-out/YYYY-MM/slug/original.mdx
**Total changes analyzed:** N

### Rules Added
- [Section updated]: Description of the new rule

### Rules Updated
- [Section updated]: What changed and why

### Patterns Noted (not added — too specific)
- Description of one-off changes that were not generalized

---

Decision Guide: Add to Skill vs. Skip

Use this when deciding whether an edit is worth encoding: