Skip to content

Zeyad-101/Readme-writer-skill

readme-writer

Verified

Writes a production-quality README.md for any code repository, grounded entirely in the repo's real contents. Give it a repo link to clone, or paste/upload the repo's files, and it inventories manifests, CI config, build files, and code, works out what kind of project it actually is, and drafts a README using only the sections that project needs — no placeholder text, no invented badges or benchmarks, no boilerplate sections that don't apply. Works the same way regardless of language, stack, or project category. Use whenever asked to write, generate, or improve a README for a repo, or for a specific named project, in whatever wording that request takes.

FileKindSize
SKILL.mdskill md5.3 KB
assets/master-template.mdmarkdown21.8 KB
references/section-selection.mdmarkdown6.0 KB
references/writing-style.mdmarkdown2.8 KB

assets/master-template.md

View on GitHub
<a id="readme-top"></a>

<div align="center">

  <!-- Light/Dark Mode Responsive Logo -->
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
    <img alt="[PROJECT_NAME] Logo" src="docs/assets/logo-light.svg" width="120" height="120">
  </picture>

  <h1>[PROJECT_NAME]</h1>

  <p>
    <strong>A high-performance, resilient solution engineered for [core mission / problem statement].</strong>
  </p>

  <!-- Status & Metric Badges -->
  <p>
    <a href="https://github.com/[ORG]/[REPO]/actions/workflows/ci.yml">
      <img src="https://img.shields.io/github/actions/workflow/status/[ORG]/[REPO]/ci.yml?branch=main&style=flat-square&label=Build%20Status" alt="Build Status">
    </a>
    <a href="https://codecov.io/gh/[ORG]/[REPO]">
      <img src="https://img.shields.io/codecov/c/github/[ORG]/[REPO]?style=flat-square&label=Coverage" alt="Coverage">
    </a>
    <a href="https://github.com/[ORG]/[REPO]/releases/latest">
      <img src="https://img.shields.io/github/v/release/[ORG]/[REPO]?style=flat-square&label=Release" alt="Latest Release">
    </a>
    <a href="https://github.com/[ORG]/[REPO]/blob/main/LICENSE">
      <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=flat-square" alt="License">
    </a>
    <!-- Add a security-scan badge only when a real, configured workflow exists. -->
    <!-- Example: CodeQL, Snyk, Dependabot, or equivalent -->
  </p>

  <!-- Quick Navigation Links -->
  <p>
    <a href="https://[ORG].github.io/[REPO]">Documentation Hub</a> ·
    <a href="#quickstart--installation">Quickstart</a> ·
    <a href="https://github.com/[ORG]/[REPO]/issues/new?template=bug_report.md">Report Issue</a> ·
    <a href="https://github.com/[ORG]/[REPO]/issues/new?template=feature_request.md">Request Feature</a>
  </p>

</div>

> **Maintainer note:** Keep this README verifiable against the repository's manifests, source code, CI/CD configuration, deployment configuration, and documented operational procedures. Do not leave stale version numbers, commands, endpoints, performance claims, or configuration examples in place.

---

## Table of Contents

- [About The Project](#about-the-project)
  - [Key Capabilities](#key-capabilities)
- [Requirements & Prerequisites](#requirements--prerequisites)
  - [Hardware Boundary Profile](#hardware-boundary-profile)
  - [Host & OS Compatibility](#host--os-compatibility)
  - [Runtimes & Toolchain Constraints](#runtimes--toolchain-constraints)
  - [Compatibility](#compatibility)
  - [External Dependencies & Services](#external-dependencies--services)
- [Configuration Matrix](#configuration-matrix)
- [Quickstart & Installation](#quickstart--installation)
  - [Option A: Containerized Workspace (Recommended)](#option-a-containerized-workspace-recommended)
  - [Option B: Local Host Setup](#option-b-local-host-setup)
- [Usage Patterns](#usage-patterns)
  - [Minimal Reproducible Example](#minimal-reproducible-example)
  - [CLI Invocation](#cli-invocation)
- [API & Interface Documentation](#api--interface-documentation)
- [Architecture & Internals](#architecture--internals)
  - [Repository Topology](#repository-topology)
  - [Internal Execution Lifecycle](#internal-execution-lifecycle)
  - [Scaling Model](#scaling-model)
- [Verification & Testing](#verification--testing)
  - [Performance & Benchmark Methodology](#performance--benchmark-methodology)
- [Deployment](#deployment)
- [Health, Readiness & Metrics](#health-readiness--metrics)
- [Observability](#observability)
- [Database Migration Policy](#database-migration-policy)
- [Rollback & Recovery](#rollback--recovery)
- [Troubleshooting / FAQ](#troubleshooting--faq)
- [Governance & Contributing](#governance--contributing)
- [Security Protocol](#security-protocol)
- [Versioning & Changelog](#versioning--changelog)
- [Licensing](#licensing)

---

## About The Project

Provide a focused 2–3 paragraph overview explaining the project's purpose, background, and architectural motivation. Highlight the exact problem it solves and why alternative tools or conventional approaches were insufficient.

```
+-------------------------------------------------------------------------------+
| ARCHITECTURAL OVERVIEW                                                        |
+-------------------------------------------------------------------------------+
| Client Request --> [ API Gateway ] --> [ Ingestion Worker ] --> [ Datastore ] |
|                             |                      |                          |
|                       Auth Validation        Schema Check                     |
+-------------------------------------------------------------------------------+
```

### Key Capabilities

- **[Capability]**: [Operational or user-visible benefit.] 
- **[Performance/Latency Claim]**: [State a measurable claim only when backed by a reproducible benchmark and defined workload.]
- **[Resilience/Fallback]**: [Describe circuit breakers, retries, degradation, or recovery behavior where applicable.]

---

## Requirements & Prerequisites

> [!IMPORTANT]
> Verify all prerequisites before installing dependencies, running project tooling, or starting the application.

### Hardware Boundary Profile

| Resource Metric | Minimum Baseline | Recommended Production Target |
| :--- | :--- | :--- |
| **CPU Architecture** | `x86_64` or `ARM64` | `[Production architecture / feature requirements]` |
| **Compute Allocation** | `[Minimum cores]` | `[Recommended cores]` |
| **System Memory (RAM)** | `[Minimum RAM]` | `[Recommended RAM]` |
| **Persistent Storage** | `[Minimum available space]` | `[Recommended storage class / capacity]` |

### Host & OS Compatibility

- **Linux**: [Supported distributions and kernel versions.] 
- **macOS**: [Supported versions and architectures.]
- **Windows**: [Native support or WSL2 requirement, if applicable.]

### Runtimes & Toolchain Constraints

| Ecosystem | Required Version Constraint | Manifest Verification Field |
| :--- | :--- | :--- |
| **Node.js** | `>= 20.12.0` | `package.json` -> `"engines": { "node": ">=20.12.0" }` |
| **pnpm** | `>= 9.0.0` | `package.json` -> `"packageManager": "pnpm@9.x"` |
| **Python** | `3.10.x - 3.12.x` | `pyproject.toml` -> `requires-python = ">=3.10,<3.13"` |
| **Rust (MSRV)** | `1.80.0+` | `Cargo.toml` -> `rust-version = "1.80"` |
| **Go** | `1.22.0+` | `go.mod` -> `go 1.22` |

> [!WARNING]
> Keep the documented constraints exactly aligned with the project's manifests, lockfiles, toolchain files, and CI matrix. Do not duplicate conflicting version requirements in different sections.

### Compatibility

Document supported compatibility ranges that are important to operators and integrators.

| Component | Supported Versions | Notes |
| :--- | :--- | :--- |
| **[PROJECT_NAME]** | `[Version range]` | `[Release/support notes]` |
| **PostgreSQL** | `15.x+` | `[Features, extensions, or migration notes]` |
| **Redis** | `7.x+` | `[Persistence/feature assumptions]` |
| **Container Runtime** | `[Supported versions]` | `[Docker/Podman/containerd notes]` |

> Keep this table synchronized with CI, deployment manifests, and dependency constraints.

### External Dependencies & Services

Document every service required at startup or during normal operation, and explicitly distinguish hard dependencies from soft/degradable dependencies.

| Dependency | Version | Default Endpoint | Dependency Type | Failure Behavior |
| :--- | :--- | :--- | :--- | :--- |
| **Redis** | `7.0+` | `6379` | `[Hard / Soft]` | `[Hard-fail / degraded mode / retry]` |
| **PostgreSQL** | `15.0+` | `5432` | `Hard` | `[Startup failure / retry / queued writes]` |
| **Docker Engine** | `24.0.0+` | N/A | `[Dev/Test only]` | `Local development/test environment cannot be started` |

---

## Configuration Matrix

Application state and network binds are configured through environment variables or the project's supported configuration mechanism. Copy the provided sample manifest to begin local development:

```sh
cp .env.example .env
```

For production environments, inject secrets through a supported secrets-management mechanism such as **Vault, AWS SSM/Secrets Manager, GCP Secret Manager, Azure Key Vault, Kubernetes Secrets, or an equivalent platform service**. Do not require checked-in `.env` files for production operation.

| Variable Name | Type | Default Value | Required? | Secret? | Description / Operational Semantics |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `NODE_ENV` | `String` | `"development"` | No | No | Active runtime profile: `development`, `test`, `production`. |
| `PORT` | `Integer` | `8080` | No | No | Local network binding port. |
| `DATABASE_URL` | `URI` | `postgres://user:pass@localhost:5432/app_db` | Yes | Yes | Connection string for persistent relational store. Production values must come from a secret/config service. |
| `REDIS_CACHE_URL` | `URI` | `redis://127.0.0.1:6379` | `[Yes/No]` | `[Yes/No]` | Ephemeral caching and ring-buffer bus. Document whether Redis is required or gracefully degraded. |
| `MAX_WORKERS` | `Integer` | `4` | No | No | Worker threads allocated for data transformation tasks. |
| `LOG_LEVEL` | `String` | `"info"` | No | No | Output threshold: `fatal`, `error`, `warn`, `info`, `debug`. |

### Environment-Specific Configuration

Document the meaningful differences between **local**, **test**, **staging**, and **production** environments. Identify unsafe development defaults and any values that must be explicitly overridden in production.

> [!CAUTION]
> Never commit `.env` manifests, private certificates, production API tokens, database credentials, or other secrets into version control. Ensure `.env` is listed within `.gitignore` and use a managed secret/configuration mechanism for deployed environments.

---

## Quickstart & Installation

### Option A: Containerized Workspace (Recommended)

Avoid local toolchain mismatches by developing directly within an isolated, preconfigured container:

1. Launch the repository in VS Code or GitHub Codespaces:
   ```sh
   code .
   ```
2. Trigger the command palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and execute:
   `Dev Containers: Reopen in Container`

All compilers, debuggers, system packages, and database daemons will initialize automatically.

### Option B: Local Host Setup

1. **Clone the repository:**
   ```sh
   git clone https://github.com/[ORG]/[REPO].git
   cd [REPO]
   ```

2. **Verify runtime requirements:**
   ```sh
   # Verify your runtime version matches the declared prerequisite
   node --version # Must satisfy the version constraint documented above
   ```

3. **Install dependencies deterministically:**
   ```sh
   # For Node ecosystems
   pnpm install --frozen-lockfile

   # Or for Python
   # uv sync --frozen

   # Or for Rust
   # cargo fetch --locked
   ```

4. **Initialize local backing datastores:**
   ```sh
   docker compose up -d postgres redis
   ```

5. **Execute migrations & start services:**
   ```sh
   pnpm run db:migrate
   pnpm run dev
   ```

> Production installation is documented separately in [Deployment](#deployment). This Quickstart is intended for development and local verification.

---

## Usage Patterns

### Minimal Reproducible Example

The simplest working invocation using standard options:

```ts
import { IngestionEngine } from "[PROJECT_NAME]";

const engine = new IngestionEngine({
  concurrency: 4,
  timeoutMs: 5000,
});

const result = await engine.process({
  source: "stream://telemetry-events",
  batchSize: 500,
});

console.log(result.metrics);
```

**Expected Return Payload:**
```json
{
  "status": "COMPLETED",
  "processedRecords": 500,
  "elapsedMs": 14.2,
  "errors": 0
}
```

### CLI Invocation

```sh
[PROJECT_NAME] --config ./.env --workers 8 --verbose
```

---

## API & Interface Documentation

Document the supported public interfaces and link to the canonical specification or generated reference.

- **HTTP/REST:** [OpenAPI/Swagger documentation or `docs/api.md`]
- **gRPC:** [`.proto` definitions / generated reference, if applicable]
- **CLI:** [Command reference]
- **SDK / Library API:** [Generated API documentation]
- **Schemas / Events:** [Schema registry or versioned schema documentation, if applicable]

For each externally consumed interface, document authentication, versioning, compatibility expectations, error semantics, and deprecation policy where relevant.

---

## Architecture & Internals

### Repository Topology

```
.
├── .devcontainer/           # DevContainer runtime environment specification
├── .github/                 # Workflows, CI/CD matrices, and issue templates
├── src/                     # Core business logic and runtime routines
│   ├── api/                 # Public HTTP/gRPC interface definitions
│   ├── engine/              # Data parsing and memory ring buffer loops
│   └── persistence/         # Schema mappings and database drivers
├── tests/
│   ├── unit/                # Fast, isolated algorithmic assertions
│   └── integration/         # Network, database, and container test suites
├── docs/                    # Architecture, API, and operational documentation
├── .env.example             # Documented baseline configuration template
├── CHANGELOG.md             # Release history and user-visible changes
└── README.md                # Project documentation entry point
```

### Internal Execution Lifecycle

<details>
  <summary><strong>Click to view Internal Execution Lifecycle</strong></summary>

1. **Phase 1 (Ingress)**: Payloads are validated against JSON schema models before thread assignment.
2. **Phase 2 (Queue)**: Valid requests append to a local Redis ring-buffer.
3. **Phase 3 (Flush)**: Batched workers drain the queue and commit records in multi-row transactions to PostgreSQL.

</details>

### Scaling Model

Document how the service scales horizontally and whether it is stateless.

- **Stateless / Replica Scaling:** [Yes/No — explain whether additional replicas can be added safely.]
- **Sticky Sessions:** [Required / Not required / N/A]
- **Leader Election:** [Required / Not required / N/A]
- **Shared State:** [Describe any state that must be externalized to Redis, PostgreSQL, object storage, etc.]
- **Worker Coordination:** [Describe queue partitioning, consumer groups, locks, or singleton workers where applicable.]

---

## Verification & Testing

Verify that local changes pass all testing and linting constraints before opening a pull request:

```sh
# 1. Run static analysis, type checking, and style formatters
pnpm run lint
pnpm run typecheck

# 2. Run unit testing suite with coverage reporting
pnpm run test:unit

# 3. Run localized integration suites against containerized datastores
pnpm run test:integration
```

### Performance & Benchmark Methodology

If the project claims latency, throughput, resource-efficiency, or scalability targets, document how those numbers are measured and reproduced.

| Metric | Target | Workload | Environment | Command / Reference |
| :--- | :--- | :--- | :--- | :--- |
| **p99 latency** | `[Target]` | `[Request/batch profile]` | `[CPU/RAM/runtime]` | `[Benchmark command or CI job]` |
| **Throughput** | `[Target]` | `[Events/requests per second]` | `[Benchmark environment]` | `[Benchmark command or CI job]` |

Do not publish performance claims without defining the workload, environment, metric, and reproducible measurement procedure.

---

## Deployment

Quickstart is for development. Document production deployment independently.

### Container Image

```sh
# Build
[CONTAINER_BUILD_COMMAND]

# Tag
[CONTAINER_TAG_COMMAND]

# Push
[CONTAINER_PUSH_COMMAND]
```

### Kubernetes / Helm

```sh
# Install or upgrade
[HELM_INSTALL_OR_UPGRADE_COMMAND]
```

Document, as applicable:

- Image registry and naming/tagging policy
- Required production configuration and secrets
- Resource requests/limits
- Replica strategy and autoscaling
- Network ingress/load balancer configuration
- Database and cache connectivity
- Migration execution order
- TLS/certificate requirements
- Required cloud/IAM permissions
- Rollout strategy and deployment health checks

For non-Kubernetes environments, replace this subsection with the canonical deployment procedure for the target platform.

---

## Health, Readiness & Metrics

Document service health and monitoring interfaces **where applicable**.

| Interface | Path / Address | Purpose | Expected Response |
| :--- | :--- | :--- | :--- |
| **Liveness** | `/healthz` | Indicates whether the process should be restarted. | `[200/expected payload]` |
| **Readiness** | `/readyz` | Indicates whether the instance can receive traffic. | `[200/expected payload]` |
| **Metrics** | `/metrics` | Prometheus-compatible or equivalent operational metrics. | `[Expected format]` |

If the application uses different mechanisms or paths, document those instead. Clarify whether readiness checks dependencies such as PostgreSQL or Redis and avoid using a deep dependency check for liveness unless that is explicitly intended.

---

## Observability

Document how operators obtain logs, metrics, traces, and correlation context.

| Signal | Implementation | Destination / Configuration | Required Fields |
| :--- | :--- | :--- | :--- |
| **Logs** | `[Structured JSON / text]` | `[stdout / collector / service]` | `[timestamp, level, service, request ID, etc.]` |
| **Metrics** | `[Prometheus / OTEL / other]` | `[Endpoint / collector]` | `[Key service metrics]` |
| **Traces** | `[OpenTelemetry / other]` | `[OTLP endpoint / collector]` | `[Trace/span context]` |

Document relevant configuration such as `OTEL_EXPORTER_OTLP_ENDPOINT`, log-level controls, sampling, retention, and redaction of sensitive data.

---

## Database Migration Policy

Document how schema changes are introduced safely.

- **Migration Tool:** [Tool / framework]
- **Execution Model:** [Automatic during deployment / operator-triggered / separate job]
- **Ordering:** [Required rollout order between application and schema changes]
- **Compatibility:** [Whether old and new application versions can coexist during rollout]
- **Backup Requirement:** [Required backup/restore procedure before risky migrations]
- **Destructive Changes:** [Approval or staged procedure for dropping/rewriting data]
- **Migration Validation:** [Command or CI/CD job]

Prefer backward-compatible, expand/contract migrations where zero-downtime rolling deploys require multiple application versions to coexist.

---

## Rollback & Recovery

Document the exact recovery path for failed deployments, bad configuration, application regressions, and incompatible migrations.

### Application Rollback

```sh
[ROLLBACK_DEPLOYMENT_COMMAND]
```

### Database Recovery

```sh
[SAFE_MIGRATION_ROLLBACK_OR_RESTORE_COMMAND]
```

Document whether database migrations are reversible, when restore-from-backup is required, and which rollback steps must be coordinated with application versions. Do not imply that a migration is reversible unless the repository actually provides a safe reverse procedure.

---

## Troubleshooting / FAQ

Document at least 3–5 high-frequency failure modes with a symptom, likely cause, and recovery action.

| Symptom | Likely Cause | Fix / Diagnostic Command |
| :--- | :--- | :--- |
| **Port already in use** | Another process owns `PORT`. | `[lsof/netstat command]`; change `PORT`. |
| **Migration lock / failure** | Another migration is running or the database is unavailable. | `[Diagnostic + remediation command]` |
| **PostgreSQL connection refused** | Database is stopped or connection settings are invalid. | `[docker compose / connectivity check]` |
| **Redis connection failure** | Redis is unavailable or URL is incorrect. | `[Diagnostic + expected degraded behavior]` |
| **Container startup failure** | Runtime/version/resource mismatch. | `[Diagnostic command / link]` |

Add project-specific issues discovered in CI, support requests, or incident reviews.

---

## Governance & Contributing

We welcome community contributions. Please ensure that all prospective changes follow our standardized procedures:

- Review our [Contribution Guide](CONTRIBUTING.md) for branch naming standards, commit syntax (Conventional Commits), and PR templates.
- Uphold our community standards by reviewing the [Code of Conduct](CODE_OF_CONDUCT.md).
- If maintainers are formally assigned by component, review [`CODEOWNERS`](.github/CODEOWNERS).

Operational ownership, escalation contacts, or incident-response details may be documented here for internal deployments, but these are optional for universal/open-source templates.

---

## Security Protocol

If you discover a security vulnerability or exploit, please **do not open a public issue**. Refer to our [Security Policy](SECURITY.md) to initiate a confidential disclosure report directly to the core maintainers.

### Supported Security Versions

| Release Line | Security Support | End of Support | Notes |
| :--- | :--- | :--- | :--- |
| `[Current major]` | `[Supported]` | `[Date / policy]` | `[Notes]` |
| `[Previous major]` | `[Supported / Limited]` | `[Date / policy]` | `[Notes]` |

Keep this table synchronized with `SECURITY.md` and the project's release policy.

---

## Versioning & Changelog

This project follows **Semantic Versioning (SemVer)** unless otherwise documented.

- **Release policy:** [Describe major/minor/patch rules.]
- **Deprecation policy:** [Describe notice period and compatibility expectations.]
- **Changelog:** See [`CHANGELOG.md`](CHANGELOG.md).
- **Latest release:** [Link to releases page.]

Do not use a "Latest Release" badge unless the repository publishes releases consistently enough for that badge to be meaningful.

---

## Licensing

Distributed under the terms of the **Apache License 2.0**. See the [LICENSE](LICENSE) file for comprehensive legal terms and conditions.

```
Copyright 2026 [ORGANIZATION_NAME]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0
```

<p align="right">(<a href="#readme-top">↑ Back to Top</a>)</p>
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall