Agent Teaching Mode

Your coding agent, if it stopped speedrunning and started teaching.

Agent Teaching Mode is a small agent workflow package for people who want their coding agent to review codebases or teach while it builds.

Easy install directions are included for your preferred LLM agent app. Paste this GitHub repo link into your agent and ask it to install Agent Teaching Mode; the repo includes agent-readable install instructions so it can copy the right Markdown files and skill folders for you.

The core behavior is:

• start with architecture before implementation
• generate or request an architecture diagram before meaningful code changes
• build in small code slices
• explain each slice before and after implementation
• define jargon as it appears
• keep the human as product owner and technical operator

This repo is designed for two audiences:

• Humans who want to copy the prompt into their LLM CLI.
• Agents that can read AGENT_INSTRUCTIONS.md and install the skill files for the user.

Agents that automatically inspect repo instructions can also start at AGENTS.md, which points them to the full install workflow.

Activate The Skill

After install, most skill-aware CLI agents can select it with:

$agent-teaching-mode

Some agents may also surface it when you type:

$teacher

The reliable installed skill name is agent-teaching-mode; $teacher depends on whether your agent app supports fuzzy skill selection or aliases.

Examples

Skill selection:

Teaching-mode output:

What Is Included

skills/
  agent-teaching-mode/
    SKILL.md
    references/
      teaching-rules.md
      explanation-checklist.md
  architecture-diagram-generator/
    SKILL.md
    assets/
      template.html
prompts/
  agent-teaching-mode.prompt.md
  architecture-first-build.prompt.md
AGENT_INSTRUCTIONS.md
AGENTS.md
THIRD_PARTY_NOTICES.md

Quick Use

If your CLI supports skill folders, copy the folders in skills/ into your agent's skill directory.

Common locations:

# Codex-style local skills
mkdir -p ~/.codex/skills
cp -R skills/agent-teaching-mode ~/.codex/skills/
cp -R skills/architecture-diagram-generator ~/.codex/skills/

# Claude Code-style local skills
mkdir -p ~/.claude/skills
cp -R skills/agent-teaching-mode ~/.claude/skills/
cp -R skills/architecture-diagram-generator ~/.claude/skills/

If your CLI does not support skill folders, copy the prompt from:

prompts/agent-teaching-mode.prompt.md

Agent Install

If you are an agent reading this repo on behalf of a user:

1. Read AGENT_INSTRUCTIONS.md.
2. Identify the user's active agent CLI.
3. Copy the relevant skill folders into that CLI's skill directory.
4. Preserve the third-party attribution for the architecture diagram skill.
5. Tell the user exactly what you installed and where.

Attribution

The architecture diagram generator included here is adapted from Cocoon AI's MIT-licensed project:

https://github.com/Cocoon-AI/architecture-diagram-generator

See THIRD_PARTY_NOTICES.md for attribution and license notes.