diataxis:readme
Use when the user asks for a README, a GitHub front page, an open source library landing page, or a documentation homepage for a repository. Writes the README as a front door that orients readers and routes them to the right deeper docs — not a tutorial, not a full reference manual, not a conceptual essay. Use a different diataxis skill when the request is specifically for a step-by-step lesson, a task guide, API details, or conceptual background.
What this skill does
# README writer ## Purpose Write or rewrite a repository README as the front door to a project. This skill uses Diátaxis principles, but does not force the README to become a tutorial, how-to, reference, or explanation page. Instead, it makes the README a landing page that orients the reader and routes them to the right documentation. ## When to use Use this skill when the user asks for: - a README - a better GitHub front page - open source library documentation entry pages - a docs homepage for a small repository Use a different skill when the request is specifically for: - a step-by-step lesson, use `diataxis:tutorial` - a task guide, use `diataxis:how-to` - API or CLI details, use `diataxis:reference` - conceptual background, use `diataxis:explanation` ## Objective Help the reader answer, quickly: - What is this? - Why would I use it? - Is it for me? - How do I get started safely? - Where do I go next? ## Required sections Prefer this structure, adapting as needed: 1. Project name and one-sentence value proposition 2. Short overview 3. Who it is for 4. Key capabilities or use cases 5. Installation 6. Quickstart 7. Minimal example 8. Documentation map 9. Status, compatibility, or stability notes 10. Contributing / support / license ## README rules - Keep the quickstart short and confidence-building. - Provide one happy-path example that works. - Do not turn the README into an exhaustive reference manual. - Do not turn the README into a conceptual essay. - Do not bury the user in every configuration option. - Link out to dedicated tutorial, how-to, reference, and explanation pages when depth is needed. ## Writing guidance ### Opening The first screenful should tell the reader: - what the project does - the main benefit - the rough audience - the fastest path to first success ### Quickstart The quickstart can borrow the shape of a tutorial, but it must stay compact. Good quickstart characteristics: - minimal prerequisites - a narrow happy path - visible result early - no long digressions - no branching unless essential If the quickstart becomes long, split it into a real tutorial and link to it. ### Documentation map Always orient readers with a short map such as: - Tutorial: start here if you are new - How-to guides: solve specific tasks - Reference: exact API and configuration details - Explanation: concepts and design decisions ### Tone and style - practical and concrete - low-friction - honest about limitations - structured for scanning - not bloated ## Inputs to gather - project name - elevator pitch - audience - install methods - minimal working example - supported platforms / versions - links or paths to deeper docs - maturity / stability notes ## Output contract Produce a README that: - is readable on GitHub - makes the project legible in under a minute - gives a trustworthy quickstart - points readers to the correct deeper docs - avoids mixing all doc types into one page ## Final self-check Before returning, verify: - the value proposition is clear in the first lines - the quickstart is actually runnable - the example produces a visible result - reference details are linked, not dumped - conceptual discussion is linked, not over-expanded - the next step after the README is obvious
Related in Ads & Marketing
ads
IncludedMulti-platform paid advertising audit and optimization skill. Analyzes Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, and Apple Ads. 250+ checks with scoring, parallel agents, industry templates, and AI creative generation.
banana
IncludedAI image generation Creative Director powered by Google Gemini Nano Banana models. Use this skill for ANY request involving image creation, editing, visual asset production, or creative direction. Triggers on: generate an image, create a photo, edit this picture, design a logo, make a banner, visual for my anything, and all /banana commands. Handles text-to-image, image editing, multi-turn creative sessions, batch workflows, and brand presets.
rpg-migration-analyzer
IncludedAnalyzes legacy RPG (Report Program Generator) programs from AS/400 and IBM i systems for migration to modern Java applications. Extracts business logic from RPG III/IV/ILE source code, identifies data structures (D-specs), file operations (F-specs), program dependencies (CALLB/CALLP), and converts RPG constructs to Java equivalents. Generates migration reports, complexity estimates, and Java implementation strategies with POJO classes, JPA entities, and service methods. Use when modernizing AS/400 or IBM i legacy systems, analyzing RPG source files (.rpg, .rpgle, .RPGLE), converting RPG to Java, mapping data specifications to Java classes, planning legacy system migration, or when user mentions RPG analysis, Report Program Generator, RPG III/IV/ILE, AS/400 modernization, IBM i migration, packed decimal conversion, or mainframe application rewrite.
brand-library-architect
IncludedBuild a complete brand library for a product — visual asset render pipeline, brand documentation set (BRAND, COPY, MANIFESTO, BIOS, FAQ, GLOSSARY, TONE, PRICING), open-source convention files (README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT), and a self-contained press kit. This skill should be used when the user asks to "build a brand library / brand kit / press kit / brand assets" for a product, "set up a brand library workflow," "create a positioning manifesto plus visual identity," or any combination of brand documentation + visual asset pipeline. Apply phase-by-phase or run end-to-end. Templates are product-agnostic and use {{TOKEN}} placeholders the skill prompts the user to fill.
writing-tech-post
IncludedAuthors engineering blog posts end-to-end: launch deep-dives, incident postmortems, architecture migrations, performance case studies, tutorials, AI/agent system writeups, security disclosures, and research-to-product translations. Picks the correct archetype, plans the abstraction ladder, enforces an evidence cadence (diagrams, benchmarks, profiles, traces, code, ablations), tunes voice against publisher house styles (Datadog, Vercel, GitHub, AWS, Meta, Cloudflare, Jane Street), and runs a pre-publish gate for narrative momentum and disclosure ethics. Use when drafting a new engineering post, restructuring a draft that feels flat, deciding which evidence form belongs where, validating that depth and product context are balanced, or preparing a postmortem, migration, or performance narrative for external publication. Do not use for API reference documentation, README authoring, marketing copy, release notes, generic SEO content, ghost-written executive thought leadership, or non-engineering long-form essays.
blog-google
IncludedGoogle API integration for blog performance: PageSpeed Insights, CrUX Core Web Vitals with 25-week history, Search Console performance, URL Inspection, Indexing API, GA4 organic traffic, NLP entity analysis for E-E-A-T, YouTube video search for embedding, and Google Ads Keyword Planner. Progressive feature availability based on credential tier (API key, OAuth/service account, GA4, Ads). Shares config with claude-seo at ~/.config/claude-seo/google-api.json. Use when user says "google data", "page speed", "core web vitals", "search console", "indexation", "GA4", "keyword research", "nlp entities", "blog performance", "youtube search", "google api setup".