init-agentic-skills

Init Agentic Skills

Invoke as $init-agentic-skills.

Make the base agentic-skills available by installing them project-local into the current project's .claude/skills and .codex/skills. Installation is distributed through the npm skillpacks package — there is no user-home (global) install path. Active installs are repo-managed directories that expose the canonical SKILL.md and exclude archive/; pinned installs intentionally point at archive/<version>. Keep domain packs project-local too; use the Guided Pack Setup below, or npx skillpacks install <pack-or-skill> when packs are needed.

Process

1. Parse $ARGUMENTS:
   • No args, init, or refresh: run npx skillpacks init from the project root to install the base skills project-local (.claude/skills + .codex/skills) and enable base_skills in .agents/project.json. Use npx skillpacks refresh instead when the project is already initialized and you only need to recreate roots from .agents/project.json.
   • status: run npx skillpacks status to report the project designation, enabled packs, and installed skills.
   • doctor: run npx skillpacks doctor to report project skill-install drift (read-only). It compares installed .claude/skills and .codex/skills copies against their canonical sources via the .agentic-skills-managed marker's source_sha. Report STALE skills with the printed fix command, unknown skills as needing a refresh to enable tracking, missing skills whose source is gone, and pinned skills as frozen. Run npx skillpacks doctor --fix to clean generated skill-root drift.
   • uninstall-global: run npx skillpacks uninstall-global only after confirming the user wants legacy repo-managed base installs removed from ~/.claude/skills and ~/.codex/skills. This cleans up installs created by the retired user-home init path; it removes only skillpacks-owned installs and leaves unmanaged directories untouched.
   • help, --help, or -h: run npx skillpacks --help.
2. Report the command run, the project skill directories, installed counts, and any warnings about non-repo-managed collisions.
3. Explain pack access separately:
   • Do not install packs/* as base skills.
   • In the project that needs domain workflows, run the Guided Pack Setup below, or npx skillpacks install <pack-or-skill> from the project shell for an explicit pack or individual pack skill.
   • If a project already has .agents/project.json, run scripts/pack.sh refresh (or npx skillpacks refresh) after this base initialization to recreate local pack skill roots.
4. If the active session still cannot see a newly installed or refreshed skill, report the skill-visibility reload path:
   • Claude Code: run /reload-skills first; /clear starts a new empty-context conversation and can pick up the refreshed registry; restart if the top-level .claude/skills directory did not exist at session start or the skill is still invisible.
   • Codex: start a fresh Codex CLI session if the $ skill list remains stale.

Guided Pack Setup

Run this when the user wants to enable domain packs in a project and has not named an explicit pack list.

1. If .agents/project.json exists, run scripts/pack.sh refresh to recreate local pack skill roots from committed project state, then report the project type, enabled packs, and installed skills. If refresh fails, report the failure and the exact command the user can retry.
2. If .agents/project.json is missing, inspect the repository before asking the user:
   • Run scripts/pack.sh recommend.
   • Check top-level files and directories, package manifests, app/framework configs, source layout, docs, existing research/, specs/, and tasks/ files.
   • Classify likely packs using the Pack Selection rules below.
   • Present a concise recommendation with evidence.
   • Present a plain-text Pack Decision Checkpoint (template below): show 2-4 numbered choices, mark the recommended choice, explain the tradeoff for each, and ask the user to reply with a number, exact pack list, status, or cancel. Include kanban only as an explicit opt-in when there is evidence of PoketoWork usage or the user asked for kanban.
   • Stop after the checkpoint. Do not install anything until the user explicitly confirms a choice in a later message.
   • After the user confirms, run the source-checkout helper scripts/pack.sh install <pack...>. For package consumers outside this checkout, the equivalent project-shell route is npx skillpacks install <pack...>.
3. For install, refresh, and guided setup installs, report:
   • .agents/project.json project type and enabled packs
   • any enabled_skills entries when present, including the skill name and source pack
   • any project_scopes entries when present, including the path, project_type, packs, and purpose
   • local skill roots created or removed under .claude/skills and .codex/skills
   • any skipped roots caused by non-repo-managed targets
   • shipping guidance: .agents/project.json is the committed project designation and should be committed when pack configuration changed; .claude/skills/** and .codex/skills/** are generated local skill roots recreated by scripts/pack.sh refresh, and generated skill roots must not be staged or committed

Do not create .agents/project.json without user confirmation during guided setup.

Pack Decision Checkpoint

Use this format when Codex needs user confirmation and request_user_input is unavailable:

## Pack Decision Checkpoint

Detected:
- [evidence]

Recommendation: `<pack>` because [reason].

Choose one:
1. `<pack>` (Recommended) — [impact/tradeoff]
2. `<alternate-pack>` — [impact/tradeoff]
3. `<pack> <matching-kanban-pack>` — [impact/tradeoff]
4. `cancel` — leave the project unconfigured

Reply with a number or an exact pack list to install.

Pack Selection

• Use business-discovery, customer-lifecycle, business-growth, or business-ops for SaaS, marketplaces, productivity apps, internal/admin tools, business workflows, and enterprise applications. business-app is a compatibility alias for all four.
• Use creator-foundation, youtube-ops, and remotion separately for creator-media work; creator-media is a compatibility alias for foundation plus YouTube operations.
• Use project-fleet for control repositories that manage downstream repos, spec-store portfolios, or spin-offs.
• Use code-quality as an additive pack for behavior-preserving refactors, type hygiene, import honesty, dependency-boundary cleanup, and module organization.
• Use alignment-loop for lightweight operator-agent calibration before committing to a full spec-interview pipeline.
• Use game for video games, prototypes, playable entertainment, game engines, store pages, playtest loops, and game assets.
• Use devtool for SDKs, CLIs, APIs, libraries, infrastructure products, developer platforms, and documentation-first developer workflows.
• PoketoWork kanban packs (business-app-kanban, devtool-kanban, game-kanban, and poketowork-kanban) are hibernated while Poketo.work is being rebuilt. Do not recommend or install kanban packs until they are reactivated.
• Use exec-loop for the plan-exec-ship execution workflow (ship, run, ship-end).
• Use agent-work-admin for roadmap management, phase planning, and spec-drift auditing.
• Use product-design for UX exploration, prototyping, feature/spec/UI interviews, brainstorming, and design systems.
• Use code-review for expert reviews, slim audits, dead-code scans, and regression checks.
• Use code-debug for investigation, debugging, and request tracing.
• Use release-ops for branch lifecycle management, deployment, and releases.
• Use product-testing for UAT journeys and dogfooding.
• Use docs-health for project hygiene auditing and dev-docs reconciliation.
• Use research-admin for research and documentation queue management.
• Use skill-dev for building, interviewing, and creating agentic skills.
• Use guided-walkthrough for step-by-step guides and UAT walkthroughs.
• Use session-analytics for session history analysis and incident triage.
• Use teardown for project teardowns and decommissioning.
• Use code-maintenance for migrations and package updates.
• Use gitops for git sync and feature-based commit workflows.
• Use context-transfer for session handoffs.
• Use agent-bridge for delegating work to other agents.
• Use repo-maintenance for bootstrapping new repos.
• Use website-polish for icon and web asset handling.
• Use report-gen for generating HTML report websites.
• Use knowledge-check for quiz-style knowledge reviews.
• Use exec-profile for execution profile patching.
• Use alignment-page-admin for compiling central alignment pages.
• Treat monorepo and code-quality as overlays. Pair overlays with a domain pack unless the user explicitly wants only the overlay behavior.
• For workflow ordering, lead-in recommendations, and overlay dependencies, read docs/pack-workflow-matrix.md.

Mixed Monorepos

Use one repo-level .agents/project.json with a primary default plus scoped overrides:

{
  "project_type": "devtool",
  "enabled_packs": ["devtool", "business-discovery", "customer-lifecycle", "business-growth"],
  "skill_pack_version": 1,
  "project_scopes": [
    {
      "path": "apps/pitwall-local",
      "project_type": "devtool",
      "packs": ["devtool"],
      "purpose": "Pitwall Local / OSS developer utility work."
    },
    {
      "path": "apps/pitwall-calcllm",
      "project_type": "business-app",
      "packs": ["business-discovery", "customer-lifecycle", "business-growth"],
      "purpose": "CalcLLM-powered connected edition research, GTM, monetization, and SaaS product work."
    },
    {
      "path": "packages/calcllm-sync",
      "project_type": "business-app",
      "packs": ["business-discovery", "customer-lifecycle", "business-growth"],
      "purpose": "Connected-edition sync and SaaS integration work."
    }
  ]
}

When a task clearly names a scoped path, route to that scope's project_type and packs. When no scope matches, use the top-level project_type as the default.

Constraints

• Drive installation through npx skillpacks (the npm skillpacks CLI); do not recreate install logic by hand or reintroduce a user-home/global install path.
• Base skills are project-local: they install into the current project's .claude/skills and .codex/skills, not into ~/.claude/skills or ~/.codex/skills.
• Do not overwrite real directories or files under .claude/skills or .codex/skills that are not repo-managed.
• Treat packs as project-local capabilities managed through the Guided Pack Setup above or scripts/pack.sh (npx skillpacks under the hood).
• Stop and report exact errors if npx skillpacks fails.
• Do not install packs/* as base skills in any mode.

Default Shipping Contract

Follow the shared shipping contract convention in CLAUDE.md.