Generate modes

Goal

Create three project-specific, behavioral mode skills under

./.{AGENT_NAME}/skills/

:

• {slug}-mode-planner

• {slug}-mode-debugger

• {slug}-mode-qa-tester

Each mode must:

1. Always state acceptance criteria and how to verify locally.
2. Never change or weaken existing tests without explicit approval.
3. When drafting skills, follow the Agent Skills spec (valid frontmatter; keep

   SKILL.md

   under ~500 lines; use progressive disclosure).

The modes must be written so they do not reference any specific benchmark, puzzle set, or domain-specific toy terms. They must read as general-purpose operating procedures.

For concrete “golden” examples of what the generated mode

SKILL.md

files should look like after adaptation, see

references/examples.md

.

Quick start

1. Activate memories

   • Run

     $activating-memories

     .
   • Ensure baseline memory skills exist under

     ./.{AGENT_NAME}/skills/memories/

   • If memories are missing or stale, update them before generating modes.

2. Choose a project slug

   • Prefer a slug stated in

     project_overview

     .
   • Otherwise derive from the repository folder name.
   • Slug rules: lowercase, digits, hyphens; no leading/trailing hyphen; no consecutive hyphens.
   • Length rule (spec compliance): generated skill

     name

     must be ≤ 64 chars and match its directory name.
     • Longest suffix is

       -mode-qa-tester

       (15 chars), so

       {slug}

       must be ≤ 49 chars.

3. Read the bundled templates

   • Read:

     • assets/planner-template.md

     • assets/debugger-template.md

     • assets/qa-tester-template.md

4. Generate three mode skills For each template:

   • Adapt it to the project by adding:
     • the

       {slug}

       mode name
     • links to relevant memories (do not paste memory contents)
     • project-specific verification commands (link to

       suggested_commands-skl

       for the canonical list)
   • Write the resulting skill to:

     • ./.{AGENT_NAME}/skills/{slug}-mode-planner/SKILL.md

     • ./.{AGENT_NAME}/skills/{slug}-mode-debugger/SKILL.md

     • ./.{AGENT_NAME}/skills/{slug}-mode-qa-tester/SKILL.md

5. Make the modes selectable via

   $switching-modes

   • If

     ./.{AGENT_NAME}/skills/switching-modes/

     exists, update its mode registry to include the three new modes.
     • Prefer editing an explicit “Mode registry” list in

       ./.{AGENT_NAME}/skills/switching-modes/SKILL.md

       (if present).
   • If it does not exist, create a project-local

     ./.{AGENT_NAME}/skills/switching-modes/SKILL.md

     that:
     • writes

       ./.{AGENT_NAME}/state.json

       with

       { "mode": "<mode-name>" }

     • documents both baseline modes (if used) and the three new project modes
     • start from

       assets/switching-modes-stub.md

       to avoid bikeshedding
   • After this, switching is done by running:

     • $switching-modes {slug}-mode-planner

     • $switching-modes {slug}-mode-debugger

     • $switching-modes {slug}-mode-qa-tester

6. Validate the generated skills

   • Minimum manual checks:
     • Each generated directory name exactly matches its SKILL frontmatter

       name

       .
     • Each generated

       description

       is third-person and includes “Use when …”.
   • Optional (if available): run

     skills-ref validate

     on each generated skill directory.

Required structure of each generated mode skill

Each mode skill must be a valid Agent Skill.

Frontmatter

Example for planner:

---
name: {slug}-mode-planner
description: Behavioral mode for planning and design work in {slug}. Use when scoping changes, producing design docs, or deciding between approaches.
---

Body

Include these sections (in any order):

• When to use (triggers)
• Operating loop (the step-by-step behavior)
• Question protocol (how to ask questions; allow questions in all modes)
• Output discipline (acceptance criteria + local verification; test-change guardrail)
• Project context pointers (links to memories)

Keep the body concise. If the mode needs lengthy reference material, create

references/

files and link them.

Adaptation rules

When adapting templates:

• Prefer links to memories, e.g.

  ../memories/project_overview-skl/SKILL.md

  , not copy/paste.
• Use the project’s terminology: module names, CLI names, test runner names, etc.
• Avoid generic fluff. Encode actionable guardrails, checks, and concrete steps.
• Ensure the mode is usable standalone by a future agent who has access to the memories.

Failure modes and how to handle them

• Unknown

  {AGENT_NAME}

  : infer from the local agent folder present (e.g.

  .claude

  ,

  .codex

  ). If none exist, ask the user what agent folder to use.
• Mode name collisions: if a target directory already exists, do not overwrite silently. Either append a suffix (e.g.

  -v2

  ) or ask the user which to keep.
• No reliable test commands: link to

  suggested_commands-skl

  and ask the user to confirm the correct test command(s) if missing.