cc-dev-template 0.1.80 → 0.1.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.80",
+  "version": "0.1.81",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/skills/agent-browser/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-browser
-description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
+description: Browser automation CLI for AI agents. Use when interacting with websites — navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, or testing web apps.
 ---
 
 # Browser Automation with agent-browser
@@ -63,97 +63,6 @@ agent-browser screenshot --full       # Full page screenshot
 agent-browser pdf output.pdf          # Save as PDF
 ```
 
-## Common Patterns
-
-### Form Submission
-
-```bash
-agent-browser open https://example.com/signup
-agent-browser snapshot -i
-agent-browser fill @e1 "Jane Doe"
-agent-browser fill @e2 "jane@example.com"
-agent-browser select @e3 "California"
-agent-browser check @e4
-agent-browser click @e5
-agent-browser wait --load networkidle
-```
-
-### Authentication with State Persistence
-
-```bash
-# Login once and save state
-agent-browser open https://app.example.com/login
-agent-browser snapshot -i
-agent-browser fill @e1 "$USERNAME"
-agent-browser fill @e2 "$PASSWORD"
-agent-browser click @e3
-agent-browser wait --url "**/dashboard"
-agent-browser state save auth.json
-
-# Reuse in future sessions
-agent-browser state load auth.json
-agent-browser open https://app.example.com/dashboard
-```
-
-### Data Extraction
-
-```bash
-agent-browser open https://example.com/products
-agent-browser snapshot -i
-agent-browser get text @e5           # Get specific element text
-agent-browser get text body > page.txt  # Get all page text
-
-# JSON output for parsing
-agent-browser snapshot -i --json
-agent-browser get text @e1 --json
-```
-
-### Parallel Sessions
-
-```bash
-agent-browser --session site1 open https://site-a.com
-agent-browser --session site2 open https://site-b.com
-
-agent-browser --session site1 snapshot -i
-agent-browser --session site2 snapshot -i
-
-agent-browser session list
-```
-
-### Visual Browser (Debugging)
-
-```bash
-agent-browser --headed open https://example.com
-agent-browser highlight @e1          # Highlight element
-agent-browser record start demo.webm # Record session
-```
-
-### iOS Simulator (Mobile Safari)
-
-```bash
-# List available iOS simulators
-agent-browser device list
-
-# Launch Safari on a specific device
-agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
-
-# Same workflow as desktop - snapshot, interact, re-snapshot
-agent-browser -p ios snapshot -i
-agent-browser -p ios tap @e1          # Tap (alias for click)
-agent-browser -p ios fill @e2 "text"
-agent-browser -p ios swipe up         # Mobile-specific gesture
-
-# Take screenshot
-agent-browser -p ios screenshot mobile.png
-
-# Close session (shuts down simulator)
-agent-browser -p ios close
-```
-
-**Requirements:** macOS with Xcode, Appium (`npm install -g appium && appium driver install xcuitest`)
-
-**Real devices:** Works with physical iOS devices if pre-configured. Use `--device "<UDID>"` where UDID is from `xcrun xctrace list devices`.
-
 ## Ref Lifecycle (Important)
 
 Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after:
@@ -168,49 +77,14 @@ agent-browser snapshot -i            # MUST re-snapshot
 agent-browser click @e1              # Use new refs
 ```
 
-## Semantic Locators (Alternative to Refs)
-
-When refs are unavailable or unreliable, use semantic locators:
-
-```bash
-agent-browser find text "Sign In" click
-agent-browser find label "Email" fill "user@test.com"
-agent-browser find role button click --name "Submit"
-agent-browser find placeholder "Search" type "query"
-agent-browser find testid "submit-btn" click
-```
-
-## Deep-Dive Documentation
-
-| Reference | When to Use |
-|-----------|-------------|
-| [references/commands.md](references/commands.md) | Full command reference with all options |
-| [references/snapshot-refs.md](references/snapshot-refs.md) | Ref lifecycle, invalidation rules, troubleshooting |
-| [references/session-management.md](references/session-management.md) | Parallel sessions, state persistence, concurrent scraping |
-| [references/authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, state reuse |
-| [references/video-recording.md](references/video-recording.md) | Recording workflows for debugging and documentation |
-| [references/proxy-support.md](references/proxy-support.md) | Proxy configuration, geo-testing, rotating proxies |
-
-## Ready-to-Use Templates
-
-| Template | Description |
-|----------|-------------|
-| [templates/form-automation.sh](templates/form-automation.sh) | Form filling with validation |
-| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, reuse state |
-| [templates/capture-workflow.sh](templates/capture-workflow.sh) | Content extraction with screenshots |
-
-```bash
-./templates/form-automation.sh https://example.com/form
-./templates/authenticated-session.sh https://app.example.com/login
-./templates/capture-workflow.sh https://example.com ./output
-```
+## Reference Files
 
-## Reflect After Use
+For common patterns (forms, auth, data extraction, parallel sessions, debugging), read `references/common-patterns.md`.
 
-After completing the browser automation task, reflect on your experience.
+For semantic locators as an alternative to refs, read `references/semantic-locators.md`.
 
-Were any commands, flags, patterns, or workarounds in this reference incorrect or missing? Did you discover a command syntax, a workaround for a specific site, or a pattern that should be documented here?
+For iOS Simulator and mobile Safari automation, read `references/ios-simulator.md`.
 
-If yes, update the relevant section of this skill file. Only add tribal knowledge — commands and patterns a fresh Claude instance would not know about agent-browser specifically. Keep within size targets.
+## Reflect
 
-Tell the user what you updated, or confirm no updates were needed.
+Use the Read tool on `references/reflect.md` to reflect on the browser automation and note any skill issues.

package/src/skills/agent-browser/references/common-patterns.md

@@ -0,0 +1,64 @@
+# Common Patterns
+
+## Form Submission
+
+```bash
+agent-browser open https://example.com/signup
+agent-browser snapshot -i
+agent-browser fill @e1 "Jane Doe"
+agent-browser fill @e2 "jane@example.com"
+agent-browser select @e3 "California"
+agent-browser check @e4
+agent-browser click @e5
+agent-browser wait --load networkidle
+```
+
+## Authentication with State Persistence
+
+```bash
+# Login once and save state
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "$USERNAME"
+agent-browser fill @e2 "$PASSWORD"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Reuse in future sessions
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+## Data Extraction
+
+```bash
+agent-browser open https://example.com/products
+agent-browser snapshot -i
+agent-browser get text @e5           # Get specific element text
+agent-browser get text body > page.txt  # Get all page text
+
+# JSON output for parsing
+agent-browser snapshot -i --json
+agent-browser get text @e1 --json
+```
+
+## Parallel Sessions
+
+```bash
+agent-browser --session site1 open https://site-a.com
+agent-browser --session site2 open https://site-b.com
+
+agent-browser --session site1 snapshot -i
+agent-browser --session site2 snapshot -i
+
+agent-browser session list
+```
+
+## Visual Browser (Debugging)
+
+```bash
+agent-browser --headed open https://example.com
+agent-browser highlight @e1          # Highlight element
+agent-browser record start demo.webm # Record session
+```

package/src/skills/agent-browser/references/ios-simulator.md

@@ -0,0 +1,25 @@
+# iOS Simulator (Mobile Safari)
+
+```bash
+# List available iOS simulators
+agent-browser device list
+
+# Launch Safari on a specific device
+agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
+
+# Same workflow as desktop - snapshot, interact, re-snapshot
+agent-browser -p ios snapshot -i
+agent-browser -p ios tap @e1          # Tap (alias for click)
+agent-browser -p ios fill @e2 "text"
+agent-browser -p ios swipe up         # Mobile-specific gesture
+
+# Take screenshot
+agent-browser -p ios screenshot mobile.png
+
+# Close session (shuts down simulator)
+agent-browser -p ios close
+```
+
+**Requirements:** macOS with Xcode, Appium (`npm install -g appium && appium driver install xcuitest`)
+
+**Real devices:** Works with physical iOS devices if pre-configured. Use `--device "<UDID>"` where UDID is from `xcrun xctrace list devices`.

package/src/skills/agent-browser/references/reflect.md

@@ -0,0 +1,9 @@
+# Reflect After Use
+
+After completing the browser automation task, reflect on your experience.
+
+Were any commands, flags, patterns, or workarounds in this reference incorrect or missing? Did you discover a command syntax, a workaround for a specific site, or a pattern that should be documented here?
+
+If yes, update the relevant section of this skill file. Only add tribal knowledge -- commands and patterns a fresh Claude instance would not know about agent-browser specifically. Keep within size targets.
+
+Tell the user what you updated, or confirm no updates were needed.

package/src/skills/agent-browser/references/semantic-locators.md

@@ -0,0 +1,11 @@
+# Semantic Locators (Alternative to Refs)
+
+When refs are unavailable or unreliable, use semantic locators:
+
+```bash
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find role button click --name "Submit"
+agent-browser find placeholder "Search" type "query"
+agent-browser find testid "submit-btn" click
+```

package/src/skills/claude-md/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: claude-md
-description: Manages CLAUDE.md files in a project. Activates when the user says "audit CLAUDE.md files", "update CLAUDE.md", "add to CLAUDE.md", or invokes /claude-md. With no arguments, audits all CLAUDE.md files. With arguments, intelligently updates the appropriate file.
+description: Manage CLAUDE.md files in a project. With no arguments, audits all CLAUDE.md files for accuracy and completeness. With arguments, intelligently updates the appropriate file.
 ---
 
 # CLAUDE.md Management
 
-Base directory for this skill: ~/.claude/skills/claude-md
-
 ## What To Do
 
 Check if arguments were provided:

package/src/skills/claude-md/references/audit-reflect.md

@@ -1,9 +1,5 @@
 # Audit Reflection
 
-**IMPORTANT: This step is mandatory. The audit workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience auditing the project's CLAUDE.md files. The purpose is to improve the claude-md skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/claude-md/references/audit.md

@@ -62,6 +62,4 @@ Remaining concerns:
 - [any issues needing human decision]
 ```
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read references/audit-reflect.md now.
+Use the Read tool on `references/audit-reflect.md` to reflect on the audit and note any skill issues.

package/src/skills/claude-md/references/create-reflect.md

@@ -1,9 +1,5 @@
 # Create Reflection
 
-**IMPORTANT: This step is mandatory. The create workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience creating a new CLAUDE.md file. The purpose is to improve the claude-md skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/claude-md/references/create.md

@@ -71,6 +71,4 @@ Verify:
 
 If all yes, proceed to the reflection step.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read references/create-reflect.md now.
+Use the Read tool on `references/create-reflect.md` to reflect on the creation process and note any skill issues.

package/src/skills/claude-md/references/modify-reflect.md

@@ -1,9 +1,5 @@
 # Modify Reflection
 
-**IMPORTANT: This step is mandatory. The modify workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience modifying the project's CLAUDE.md files. The purpose is to improve the claude-md skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/claude-md/references/modify.md

@@ -51,6 +51,4 @@ If the content would make the file exceed ~100 lines, consider:
 
 Tell the user what was added and where. If creating a new CLAUDE.md file, explain why that location was chosen.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read references/modify-reflect.md now.
+Use the Read tool on `references/modify-reflect.md` to reflect on the modification and note any skill issues.

package/src/skills/creating-agent-skills/SKILL.md

@@ -11,8 +11,8 @@ Ask the user what they need.
 
 | Intent | Action |
 |--------|--------|
-| Create a new skill | Read `references/create-step-1-understand.md` |
-| Fix, improve, audit, or modify an existing skill | Read `references/fix-step-1-diagnose.md` |
+| Create a new skill | Use the Read tool on `references/create-step-1-understand.md` to start the creation workflow |
+| Fix, improve, audit, or modify an existing skill | Use the Read tool on `references/fix-step-1-diagnose.md` to diagnose the issue |
 
 If the user says "audit my skills", that is the fix path.
 If they mention a specific skill that needs changes, that is also the fix path.

package/src/skills/creating-agent-skills/references/create-step-1-understand.md

@@ -48,4 +48,4 @@ Move on when all of these are true:
 - You understand WHY the approaches work, not just WHAT they are
 - The user confirms you understand their needs
 
-Read `references/create-step-2-design.md`.
+Use the Read tool on `references/create-step-2-design.md` to design the skill's structure.

package/src/skills/creating-agent-skills/references/create-step-2-design.md

@@ -164,7 +164,7 @@ Every procedural skill must end with a dedicated reflection step file. This is a
 
 The reflection step is where the agent looks back on its experience using the skill and, if the instructions were wrong, incomplete, or suboptimal, updates the skill files. This creates a self-learning loop — skills improve through use.
 
-The chain link to the reflection step must use mandatory language. The agent must understand that the workflow is incomplete without it. Example: "**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**"
+The chain link to the reflection step must use the redirect pattern — frame reading the reflection step as how the agent presents results to the user. Example: "Use the Read tool on `references/step-N-reflect.md` to review your work and report results to the user."
 
 For informational skills, append a reflection section to the end of SKILL.md (since there is no step chain).
 
@@ -201,5 +201,5 @@ Ask: "Does this design look right?"
 
 | Context | Action |
 |---------|--------|
-| Creating a new skill | Read `references/create-step-3-write.md` |
-| Fixing an existing skill (came from fix-step-1-diagnose) | Read `references/fix-step-2-apply.md` to apply the structural changes |
+| Creating a new skill | Use the Read tool on `references/create-step-3-write.md` to write the skill files |
+| Fixing an existing skill (came from fix-step-1-diagnose) | Use the Read tool on `references/fix-step-2-apply.md` to apply the structural changes |

package/src/skills/creating-agent-skills/references/create-step-3-write.md

@@ -113,7 +113,7 @@ Each step file covers ONE phase of the workflow. Structure each file:
 
 1. A clear header naming the step
 2. Immediate actionable instructions — what to do NOW
-3. A chain link at the bottom: "Read `references/[next-step].md`" with an optional condition
+3. A chain link: "Use the Read tool on `references/[next-step].md` to [what the next step accomplishes]"
 
 **Critical rules:**
 - No table of contents across steps
@@ -144,8 +144,8 @@ description: [third person, trigger phrases, WHEN not HOW]
 
 | Choice | Action |
 |--------|--------|
-| Option A | Read `references/step-1-a.md` |
-| Option B | Read `references/step-1-b.md` |
+| Option A | Use the Read tool on `references/step-1-a.md` to [what it accomplishes] |
+| Option B | Use the Read tool on `references/step-1-b.md` to [what it accomplishes] |
 ```
 
 Keep it minimal. Only include context that is needed at EVERY activation.
@@ -165,19 +165,51 @@ Every procedural skill must have a dedicated reflection step as the final file i
 
 **The reflection step file** should contain:
 
-1. **Mandatory language at the top**: Start with "**IMPORTANT: This step is mandatory. The [workflow name] workflow is not complete until this step is finished. Do not skip this.**"
-2. **Assessment**: Domain-specific questions — "Were any instructions wrong, incomplete, or misleading? Did you have to figure something out that the skill should have told you? Did any commands, paths, or patterns fail and require correction?"
-3. **Action**: "If yes, identify the specific file where the issue lives, read it, and apply the fix. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know."
-4. **Report**: "Tell the user what you changed and why, or confirm that no updates were needed."
+1. **Assessment**: Domain-specific questions — "Were any instructions wrong, incomplete, or misleading? Did you have to figure something out that the skill should have told you? Did any commands, paths, or patterns fail and require correction?"
+2. **Action**: "If yes, identify the specific file where the issue lives, read it, and apply the fix. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know."
+3. **Report**: "Tell the user what you changed and why, or confirm that no updates were needed."
 
 Tailor the assessment questions to the skill's domain — what "went wrong" means for a prompting skill is different from what it means for a browser automation skill.
 
-**The chain link to the reflection step** (in the previous step file) must use mandatory language. Do not use a soft chain link. Example:
+### Chain Links Between Steps
 
+Chain links connect one step to the next. The key challenge: after a heavy generation step, the model's completion impulse is strong — it wants to present results and stop. Chain links must redirect that impulse rather than fight it.
+
+**The redirect pattern:**
+
+```
+Use the Read tool on `references/step-N-[name].md` to [what the next step accomplishes for the user].
+```
+
+This works because it frames reading the next step as HOW the model accomplishes what it already wants to do (present results, finish the task).
+
+**Why the old "IMPORTANT: You are not done" pattern fails:** Negative framing ("you are NOT done") fights the completion impulse head-on. After heavy generation, the model has strong momentum toward completion and ignores imperative warnings. The redirect pattern harnesses that momentum instead.
+
+**Pre-work priming:** At the TOP of generation-heavy steps (before the work begins), add a framing line:
+
+```
+These are drafts — review and present final results in the next step.
+```
+
+This primes the model to expect a follow-up step, reducing the completion impulse before it builds.
+
+**Integration rules:**
+- Place chain links INSIDE the action section, not as a separate afterthought section
+- For the final work step before reflection/presentation: frame the next step as where results get presented to the user
+- Keep chain links to one line — no multi-line bold warnings
+
+**Before/after example:**
+
+Before (old pattern — fails after heavy generation):
 ```
 **IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Read `references/step-N-reflect.md` now.
+Read `references/step-4-reflect.md` now.
+```
+
+After (redirect pattern — works with the completion impulse):
+```
+Use the Read tool on `references/step-4-reflect.md` to review your work and report results to the user.
 ```
 
 For informational skills (no step chain), append a reflection section to the end of SKILL.md instead.
@@ -208,4 +240,4 @@ With these principles applied, write all the skill files now:
 2. For procedural: each step file in `references/`
 3. Any `scripts/` or `templates/` files if the design calls for them
 
-Read `references/create-step-4-review.md` when all files are written.
+Use the Read tool on `references/create-step-4-review.md` to review all files before proceeding.

package/src/skills/creating-agent-skills/references/create-step-4-review.md

@@ -45,7 +45,7 @@ Go through each file and verify:
 - Description uses third person with quoted trigger phrases?
 - All referenced files exist? (no broken links)
 - For procedural skills: dedicated reflection step file as the final step in the chain?
-- Chain link to reflection step uses mandatory language? ("IMPORTANT: You are not done. You MUST read and complete the next step.")
+- Chain link to reflection step uses redirect pattern? ("Use the Read tool on `references/...` to review your work and report results to the user.")
 - For informational skills: reflection section at the end of SKILL.md?
 - For forked-context skills: "Skill Observations" section in the output format?
 
@@ -64,4 +64,4 @@ Only proceed when validation passes and self-review is clean.
 
 If you found and fixed issues, re-run both the self-review and validation to confirm.
 
-Read `references/create-step-5-install.md` when review passes with no remaining issues.
+Use the Read tool on `references/create-step-5-install.md` to install and test the skill.

package/src/skills/creating-agent-skills/references/create-step-5-install.md

@@ -62,6 +62,4 @@ Summarize what was created:
 - Trigger phrases
 - File structure (list all files)
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/create-step-6-reflect.md` now.
+Use the Read tool on `references/create-step-6-reflect.md` to review your work and report results to the user.

package/src/skills/creating-agent-skills/references/create-step-6-reflect.md

@@ -1,8 +1,6 @@
 # Step 6: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The skill creation workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience creating this skill. The purpose is to improve the creating-agent-skills skill itself based on what you just learned.
+Reflect on your experience creating this skill and report results to the user. This step improves the creating-agent-skills skill itself based on what you just learned.
 
 ## Assess
 

package/src/skills/creating-agent-skills/references/fix-step-1-diagnose.md

@@ -74,10 +74,11 @@ Evaluate each file against these criteria:
 
 ### Self-Learning
 - For procedural skills: does the skill have a dedicated reflection step file as the final step in its chain?
-- Does the chain link to the reflection step use mandatory language? ("IMPORTANT: You are not done. You MUST read and complete the next step.")
+- Does the chain link to the reflection step use the redirect pattern? (e.g., "Use the Read tool on `references/step-N-reflect.md` to review your work and report results to the user.")
+- Do chain links use positive redirect framing, not negative warnings like "IMPORTANT: You are not done"?
 - For informational skills: is there a reflection section at the end of SKILL.md?
 - For forked-context skills (`context: fork`): does the output format include a "Skill Observations" section?
-- If missing or embedded as a section in another step file, flag it — every procedural skill needs a separate mandatory reflection step.
+- If missing or embedded as a section in another step file, flag it — every procedural skill needs a separate reflection step.
 
 ## Summarize Findings
 
@@ -114,5 +115,5 @@ Tell the user which type of fix is needed.
 
 | Fix Type | Action |
 |----------|--------|
-| Surface fixes only | Read `references/fix-step-2-apply.md` |
-| Structural changes needed | Read `references/create-step-2-design.md` first to design the new structure, then read `references/fix-step-2-apply.md` to apply |
+| Surface fixes only | Use the Read tool on `references/fix-step-2-apply.md` to apply the fixes |
+| Structural changes needed | Use the Read tool on `references/create-step-2-design.md` to design the new structure, then read `references/fix-step-2-apply.md` to apply |

package/src/skills/creating-agent-skills/references/fix-step-2-apply.md

@@ -94,7 +94,7 @@ Does this justify its token cost? If Claude already knows it — remove it. If i
 
 **Fix description:** Rewrite to third person, add quoted trigger phrases, focus on WHEN not HOW.
 
-**Add reflection step:** Create a dedicated reflection step file as the final step in the chain. Add a mandatory chain link from the previous final step using "**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**" See `references/create-step-3-write.md` "Reflection Step" section for the full writing guidance. For informational skills, append a reflection section to the end of SKILL.md instead. For forked-context skills, add a "Skill Observations" section to the output format instead.
+**Add reflection step:** Create a dedicated reflection step file as the final step in the chain. Add a redirect chain link from the previous final step: "Use the Read tool on `references/step-N-reflect.md` to review your work and report results to the user." See `references/create-step-3-write.md` "Chain Links Between Steps" section for the full pattern. For informational skills, append a reflection section to the end of SKILL.md instead. For forked-context skills, add a "Skill Observations" section to the output format instead.
 
 ## Apply the Changes
 
@@ -102,4 +102,4 @@ Make all planned modifications now.
 
 For structural changes that involve writing new files (new step files, new SKILL.md sections, new scripts), reference `references/create-step-3-write.md` for the complete writing guidance — it covers size targets, step file structure, MCP tool references, and anti-patterns in more depth than the principles above.
 
-Read `references/fix-step-3-validate.md` when all fixes are applied.
+Use the Read tool on `references/fix-step-3-validate.md` to validate and test the fixes.

package/src/skills/creating-agent-skills/references/fix-step-3-validate.md

@@ -53,6 +53,4 @@ Summarize what was fixed:
 - What was wrong and how it was resolved
 - Confirm with the user that the skill now behaves as expected
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/fix-step-4-reflect.md` now.
+Use the Read tool on `references/fix-step-4-reflect.md` to review your work and report results to the user.

package/src/skills/creating-agent-skills/references/fix-step-4-reflect.md

@@ -1,8 +1,6 @@
 # Step 4: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The skill fix workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience fixing this skill. The purpose is to improve the creating-agent-skills skill itself based on what you just learned.
+Reflect on your experience fixing this skill and report results to the user. This step improves the creating-agent-skills skill itself based on what you just learned.
 
 ## Assess
 

package/src/skills/creating-agent-skills/templates/router-skill.md

@@ -11,6 +11,6 @@ Ask the user what they need.
 
 | Intent | Action |
 |--------|--------|
-| {{First option}} | Read `references/{{first-workflow}}.md` |
-| {{Second option}} | Read `references/{{second-workflow}}.md` |
-| {{Third option}} | Read `references/{{third-workflow}}.md` |
+| {{First option}} | Use the Read tool on `references/{{first-workflow}}.md` to {{what it accomplishes}} |
+| {{Second option}} | Use the Read tool on `references/{{second-workflow}}.md` to {{what it accomplishes}} |
+| {{Third option}} | Use the Read tool on `references/{{third-workflow}}.md` to {{what it accomplishes}} |

package/src/skills/creating-sub-agents/references/create-step-1-understand.md

@@ -43,4 +43,4 @@ Move on when all of these are true:
 - Tool requirements are known
 - The user confirms you understand their needs
 
-Read `references/create-step-2-design.md`.
+Use the Read tool on `references/create-step-2-design.md` to design the sub-agent's configuration.

package/src/skills/creating-sub-agents/references/create-step-2-design.md

@@ -178,4 +178,4 @@ Present the complete design:
 
 Ask: "Does this design look right?"
 
-Read `references/create-step-3-write.md` after confirmation.
+Use the Read tool on `references/create-step-3-write.md` to write the sub-agent's system prompt.

package/src/skills/creating-sub-agents/references/create-step-3-write.md

@@ -151,4 +151,4 @@ With these principles applied, write the complete `.md` file now:
 1. YAML frontmatter with all designed configuration
 2. System prompt body following the structure above
 
-Read `references/create-step-4-review.md` when the file is written.
+Use the Read tool on `references/create-step-4-review.md` to review the sub-agent before installation.

package/src/skills/creating-sub-agents/references/create-step-4-review.md

@@ -64,4 +64,4 @@ Handle results:
 
 Only proceed when validation passes and self-review is clean.
 
-Read `references/create-step-5-install.md` when review passes.
+Use the Read tool on `references/create-step-5-install.md` to install and test the sub-agent.

package/src/skills/creating-sub-agents/references/create-step-5-install.md

@@ -75,6 +75,4 @@ Summarize what was created:
 - Memory scope (if any)
 - Skills preloaded (if any)
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/create-step-6-reflect.md` now.
+Use the Read tool on `references/create-step-6-reflect.md` to reflect on the creation process and note any skill issues.