Reason Commons skills

Skills that help people and groups work out what they are trying to achieve and what to do about it, in conversation with an AI agent, and keep that reasoning so it builds up. They work in Claude Code, Codex and other agents that support SKILL.md skills.

1 · Install

One command puts the skills in your agent.

2 · Think together

Work a goal, problem or plan through in conversation.

Pass it on

A short message to send a colleague.

Start here

Install the skills once:

npx skills add life-itself/reasoncommons

That lists the skills in this repository and asks which agents to install them into. To install just the conversational skill:

npx skills add life-itself/reasoncommons -s reason-commons

To install it for one agent in every project:

npx skills add life-itself/reasoncommons -s reason-commons -a claude-code -g

Replace claude-code with the agent you use. Run npx skills add life-itself/reasoncommons --list to see the available skills without installing them.

Don't want to install anything? Print a skill as a ready-to-paste prompt, or give your agent the raw file:

npx skills use life-itself/reasoncommons@reason-commons

https://raw.githubusercontent.com/life-itself/reasoncommons/main/skills/reason-commons/SKILL.md

An installed copy includes the skill's helper script and references, so installation is the best option.

The skills

Skill	What it does	Use it when
`reason-commons`	Helps people work through a goal or problem in conversation and turn it into agreed next steps, keeping who said what, what is still unfinished, what was accepted and diagrams of it	You want to think through a goal, problem, conflict, proposed change, obstacle or action with one person or a group
`scrollable-explainer`	Gives contributors principles and patterns for writing scroll-driven visual explainers	You are writing a scrolling explainer for the public series

Start a reasoning conversation

After installing, open your agent in the folder where you want the working state to live and paste a prompt like this:

Use the reason-commons skill to help me think through why customer quotes are late. My name is Alice. Keep the working state in reason-commons.yaml.

You can begin with a goal, a problem, a conflict, a proposed change, an obstacle or a sequence of actions. You do not need to know the method underneath or prepare a document. The agent will capture useful statements, keep contributors' names attached to their ideas, and ask one focused question at a time.

To resume later, open the same folder and say:

Use the reason-commons skill and resume from reason-commons.yaml. Show me the most useful unfinished reasoning to work on next.

For a group, name people as they contribute. If speaker labels come from a transcript or voice system, give those labels to the agent; the skill does not guess who spoke.

What the backlog is for

The backlog is the reasoning that still needs attention: an observation that has not been connected or explained, a causal link that needs testing, an assumption to examine, or an objection to resolve. It is not a second task manager and it is not a list of every possible question. The agent keeps a small active subset, preserves the rest, and prefers working through existing reasoning before asking the group for more material.

Acceptance and backlog are separate. A person can accept a useful statement or connection while leaving a question about it in the backlog. Drawing an arrow does not by itself finish the reasoning.

How accepted reasoning becomes diagrams

New statements and connections begin as proposals. They become accepted only when a person explicitly endorses the identified item or fragment; silence and moving on do not count. A substantive objection marks the item disputed until it is resolved.

After an accepted change, the helper validates the working YAML and saves one numbered snapshot of that turn's accepted state. It then updates two SVG diagrams for each affected tree:

The full view shows all currently accepted statements and accepted connections.
The latest-change view highlights what was added, changed or removed, with enough neighboring context to review the change.

Proposals, disputes and backlog-only edits stay in the working YAML but do not create a new accepted snapshot. The YAML is the source of truth; the diagrams are derived views. The skill normally runs the helper and links both diagrams when accepted reasoning changes. Python with PyYAML is required; the current helper draws its SVG directly without Graphviz or a JavaScript renderer; see reason-commons/references/views.md for details.

Send this to a colleague

Try the Reason Commons skill to think through a goal, problem, conflict or plan together. Install it with `npx skills add life-itself/reasoncommons -s reason-commons`, then ask your agent: "Use the reason-commons skill to help me think through [topic]. My name is [name]." The agent keeps unfinished reasoning in a backlog and turns explicitly accepted reasoning into full and latest-change diagrams. More: https://reasoncommons.com/skills

For maintainers

Skills live at top level so they work outside one agent runtime. Link the skills you use into .claude/skills/ for Claude Code or .agents/skills/ for Codex. This repository tracks the Codex link for reason-commons.
ltp-project and ltp-visualize were retired on 2026-10-21 with the Reason Commons app whose import format they served. tree-gen, annotation-mapping, contribution-proposals, goal-alignment and project-ltp were retired earlier. All remain in Git history.

Canonical packages and public guide

Installable packages and their helpers/tests remain under skills/. The public /skills guide is exported from this file by python3 scripts/export-website.py; its package links point to canonical repository sources. Finished website content lives under website/.