Article Post Writing Skill

What This Skill Covers

Use this skill for content articles, not generic blog posts. It is designed for educational and practical long-form content for users of the Tarsk product, not for developers working on the Tarsk codebase. Keep the writing focused on what a reader can do in the app, what they can learn from the product experience, and how the feature helps them.

Do not include implementation details from the Tarsk codebase unless the user explicitly asks for developer-facing material. Avoid internal architecture, framework choices, platform runtime details, repository structure, file paths, component names, internal tool wiring, or build and packaging details such as Electrobun. When a feature has platform constraints, explain them in product terms that help the reader use the feature successfully.

It is designed for educational and practical long-form content, including:

• Explainers
• Tutorials
• Product how-tos
• Case studies
• Opinion pieces

Do not force one universal article structure onto every assignment. First determine the article type, then use the matching template.

Determine the Article Type First (Required)

Before researching or drafting, determine which article type best fits the request.

If the type is clear from the prompt

Proceed with that type.

If the type is ambiguous

Ask the user to choose one of:

• Explainer
• Tutorial
• Product how-to
• Case study
• Opinion

If needed, briefly clarify the difference:

• Explainer: teaches a concept or system
• Tutorial: walks the reader through doing something step by step
• Product how-to: shows how to accomplish something in a product
• Case study: shows what happened, what was done, and what was learned
• Opinion: argues a point of view and defends it

Gather Inputs Before Research (Required)

If the prompt does not already include enough source material, ask the user for relevant inputs before research.

Useful inputs include:

• Relevant links or documentation
• Product context
• Internal notes or briefs
• Existing research
• Examples of competing or similar content
• Target keyword or topic phrase
• Intended audience, if the default may be wrong

Treat any user-provided URLs, docs, or example articles as background material only.

• Do not quote them directly
• Do not cite them by name or URL in the article body
• Do not write phrases like "according to" or "as explained by"
• Do not include a references, sources, or further reading section unless the user explicitly asks for one
• Synthesize the information into original copy grounded in the product and codebase, not in the wording of the source material

Do not assume hidden context. Ask for supporting material when it would improve accuracy.

Research First (Required)

Before writing any article, you MUST delegate research.

1. Use the task tool with subagent_type: "researcher"
2. In the description, specify both the topic and where to save

task(
    subagent_type="researcher",
    description="Research [TOPIC]. Save findings to research/[slug].md"
)

Example:

task(
    subagent_type="researcher",
    description="Research how teams adopt AI coding agents in 2026. Save findings to research/ai-coding-agents-adoption.md"
)

1. After research completes, read the findings file before writing
2. Use the research to sharpen claims, examples, terminology, and practical guidance

Do not draft first and research later.

Human Voice Pass (Required)

After drafting and before saving any article, you MUST apply the stop-slop skill.

1. Read .agents/skills/stop-slop/SKILL.md
2. Read references/phrases.md, references/structures.md, and references/examples.md
3. Edit the full draft against the Core Rules and Quick Checks
4. Score Directness, Rhythm, Trust, Authenticity, and Density from 1-10 each
5. Revise if the total is below 35/50
6. Save the edited article, then generate the hero image

Treat stop-slop as part of article creation, not an optional cleanup step. Apply these rules during drafting and editing:

• Cut filler phrases and throat-clearing.
• Avoid formulaic structures, especially binary contrast patterns like "this, not that," "not X, but Y," and similar compare-and-correct phrasing.
• Rewrite negative listings into direct statements.
• Use active voice with a clear human actor.
• Keep inanimate objects from performing human actions.
• Prefer specific nouns and verbs over vague summary language.
• Put the reader in the room. Use concrete scenes, actions, UI states, commands, and outcomes.
• Vary sentence length and paragraph endings.
• Remove em dashes.
• Rewrite any sentence that sounds like a pull-quote, slogan, or tidy contrast.

Do not skip this pass. An article is not complete until it passes stop-slop.

Content Standards (Required)

Every article must stand alone.

Audience boundary rules:

• Write for users of the product, not for developers inspecting the implementation

• Explain features through product behavior, UI flows, setup steps, outcomes, limitations, and user decisions

• Do not expose internal Tarsk implementation details unless the user explicitly requests a developer-facing article

• Avoid references to internal frameworks, runtimes, repo organization, component names, package boundaries, or other codebase internals such as Electrobun

• If a desktop-only or platform-specific limitation matters, explain it plainly as a product constraint and what the reader should do as a result

• Do not punt essential detail to another post on the site

• Do not link to /blog/... or /articles/...

• Do not write "see our separate post" or "we covered this elsewhere"

• If an important explanation belongs in the current article, include it

• If it does not fit, leave it out

Source handling rules:

• User-provided links are for research and factual grounding, not attribution in the final article
• Do not quote source websites, docs, or articles unless the user explicitly asks for quotations
• Do not mention source site names or URLs in the article body
• Do not include inline citations, footnotes, or a sources section unless explicitly requested
• Rewrite everything in an original voice that reflects the product, code, and user task rather than the phrasing of outside material

Also:

• Do not mention daily changelogs for model updates
• Do not write about automated model-list sync, changelog generation, or internal catalog maintenance
• Focus on what the reader can understand or do

Audience and Tone Defaults

Unless the user specifies otherwise:

• Default audience: beginners
• Default tone: authoritative and polished
• Default depth: balanced practical depth with clear explanations and concrete examples

Do not mechanically define every term. Do not flatten the writing into oversimplified beginner prose. Write clearly, but with confidence.

Output Structure (Required)

Every article MUST have both a post and a hero image.

articles/
└── <slug>/
    ├── post.md
    └── hero.png

Example output locations:

• Article content: website/src/components/articles/<slug>/post.md
• Hero image: website/public/images/articles/<slug>/hero.png

You MUST complete both steps:

1. Write the article to website/src/components/articles/<slug>/post.md
2. Generate a hero image using generate_image and save to website/public/images/articles/<slug>/hero.png

An article is not complete without its hero image.

Workflow (Required)

Follow this workflow in order:

1. Determine the article type
2. Gather missing inputs and source links if needed
3. Delegate research and read the findings
4. Draft using the matching article-type template
5. Add practical material where it materially helps:
   • UI walkthroughs
   • screenshots
   • diagrams
   • examples
   • commands or code snippets only when they are part of the user's product workflow and not Tarsk implementation details
6. Run the stop-slop pass
7. Save the article
8. Generate the hero image

Article-Type Templates (Required)

Choose the structure that matches the article type.

1. Explainer

Use for concept education, overviews, comparisons, or system understanding.

Required structure:

1. Hook
2. Why this matters
3. Core concept or concepts
4. How it works
5. Concrete examples
6. Common mistakes or misconceptions
7. Summary and CTA

Guidance:

• Prioritize conceptual clarity
• Use examples to make abstractions concrete
• Anticipate likely reader confusion

2. Tutorial

Use when the reader should complete a task or build something step by step.

Required structure:

1. Hook
2. What the reader will build, do, or learn
3. Prerequisites
4. Step-by-step instructions
5. Why each step matters
6. Validation or expected outcome
7. Troubleshooting
8. Summary and CTA

Guidance:

• Steps should be sequential and testable
• Include commands, code, screenshots, or expected outputs where useful
• Make success criteria explicit

3. Product How-To

Use when showing how to accomplish a task inside a product.

Required structure:

1. Hook
2. What problem this solves
3. Requirements or setup
4. Step-by-step product workflow
5. Optional advanced tips
6. Common pitfalls
7. Summary and CTA

Guidance:

• Focus on the user goal, not feature marketing
• Include UI flow details when they matter
• Mention settings, navigation, or expected states clearly
• Keep the explanation at the product layer unless the user explicitly asked for developer-facing implementation detail

4. Case Study

Use when documenting a real example, implementation, experiment, or outcome.

Required structure:

1. Hook
2. Context or background
3. Problem
4. Approach
5. Results or outcomes
6. Lessons learned
7. Summary and CTA

Guidance:

• Keep the narrative grounded in specifics
• Distinguish facts, interpretations, and lessons
• Use metrics or evidence when available

5. Opinion

Use when making a clear argument or point of view.

Required structure:

1. Hook
2. Thesis
3. Context
4. Main arguments
5. Counterarguments or limitations
6. Practical implications
7. Summary and CTA

Guidance:

• Be explicit about the claim
• Steelman opposing views before rebutting them
• End with useful implications, not just rhetoric

Shared Writing Rules

Across all article types:

• Open strongly within the first 2-3 sentences
• Use clear H2 and H3 structure
• Prefer concrete examples over abstract filler
• Include practical assets when they materially improve understanding
• Keep sections purposeful and non-redundant
• Write at the user and product level, not the codebase implementation level
• Avoid internal engineering detail unless the user explicitly asks for it
• Avoid generic transitions and empty emphasis
• Avoid binary contrast constructions such as "this, not that," "not X, but Y," "more than," and similar framing that sets up one idea only to swat it away
• State the intended idea directly instead of using contrast as a stylistic crutch
• End with a concise summary and a CTA appropriate to the topic and article type

Do not require or include a forced "3 key takeaways" section.

Cover Image Generation

After writing the article, generate a hero image using generate_image and save it to the required article image path.

Writing Effective Image Prompts

Structure the prompt with these elements:

1. Subject: what the image is actually about
2. Style: minimalist, isometric, flat design, 3D render, watercolor, editorial illustration, and so on
3. Composition: centered, layered, asymmetrical, wide negative space, and so on
4. Color palette: specific colors or mood
5. Lighting or atmosphere: soft diffused light, neon glow, dramatic shadow, warm daylight, and so on
6. Technical framing: landscape composition, room for title overlay, clean focal area

Example Prompts

For a technical explainer:

Editorial-style illustration of interconnected modular systems represented as clean geometric blocks exchanging glowing signals. Deep navy background with electric blue and soft violet accents. Minimal, modern, high-clarity composition with generous negative space for title overlay.

For a tutorial:

Clean flat illustration of a workspace in progress with screen panels, code fragments, checkmarks, and directional flow elements that suggest a step-by-step process. Bright but restrained palette, approachable style, centered composition, room for title text.

For a case study or opinion piece:

Conceptual editorial illustration showing a transition from complexity to clarity using layered shapes, subtle grids, and directional motion. Sophisticated muted palette with one strong accent color. Professional, reflective tone with room for headline overlay.

SEO Considerations

• Include the main keyword in the title and first paragraph
• Use the keyword naturally 3-5 times where appropriate
• Keep the title under 60 characters
• Write a meta description of 150-160 characters
• Match headings and section order to reader intent
• Favor clarity and search intent coverage over keyword stuffing

Quality Checklist

Before finishing:

• Article type identified and used intentionally
• Missing source material requested when needed
• Research completed and findings reviewed before drafting
• Post saved
• Hero image generated
• Hook earns attention in the first 2-3 sentences
• Structure matches the chosen article type
• Practical examples or assets included where useful
• Summary is concise and useful
• CTA matches the topic and article type
• No forced "3 key takeaways" section
• stop-slop pass completed
• stop-slop score 35/50 or higher across the five dimensions
• No binary contrast phrasing such as "this, not that" or "not X, but Y"
• No quoted or slogan-like pull-quote sentences that exist for style instead of clarity
• No links or references to other blog posts or articles
• No quoted or cited external source material unless explicitly requested
• No mentions of source site names or URLs in the article body unless explicitly requested
• No mentions of daily model changelogs or automated catalog sync
• No unnecessary Tarsk codebase implementation details such as framework, runtime, repo, or packaging internals
• Article is clearly useful to product users rather than developers inspecting internals