Skip to content
Skills Library
Programming · Writing

readme-docs

/readme-docs

Create or refresh a distinctive, evidence-backed `README.md` landing page for newcomers. Use when a README is missing, thin, generic, stale, or hard to navigate. Covers purpose, audience, first success, proof, examples, and documentation routes.

Licence
MIT
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
2
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Create or refresh a distinctive, evidence-backed `README.md` landing page for newcomers. Use when a README is missing, thin, generic, stale, or hard to navigate. Covers purpose, audience, first success, proof, examples, and documentation routes.

Original author description

Create or refresh a distinctive, evidence-backed `README.md` landing page for newcomers. Use when a README is missing, thin, generic, stale, or hard to navigate. Covers purpose, audience, first success, proof, examples, and documentation routes.

How it works

  1. Purpose
  2. Route supporting resources
  3. Landing-page contract
  4. Workflow
  5. Managed visuals
  6. Content boundary
  7. Completion
Original SKILL.md headings · 84 lines, 571 words
SKILL.md preview
---
name: readme-docs
description: "Create or refresh a distinctive, evidence-backed `README.md` landing page for newcomers. Use when a README is missing, thin, generic, stale, or hard to navigate. Covers purpose, audience, first success, proof, examples, and documentation routes."
---

# README landing page

## Purpose

Make `README.md` a useful front door: establish identity, audience, value, proof, first success, and
deeper documentation routes in the order a newcomer needs them. This skill owns README content;
specialized documentation skills own their files under `docs/`.

## Route supporting resources

- Start from [`assets/README_TEMPLATE.md`](assets/README_TEMPLATE.md) for a missing, thin, or
  structurally failed README.
- Read [`references/readme_best_practices.md`](references/readme_best_practices.md) when project type
  or section choice is unclear.
- Read [`references/landing_page_ideas.md`](references/landing_page_ideas.md) when the page needs a
  stronger signature promise or proof treatment.
- Apply [`references/review_checklist.md`](references/review_checklist.md) for broad refreshes and
  final landing-page audits.
- Apply [`references/scoring_rubric.md`](references/scoring_rubric.md) for explicit scoring,
  before/after comparison, or a broad refresh.

Resolve every template placeholder before delivery.

## Landing-page contract

- Use one H1 for the project name, followed by a plain-prose opening paragraph of at most 250
  characters. State purpose, audience or use case, main benefit, and a distinguishing detail when
  space allows. Put links, badges, code, URLs, and setup after that paragraph.
- Establish purpose and the strongest available proof before `Quick start`.
- Give a verified install/run path that reaches a meaningful result, plus one representative example
  and expected behavior when useful.
- Summarize three to six concrete capabilities or outcomes and curate three to eight primary
  documentation routes before grouping a larger docset.
- Include supported status, limitations, prerequisites, platforms, help, license, citation, or
  contributor routes only when repository evidence makes them useful.
- Preserve current explanations, examples, visuals, warnings, and credits that remain accurate.

## Workflow

1. Read operative repository rules, the current README, core docs, manifests, executable front
   doors, examples, tests, screenshots, release/deployment evidence, and license files.
2. Derive the project name, audience, primary value, project type, first-success path, strongest
   proof, and adoption constraints from current evidence.
3. For a broad refresh, score the current page and identify the two highest-value improvements.
4. Design the newcomer journey: identity and value, proof, first success, representative use,
   deeper routes, then secondary adoption context.
5. Write a project-specific opening and choose a live demo, screenshot, output sample, compact
   transformation, architecture visual, or worked scenario that proves the signature promise.
6. Verify every command that is safe and practical. Match paths, claims, live links, deployment
   URLs, status, and license wording to repository evidence.
7. Apply the routed review checklist, repository Markdown/ASCII checks, and
   `tests/test_readme_first_paragraph.py` when present. Re-score broad refreshes.

## Managed visuals

When the project has a visual interface/output or the user requests screenshots, include this exact
empty block for `screenshot-docs`:

```markdown
<!-- screenshots:begin (managed by screenshot-docs) -->
<!-- screenshots:end -->
```

This skill owns surrounding prose and the sentinel lines. `screenshot-docs` owns capture,
`docs/screenshots/`, alt text, embed syntax, and the content between sentinels.

For a browser app, place a confirmed live link near the opening. Use a configured URL; derive a
Pages URL only when deployment evidence confirms it.

## Content boundary

Keep the value proposition, primary onboarding path, representative example, and navigation context
in README. Route exhaustive APIs, configuration, architecture, troubleshooting, and maintainer
process to their owning docs. Turn substantive missing docs and remaining landing-page opportunities
into bounded follow-ups with an owner, target, evidence, success criteria, and verification.

## Completion

Return the updated README, commands and links checked, unresolved claim status, and routed doc gaps.
For broad refreshes, include before/after scoring and the strongest gain. Finish only when the quick
start reaches a real result, the page carries project-specific proof when applicable, all placeholders
are resolved, and current valuable content remains discoverable.
Files in this package (7)
  • SKILL.md 5 KB
  • agents/openai.yaml 1 KB
  • assets/README_TEMPLATE.md 3 KB
  • references/landing_page_ideas.md 4 KB
  • references/readme_best_practices.md 10 KB
  • references/review_checklist.md 4 KB
  • references/scoring_rubric.md 6 KB

Versions

RepositoryScoreLicence
This page · vosslab/vosslab-skills100MIT
rimega92/Engineering-Skills100MIT

Database snapshot: 13.11.2026 · package version 99518c2e9992 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95readme
    When the user wants to create or update a README.md file for a project. Also use when the user says 'write readme,' 'create readme,' 'document this project,' 'project documentation,' or asks for he...
  • 95aif-docs
    Generate and maintain project documentation. Creates a lean README as a landing page with detailed docs pages split by topic in the configured docs directory. Use when user says "create docs", "write documentation", "update docs", "generate readme", or "document project".
  • 100rc-readme
    Writes or refreshes a project README from evidence in the codebase. Use to generate or update one. Do not use for API specs or changelogs.
  • 96create-readme
    Use when generating or updating a project README.md or CHANGELOG.md.
  • 100readme-generator-free
    Generate polished README files from project code. Use when the user says "generate readme", "create README", "write project documentation", "make a readme", or asks for README generation, project documentation, installation docs, usage docs, API docs, badges, or repository…
  • 100arch-docs
    Create or refresh `docs/CODE_ARCHITECTURE.md` and `docs/FILE_STRUCTURE.md` from repository evidence. Use for architecture or file-layout documentation. Use other documentation skills for README, installation, usage, or repo-wide updates.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.