Skip to content

AlpacaLabsLLC/skills-for-architects / skills/learn

Guided, hands-on course teaching architects how to use Codex or Claude Code — six short modules, each built around an exercise on a bundled sandbox project (a fictional Brooklyn art museum expansion). Resumable across sessions via PROGRESS.md. Use when the user runs $learn or /as:learn, says they're new to AI-assisted project work, or asks how to learn it.

# Learn — Codex and Claude Code

A resumable, hands-on course teaching architects how to use Codex or Claude Code. Six modules, most ~15–20 minutes, each built around an exercise on the bundled sandbox project — a fictional Brooklyn art museum planning a rooftop expansion (`sandbox/art-museum/`, six deliberately messy files).

## Usage

| Host | Start | Resume |
|---|---|---|
| Codex | `$learn` | `$learn` reads `PROGRESS.md` and resumes |
| Claude Code | `/as:learn` | `/as:learn` reads `PROGRESS.md` and resumes |

Progress is tracked in `PROGRESS.md` in the practice folder (default `~/architecture-studio-101`; the earlier `~/claude-code-101` location is recognized). Delete it to restart the course.

On Claude Code, the first-session notice points to `/as:studio` or `/as:learn`. Codex has no equivalent Claude hook; start with `$studio` or `$learn` directly.

## Design

- **Do, then explain** — the learner's hands are on the keyboard within a few sentences of any teach beat.
- **The tutor never does the exercise for them** — it guides and reviews.
- **Studio analogies throughout** — `AGENTS.md` (Codex) or `CLAUDE.md` (Claude Code) is the standards binder, skills are capability cards describing outcomes, constraints and checks, markdown is plain paper.
- **Three ideas thread the course**: this version stores project files locally while sending prompts and needed file contents to the configured Codex or Claude service, Arch Studio is an open-source harness on both hosts (fork it, make it your own), and course/project memory is plain files you can read. Future cloud-based versions may require accounts and work differently.
- **One worksurface for firm extensions**: the course uses a sandbox-local skill, while real firm-created skills default to the initialized studio’s `.agents/skills/` on Codex or `.claude/skills/` on Claude Code; ordinary users do not maintain the installed plugin source.
- **Module 6 closes with real work** — a source-check drill (trace claims to their lines, then ask about what the document *doesn't* say), a short professional checklist (firm policy, low-stakes, work on a copy — recommended, never imposed), and one real task end to end. Data privacy is taught back in Module 2, where consent is taught. The learner can quit `$learn` or `/as:learn` at any moment, no questions asked.
- The sandbox files are engineered: the CSV has a duplicate row, mixed units, and a TBD; `IMG_4032.txt` is a mislabeled voice memo; `Scan_001.txt` is a regulatory excerpt with enough specifics to make an invented claim plausible — and deliberate silences to plant it in.

An advanced track — bigger jobs, plan mode, subagents, skill authorship in depth, running the office skill library — is planned as a follow-on course. Its precedent material keeps distinct teaching examples outside the installable `skills/` tree and points task-management lessons to the canonical `/as:tasklist` implementation instead of duplicating it.

## Bundled material

| Directory | Used in | Contents |
|-----------|---------|----------|
| `sandbox/` | Modules 1–6 | The fictional Greenpoint Museum of Art — six deliberately messy files with engineered flaws |
| `templates/` | Module 3 | `office-CLAUDE.md`, copied as `AGENTS.md` on Codex or `CLAUDE.md` on Claude Code |
| [`../../assets/learn-examples/`](../../assets/learn-examples/) | Advanced track (planned) | Two distinct, non-installable example skills to study and modify: `ascii-name` and `clean-downloads` |
| [`../tasklist/`](../tasklist/) | Advanced track (planned) | The canonical task-management skill to study and invoke as `$tasklist` on Codex or `/as:tasklist` on Claude Code; it is referenced rather than copied |
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall