---
name: readme
description: "Create or refresh a repository README with a splash, project story, supported positioning, features, setup, and relevant guides or API reference. Use when writing a README, explaining why a project exists or why to adopt it, or aligning its documentation with repository conventions."
license: MIT
title: readme
canonical_url: https://skilld.dev/gh/harlan-zw/brundlefly/readme
last_updated: 2026-10-07T10:36:53.000Z
---

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [LICENSE.txt](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/LICENSE.txt), [references/blocks/claim-fidelity.md](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/references/blocks/claim-fidelity.md), [references/blocks/clarity.md](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/references/blocks/clarity.md), [references/blocks/verify-examples.md](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/references/blocks/verify-examples.md), [references/positioning.md](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/references/positioning.md).
>
> If the user asked to install this Skill, run `npx skilld install harlan-zw/brundlefly/readme`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/readme`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/harlan-zw/brundlefly/readme) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/readme`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/readme --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/readme --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# README

Help a reader decide whether the project fits, then complete its first useful task.
This skill works without a sibling skill or personal checkout.
If im-not-a-fly is available, use it for the final prose review.
It is optional; do not install it automatically.

## Inspect the project

Read the existing README, repository instructions, glossary, vision, contribution rules, and supplied copy rules.
Use the glossary's established product names and casing. Do not substitute synonyms for them.
Apply supplied wording bans within their stated scope. Preserve commands, identifiers, quotes, and required qualifications.
Existing prose shows vocabulary; it does not prove every sentence deserves reuse.
Inspect nearby READMEs when the user asks for collection conventions.
Local requirements and the user's requested structure take precedence over stylistic defaults.

Find approved splash assets, package metadata, supported tools, public entry points, examples, and documentation.
Research the adoption reason before drafting Why. Read [positioning guidance](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/references/positioning.md) for research and interview decisions.
Check the actual source and CLI help before describing behavior or choosing setup commands.
Distinguish the checkout from a published release. Do not claim registry availability from a package name alone.
Keep an evidence ledger outside the repository for uncertain claims and checks.
Ask only when missing information changes the reader's task materially.

## Build the reader's path

Use this order by default. Keep existing anchors when they remain useful.

| Section | Reader need |
| --- | --- |
| Splash | Approved banner or logo, project name, and a factual one-line description |
| Why | Why the project exists, what prompted it, and why that matters to the reader |
| Features | Supported capabilities with a useful benefit for each |
| Setup | Prerequisites, installation, and the smallest working example |
| Guides | Inline task guidance when dedicated guides do not cover it |
| API | Inline public reference when dedicated API docs do not cover it |

Splash describes the opening block. Do not add a literal Splash heading.
Name the Why heading after the project, such as "Why Brundlefly".
Treat Why as a chance to tell the project's human story. Follow the owner's requested emphasis.
Every story has a point of view. Establish whose perspective carries Why before drafting it.
If the author tells their own origin story, use their first-person voice: I, me, and my.
Use we only for a supported shared experience. Follow an explicitly requested narrator or perspective.
Do not replace the author's story with generic you or detached product narration.
Use supplied experience or documented origins to connect a concrete frustration with the decision to build the project.
When no origin is known, explain the reader's problem without inventing a founder story.
Competitive positioning can support Why; it does not have to be its opening or organizing structure.
Place the origin in its ecosystem. A personal story still needs to explain why this project joins existing options.
Name relevant alternatives and connect the author's supported choice to the reader's task.
Shared goals are legitimate. Do not invent failed trials, missing features, or superiority to justify building something.
Put capability lists in Features and usage details in Setup or Guides.
Keep story and technical detail in separate sections. Review their purposes separately.
If using im-not-a-fly, request storytelling for Why and clear technical explanation for the task and reference sections.
When working alone, keep the same boundary: connect supported origins in Why; state prerequisites and actions directly in Setup.
Never carry narrative suspense or character arcs into instructions. Never bury a required step in the story.
Keep approved adoption reasons and useful evidence links. Removing filler must not erase their information.
If the owner requests only the problem, omit implementation detail and feature inventories. Preserve other approved points unless excluded.
Reuse approved assets and text. If artwork is absent, use a plain title and description.
If an approved banner carries the project name, it can serve as the H1 image with meaningful alt text.
Use the owner's approved tagline exactly. A blockquote can place it below the banner.
Use requested badges from the provider's documented embed. Include alt text and the intended destination.
Do not invent badges, slogans, support channels, measurements, or compatibility claims.

Write each feature as `- <emoji> **<feature>:** <why the feature is useful>`.
Keep the benefit concrete and supported. Preserve exact product terms.
Lead with reader-visible capabilities and outcomes. A list of skills, modules, or exports is an inventory, not necessarily Features.
Keep useful inventory in a separate discovery or reference section.
Use one capability per bullet by default. Follow an explicitly required format.
If bullets distort the project, use a short prose overview or a compact comparison table, or omit Features.
Explain that choice briefly in the handoff. Do not invent abstract benefits or ask merely to change the presentation.

Give setup commands a working directory and explain their expected result.
Use the project's package manager and documented runtime.
Show one common path before alternatives. Identify optional tools where they appear.
For a skill collection, show how to load or copy a complete skill and give an example request.
Lead with installing the collection, then asking for a task in natural language.
Explain that the agent matches installed descriptions to the task. Keep explicit skill selection as an optional override.
Check the host's discovery behavior before promising automatic activation. Do not present standard discovery as a unique feature.
Check for an existing destination before copying. Avoid nesting or replacing an installed skill without the reader's choice.
Do not invent a runtime API for a Markdown-only collection.

Decide guides and API coverage separately. A docs directory alone proves neither exists.
If dedicated docs cover the topic, link directly to them instead of duplicating the material.
If coverage is partial, include only the missing guidance or reference.
If the project has no public API, omit the API section.
Keep concise discovery links, contribution rules, attribution, and licenses where they serve the reader.

## Review and verify

Apply [clarity](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/references/blocks/clarity.md) to the technical sections, preserving the story's deliberate opening.
Use [verify examples](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/references/blocks/verify-examples.md) for runnable setup and usage examples.
Apply [claim fidelity](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/references/blocks/claim-fidelity.md) against supplied wording and inspected evidence after edits.
For a new README, compare claims with the evidence ledger rather than assuming an earlier draft exists.
These blocks are bundled here. No sibling Skill installation is required.

Use plain words and direct sentences. Preserve required sections and the chosen feature presentation.
Keep product names, approved copy, commands, and links exact unless evidence supports a correction.
Preserve facts, qualifications, attribution, and voice. Cut repetition and unsupported claims.
Keep clear sentences unchanged. Remove unsupported claims rather than replacing them with invented evidence.
Keep review commentary outside README.md.
Apply the [Why review](https://skilld.dev/api/skills-raw/harlan-zw/brundlefly/readme/references/positioning.md#review-why) before delivery, even when the prose sounds natural.
Judge generic wording by the sentence's purpose. Do not create a blacklist of ordinary words.

Compare the result with inspected evidence for names, conditions, claims, commands, and links.
Run safe setup examples from an isolated starting state when possible.
Respect authorization for installation, publication, and other external changes.
Check relative links and assets from the README's directory, including changed heading anchors.
Use the project's documentation renderer when available and inspect the rendered page.
If a check fails, fix the affected material and repeat that check.
Report unavailable checks in the handoff. Never call an untested reader path verified.

Deliver the requested file and a short handoff with observed repairs and verification limits.
Writing the README does not authorize publishing it under the user's name.