Readme Authoring

Deep README workflow—audience, value proposition, quickstart, configuration, troubleshooting, contributing, and badges/links hygiene. Use when bootstrapping...

Security Scan

An instruction-only README authoring workflow that is internally consistent with its stated purpose and requests no credentials, installs, or unusual privileges.

Purpose & Capability

The name/description (deep README workflow) matches the SKILL.md content. The skill is purely authoring guidance and does not request binaries, environment variables, or access to external services that would be unrelated to producing README content.

Instruction Scope

SKILL.md contains structured authoring guidance and checklists only. It does not instruct the agent to read arbitrary system files, access credentials, or send data to external endpoints. It recommends verifying quickstarts in CI or a fresh machine, which is reasonable guidance but is not an instruction to automatically execute commands or access secrets.

Install Mechanism

No install spec and no code files — instruction-only skills have the lowest install risk. Nothing is downloaded or written to disk by the skill itself.

Credentials

The skill requests no environment variables or credentials. It mentions documenting environment variables for the project (as content guidance) but does not attempt to read or require them.

Persistence & Privilege

always is false (default), model invocation is allowed (normal), and the skill does not request persistent presence or modify other skills/configs. There are no elevated privileges requested.

Assessment

This is a low-risk, instruction-only skill for producing better README files. Before installing or invoking it, note that: (1) it does not request credentials or install anything, (2) it recommends verifying quickstarts in CI or on a fresh machine — if you allow an agent to execute commands, review any generated run/CI scripts before executing, and never paste real secrets into generated examples, and (3) standard caution applies if you give the agent runtime or command-execution capabilities (those risks come from the agent environment, not this skill).

README Authoring (Deep Workflow)

A README is the front door of a repository. Optimize for time-to-first-success: install, run, verify—then add depth for contributors and operators.

When to Offer This Workflow

Trigger conditions:

• New repo; users cannot get running from docs alone
• Open-source release needing clear license and support expectations
• Internal library consumed by many teams

Initial offer:

Use six stages: (1) audience & promise, (2) above-the-fold, (3) quickstart, (4) configuration & operations, (5) contributing & governance, (6) maintenance). Confirm package ecosystem and license.

---

Stage 1: Audience & Promise

Goal: First paragraph states what the project does, for whom, and non-goals if confusing.

Exit condition: Reader knows in 30 seconds if this repo matches their need.

---

Stage 2: Above the Fold

Goal: Title, optional badges (CI, version, license), one screenshot or demo GIF if UI helps.

Practices

• Link out to a full docs site when README would exceed ~300 lines

---

Stage 3: Quickstart

Goal: Copy-paste commands that work on a clean machine; pin versions or point to release tags.

Include

• Prerequisites (runtime, tools)
• Install and the first command with expected output shape

---

Stage 4: Configuration & Operations

Goal: Environment variables table with defaults; ports; production notes (TLS, scaling, observability).

Security

• Never document real secrets; reference secret stores and rotation

---

Stage 5: Contributing & Governance

Goal: Link CONTRIBUTING.md, code of conduct, issue/PR templates; security disclosure policy for OSS.

---

Stage 6: Maintenance

Goal: Changelog link or release notes; owning team; deprecation notices when relevant.

---

Final Review Checklist

• Opening clarifies purpose and audience
• Quickstart verified on a fresh machine or CI
• Configuration and security expectations documented
• Contributing and license paths clear
• Maintenance signals (changelog, ownership) present

Tips for Effective Guidance

• Run quickstart in CI (Docker or script) for critical OSS projects.
• Keep README skimmable; move deep dives to docs/.
• For libraries: link API reference and migration guides prominently.

Handling Deviations

• Monorepo: root README as an index to packages with one-liner descriptions each.