refresh-readme-from-reference

Files (1)

• SKILL.md

SKILL.md (first lines)

# Refresh a README in the aesthetic of a reference repo

Adopt another project's README visual structure — centered hero, badges, hero image/code, bullet list of selling points, paseo-style section order — while keeping all of the project's actual content (features, install steps, examples, schema). This is an **aesthetic refresh**, not a content rewrite: the project's claims and code must survive verbatim; only the *shape* changes.

This skill encodes the approach used to bring `Okohedeki/airlock-config`'s README in line with the `getpaseo/paseo` aesthetic.

## When this skill fires

Trigger patterns:
- "Make my README look like [github.com/foo/bar](url)"
- "I want this to look like getpaseo/paseo"
- "Refresh the README"
- "The README is content-rich but visually flat"
- "Add badges / a hero / make it look more polished"
- Any time the user names a *reference repo* as the model.

## Workflow

### 1. Fetch the reference's RAW markdown (load-bearing)

Do **not** use WebFetch for this — it summarises and strips HTML, which is exactly the visual structure you need to study. Use `curl`:

```sh
curl -sL https://raw.githubusercontent.com/<owner>/<repo>/<branch>/README.md
```

Read the *entire* response. The aesthetic lives in:
- The opening HTML block (`<p align="center">`, `<h1 align="center">`, badge rows)
- The image/screenshot placement (logo, hero mockup, mobile screenshot)
- The tagline structure (centered, one line, after the badge row)
- The bullet list style (number of bullets, bold-prefix vs not, length of each)
- The section order and naming (Getting Started → CLI → Features → Dev → License is paseo; "About / Features / Install / Usage" is older OSS)
- The footer (star history image? badges? sponsors?)

Make a list of the **building blocks** you'll reuse.

### 2. Inventory the existing README's content

Open the project's current `README.md`. Identify:
- The project's tagline (one sentence on what it does).
- The 3–6 most important selling points / differentiators.
- Code examples that MUST be preserved (the demo, the schema snippet, the curl commands).
- Section headings the project currently uses — which map onto the new structure, which become redundant, which need to be added.

Do not invent claims. If the reference repo has a "Self-hosted" bullet and yours doesn't have anything analogous, drop the bullet — don't manufacture one.

### 3. Sketch the new structure (paseo-style template)

A paseo-style README skeleton:

```markdown
<p align="center">
  <img src="assets/logo.svg" width="64" height="64" alt="<Project> logo">
</p>

<h1 align="center"><Project Name></h1>

<p align="center">
  <a href="..."><img src="https://img.shields.io/github/stars/<owner>/<repo>?style=flat&logo=github" alt="stars"></a>
  <a href="..."><img src="https://img.shields.io/github/v/release/<owner>/<repo>?style=flat&logo=github" alt="release"></a>
  <a href="..."><img src="https://img.shields.io/npm/v/<package>?style=flat&logo=npm" alt="npm"></a>
  <a href="..."><img src="https://img.shields.io/badge/license-Apache--2.0-555" alt="license"></a>
</p>

<p align="center"><One-sentence tagline.></p>

<!-- Hero: either an image OR a syntax-highlighted code block. Prefer the
     code block if there's no real product screenshot yet. -->
```<lang>
# Concrete, minimal example of the artifact the project produces.
```

---

<One-paragraph reframing of the tagline with the "and here's why it matters" line.>

- **<Selling point 1>:** <one-sentence explanation>.
- **<Selling point 2>:** <one-sentence explanation>.
- **<Selling point 3>:** <one-sentence explanation>.
- **<Selling point 4>:** <one-sentence explanation>.
- **<Selling point 5>:** <one-sentence explanation>.

## Getting Started
<install + 30-second demo>

## CLI
<command surface, in a code block>

## How it works / Features
<conceptual model, 3–4 short paragraphs>

## <Domain-specific section: A2A / Integrations / Plugins / etc.>

## Development
<npm install / typecheck / test / build>

## License
<spdx-id>
```

### 4. Handle the hero visual

Prefer in this order:
1. **A real screenshot/logo** if the project has one — embed at the canonical `assets/` or `docs/` path.
2. **A syntax-highlighted code block** showing the artifact (a YAML config, an SDK call, a JSON response). This is *very* effective for tools that produce a configuration file or a CLI command — the artifact IS the product.
3. **A placeholder logo** + code block — a hand-rolled minimal SVG at `assets/logo.svg`, 64×64 viewbox, one color, single geometric form. Good enough to ship the layout today; replace later.

For the placeholder, a simple template:

```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="<Project> logo">
  <title><Project></title>
  <rect x="6" y="6" width="52" height="52" rx="10" ry="10" fill="<dark-color>"/>
  <!-- one or two simple paths/shapes evoking the project -->
</svg>
```

### 5. Write the new README wholesale

From Okohedeki/dotclaude, Apache-2.0.

More from Okohedeki/dotclaude