playbooks

home / skills / toilahuongg / shopify-agents-kit / readme

readme skill

/.claude/skills/readme

This skill updates a project's README.md by analyzing the codebase, extracting structure, and generating comprehensive documentation with clear sections.

npx playbooks add skill toilahuongg/shopify-agents-kit --skill readme

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.0 KB
---
name: readme
description: Update the project README.md with comprehensive documentation based on the current codebase state. Use when the README needs updating or is outdated.
disable-model-invocation: true
---

# Update README

Update the project README.md with comprehensive documentation.

1. **Analyze Project Structure and State**
   - List the files in the root directory to identify the project type (Node.js, Python, etc.).
   - Read key configuration files if they exist (e.g., `package.json`, `tsconfig.json`, `shopify.app.toml`, `fly.toml`, `requirements.txt`, `Gemfile`, `cargo.toml`).
   - List the contents of valid source directories (e.g., `app/`, `src/`, `lib/`, `components/`) to understand the architecture.

2. **Read Existing Documentation**
   - Read the current `README.md` to preserve any manual sections or specific instructions the user has added.
   - If available, read `.agent/brain/task.md` or `implementation_plan.md` to understand recent changes and current features (optional, do not fail if missing).

3. **Generate/Update README.md**
   - Rewrite `README.md` to include the following sections (adapt as necessary for the project type):
     - **Project Title & Description**: A clear summary of what the project does.
     - **Features**: A list of key features inferred from the codebase and installed packages/skills.
     - **Tech Stack**: Languages, frameworks, and key libraries used.
     - **Prerequisites**: Tools needed to run the project (Node, Python, Docker, etc.).
     - **Getting Started / Installation**: Step-by-step instructions to install dependencies and run the project (e.g., `npm install`, `npm run dev`).
     - **Project Structure**: A high-level overview of the main directories.
     - **Workflows & Skills**: Mention available workflows (like this one) or skills if relevant.
     - **License**: If a license file exists, mention it.

4. **Review and Verification**
   - Ensure the new `README.md` is formatted correctly in Markdown.
   - Check that all links (if any) are valid.

Overview

This skill updates a project's README.md with clear, up-to-date documentation based on the current codebase. It inspects project files and configuration to infer features, tech stack, installation steps, and structure, then generates a polished Markdown README. It preserves existing human-written sections when present.

How this skill works

The skill scans the repository root and reads common config files (package.json, requirements.txt, rust/Cargo files, toml configs) and source directories (app/, src/, components/, lib/). It reads any existing README and optional task notes to preserve manual instructions, then synthesizes a complete README with title, description, features, tech stack, prerequisites, installation, structure, workflows, and license notes. Finally, it validates Markdown formatting and checks for obvious broken links.

When to use it

  • The current README is missing or sparse and you need a ready-to-use documentation file.
  • The codebase changed significantly and the README is outdated.
  • You want a consistent README format across projects for onboarding or publishing.
  • You need README content that reflects installed dependencies and detected frameworks.
  • Before publishing the project or creating a release to ensure docs are accurate.

Best practices

  • Keep the README focused and actionable: quick start first, deeper details later.
  • Preserve any manual or sensitive instructions from the existing README; do not overwrite without review.
  • Run the skill after major dependency or architecture changes to keep docs aligned with code.
  • Manually review generated commands (scripts, ports, env vars) before sharing publicly.
  • Add project-specific examples or badges after generation to reflect CI, coverage, or deploy status.

Example use cases

  • Generate a complete README for a freshly scaffolded Node.js or Python app with detected packages and start scripts.
  • Update docs for a frontend app by listing directories like src/, components/, public/ and dev server commands.
  • Refresh README for a microservice with Docker and deploy config (Dockerfile, fly.toml) including prerequisites and run instructions.
  • Create a README that highlights available agent workflows or automation skills present in the repo.
  • Produce a license and contribution note when a LICENSE file is detected.

FAQ

Will this skill overwrite existing README content?

It updates the README while preserving existing manual sections when detected; review changes before committing.

Which files does it inspect to infer project details?

It reads common config and manifest files (package.json, requirements.txt, Cargo.toml, toml configs) and lists source dirs like src/, app/, components/ to infer stack and features.