Devtool DX Journey — agentic-skills

Terminology note (2026-06-05): References to install.sh in this document reflect the installer name at time of writing. The script has since been renamed to init.sh. See README.md for current commands.

Scope: maps the developer experience of adopting and living with this specific repo — the agentic-skills shared skill library — from install through long-term retention. Grounded in observable repo signals (README.md, install.sh, scripts/pack.sh, scripts/agent-mode.sh, scripts/skill-deps.sh, scripts/skill-versions.sh, docs/operating-modes.md, docs/packs.md, CLAUDE.md, .agents/project.json). Not a generic devtool DX playbook.

Continuity: this is the third step in the devtool research chain and assumes the audience framing from research/devtool-user-map.md (solo builders, repo-embedded contributors, hybrid-mode orchestrators) and the setup mechanics from research/devtool-integration-map.md (two-CLI symlink install, .agents/project.json project designation, CLI-restart requirement). Sections below should be read as the lived sequence a developer moves through, not as discrete, optional stations.

Install

The install is a one-time, two-layer move: global core skills once per machine, plus pack enablement once per project.

• Preconditions (out of scope of this repo but load-bearing): Claude Code CLI and/or OpenAI Codex CLI installed and authenticated, bash, git, symlink-capable filesystem, writable $HOME. See research/devtool-integration-map.md § "Required integrations". The user who has zero AI-coding CLIs installed yet will spend more calendar time on vendor signup and auth than on this repo.
• Clone to a stable path. git clone <repo> ~/some/persistent/path && cd ~/some/persistent/path. The checkout path is load-bearing: project-local symlinks created later point at this absolute path. Moving or renaming the checkout breaks every consumer project silently (research/devtool-integration-map.md § "Migration risks" — checkout-path coupling).
• Run ./install.sh. Symlinks global/claude/ into ~/.claude/skills/ and global/codex/ into ~/.codex/skills/ (install.sh:130–135). Prints a per-skill Installed ... line and a final Installed N ... skills -> ... summary (install.sh:140–144). Stale symlinks pointing at deleted skills are swept first (install.sh:131–132), so re-running is safe.
• Domain packs are not installed globally — on purpose. install.sh:142 prints: Domain packs were not installed globally. Use scripts/pack.sh install <pack> from a project. This is an intentional context-hygiene decision: a B2B SaaS session should not load game-design skills, and a game repo should not load monetization-research skills. The DX cost is one extra explicit step per project; the DX benefit is no cross-contamination.
• Uninstall is symmetrical. ./install.sh --uninstall removes only symlinks that point back into this checkout (install.sh:33–39, 115–128). Hand-authored or third-party skills in ~/.claude/skills or ~/.codex/skills are not touched. There is no install.sh --uninstall --dry-run; a user who wants to preview must inspect the script.

Known friction at install time:

• No installer detects missing CLIs. install.sh does not check whether claude or codex is on $PATH. A user who installs before installing either CLI sees success, then finds the skills silently unreachable at first invocation.
• No version pin advertised. The install doesn't print a repo version; scripts/skill-versions.sh covers per-skill version fields (version: 1.0.0 in each SKILL.md), but there is no repo-level "you just installed agentic-skills vX" message.

Quickstart

Quickstart is the first few minutes after install, where the developer points the library at a real project and gets a working .agents/project.json.

• From inside Claude Code or Codex, invoke the pack skill with no arguments. /pack (Claude) or $pack (Codex) runs the guided setup: it detects whether .agents/project.json exists, offers pack recommend if it does not, and writes the file on confirmation. The Codex surface is semantically identical (pack:packs/devtool/codex/pack/).
• Or run the script directly. /path/to/agentic-skills/scripts/pack.sh recommend reads project signals (language, framework hints, existing files) and suggests devtool, business-app, game, or code-quality. scripts/pack.sh install <pack> creates .agents/project.json with project_type, enabled_packs, and skill_pack_version, then symlinks pack skills under .claude/skills/ and .codex/skills/ (see docs/packs.md § "Local Symlinks").
• Optionally set the operating mode. scripts/pack.sh set-mode claude-only|codex-only|hybrid|unset, or export SKILLS_AGENT_MODE=... for a shell-scoped override. scripts/agent-mode.sh resolves the effective mode as env > file > unset (docs/operating-modes.md § "Mode-signal resolution"). A first-time user can skip this step entirely — modes only matter once they want hybrid delegation.
• Restart the CLI. README.md:51 and docs/packs.md:43 explicitly warn: pack.sh refresh does not hot-reload an already-running Claude Code or Codex session. The user must exit and restart. This is the most-cited piece of quickstart friction in the repo and is called out verbatim in README.md, docs/packs.md, and research/devtool-user-map.md § "Adoption blockers".
• Commit .agents/project.json. docs/packs.md:79 directs committing the designation file but not .claude/skills/ / .codex/skills/ (which are per-checkout). A teammate pulling the commit regenerates symlinks via pack.sh refresh or /pack with no arguments.

Time-to-first-skill-invocation for a user who already has one CLI installed and authenticated: roughly 5–15 minutes, dominated by reading the /pack guided flow and the CLI restart round-trip. For a user who has never used either CLI, add whatever the vendor signup flow costs.

First success

First success is the moment an invocation of a repo-shipped skill visibly changes the project in a useful, reversible way — validating the install and the project designation.

• Canonical first success: a /run (or $run) cycle. From within Claude Code or Codex, the developer types /run or $run. The skill at global/{claude,codex}/run/SKILL.md plans the next incomplete step from tasks/todo.md (or the current phase from tasks/roadmap.md with --phase), enters plan mode for approval, and on approval executes exactly that step. This exercises plan-mode-first, ship-one-step, and the task-file protocol in a single round-trip.
• If tasks/todo.md is empty or missing, /run falls back to inviting the user to run /roadmap or /research-roadmap first. This is the honest "there is nothing to run yet" path — the developer does not hit a cryptic failure, they see an explicit "no pipeline queued" message and a next-command suggestion.
• Alternative first-success path: a research skill. For the devtool pack in particular, $devtool-user-map / $devtool-integration-map produce visible research artifacts under research/. The artifact is a committed Markdown file with a known section contract; success is a file that exists, passes a quick read-over, and unblocks the next chain step in tasks/todo.md.
• Visible signals of success. A green /run cycle produces: a dated tasks/history.md entry, one or more commits on the primary branch (commit-and-push-by-feature), and an updated tasks/todo.md line tick. Failure modes are loud — plan-mode denial, tool-permission denial, or skill-not-found messages. There is no silent-failure class for a standard /run path.

Known friction at first success:

• Plan-mode approval UX is CLI-specific. Claude Code uses EnterPlanMode / ExitPlanMode tools and renders an approval UI. Codex does not have an equivalent modal gate — its $run flow prints the plan and waits for a confirmation message. The two experiences are not interchangeable; a user switching harnesses mid-session will be briefly confused.
• Task-file discipline is a precondition. A repo without tasks/todo.md and tasks/roadmap.md cannot productively use /run. The /roadmap and /research-roadmap skills bootstrap these, but the sequence is not obvious at first encounter. A new user can spend several minutes looking for a "do a thing" button before realizing the library is pipeline-driven by design.

Error recovery

The repo's error recovery is a small set of audit scripts plus two reconciliation skills. Errors show up in predictable places; recovery is explicit, not auto-healing.

• Missing or broken skill references: scripts/skill-deps.sh --broken. Walks every SKILL.md, extracts cross-referenced file paths and skill names, and reports missing ones. Run this first when /run or /plan complains about a missing skill.
• Missing version frontmatter: scripts/skill-versions.sh --missing. Flags SKILL.md files without a version: field. Run after creating or editing a skill. Pairs with --check-bumped elsewhere in the workflow.
• Skills invisible to the CLI: restart the CLI. By far the most common first-session error. Symptoms: /pack install devtool succeeded, but /devtool-user-map "doesn't exist". Fix: exit the CLI, start a fresh session. README.md:51, docs/packs.md:43, and research/devtool-user-map.md § "Adoption blockers" all surface this because it is the single most frequent support question a first-time user would ask.
• Corrupt or stale local symlinks: scripts/pack.sh refresh. Rebuilds .claude/skills/ and .codex/skills/ from the current .agents/project.json. Safe to re-run. Still requires a CLI restart after.
• Docs drifted from code: $spec-drift or /reconcile-dev-docs. spec-drift audits specs/.md against implementation and reports diverged and unimplemented features. reconcile-dev-docs reconciles tasks/roadmap.md, tasks/todo.md, tasks/history.md, tasks/phases/, specs, and git history against each other. Neither fixes code — they produce correction todos and optional mechanical patches. Historical evidence in tasks/history.md (e.g. $spec-drift fix packs/business-app//scale-audit, $spec-drift fix approval-packet references) shows these are the repo's actual recovery path when documentation and implementation diverge.
• Approval-packet mismatch in hybrid mode. When /delegate or /handoff --target=codex produces a packet Codex cannot consume, the immediate symptom is a schema-validation failure against specs/approved-plan.schema.json. Recovery is to regenerate the packet from the current Claude session after confirming schema parity, not to hand-edit the JSON.
• Lost pack lock on a crashed session. scripts/pack.sh acquires a mutex at .agents/.pack.lock/ (scripts/pack.sh:44–58). A crashed pack install leaves the directory behind; pack.sh times out after 30 seconds. Manual recovery: rmdir .agents/.pack.lock once the user confirms no other pack.sh process is running.

What is notably absent from the recovery surface:

• No rollback tooling. install.sh --uninstall and pack.sh remove revert current state; neither captures the previous .agents/project.json to restore (research/devtool-integration-map.md § "Migration risks"). A misbehaving pack install is recovered by re-running the previous install and restarting the CLI, not by a one-command undo.
• No skill-behavior test harness. skill-deps.sh and skill-versions.sh validate references and frontmatter, not behavior. A SKILL.md whose contract says "produces sections A/B/C" and which actually produces only A/B is not caught until a human reads the output. Combined with the explicit No GitHub Actions rule in CLAUDE.md, there is no CI gate — drift is caught by spec-drift / reconcile-dev-docs sessions.
• No hot reload. As above: every recovery path that touches skills ends with "restart the CLI".

Production adoption

"Production" for this library is the steady-state where a developer runs the full plan → run → ship cycle on the primary branch of a real project, with agent-authored commits and task-file updates as the visible work.

• The adoption loop is ship-one-step. CLAUDE.md § "Always Ship Mutations" and the ship-one-step handoff contract define the cadence: /plan writes a self-contained next-step plan, the user approves, a clear-context session implements exactly one step, validates, updates tasks/todo.md and tasks/history.md, commits and pushes via /commit-and-push-by-feature, and ends in plan mode for the next approval. The commits in this repo's own git log (e.g. a2a092e, 35f8ff5, 87e7316) are literal artifacts of this loop.
• Direct-to-primary git flow. CLAUDE.md § "Core Principles" — commits land on master (or main) by default, no feature branches unless the user explicitly asks. This is a real DX choice: it trades PR-review overhead for shorter cycle time and makes the task-file protocol the review surface. Teams that require PR-per-change will have to override per-invocation or fork the skills (research/devtool-integration-map.md § "Compatibility constraints").
• No GitHub Actions. CLAUDE.md hard-codes this. Production validation is the user's local scripts/skill-deps.sh, scripts/skill-versions.sh, plus whatever project-specific tests the consumer repo runs. This is a deliberate simplicity bet; it is also the source of the "no automated gate" risk called out in research/devtool-integration-map.md § "Migration risks".
• Docs stay live with code via dated tasks/history.md entries. Every shipped step writes a ## YYYY-MM-DD — <title> section describing what changed and why. Over time this becomes the primary changelog; there is no separate CHANGELOG.md at the repo root. git log plus tasks/history.md is the production audit trail.
• Archive-first for canonical doc rewrites. Before substantively rewriting a research/.md or specs/.md file, the operator snapshots the old file under docs/history/archive/YYYY-MM-DD/HHMMSS/<original-path>. Append-only edits and new files skip this step. The policy is manual discipline, not tooling-enforced, which is both its flexibility and its weakness (a forgetful session can silently overwrite canonical thinking).
• Skill versioning is explicit and mechanical. Each SKILL.md carries a version: field; scripts/skill-versions.sh --check-bumped catches unchanged versions on edited skills. A pack that promotes a new skill bumps that skill's version; the repo as a whole does not publish a consumer-facing version (consumers pin to a git SHA if they want stability — see research/devtool-integration-map.md § "Compatibility constraints").

Observable production signals in this repo right now: 14 ticked items in the current priority documentation todo section (tasks/todo.md:1007–1020), a tasks/history.md that spans weeks with daily-cadence entries, and three commits on master in the last hour from the most recent ship-one-step cycle.

Team rollout

Team rollout is where the individual-tool DX meets multi-developer discipline. This repo's team story is lighter than its solo story, with specific friction points.

• The commit-and-regenerate contract. One developer installs a pack, commits .agents/project.json to the team's project, and pushes. Teammates pull, run /pack with no arguments (or scripts/pack.sh refresh from the CLI-external path), and restart their CLIs. docs/packs.md:79 hard-codes this contract: the designation file travels with the repo; the symlinks do not.
• Every developer clones agentic-skills to the same relative path. Because project-local symlinks are absolute paths back to the checkout, a team that agrees on ~/code/agentic-skills (or equivalent) avoids per-developer pack.sh refresh pain. Teams that each put the checkout wherever convenient pay that cost forever. The repo does not document a recommended path; this is something a team should standardize in its own onboarding doc (research/devtool-user-map.md § "Adoption blockers" — no CONTRIBUTING.md).
• Operating mode is a per-developer choice, not a per-team choice. .agents/project.json can set agent_mode, but SKILLS_AGENT_MODE overrides per-shell. A team lead who commits agent_mode: "hybrid" to enforce the planner/executor split cannot force individual developers into that mode — a developer who only has one CLI installed will see the shell override win. This is correct design for a library that doesn't assume uniform vendor subscriptions; it is also a gap if the team wants strict uniformity.
• Skill authorship is a 2x cost. A team that writes its own shared skills pays the dual Claude/Codex mirror tax on every skill unless it accepts a Claude-only surface like /delegate. research/devtool-integration-map.md § "Migration risks" calls this out as perpetual: the cost is paid at authoring time and again at every refactor. Teams that author many skills should budget for the drift-catching discipline ($spec-drift) and for the $reconcile-dev-docs cycles that keep the two sides aligned.
• Session-restart chore compounds at scale. A five-developer team rotating through ten repos each hitting a pack refresh sees the restart cost five, ten, or more times per week in aggregate. This is the single biggest thing an automation layer could improve; none exists in this repo today (research/devtool-integration-map.md § "Migration risks" — session-restart chore compounds).
• No shared skill registry. Teams that want a private skill library fork agentic-skills, add their skills under packs/<team-pack>/, and point each project at the fork. The create-skill → pack promote flow under global/{claude,codex}/create-skill/ is designed for this. There is no alternative "publish to a registry" path — the git repo is the registry.

Team rollout honestly lands better in small organizations (≤15 engineers, one to three repos) where standardization is social rather than contractual. A larger org will want a CONTRIBUTING doc, an automated skill-contract test harness, a published version, and possibly a central skill registry — none of which this repo ships today.

Retention

Retention is the set of habits that keep a developer coming back to the library three weeks, three months, three years after install. This repo's retention story is unusual: it retains users who internalize the workflow and loses users who don't.

• Plan-mode-first becomes muscle memory. CLAUDE.md § "Workflow Orchestration" treats plan-mode-first as a default, not advice. A developer who adopts it stops typing free-form requests to the CLI and starts typing /plan or $plan for any non-trivial change. Retention flows from the reduced rework — fewer abandoned sessions, fewer "wait, that's not what I wanted" course corrections. The retention hook is the quality difference between unplanned and planned agent output, which is visible within a few sessions.
• Ship-one-step becomes the unit of progress. Each step ships, updates tasks/todo.md and tasks/history.md, commits, pushes, and ends in a plan-mode-ready state for the next step. A developer who adopts this reports progress in units of "one ship cycle" rather than "one work session". The retention hook is the visible forward motion — tasks/history.md grows, commits land on primary, the next step is already pre-planned.
• Tasks-as-docs replaces changelog discipline. tasks/roadmap.md, tasks/todo.md, tasks/history.md, and tasks/phases/ together form a living project narrative. Retention hook: a developer who returns to a repo after two months reads tasks/history.md + tasks/todo.md and is caught up in minutes, without hunting through commits or wikis.
• Self-improvement loop via tasks/lessons.md. CLAUDE.md § "Self-Improvement Loop" directs writing patterns after corrections. Users who actually maintain this file report a measurable drop in repeated mistakes over time; users who don't, don't. The retention hook is tool quality compounding with use — the library gets more useful to that specific developer over months.
• Hybrid mode gradually pulls in the second CLI. A developer who starts Claude-only and later installs Codex unlocks /delegate and /handoff --target=codex. The pack and mode design lets them opt in per project. Retention hook: the path from single-CLI to hybrid does not require a migration — the same project keeps working, it just gains a new option.
• Create-skill + pack promote turns the library into a personal dotfile. global/{claude,codex}/create-skill/ scaffolds a user-local skill under ~/.claude/skills/ or ~/.codex/skills/; the pack promote flow moves it into a pack fork. Retention hook: long-term users accumulate their own skills on top of the library and come to treat their fork of agentic-skills the way they treat their shell config — a personal artifact that grows.

Observable anti-retention signals in this repo — honest failure modes:

• The session-restart chore. Multiple restarts per day, per project, every time packs change. A user who never internalizes the cause-and-effect of pack.sh refresh + restart churns on "my skills disappeared" and leaves.
• The 2x mirror tax. A user who edits only one side of a Claude/Codex pair will see $spec-drift catch it eventually — but if they never run the drift audit, the mirror rots silently. The retention hook here is negative: silently rotted skills make the library feel unreliable.
• The terminology cliff. "Global", "pack", "operating mode", "approval packet", "archive-first", "ship-one-step", "implementation-safe vs review-only" — research/devtool-user-map.md § "Adoption blockers" calls this out. A developer who bounces off the vocabulary in the first session never returns.
• The dense operating-modes doc. docs/operating-modes.md is authoritative and long. A developer who needs it at 11pm on a first install and doesn't finish it pattern-matches the library as "heavy" and defaults back to raw CLI usage.
• No version pin, no deprecation contract. A user tracking master accepts that skill names and behavior can shift. That shift is almost always captured in tasks/history.md, but a user who missed the history entry will experience a skill they relied on quietly changing shape. Retention survives if the user pins to a SHA; it leaks if they don't and don't read history.

The retained-user profile, concretely: someone who has written at least one of their own skills, maintains tasks/lessons.md, has ship-one-step in their fingers, and treats the agentic-skills repo as part of their editing environment rather than as a tool they invoke. The churned-user profile: someone who installed once, hit the restart chore, hit the terminology cliff, didn't find a short-form quickstart, and went back to raw Claude Code or Codex.