Practice - document a complex procedure

Simple procedures make good first skills. Complex procedures are where skill files earn their keep. This session is about the harder case: a procedure with multiple branches, dependencies, and failure modes that interact.

What this actually is

A complex procedure is one where the path through the steps changes based on what happens at certain checkpoints. The output of step three determines which version of step five you run. A partial failure in step six means you need to decide whether to continue or roll back.

Documenting a complex procedure requires encoding that branching logic explicitly. If the skill file only covers the happy path, it will fail at the first branch.

Walk-through

Pick a procedure with at least five steps and two common failure modes that you have actually encountered. Good candidates:

• Setting up a new development environment from scratch (operating system, dependencies, accounts)
• Migrating a database schema in production with zero downtime
• Debugging a production incident from alert to resolved
• Onboarding a new engineer to a large codebase

Start by writing the happy path. Get the steps right when nothing goes wrong. Then add the branches.

Here is the branch encoding pattern:

3. Run database migration: `npm run db:migrate`
   - If exit 0: proceed to step 4
   - If exit 1 with "duplicate column": the migration was already applied — skip to step 4
   - If exit 1 with any other message: stop, do not proceed, follow the rollback procedure in Gotchas

4. Verify migration: `npm run db:verify-schema`

The branch is inside the step, not in a separate section. This keeps the step self-contained and the agent does not have to jump between sections to understand what to do.

If/then logic for agent skills

Agent skills can use a simplified if/then notation:

5. Check deployment target:
   - If `DEPLOY_TARGET=staging`: run `npm run deploy:staging`
   - If `DEPLOY_TARGET=production`: run `npm run deploy:prod`
   - If `DEPLOY_TARGET` is unset: stop and report "DEPLOY_TARGET is required"

The agent reads all three branches and executes the one that matches the current environment. This is more reliable than putting the branch logic in a shell script because it is visible in the skill file where the agent can reason about it.

Requirements for this session

• At least five numbered steps
• At least two branch points (if/then conditions)
• A gotchas section with at least three entries, each with trigger, symptom, and recovery
• At least one dependency on another skill (real or invented)

If you get stuck

If the branching logic is getting complicated: draw it as a flowchart first, then translate the flowchart into steps. The flowchart reveals where the branches are and what conditions trigger them.

If you have a step that depends on the outcome of a branch from a previous step: use an explicit state variable. "If step 3 took the rollback path, skip steps 4-6 and go directly to step 7."

If the procedure is too complex for one file: split it. The main skill file describes the top-level procedure and calls sub-skills for each major branch. This is the same pattern as calling a function from another function.

Deliverable

A complete skill file with branches, dependencies, and a comprehensive gotchas section. The success criterion: run the skill through Claude on a safe target — staging, a test repo, a local environment. Claude should not ask for clarification at any branch point, because the branch conditions are explicit.