Cognition Alignment Skill

An interactive decision report skill for Claude Code that bridges the cognition gap between user and agent.

The agent produces a structured JSON report with decision points, the user reviews it in an interactive HTML interface, selects options, adds feedback, and exports their choices back to the agent.

Install

# Clone into your Claude Code skills directory
git clone https://github.com/JeiKeiLim/cognition-alignment-skill ~/.claude/skills/cognition-alignment

Or install directly from GitHub:

/install https://github.com/JeiKeiLim/cognition-alignment-skill

Usage

In any Claude Code session, describe a situation with multiple viable paths:

• "I need to decide on the database strategy for our new service"
• "Help me review the architecture options before we start"
• "Show me the trade-offs for this API design"

The skill triggers automatically when the agent recognizes ambiguity that needs user judgment. It produces an interactive HTML report that opens in your browser.

The workflow

1. Agent analyzes the situation and produces a decision report
2. An interactive HTML report opens in your browser
3. You review context, select options, add feedback
4. You copy the result (Markdown or JSON) and paste it back
5. The agent proceeds with your chosen direction

Features

• Structured narrative — background, implications, and trade-offs per decision
• Selectable options — radio-button cards with pros, cons, and effort badges
• Custom answer — write your own approach if none of the options fit
• Mermaid diagrams — optional architecture/flow diagrams at top level or per decision
• Before/after diffs — show concrete code/config changes for each option
• Severity levels — critical, important, consider
• Export — Copy as Markdown, Copy as JSON, or Download JSON
• Full-context export — exported JSON includes the full report so it works in a new session
• Self-contained HTML — no external dependencies, system fonts, works offline (except diagrams)

Repository structure

cognition-alignment-skill/
├── SKILL.md                          # Skill definition
├── schema/
│   └── decision-report.schema.json   # JSON Schema for input reports
├── assets/
│   └── decision-reviewer.html        # Self-contained interactive HTML template
└── examples/
    └── example-report.json           # Sample decision report

License

MIT