article-writer
Write technical articles with web research, runnable examples, and translations in author's voice
When & Why to Use This Skill
The Article Writer skill is a comprehensive agentic solution designed to automate the end-to-end lifecycle of technical content creation. It excels at performing deep web research, planning structured outlines, and drafting articles that strictly adhere to a specific author's voice and tone. A unique differentiator is its ability to generate, verify, and integrate fully runnable companion projects (supporting Laravel, Node.js, Python, and more), ensuring that every code example provided is technically accurate and production-ready. It also features built-in multi-language translation and word-count enforcement for professional publishing standards.
Use Cases
- Developing high-quality technical tutorials that include verified, runnable code repositories to enhance reader engagement and trust.
- Scaling technical blog production by mimicking a lead architect's unique writing style and vocabulary across multiple articles.
- Automating the research and drafting of documentation for rapidly evolving technologies by fetching the latest data from official web sources.
- Creating localized versions of technical guides where complex code snippets and project structures remain consistent and functional across all languages.
- Streamlining the creation of technical whitepapers that require a balance of deep research, opinionated analysis, and practical implementation examples.
| name | article-writer |
|---|---|
| description | Write technical articles with web research, runnable companion projects, and translations in author's voice |
Article Writer
Create technical articles with companion projects and multi-language support.
Quick Start
- Determine author (from task or first in authors.json)
- Create folder structure (including
code/folder) - Load author profile
- Load settings.json (including
article_limits.max_words) - Follow phases: Initialize → Plan → Research → Draft → Companion Project → Integrate → Review → Condense → Translate → Finalize
Workflow Overview
Plan → Research → Draft (initial) → Create Companion Project → Update Draft → Review → Condense → Translate → Finalize
↑ ↓ ↓
└──────── Iterate ─────────────┘ │
↓
(if over max_words)
Folder Structure
content/articles/YYYY_MM_DD_slug/
├── 00_context/ # author_profile.json
├── 01_planning/ # classification.md, outline.md
├── 02_research/
│ ├── sources.json # All researched sources
│ └── research_notes.md
├── 03_drafts/
│ ├── draft_v1.{lang}.md # Initial draft
│ └── draft_v2.{lang}.md # After companion project integration
├── 04_review/ # checklists
├── 05_assets/images/
├── code/ # COMPANION PROJECT
│ ├── README.md # How to run the companion project
│ ├── src/ # Companion project source code/files
│ └── tests/ # Tests (if applicable)
├── {slug}.{primary_lang}.md # Primary article
└── {slug}.{other_lang}.md # Translations
Phases
Phase 0: Initialize
- Get author, generate slug, create folder
- Create
code/directory for companion project - Copy author profile to
00_context/ - Load
article_limits.max_wordsfrom settings.json
Phase 1: Plan
- Classify article type
- Create outline
- Plan companion project type and scope
- CHECKPOINT: Get approval
Phase 2: Research (Web Search)
- Search official documentation
- Find recent news (< 1 year for technical)
- Record all sources
Phase 3: Draft (Initial)
- Write initial draft in primary language
- Mark places where example code will go:
<!-- EXAMPLE: description --> - Save as
03_drafts/draft_v1.{lang}.md
Applying Author Voice
Use ALL author profile data when writing:
Manual Profile Data
tone.formality: 1=very casual, 10=very formaltone.opinionated: 1=always hedge, 10=strong opinionsphrases.signature: Use naturally (don't overdo)phrases.avoid: Never use thesevocabulary.use_freely: Assume reader knows thesevocabulary.always_explain: Explain on first use
Voice Analysis Data (if present in
voice_analysis)sentence_structure.avg_length: Target this sentence lengthsentence_structure.variety: Match style (short/moderate/long)communication_style: Reflect top traits in tonecharacteristic_expressions: Sprinkle these naturallysentence_starters: Use these patternssignature_vocabulary: Prefer these words
Example:
For author with:
{
"tone": { "formality": 4, "opinionated": 7 },
"voice_analysis": {
"sentence_structure": { "avg_length": 14, "variety": "moderate" },
"communication_style": [{ "trait": "enthusiasm", "percentage": 32 }],
"characteristic_expressions": ["na prática", "o ponto é"],
"sentence_starters": ["Então", "O interessante é"]
}
}
Write with:
- Conversational but confident tone
- Medium sentences (~14 words)
- Enthusiastic energy
- Occasional "na prática" and "o ponto é"
- Some sentences starting with "Então" or "O interessante é"
Phase 4: Create Companion Project ⭐
Use Skill(companion-project-creator) for this phase
CRITICAL: Companion projects must be COMPLETE, RUNNABLE, and VERIFIED.
A Laravel companion project is a FULL Laravel installation. A Node companion project is a FULL Node project.
The companion project is NOT complete until you have actually run and tested it.
Step 1: Load Companion Project Defaults from Settings
Read .article_writer/settings.json first:
# View defaults for the companion project type
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings code
Or read JSON and extract:
const settings = JSON.parse(fs.readFileSync('.article_writer/settings.json'));
const codeDefaults = settings.companion_project_defaults.code;
// codeDefaults.scaffold_command
// codeDefaults.verification.install_command
// codeDefaults.verification.run_command
// codeDefaults.verification.test_command
Step 2: Merge with Article Overrides
If article task has companion_project field, those values override settings defaults.
Step 3: Execute Scaffold Command
# From settings.companion_project_defaults.code.scaffold_command
composer create-project laravel/laravel code --prefer-dist
Step 4: Add Article-Specific Code
Add your custom code on top of the scaffolded project:
- Models, Controllers, Routes
- Migrations, Seeders
- Tests
Never create partial projects with just a few files.
Step 5: VERIFY (Mandatory) ⚠️
You MUST actually run these commands and confirm they succeed:
cd code
# 1. Install dependencies - MUST SUCCEED
composer install
# ✓ Check: No errors, vendor/ directory exists
# 2. Setup - MUST SUCCEED
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate
# ✓ Check: No errors
# 3. Run application - MUST START
php artisan serve &
# ✓ Check: "Server running on http://127.0.0.1:8000"
# Stop the server after confirming
# 4. Run tests - ALL MUST PASS
php artisan test
# ✓ Check: "Tests: X passed" with 0 failures
If ANY step fails:
- Read the error message
- Fix the code
- Re-run verification from step 1
- Repeat until ALL steps pass
DO NOT proceed to Phase 5 until verification passes.
Companion Project Types
| Article Topic | Project Type | What to Create |
|---|---|---|
| Laravel/PHP code | code |
Full Laravel project via composer create-project |
| JavaScript/Node | node |
Full Node project via npm init |
| Python | python |
Full Python project with venv |
| DevOps/Docker | config |
Complete docker-compose setup |
| Architecture | diagram |
Complete Mermaid diagrams |
| Project management | document |
Complete templates + filled examples |
Verification Checklist
Before proceeding to Phase 5:
- Scaffold command executed successfully
- All article-specific code added
-
install_commandsucceeded (vendor/node_modules exists) -
run_commandstarts application without errors -
test_commandruns with 0 failures - README.md explains setup and usage
For Code Companion Projects (Laravel)
code/
├── README.md # Setup and run instructions
├── app/
│ └── ... # Minimal app code
├── database/
│ ├── migrations/
│ └── seeders/
├── tests/
│ └── Feature/ # Pest tests for main features
├── composer.json
└── .env.example # SQLite by default
Standards for Laravel companion projects:
- Use SQLite (no external DB needed)
- Use Pest for tests
- Include at least 2-3 tests for main features
- Add comments referencing article:
// See article section: "Rate Limiting Basics" - Keep dependencies minimal
- Include setup script if complex
For Document Companion Projects
code/
├── README.md # What the documents demonstrate
├── templates/
│ └── ... # Reusable templates
└── examples/
└── ... # Filled-in examples
Phase 5: Integrate Companion Project into Draft
- Replace
<!-- EXAMPLE: -->markers with actual code snippets - Add file references: "See
code/app/Models/Post.php" - Add run instructions in appropriate sections
- Save as
03_drafts/draft_v2.{lang}.md
Phase 6: Review (Comprehensive)
Review the article as a whole:
Explanation Flow
- Does the narrative flow logically?
- Are concepts introduced before being used?
- Does the companion project appear at the right time?
Companion Project Integration
- Do code snippets match the full companion project?
- Are file paths correct?
- Can readers follow along?
Voice Compliance
- Matches author's formality level?
- Uses signature phrases appropriately?
- Avoids forbidden phrases?
- Opinions expressed match author's positions?
- If voice_analysis present:
- Sentence length matches avg_length?
- Communication style traits reflected?
- Characteristic expressions used (not overused)?
Technical Accuracy
- Code snippets are correct?
- Companion project actually runs?
- Tests pass?
Completeness
- All outline points covered?
- Sources properly cited?
- Companion project fully demonstrates topic?
CHECKPOINT: Confirm article + companion project are ready
Phase 6b: Condense (Word Limit Enforcement) ⚠️
This phase is MANDATORY if article exceeds max_words from settings.
Step 1: Check Word Count
# Count words in article (excluding frontmatter and code blocks)
# Frontmatter: lines between first --- and second ---
# Code blocks: lines between ``` markers
# Simple word count of prose content only:
sed '/^---$/,/^---$/d; /^```/,/^```$/d' draft_v2.{lang}.md | wc -w
Step 2: Load Word Limit from Settings
# Read max_words from settings.json
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings
# Or read JSON directly:
# jq '.article_limits.max_words' .article_writer/settings.json
Step 3: Condense if Over Limit
If word count > max_words:
Identify Condensation Targets (in order of priority):
- Redundant explanations of the same concept
- Overly verbose transitions
- Repeated caveats or disclaimers
- Extended tangents not central to the topic
- Excessive examples when fewer would suffice
Condensation Techniques (preserve quality):
- Combine related paragraphs
- Replace lengthy explanations with concise summaries
- Convert verbose lists to compact bullet points
- Remove filler words and phrases
- Tighten sentence structure
CRITICAL: Preserve Author Voice
- Keep signature phrases and expressions
- Maintain the same tone (formality level)
- Preserve the author's opinion style
- Keep characteristic sentence structures
- Retain enthusiasm/energy level from voice profile
DO NOT Remove:
- Code examples or snippets (these don't count toward word limit)
- Critical technical explanations
- Prerequisites or setup instructions
- Safety warnings or important notes
- References to the companion project
Step 4: Verify Condensed Version
After condensing:
- Word count is now ≤ max_words
- Article still reads naturally (not choppy)
- All key points are preserved
- Technical accuracy maintained
- Author voice is consistent throughout
- Flow and narrative structure intact
Step 5: Save Condensed Draft
# Save as draft_v3 (condensed version)
# 03_drafts/draft_v3.{lang}.md
If unable to condense below max_words without quality loss:
- Document the reason in the task
- Note the final word count achieved
- Flag for human review
CHECKPOINT: Article is within word limit while maintaining quality
Phase 7: Translate
- Create versions for other languages
- Keep code snippets unchanged
- Translate comments in code if needed
Phase 8: Finalize
- Write final article with frontmatter
- Update article_tasks.json with:
- output_files
- sources_used
- companion_project info
- Verify companion project README is complete
When to Skip Companion Projects
Only skip if a companion project makes absolutely no sense:
- Pure opinion pieces with no actionable content
- News/announcement summaries
- Historical retrospectives
- Philosophical discussions
If skipping, document in task:
{
"companion_project": {
"skipped": true,
"skip_reason": "Opinion piece with no actionable code or templates"
}
}
Companion Project README Template
# Companion Project: [Topic]
Demonstrates [what this companion project shows] from the article "[Article Title]".
## Requirements
- PHP 8.2+
- Composer
- (any other requirements)
## Setup
\`\`\`bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
\`\`\`
## Run Tests
\`\`\`bash
php artisan test
\`\`\`
## Key Files
| File | Description |
|------|-------------|
| `app/Models/Post.php` | Demonstrates eager loading |
| `tests/Feature/QueryTest.php` | Tests N+1 detection |
## Article Reference
This companion project accompanies the article:
- **Title**: [Article Title]
- **Section**: See "Implementing Eager Loading" section
Companion Project Comments Style
<?php
// ===========================================
// ARTICLE: Rate Limiting in Laravel 11
// SECTION: Creating Custom Rate Limiters
// ===========================================
namespace App\Providers;
use Illuminate\Support\Facades\RateLimiter;
class AppServiceProvider extends ServiceProvider
{
public function boot(): void
{
// Custom rate limiter for API endpoints
// See article section: "Dynamic Rate Limits"
RateLimiter::for('api', function (Request $request) {
return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});
}
}
Recording Companion Project in Task
{
"companion_project": {
"type": "code",
"path": "code/",
"description": "Minimal Laravel app demonstrating rate limiting",
"technologies": ["Laravel 11", "SQLite", "Pest 3"],
"has_tests": true,
"files": [
"app/Providers/AppServiceProvider.php",
"routes/api.php",
"tests/Feature/RateLimitTest.php"
],
"run_instructions": "composer install && php artisan test"
}
}