Skill Council

A council of specialized agents that collaborate to produce high-quality Claude Code skills. The council analyzes needs, researches current best practices, writes concise instructions, tests quality, and reviews security — then installs the skill directly into .claude/skills/.

Modes of operation

1. Explicit creation

User asks directly via /skill-council or in natural language: "create a skill for X".

Flow: Architect → Researcher → Writer → Tester → Reviewer → Install

2. Dynamic detection

The council detects opportunities to create skills. Behavior is configurable:

• confirm (default): Propose the skill, ask before creating
• auto: Create silently, notify the user
• off: No detection

Detection signals (see detection/signals.md):

• New project initialized (package.json, pyproject.toml, go.mod created)
• Complex task with no matching skill
• Major dependency added (Prisma, Stripe, etc.)
• Same type of request repeated 3+ times

3. Conversational mode

For large projects or major changes, present a "skill plan" (list of recommended skills) that the user reviews before creation begins. Use this when detecting a new project init or a major architectural change.

Council agents

Agent	Phase	Role	Reference
Architect	Analysis	Scans project, plans skill structure, avoids duplicates	council/architect.md
Researcher	Research	Fetches current docs via Context7 MCP, finds patterns	council/researcher.md
Writer	Construction	Writes SKILL.md and supporting files	council/writer.md
Tester	Validation	Creates eval scenarios, tests trigger accuracy	council/tester.md
Reviewer	Validation	Security audit, concision check, quality gate	council/reviewer.md

Workflow

Phase 1: ANALYSIS (Architect)
  Scan .claude/skills/ for existing skills
  Scan project stack (package.json, pyproject.toml, etc.)
  Produce a structured plan
  → Output: plan.json

Phase 2: RESEARCH (Researcher)
  Use Context7 MCP to fetch current documentation
  Identify up-to-date patterns and best practices
  → Output: research notes for the Writer

Phase 3: CONSTRUCTION (Writer)
  Write SKILL.md with proper YAML frontmatter
  Create supporting files if plan requires them
  Follow templates from templates/ directory
  → Output: complete skill directory

Phase 4: VALIDATION (Tester + Reviewer, iterative)
  Tester: create 3-5 eval scenarios, verify triggers
  Reviewer: security checklist, concision, naming, description quality
  If issues found → return to Writer with specific corrections
  Max 2 revision rounds, then install with warnings if needed
  → Output: validated skill OR skill with noted caveats

Phase 5: INSTALL
  Write skill files to .claude/skills/<skill-name>/
  Confirm to user with summary of what was created

When creating MULTIPLE skills:
  Run the full Phase 1-5 pipeline for each skill sequentially.
  Do not attempt to write multiple skills in parallel via subagents.
  You may batch the Architect analysis for all skills upfront,
  then write each skill one at a time.

Executing the council

Critical: file writing rules

Subagents in Claude Code cannot reliably persist file writes. Follow these rules strictly:

The main orchestrator (you) handles ALL file writes. Never delegate file creation to subagents. Subagents can read files and produce analysis/content as text output, but only the main orchestrator writes to .claude/skills/.

Recommended execution strategy

For a single skill: Work inline — read each agent's reference file and follow the procedure sequentially. This is the most reliable approach.

For multiple skills: Work on each skill sequentially in the main loop. Do NOT spawn parallel writer subagents that try to create files. You may use subagents for read-only tasks (scanning the codebase, researching patterns), but always write the final skill files yourself.

Subagents are safe for:

• Reading and analyzing source code
• Scanning existing skills for duplicates
• Researching patterns across the codebase
• Producing content as text output for the orchestrator to write

Subagents must NOT:

• Create files or directories
• Write to .claude/skills/
• Modify any files on disk

Execution flow

1. Read council/architect.md — follow its procedure to produce a plan
2. Read council/researcher.md — follow its procedure if dependencies need research
3. Read council/writer.md — follow its procedure, then write the files yourself
4. Read council/tester.md — follow its procedure to validate
5. Read council/reviewer.md — follow its procedure for final review
6. If revisions needed, repeat steps 3-5 (max 2 rounds)
7. Confirm to the user what was installed

Usage examples

Users interact with the council through natural language. Typical requests:

• "Create a skill for our Prisma migration conventions"
• "Scan this project and propose a skill plan"
• "Improve the managing-prisma-migrations skill"
• "List all skills created by the council"
• "Show me what's inside the creating-rest-endpoints skill"
• "Set detection to auto mode"

Configuration

Detection mode is stored in .claude/skills/skill-council/config.json:

{
  "detection_mode": "confirm",
  "max_revision_rounds": 2,
  "context7_enabled": true
}

If Context7 MCP server is not available, the Researcher phase is skipped and the Writer uses Claude's built-in knowledge. The council still produces quality skills, just without guaranteed up-to-date library documentation.

Quality standards

Every skill produced by the council must:

1. Have a name field: lowercase, hyphens, gerund form preferred (e.g., managing-prisma-migrations)
2. Have a description field: third person, includes what it does AND when to trigger, under 1024 chars
3. Keep SKILL.md body under 500 lines
4. Use consistent terminology throughout
5. Include concrete examples (input/output pairs where relevant)
6. Avoid time-sensitive information
7. Not over-explain things Claude already knows
8. Use progressive disclosure if content exceeds ~200 lines

Anti-patterns to avoid

• Do not create skills for one-off tasks that won't recur
• Do not create skills that duplicate existing ones in .claude/skills/
• Do not over-engineer: a simple SKILL.md is better than a complex multi-file structure when the task is straightforward
• Do not include hardcoded credentials, API keys, or secrets
• Do not use Windows-style paths

Templates

Templates for different skill complexity levels:

• Simple: templates/skill-minimal.md
• Standard: templates/skill-standard.md
• Complex (with scripts): templates/skill-complex.md
• Evaluation scenarios: templates/eval-template.json

Examples

See examples/ for sample skills produced by the council:

• examples/prisma-skill/ — Standard skill for Prisma ORM patterns
• examples/api-conventions-skill/ — Skill with reference file for API design