c-kapsalis/second-read

Second Read is an agent skill for editing a draft before you publish it. Give your agent the draft and what it is for: who reads it, what it must do, what you can prove. Second Read reads it the way that reader will, in order, and hands back the edits it would make, each tied to the exact words it changes.

1. Reads in the reader's order. It groups related passages into labeled threads (claim, evidence, example, counterargument) so you can see how the argument travels.
2. Proposes the smallest edit that fixes a real problem: replace, insert, move or delete, each anchored to a verbatim quote and marked required (a checkable error) or optional (style or flow).
3. Asks where a reader could go another way. At most three questions, placed right after the passage where a first-time reader might take something other than what you meant. No quiz at the end, no score for you.
4. Assembles the version you approve and proofreads the new order again. It keeps your voice and invents no facts. A clean draft gets zero changes.

How to ask

Paste a brief and draft in this shape when you can. If you are editing an existing file in a knowledge base, Second Read can first inspect relevant, authorized project context from linked notes or connected tools. It asks for a missing detail only when the answer could materially change an edit:

My actual intention: Argue that the city should run a six-month pilot to
make late-night buses reliable before deciding anything about fares.
Audience: Residents who know little about transport policy.
Voice: Direct, thoughtful, memorable. Not academic or promotional.
Constraints: Keep my strongest sentences. Invent no statistics or policies.
Draft:
...

It picks its checks from what the draft does, not from its length: essays and explanations, policy arguments, fiction and narrative, copy and branding, and documentation using Canonical's documentation style and Diátaxis, plus distinct pathways for public relations, reported journalism, SEO, emails, landing pages and paid textual ads.

Writing inside an Obsidian vault, Notion workspace or Markdown repository

Second Read is particularly useful when the draft belongs to a larger text-based project: a product, company, publication, campaign or personal knowledge base. When the agent can read that workspace, it should start with the draft and its relevant links, discover approved positioning/terminology/earlier assets, and propose the same two-or-fewer concrete edits. It does not need the whole vault in its model context, nor does it need permission to reorganize it.

For local Markdown/Obsidian, the optional read-only helper returns a small list of candidate related notes without their full content:

python3 scripts/knowledge_context.py --root /path/to/vault --target projects/launch/draft.md

The agent still needs to read the relevant files and judge provenance; it must not assume every backlinked note is current or authoritative. With Notion, use your authorized Notion integration if available. The skill alone does not provide a Notion connection, and the Notion API's standard search endpoint is title-based, not full-text search.

Optional ways to make a knowledge base easier for agents to navigate

You do not need to change your organization to use Second Read. For a new or growing workspace, the following suggestions can reduce irrelevant retrieval and repeated instructions, although they are not guaranteed token savings and are not required by the skill:

• Link each ongoing project from a short index or map of content, then link its brief, approved claims, writing conventions and related drafts.
• Use existing Obsidian properties/tags/aliases or Notion database properties/relations for project, status and ownership where helpful; do not create duplicate metadata merely for an agent.
• Keep the current brief and product facts easy to distinguish from old brainstorms and unpublished variants. In Notion, page owners and verification can help people identify maintained pages; verification does not independently prove business claims.
• Give agent-facing instructions short, descriptive pointers to deeper references, instead of copying brand rules into every draft. Read only the relevant sections before expanding. Keep one source of truth.

Authoritative references: Obsidian properties, internal links, search, backlinks; Notion workspaces and databases, wikis and verified pages; Matt Pocock's writing-for-agents (context pointers, progressive disclosure, pruning duplicate instructions). These resources describe their platforms or a design approach, not an obligatory universal folder template.

Install

Claude Code

/plugin marketplace add C-Kapsalis/second-read

/plugin install second-read@second-read

Then share a draft: "Give this a second read before I publish it."

Claude (web and Desktop) and ChatGPT

Download second-read.zip from the latest release and upload it as a skill (Claude: Customize > Skills; ChatGPT: the Skills tab). In Claude you can instead upload second-read-plugin.zip under Customize > Plugins. Code execution must be on for the scripts.

For a ChatGPT or Codex public plugin-directory submission, the release also includes second-read-openai.zip, a portable skills-only package. A directory listing appears only after the platform review and publication steps.

OpenCode, OpenClaw, Codex, Gemini CLI, Cursor, Copilot, Goose, Cline, Windsurf and other agents

Second Read follows the open Agent Skills format, so one command installs it into the agents you choose (needs Node.js):

npx skills add C-Kapsalis/second-read

Add -g to install it for your user instead of the current project, or -a opencode (or another agent's name) to pick the agent.

To install by hand, download second-read.zip from the latest release and unzip it so the second-read/ folder sits in your agent's skills folder:

Paths are from each agent's documentation on 2026-10-22; check yours if the skill does not load. I have checked the Claude Code plugin locally; the other installs are untested, so please open an issue with what happened.

The scripts (optional)

The skill works in plain chat. Optional scripts, Python standard library only, add a reproducible trail:

python3 scripts/edit_review.py validate review.json
python3 scripts/edit_review.py render review.json --output second-read.html
python3 scripts/edit_review.py apply review.json --accept e1 e3 --output revised.md

edit_review.py checks that every proposed edit quotes your draft verbatim, renders a private offline page where you accept or reject each change, and applies the accepted set. assets/review.example.json shows the format.

python3 scripts/product_verify.py --root ./your-product --manifest claims.json --document README.md

product_verify.py checks product claims in a document against a checkout and reports each as corroborated, contradicted or unknown. It runs commands only with --allow-exec and makes network requests only with --allow-network; read references/PRODUCT-VERIFICATION.md first.

License

MIT. Personal project of Christoforos Kapsalis.