| name | refine-write-article-skill |
| description | Analyze manual edits made to an AI-generated blog article and update the write-article skill with the learnings. Use after manually correcting an AI-drafted article to improve future article generation. Triggers: refine skill, learn from edits, update skill from article, improve article skill, analyze my edits. |
| argument-hint | <path-to-article> - optional path to the article index.mdx (defaults to current file) |
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:
- If an article path was passed as an argument, use it.
- Otherwise, use the currently open file (should be an
index.mdx).
- 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.
| Category | What to look for |
|---|
| Voice | Rewrites to sentence structure, word swaps, changes to how "I/you/we" is used, removal of AI-ish phrases |
| Tone | Changes to enthusiasm level, hedging removed or added, more/less direct |
| Structure | Sections reordered, headings renamed/removed/added, intro rewritten |
| Anti-pattern removal | Em dashes replaced, emojis deleted, banned phrases removed ("delve", "leverage", etc.) |
| Code examples | Code added, removed, simplified, or corrected |
| Component decisions | Inline HTML replaced with a component, or vice versa; component props changed |
| Frontmatter | Title, description, tags, or freebie changed |
| Factual/technical | Corrections to accuracy, not style |
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:
| Edit type | Add to skill? |
|---|
| Replaced "leverage" with "use" | Yes — add to banned words |
| Removed an em dash | Yes — reinforce the no-em-dash rule with the specific context |
| Rewrote the intro to lead with the problem | Yes — add as a structural rule if not already present |
| Changed a specific CSS value in a code example | No — factual fix, not reusable |
| Renamed a heading | Maybe — only if the AI's naming pattern is systematically off |
| Removed a "Conclusion" section | Yes if the current rule says to include one; update the rule |
| Simplified a React component to an Astro component | Yes — add to the Astro vs React decision table |
Added a <Tangent> around a paragraph | Maybe — only if there is a clear pattern for what belongs in tangents |
| Changed "Let's" to "Let us" | No — too minor, does not affect reading experience |
| Deleted the closing sentence entirely | Yes if it was a platitude; add it to the banned phrases list |
