← Files ShipFrameARCHIVED FILE
skills/generate-readme/SKILL.md
7.88 KB · Oct 4, 2026 · 12:31 UTC
---
name: generate-readme
description: Generate or refresh a team-ready README by scanning stack, purpose, commands, and project conventions.
allowed-tools: AskUserQuestion Glob Read Grep Write
effort: medium
---
# generate-readme
Generate a `README.md` file following the ShipFrame team-ready standard. Scan the project to auto-detect as much as possible, then ask only what cannot be inferred.
---
## Step 1 — Gather project context
Scan the project root to detect the tech stack and structure. Use Glob and Read tools — do not guess.
**Detect:**
- **Language & runtime:** `package.json`, `composer.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pubspec.yaml`
- **Framework:** check dependencies in `package.json` for `next`, `react`, `vue`, `nuxt`, `express`, `fastify`, `laravel` (via `composer.json`), etc.
- **Database:** look for `prisma`, `drizzle-orm`, `typeorm`, `mongoose`, `pg`, `mysql2`, `sqlite3`, `@supabase`, `pgsql` in dependency files or config files
- **Package manager:** `pnpm-lock.yaml` → pnpm, `yarn.lock` → Yarn, `bun.lockb` → Bun, `package-lock.json` → npm
- **Build tools:** `vite.config.*`, `webpack.config.*`, `turbo.json`
- **Container/infra:** `Dockerfile`, `docker-compose.*`
- **CI/CD:** `.github/workflows/`
- **Dev commands:** read `package.json` scripts section, `Makefile`, or `composer.json` scripts
Read these files if they exist:
- `package.json`
- `composer.json`
- `README.md` (first 50 lines — to avoid overwriting intentional content)
- `.env.example` (keys only, never values)
---
## Step 2 — Ask the user for missing information
After scanning, ask only for information that could not be inferred from the codebase. Use `AskUserQuestion` with a single call covering all needed fields at once (1–4 questions max).
Always ask:
1. **Project name + repository clone URL** — if not clear from `package.json`, `composer.json`, or folder name
2. **Short project description** — one sentence explaining what the project does
3. **Credentials/config location** — where developers get environment variable values (e.g. Passbolt, 1Password, a shared drive link — never hardcode actual values)
4. **Contact info** — Project Manager name + email, Tech Lead name + email
Only ask for stack details if they genuinely could not be detected.
---
## Step 3 — Generate README.md
If `README.md` already exists and contains non-placeholder content, ask for confirmation before overwriting and preserve any clearly intentional hand-written sections.
Write `README.md` at the project root using the template below. Fill every section with real detected values. Use placeholder text only where data is unavailable and mark it with `<!-- TODO: fill in -->`.
Rules:
- Use the project's actual logo if `public/` or `assets/` contains an `.svg` or image with "logo" in the name; otherwise omit the `<img>` tag.
- List only the stack components actually detected — do not invent extras.
- Commands table: list only commands that exist in `package.json` scripts, `Makefile`, or `composer.json` scripts. Do not fabricate commands.
- Keep the tone professional but friendly, matching the example format.
- Never include sensitive values (passwords, API keys, tokens).
---
### README.md template
````markdown
<div align="center">
<img src="./public/<logo-file>" alt="icon">
<h3>
<project-name> 🚀 ShipFrame
</h3>
<a href="#-stack">
Stack
</a>
<span> ✦ </span>
<a href="#-getting-started">
Getting Started
</a>
<span> ✦ </span>
<a href="#-useful-commands">
Commands
</a>
<span> ✦ </span>
<a href="#-contribution">
How to contribute
</a>
<span> ✦ </span>
<a href="#-deployment">
How to do a deployment
</a>
<span> ✦ </span>
<a href="#-contact">
Contact
</a>
</div>
## 🛠️ Stack
To start working with <project-name> you will need to have some tools previously installed.
#### Prerequisites
- SO: OSX, Linux, Windows with WSL2
<!-- List only prerequisites that are genuinely required based on detected stack -->
- [**<Runtime & version>**](<official-url>)
- [**<Package manager>**](<official-url>)
- [**<Database>**](<official-url>)
#### Technical Information
<!-- List only what was detected -->
- [**<Framework & version>**](<official-url>)
- [**<Key library>**](<official-url>)
- [**<Container/infra tool>**](<official-url>)
## 🧑💻 Getting Started
1. **Clone** this repository.
```bash
git clone git@github.com:<org>/<repo>.git
```
2. Copy the `.env.example` file to `.env` and set all the necessary environment values.
```bash
cp .env.example .env
```
You can find the credentials in [<credentials-location>](<credentials-url-if-provided>). If you don't have access, please [contact](#-contact) your Project Manager or Tech Lead.
3. Install the dependencies.
<!-- Adapt to the detected package manager and language -->
```bash
<install command>
```
4. <!-- Add any additional required setup steps detected from README or scripts, e.g. key generation, migrations, seed -->
5. Run the development server.
```bash
<dev command>
```
## 🖥️ Useful Commands
| | Command | Action |
| :-- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
<!-- List only commands that exist in scripts -->
| ⚙️ | `<command>` | <what it does> |
> Commands used in this project are from <tooling>. <!-- Add a relevant cheatsheet link if applicable -->
## 🧠 Contribution
There are some "rules" to follow if you want to contribute to this project.
#### Branch Naming
To start contributing you will need to create a branch from your development branch following these steps:
1. Identify the ticket of your task in [ClickUp](https://app.clickup.com/31625254/home).
2. Once you identify the ticket, note its ID (found in the URL or in the left corner of the modal).
3. Our branch naming convention is based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) followed by the ClickUp task ID:
- **fix**: patches a bug (correlates with PATCH in Semantic Versioning).
- **feat**: introduces a new feature (correlates with MINOR in Semantic Versioning).
- **hotfix**: patches a bug live in PRODUCTION (promote to production ASAP).
Branch name format: `feat/CU-[ClickUp task ID]-[optional-detail]`
Examples: `feat/CU-86aydqtf5-Login` or `feat/CU-86aydqtf6`
#### Descriptive Commits
Make commits referencing the ClickUp ID: `feat/CU-[ID] Task title`
#### Create a PR
Include the following in your Pull Request description:
- **Explanation of Unrelated Changes:** If there are changes unrelated to the ticket, explain why they were included.
- **Screenshots:** Attach screenshots of screens that changed to facilitate visual review.
- **Other tickets affected:** If the changes affect other tickets, list them and leave a comment on those tickets with the PR URL.
> **IMPORTANT:** Never add sensitive information to the repository (passwords, API keys, etc.)
> **REMEMBER:** Keep PRs as small and focused as possible.
## 🚀 Deployment
<!-- Describe the CI/CD pipeline detected or ask the user to fill this in -->
We use CI/CD for deployments. To deploy, merge an approved PR to the correct branch:
- **`<environment>`** environment → merge PR to `<branch>` branch.
## 📞 Contact
For support or questions, please contact:
Project Manager: <a href="mailto:<pm-email>"><pm-name></a>
Tech Lead: <a href="mailto:<tl-email>"><tl-name></a>
````
---
## Step 4 — Write the file and confirm
Write the completed `README.md` to the project root.
Then report:
- What was auto-detected vs. what the user provided
- Any sections left with `<!-- TODO: fill in -->` placeholders and why
- Reminder not to commit sensitive values
Do not continue or suggest further steps after reporting.
SHA-256: bd63b25433c13878d597011536738d13b6e8ddcebb0392fe300059227cdcad80