# tsenart/council-skill architecture

> Architecture diagram of the GitHub repository tsenart/council-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsenart/council-skill
- Repository: https://github.com/tsenart/council-skill

## Overview

This repository is a **portable “skill package”**, not a conventional application. Its purpose is to add a reusable **multi-agent deliberation protocol** to coding agents such as Codex, Claude Code, and Amp through the `skills` CLI.

The **core runtime artifact** is `skills/council/SKILL.md`. That is the installable entry point the host agent actually loads. Everything else in the skill folder supports that one skill definition.

The skill’s **reference bundle** lives under `skills/council/references/`. These files appear to define the operating inputs for the council:
- `protocol.md` — the deliberation flow and rules
- `verdict-template.md` — the expected final output shape
- `profiles.yaml` — structured persona/profile mapping
- `personas/*.md` — individual analyst personas used to diversify viewpoints

Architecturally, the data flow is: **user prompt → host agent → council skill → protocol + persona references → round-based analysis → final verdict**. The skill is designed to turn one prompt into a coordinated multi-perspective review rather than a single-model answer.

The protocol is intentionally **three-round and blind-first** according to the README: independent analysis first, then cross-examination, then a final verdict. That is the main behavioral boundary of the system and the key thing to capture in a diagram.

A notable design choice is that the skill is **host-neutral**. The repository keeps the portable council logic in one place, while allowing thin host-specific installation into the target agent’s skills directory. The README calls out different install targets for Codex, Claude Code, and Amp.

The repository also includes **usage guidance and example outputs** under `examples/`. `prompt-library.md` provides prompt patterns, and `sample-verdict.md` shows what a finished council response should look like. These files are documentation, not execution logic, but they shape how users invoke the skill and interpret its output.

Validation is handled by `scripts/smoke-test.sh`, which exercises local installation via `npx skills add` and checks that the skill can be discovered and installed for the supported agents. This is the main automated boundary test for the package.

`.github/workflows/ci.yml` likely runs that smoke test in CI, so the repo’s operational guarantee is: the skill remains installable from a checkout and the packaged layout stays compatible with the `skills` ecosystem.

In diagram terms, the important subsystems are:
1. **Skill definition** (`SKILL.md`)
2. **Protocol and persona references**
3. **Examples/documentation**
4. **Install/validation tooling**
5. **CI verification**

The overall architecture is a **content-driven agent plugin**, with no backend service, database, or runtime server. Its “execution environment” is the consuming coding agent plus the `skills` installer, and its main output is a structured council verdict rather than programmatic state.

Main entry points: [`skills/council/references/personas`](https://github.com/tsenart/council-skill/tree/main/skills/council/references/personas) (Personas), [`skills/council/SKILL.md`](https://github.com/tsenart/council-skill/blob/main/skills/council/SKILL.md) (Council skill), [`examples`](https://github.com/tsenart/council-skill/tree/main/examples) (Examples), [`skills/council/references/protocol.md`](https://github.com/tsenart/council-skill/blob/main/skills/council/references/protocol.md) (Protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_skill["Skill package"]
  node_skill_entry["Council skill<br/>skill entrypoint<br/>[SKILL.md]"]
  node_protocol["Protocol<br/>deliberation flow<br/>[protocol.md]"]
  node_profiles["Profiles<br/>persona mapping<br/>[profiles.yaml]"]
  node_verdict_template["Verdict template<br/>output schema"]
  node_personas["Personas<br/>analyst set"]
  node_persona_ada["Ada<br/>persona<br/>[ada.md]"]
  node_persona_aristotle["Aristotle<br/>persona<br/>[aristotle.md]"]
  node_persona_aurelius["Aurelius<br/>persona<br/>[aurelius.md]"]
  node_persona_feynman["Feynman<br/>persona<br/>[feynman.md]"]
end

subgraph group_group_docs["Docs and examples"]
  node_examples["Examples<br/>usage docs"]
  node_prompt_library["Prompt library<br/>prompt patterns<br/>[prompt-library.md]"]
  node_sample_verdict["Sample verdict<br/>example output<br/>[sample-verdict.md]"]
  node_readme["README<br/>project overview<br/>[README.md]"]
end

subgraph group_group_tooling["Validation tooling"]
  node_smoke_test["Smoke test<br/>install check<br/>[smoke-test.sh]"]
  node_ci["CI workflow<br/>verification pipeline<br/>[ci.yml]"]
end

node_repo["council-skill<br/>portable skill package"]

node_repo -->|"packages"| node_skill_entry
node_skill_entry -->|"loads"| node_protocol
node_skill_entry -->|"uses"| node_profiles
node_skill_entry -->|"formats"| node_verdict_template
node_skill_entry -->|"includes"| node_personas
node_protocol -->|"orchestrates"| node_personas
node_profiles -->|"maps to"| node_personas
node_personas -->|"contains"| node_persona_ada
node_personas -->|"contains"| node_persona_aristotle
node_personas -->|"contains"| node_persona_aurelius
node_personas -->|"contains"| node_persona_feynman
node_repo -->|"documents"| node_readme
node_repo -->|"shows"| node_examples
node_examples -->|"guides"| node_prompt_library
node_examples -->|"demonstrates"| node_sample_verdict
node_repo -->|"validates"| node_smoke_test
node_smoke_test -->|"runs in"| node_ci
node_ci -.->|"guards"| node_repo

click node_skill_entry "https://github.com/tsenart/council-skill/blob/main/skills/council/SKILL.md"
click node_protocol "https://github.com/tsenart/council-skill/blob/main/skills/council/references/protocol.md"
click node_profiles "https://github.com/tsenart/council-skill/blob/main/skills/council/references/profiles.yaml"
click node_verdict_template "https://github.com/tsenart/council-skill/blob/main/skills/council/references/verdict-template.md"
click node_personas "https://github.com/tsenart/council-skill/tree/main/skills/council/references/personas"
click node_persona_ada "https://github.com/tsenart/council-skill/blob/main/skills/council/references/personas/ada.md"
click node_persona_aristotle "https://github.com/tsenart/council-skill/blob/main/skills/council/references/personas/aristotle.md"
click node_persona_aurelius "https://github.com/tsenart/council-skill/blob/main/skills/council/references/personas/aurelius.md"
click node_persona_feynman "https://github.com/tsenart/council-skill/blob/main/skills/council/references/personas/feynman.md"
click node_examples "https://github.com/tsenart/council-skill/tree/main/examples"
click node_prompt_library "https://github.com/tsenart/council-skill/blob/main/examples/prompt-library.md"
click node_sample_verdict "https://github.com/tsenart/council-skill/blob/main/examples/sample-verdict.md"
click node_readme "https://github.com/tsenart/council-skill/blob/main/README.md"
click node_smoke_test "https://github.com/tsenart/council-skill/blob/main/scripts/smoke-test.sh"
click node_ci "https://github.com/tsenart/council-skill/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_entry,node_protocol,node_profiles,node_verdict_template,node_personas,node_persona_ada,node_persona_aristotle,node_persona_aurelius,node_persona_feynman toneBlue
class node_examples,node_prompt_library,node_sample_verdict,node_readme toneAmber
class node_smoke_test,node_ci toneMint
class node_repo toneNeutral
```

## Components

### Skill package

Installable council skill and its reference bundle.

- [Council skill](https://github.com/tsenart/council-skill/blob/main/skills/council/SKILL.md): skill entrypoint · Installable skill definition loaded by the host agent. · `skills/council/SKILL.md`
- [Protocol](https://github.com/tsenart/council-skill/blob/main/skills/council/references/protocol.md): deliberation flow · Three-round blind-first process: independent analysis, cross-examination, then final verdict. · `skills/council/references/protocol.md`
- [Profiles](https://github.com/tsenart/council-skill/blob/main/skills/council/references/profiles.yaml): persona mapping · Structured mapping that assigns or selects analyst personas for the council. · `skills/council/references/profiles.yaml`
- [Verdict template](https://github.com/tsenart/council-skill/blob/main/skills/council/references/verdict-template.md): output schema · Expected final response structure for a completed council verdict. · `skills/council/references/verdict-template.md`
- [Personas](https://github.com/tsenart/council-skill/tree/main/skills/council/references/personas): analyst set · Reference personas used to diversify viewpoints during deliberation. · `skills/council/references/personas`
- [Ada](https://github.com/tsenart/council-skill/blob/main/skills/council/references/personas/ada.md): persona · Analyst persona file. · `skills/council/references/personas/ada.md`
- [Aristotle](https://github.com/tsenart/council-skill/blob/main/skills/council/references/personas/aristotle.md): persona · Analyst persona file. · `skills/council/references/personas/aristotle.md`
- [Aurelius](https://github.com/tsenart/council-skill/blob/main/skills/council/references/personas/aurelius.md): persona · Analyst persona file. · `skills/council/references/personas/aurelius.md`
- [Feynman](https://github.com/tsenart/council-skill/blob/main/skills/council/references/personas/feynman.md): persona · Analyst persona file. · `skills/council/references/personas/feynman.md`

### Docs and examples

Usage guidance and sample outputs for the skill.

- [Examples](https://github.com/tsenart/council-skill/tree/main/examples): usage docs · Prompt patterns and example council output for users of the skill. · `examples`
- [Prompt library](https://github.com/tsenart/council-skill/blob/main/examples/prompt-library.md): prompt patterns · Guidance for composing prompts that work well with the council. · `examples/prompt-library.md`
- [Sample verdict](https://github.com/tsenart/council-skill/blob/main/examples/sample-verdict.md): example output · Illustrative finished council response shape. · `examples/sample-verdict.md`
- [README](https://github.com/tsenart/council-skill/blob/main/README.md): project overview · Explains the skill package, host-neutral installation, and operating model. · `README.md`

### Validation tooling

Local install checks and CI verification.

- [Smoke test](https://github.com/tsenart/council-skill/blob/main/scripts/smoke-test.sh): install check · Local validation script that exercises package discovery and installation. · `scripts/smoke-test.sh`
- [CI workflow](https://github.com/tsenart/council-skill/blob/main/.github/workflows/ci.yml): verification pipeline · Automated workflow that runs repository checks and validates installability. · `.github/workflows/ci.yml`

### Other components

- **council-skill**: portable skill package · Host-neutral repository that packages a multi-agent deliberation protocol for coding agents.

## Connections

- council-skill → Council skill: packages · Repository centers on the installable skill entrypoint.
- Council skill → Protocol: loads · Skill entry references the council deliberation protocol.
- Council skill → Profiles: uses · Skill entry relies on persona/profile mapping.
- Council skill → Verdict template: formats · Skill entry shapes the final council response via template.
- Council skill → Personas: includes · Skill entry pulls in the persona reference set.
- Protocol → Personas: orchestrates · Protocol uses personas during blind-first analysis and cross-examination.
- Profiles → Personas: maps to · Profile data binds structured roles to persona files.
- Personas → Ada: contains · Persona reference bundle includes Ada.
- Personas → Aristotle: contains · Persona reference bundle includes Aristotle.
- Personas → Aurelius: contains · Persona reference bundle includes Aurelius.
- Personas → Feynman: contains · Persona reference bundle includes Feynman.
- council-skill → README: documents · README explains the portable skill architecture and installation targets.
- council-skill → Examples: shows · Repository includes usage guidance and example outputs.
- Examples → Prompt library: guides · Prompt library provides invocation patterns.
- Examples → Sample verdict: demonstrates · Sample verdict shows the expected council output shape.
- council-skill → Smoke test: validates · Smoke test checks local install and discovery of the skill package.
- Smoke test → CI workflow: runs in · CI workflow executes the smoke test for verification.
- CI workflow → council-skill: guards · Continuous integration protects packaged layout and installability.