# How to Add a Custom Council Member to the Council of High Intelligence

> Learn how to add a custom council member with a new persona to the Council of High Intelligence. Create a Markdown file in agents/ following the schema and optionally register the member.

- Repository: [nyk/council-of-high-intelligence](https://github.com/0xNyk/council-of-high-intelligence)
- Tags: how-to-guide
- Published: 2026-07-03

---

**To add a custom council member with a new persona, create a Markdown file in `agents/` following the front-matter schema used by existing members, ensure the filename matches the `council-*.md` glob pattern, and optionally register the member in the public tables of [`README.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/README.md) and [`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.md) for discovery and triad selection.**

The Council of High Intelligence orchestrates multi-agent deliberation using persona definitions stored as Markdown files. Each **agent definition** file contains structured metadata and behavioral instructions that the coordinator uses for panel selection, provider routing, and polarity-pair composition. Adding a custom council member requires no code changes—only file creation and optional documentation updates.

## Creating the Agent Definition File

The system discovers members by scanning `agents/` for files matching the pattern `council-*.md`. Each file must contain YAML front-matter and standardized Markdown sections that define the persona's analytical lens.

### Copying the Template Structure

Start by duplicating an existing member file to ensure you inherit the correct structure. The file [`agents/council-ada.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/agents/council-ada.md) serves as the canonical reference implementation.

```bash
cp agents/council-ada.md agents/council-zen.md

```

Rename the file to use your desired slug (e.g., [`council-zen.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/council-zen.md)). The coordinator parses these files at runtime, so the filename itself becomes part of the member's identity in the system.

### Configuring Front-Matter Fields

Edit the YAML front-matter at the top of your new file. These fields drive the auto-router and panel selection logic:

- **`name`**: The unique identifier (e.g., `council-zen`)
- **`description`**: A short summary for CLI help text and discovery tables
- **`model`**: The default LLM tier (e.g., `sonnet`, `opus`, `gpt-4o`) used when provider auto-routing is active
- **`color`**: ANSI color code for terminal output (e.g., `teal`, `magenta`)
- **`tools`**: Array of available tool capabilities (e.g., `["Read", "Grep", "WebSearch"]`)
- **`council`**:
  - **`figure`**: The historical or archetypal persona name (e.g., "Zen Master")
  - **`domain`**: The expertise area (e.g., "Mindful presence & paradox")
  - **`polarity`**: A concise question representing the member's default analytical stance
  - **`polarity_pairs`**: List of member slugs to engage in forced tension debates (e.g., `["karpathy", "machiavelli"]`)
  - **`triads`**: Category keywords for automatic triad composition (e.g., `["strategy", "design"]`)
  - **`provider_affinity`**: Prioritized list of preferred providers (`anthropic`, `openai`, `google`, `ollama`, `nvidia_nim`, `cursor_cli`)

Missing front-matter fields will cause the coordinator to error during panel selection, so verify completeness against [`agents/council-ada.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/agents/council-ada.md).

### Writing the Persona Sections

Below the front-matter, maintain the exact heading structure so the coordinator can splice content automatically:

```markdown

## Identity

Define the persona's worldview and voice.

## Grounding Protocol

List behavioral constraints (e.g., brevity rules, jargon restrictions).

## Analytical Method

Numbered steps describing the reasoning process.

## What You See That Others Miss

Unique observational strengths.

## What You Tend to Miss

Acknowledged blind spots.

## When Deliberating in Council

Instructions for multi-agent debate format.

## Output Format (Council Round 2)

Template for structured disagreement and position updates.

## Output Format (Standalone)

Template for single-agent execution mode.

```

## Registering the Member for Discovery

While the coordinator automatically picks up any `council-*.md` file, adding the member to public tables ensures users can discover it via `--members` flags and auto-triad selection.

### Automatic Discovery via File Globbing

Once you commit the file to the repository, the coordinator will include it in the next execution cycle without restart. The discovery logic glob-matches `agents/council-*.md` and parses each file's front-matter to build the available member list.

### Updating Public Documentation Tables

Add your member to the catalog table in [`README.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/README.md) (around lines 81-102) to make it discoverable:

```markdown
| Agent            | Figure      | Domain                | Default Model | Polarity |
|------------------|------------|----------------------|---------------|----------|
| `council-zen`    | Zen Master | Mindful presence & paradox | opus | What is the shape of a problem? |

```

If your member should participate in default triads, append a row to the "Pre-defined Triads" table in [`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.md) (around lines 83-106):

```markdown
| Domain Keyword | Triad                     | Rationale |
|---------------|---------------------------|-----------|
| `design`      | Rams + Torvalds + Zen     | User clarity + pragmatic ship + mindful paradox |

```

## Integrating with Triads and Polarity Pairs

To leverage the council's forced tension logic, configure **polarity pairs** and **triads** in your member's front-matter.

**Polarity pairs** create dialectical opposition. In your new file's front-matter, list the slugs of members that create productive disagreement:

```yaml
polarity_pairs:
  - karpathy
  - machiavelli

```

**Triads** enable three-member panel composition. Add domain keywords that match the triad definitions in [`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.md):

```yaml
triads:
  - strategy
  - design

```

The coordinator reads these relationships at runtime to construct panels with intentional cognitive diversity.

## Verification and Testing

After creating the file, validate the integration using the simulation checklist:

```bash
./scripts/council-simulation-checklist.sh

```

This script verifies that:
- All front-matter fields parse correctly
- The member loads without schema errors
- Polarity references resolve to existing members
- Output templates render correctly in both standalone and council modes

Run this check before committing to ensure no regression in the deliberation pipeline.

## Summary

- **Create** a new file in `agents/council-<slug>.md` using [`agents/council-ada.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/agents/council-ada.md) as the template
- **Configure** all required front-matter fields including `council:` metadata for routing and polarity
- **Write** standardized sections (`Identity`, `Grounding Protocol`, `Analytical Method`, etc.) to control persona behavior
- **Register** optionally in [`README.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/README.md) and [`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.md) tables for public discovery and triad assignment
- **Test** using [`scripts/council-simulation-checklist.sh`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/scripts/council-simulation-checklist.sh) to verify parser compatibility

## Frequently Asked Questions

### What happens if I forget to add a required front-matter field?

The coordinator will throw a parsing error during panel selection and abort the deliberation. Always verify your YAML against the schema in [`agents/council-ada.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/agents/council-ada.md) before running the simulation checklist.

### Can I use any filename pattern for the agent file?

No. The coordinator specifically glob-matches `agents/council-*.md`. Files named [`member-zen.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/member-zen.md) or [`zen.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/zen.md) will be ignored by the discovery logic. Use the `council-<slug>.md` format.

### How do I specify which LLM provider the new member should use?

Set the `provider_affinity` list in the front-matter. Order matters—the auto-router attempts providers in the sequence you specify (e.g., `["anthropic", "openai", "google"]`). The first available provider for the requested model tier will be selected.

### Do I need to modify [`install.sh`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/install.sh) when adding a new member?

No. The installation script copies the entire `agents/` directory recursively, so any new `council-*.md` files are automatically included in fresh installations without edits to the installer.