A production-grade, open-source skill that gives AI coding agents the ability to transform any repository into accurate, engaging, publication-quality technical articles — grounded in evidence, not hype.

What  ·  Architecture  ·  Workflow  ·  Article Types  ·  Audiences  ·  Usage  ·  Philosophy  ·  Structure  ·  Roadmap  ·  Author

---

What This Is

skills/article-writer is a drop-in skill package for any AI coding agent — Claude, GPT-4, or any agent with file-read access. It enforces a discipline-first writing process: read the code, understand the architecture, verify every claim, then write.

It generates Medium articles, dev.to posts, engineering blog posts, architecture deep dives, launch announcements, and release notes — all grounded in what the repository actually does, not what sounds impressive.

It is not a content marketing tool. It is not a buzzword generator. It is a structured system that teaches an agent to produce technical writing that helps engineers genuinely learn from your work.

Why does this exist? (Click to expand)

Most AI-generated technical articles share the same failure modes:

Failure	Impact
Claims unsupported by actual code	Destroys credibility when engineers check
Invented benchmarks	Catastrophic when reproduced and disproved
Architecture diagrams contradicting implementation	Misleads decision-makers
Hype language ("blazing fast", "enterprise-ready")	Signals the article wasn't written by an engineer
Shallow explanations	Leaves readers no better informed than before

This skill enforces a single rule: if you cannot point to the evidence in the repository, you cannot make the claim in the article.

---

Skill Architecture

graph TB
    classDef entry fill:#6366f1,stroke:#4f46e5,color:#fff,font-weight:bold
    classDef process fill:#0f172a,stroke:#334155,color:#94a3b8
    classDef template fill:#166534,stroke:#15803d,color:#bbf7d0
    classDef output fill:#7c2d12,stroke:#c2410c,color:#fed7aa
    classDef check fill:#1e3a5f,stroke:#1d4ed8,color:#bfdbfe

    USER(["👤 User Request\nWrite me an article..."]) --> SKILL

    SKILL["📋 SKILL.md\nActivation · Inputs · Outputs\nConstraints · Success Criteria"]:::entry

    SKILL --> WORKFLOW["🔄 WORKFLOW.md\n13-Step Deterministic Process"]:::process
    WORKFLOW --> AUDIENCE["👥 AUDIENCE.md\nBeginner · Engineer\nSecurity · Founder"]:::process
    WORKFLOW --> STYLE["✍️ STYLE_GUIDE.md\nParagraphs · Voice\nVocabulary · Code"]:::process
    WORKFLOW --> FACT["🔍 FACT_CHECKING.md\nVerified · Inferred\nProhibited Claims"]:::check
    WORKFLOW --> DIAGRAMS["📊 DIAGRAMS.md\nMermaid · Sequence\nArchitecture · Flow"]:::process
    WORKFLOW --> SEO["🔎 SEO.md\nTitles · Keywords\nMeta · Structure"]:::process

    WORKFLOW --> TEMPLATES{{"📁 TEMPLATES/"}}:::template
    TEMPLATES --> TM["📝 medium.md"]:::template
    TEMPLATES --> TD["📝 devto.md"]:::template
    TEMPLATES --> TA["📝 architecture.md"]:::template
    TEMPLATES --> TR["📝 research.md"]:::template
    TEMPLATES --> TL["📝 launch.md"]:::template
    TEMPLATES --> TRE["📝 release.md"]:::template

    FACT --> CHECKLIST["✅ CHECKLIST.md\n40+ Pre-Publication Gates\n7 Quality Categories"]:::check

    CHECKLIST --> OUTPUT(["📄 Publication-Ready\nMarkdown Article"]):::output

    EXAMPLES["💡 EXAMPLES/\nexcellent_article.md\nweak_article.md"]:::process -.->|"reference"| WORKFLOW

    PROMPTS["🤖 PROMPTS.md\n8 Reusable Agent\nPrompt Templates"]:::process -.->|"activate"| SKILL

Loading

---

13-Step Writing Workflow

flowchart LR
    classDef phase1 fill:#1e3a5f,stroke:#1d4ed8,color:#bfdbfe
    classDef phase2 fill:#1a1a2e,stroke:#7c3aed,color:#ddd6fe
    classDef phase3 fill:#0d2818,stroke:#15803d,color:#bbf7d0
    classDef phase4 fill:#3b0764,stroke:#a21caf,color:#f0abfc
    classDef decision fill:#3b1f0a,stroke:#c2410c,color:#fed7aa,shape:diamond

    subgraph RESEARCH ["🔬  Phase 1 — Research"]
        S1["1️⃣ Inspect\nRepository"] --> S2["2️⃣ Read README\n& Docs"]
        S2 --> S3["3️⃣ Analyze\nSource Code"]
        S3 --> S4["4️⃣ Review Examples\n& Tests"]
    end

    subgraph UNDERSTAND ["🧠  Phase 2 — Understand"]
        S5["5️⃣ Frame the\nProblem"] --> S6["6️⃣ Verify Claims\nvs Implementation"]
        S6 --> S7["7️⃣ Define\nTarget Audience"]
        S7 --> S8["8️⃣ Select\nTemplate"]
    end

    subgraph WRITE ["✍️  Phase 3 — Write"]
        S9["9️⃣ Draft\nContent"] --> S10["🔟 Self-Review\nPass"]
    end

    subgraph VERIFY ["✅  Phase 4 — Verify & Deliver"]
        S11["1️⃣1️⃣ Fact-Check\nAll Claims"] --> S12["1️⃣2️⃣ Improve\nReadability"]
        S12 --> S13["1️⃣3️⃣ Final Checklist\n& Delivery"]
    end

    RESEARCH:::phase1 --> UNDERSTAND:::phase2
    UNDERSTAND:::phase2 --> WRITE:::phase3
    WRITE:::phase3 --> VERIFY:::phase4

    style RESEARCH fill:#1e3a5f22,stroke:#1d4ed8,color:#bfdbfe
    style UNDERSTAND fill:#1a1a2e22,stroke:#7c3aed,color:#ddd6fe
    style WRITE fill:#0d281822,stroke:#15803d,color:#bbf7d0
    style VERIFY fill:#3b076422,stroke:#a21caf,color:#f0abfc

Loading

---

Article Types

Article Types

📝 All Six Supported Article Types

Type	Template	Best For	Tone	Length
📰 Medium Article	medium.md	Broad developer audience, narrative-driven exploration	Educational, storytelling	800–2500 words
👩‍💻 dev.to Post	devto.md	Community tutorials with complete working code	Practical, hands-on	600–1500 words
🏗️ Architecture Deep Dive	architecture.md	Senior engineers evaluating system design decisions	Precise, analytical	1500–3000 words
🔬 Research Summary	research.md	Investigation-style findings with trade-off analysis	Academic, evidence-based	1200–2500 words
🚀 Launch Announcement	launch.md	Introducing a new project or major feature	Confident, grounded	600–1200 words
📦 Release Notes	release.md	Version-specific changelog with narrative context	Direct, migration-focused	400–800 words

---

Audience Support

mindmap
  root((Target\nAudiences))
    Beginners
      Define every acronym
      Explain why before how
      Use analogies
      Complete runnable examples
    Professional Engineers
      Lead with trade-offs
      Show internal mechanisms
      Peer-to-peer tone
      Realistic code examples
    Security Researchers
      Explicit threat models
      Trust boundary description
      Specific algorithm names
      Acknowledge attack surfaces
    Open-Source Contributors
      Repository structure tour
      Testing philosophy
      Contribution opportunities
      Architectural constraints
    Startup Founders
      Problem and stakes first
      Clear capability summary
      Maturity and license signals
      No deep implementation detail
    Technical Decision-Makers
      Operational properties
      Compliance features
      Failure mode description
      Upgrade and migration paths

Loading

---

How AI Agents Should Use This

When a user requests an article, blog post, write-up, or technical explainer, the agent follows this exact sequence:

Step	File	What the Agent Does	Why It Matters
1	SKILL.md	Confirm this skill applies to the request	Prevents activating for wrong task types
2	WORKFLOW.md	Execute all 13 steps in order — never skip	Research phase feeds every downstream decision
3	STYLE_GUIDE.md	Apply writing standards to every paragraph	Enforces active voice, paragraph limits, code conventions
4	FACT_CHECKING.md	Verify every claim against repository evidence	No benchmark, metric, or testimonial appears without a source
5	TEMPLATES/	Select the template matching the article type	Scaffold ensures correct structure per platform
6	CHECKLIST.md	Gate on all 40+ pre-publication checks	Nothing ships with a failing item — no exceptions

Non-negotiable rule: Any claim that cannot be traced to repository evidence must be verified or removed. The agent never skips the fact-checking phase.

Example prompt to activate this skill:

Write a Medium article about this parser library for intermediate Go developers.
Follow the article-writer skill in skills/article-writer/.

---

Design Philosophy

Teach before you persuade An article that helps a reader understand a problem earns trust. An article that claims superiority without evidence destroys it. Establish the problem fully before naming the solution. Evidence-first writing Every major claim must trace to source code, tests, documentation, or commit history within the repository. If the evidence does not exist, the claim does not appear.

Honest trade-offs Good engineering writing acknowledges limitations. If a project is fast but memory-hungry, say so. Readers are engineers — they will find the trade-offs themselves. Better they hear it from you first. Clarity over cleverness The best technical writing sounds like a knowledgeable colleague explaining something plainly. Not a press release. Not an academic paper. A colleague.

---

Repository Structure

skills/
└── article-writer/
    ├── SKILL.md            ← Entry point: activation, inputs, outputs, constraints
    ├── README.md           ← Skill quick-reference
    ├── WORKFLOW.md         ← 13-step deterministic writing process
    ├── STYLE_GUIDE.md      ← Paragraph, sentence, tone, Markdown standards
    ├── FACT_CHECKING.md    ← 4-category claim protocol + per-domain checklists
    ├── SEO.md              ← Titles, keywords, metadata — without stuffing
    ├── AUDIENCE.md         ← 6 audience profiles with calibration rules
    ├── DIAGRAMS.md         ← When and how to generate Mermaid visuals
    ├── CHECKLIST.md        ← 40+ pre-publication gates across 7 categories
    ├── PROMPTS.md          ← 8 copy-paste agent prompts by article type
    ├── TEMPLATES/
    │   ├── medium.md       ← Narrative-driven with full placeholder scaffold
    │   ├── devto.md        ← With front matter and Liquid callout support
    │   ├── architecture.md ← Component tables, Mermaid diagrams, trade-off analysis
    │   ├── research.md     ← Abstract, methodology, appendix structure
    │   ├── launch.md       ← Problem-first with honest current-state section
    │   └── release.md      ← Breaking changes, migrations, contributor credits
    └── EXAMPLES/
        ├── excellent_article.md   ← Annotated reference (7 strengths explained)
        └── weak_article.md        ← Anti-patterns with 10 annotated failure modes

---

Contribution Guidelines

How to contribute

Contributions that improve accuracy, coverage, or clarity are welcome.

• Templates — Add templates for new platforms (Substack, Hashnode, LinkedIn) following the existing placeholder format
• Examples — Add annotated examples of excellent and weak articles; always explain why the writing works or fails
• Prompts — Add prompts for article types not currently covered in PROMPTS.md
• Style guidance — Propose additions to STYLE_GUIDE.md with concrete before/after examples

The one non-negotiable constraint: Do not add guidance that encourages hype, keyword stuffing, or unsupported claims.

Pull requests should include a brief description of what changed and why.

---

Roadmap

• Audience-specific quality scoring rubric
• Automated fact-check diff — compare draft claims against repo evidence
• Multi-platform publishing workflow (Medium API, dev.to API)
• Diagram generation workflow using Mermaid + code analysis
• Localization guidance for non-English audiences
• Versioned article update workflow — when code changes, flag stale claims
• Integration with changelog parsers for automated release notes

---

The Golden Rule

Every generated article must answer eight questions:

1. What problem exists?
2. Why should the reader care?
3. Why are current approaches insufficient?
4. How does this project address the problem?
5. How does it work internally?
6. What are its strengths?
7. What are its limitations?
8. What future improvements are possible?

If the repository cannot support a claim with evidence — that claim does not appear.

---

Built by

fiscalmindset

Thinking Engineer github.com/fiscalmindset algsoch@gmail.com

^{MIT License · Use freely · Improve openly · Attribute optionally}