Agents Init

agents-init

Wire AGENTS.md (the cross-vendor agent-context convention) as the single source of truth, with CLAUDE.md as a symlink so Claude Code reads the same file. Idempotent — re-running on an already-wired repo is a no-op.

All filesystem mutation lives in scripts/wire_agents.py. Never use Bash mv / ln / cp / rm to manipulate CLAUDE.md or AGENTS.md directly — always invoke the script.

Resolve the script path once

At the start of every invocation, resolve the script path (handles version bumps):

SCRIPT="$(ls -d ~/.claude/plugins/cache/hideki-plugins/agents-init/*/skills/agents-init/scripts/wire_agents.py 2>/dev/null | sort -V | tail -1)"

If $SCRIPT is empty, the skill is not installed correctly — tell the user and stop.

Workflow

Critical — do not stop after /init. The deliverable of this skill is a CLAUDE.md symlink pointing to AGENTS.md, not a freshly-generated CLAUDE.md. When the needs-init branch delegates to /init, that's an intermediate step — /init returns control to you, and you MUST continue with --wire and the final verification in the same turn. The skill is complete only after Step 4 confirms the symlink exists.

Step 1: Detect state

From the project root the user wants to wire (do NOT change directory away from the user's cwd):

python "$SCRIPT" --detect

Stdout is one JSON line. For conflict, a unified diff is also printed to stderr.

{"state": "...", "platform": "linux|darwin|windows", "claude_is_symlink": false, "symlink_target": null, "claude_real_file": false, "agents_exists": false}

Possible state values: needs-init, ready-claude, ready-agents, identical, conflict, wired, foreign-symlink.

Step 2: Branch on state

When the script is invoked in --wire mode against a needs-init state, it returns an error — that's intentional, /init must run first.

needs-init detail (high-risk path — read every time)

The /init call is a multi-turn detour that can take significant work (codebase exploration, writing CLAUDE.md). When /init returns, the temptation is to treat the new CLAUDE.md as the deliverable and stop. Do not. That leaves the repo in ready-claude state — not the goal.

Required sequence, in the same skill invocation:

1. Run python "$SCRIPT" --detect → state is needs-init.
2. Invoke /init. Wait for it to return.
3. Immediately run python "$SCRIPT" --wire. This renames the just-created CLAUDE.md → AGENTS.md and creates the CLAUDE.md symlink.
4. Continue to Step 3 (Report) and Step 4 (Verify). Do not end your turn between any of these.

If you find yourself about to send a message to the user that says "CLAUDE.md created" without having run --wire first, you are about to fail this skill — go back and run --wire.

Step 3: Report

The --wire output is one JSON line with:

• actions — literal shell-style commands the script ran (e.g. mv CLAUDE.md AGENTS.md, ln -s AGENTS.md CLAUDE.md).
• warnings — any .gitignore issues.
• suggested_git — the commit command to recommend.

Relay all three to the user in a short message. Do NOT execute the git commit yourself — print it as a suggestion.

If actions contains a WARNING: file copy used line, surface it prominently — the user is on Windows and must re-run the skill after editing AGENTS.md.

Step 4: Verify wired (mandatory before declaring done)

After any successful --wire, re-run detection to confirm the end state:

python "$SCRIPT" --detect

The JSON state must be "wired". If it is anything else (ready-claude, needs-init, etc.), the wiring did not complete — surface the actual state to the user and stop; do not report success.

This step is non-negotiable on the needs-init path. It is the guardrail that catches the failure mode of "ran /init, forgot to wire". Skip only on wired (already verified in Step 1) and on aborted/foreign-symlink-declined runs.

Rules

• Never commit on behalf of the user. Print the suggested git command; let them run it.
• Never duplicate the script's filesystem logic in Bash. Every mutation goes through $SCRIPT.
• Never modify .gitignore. The script only warns when a file is ignored.
• Stay in the user's cwd. The script operates on ./CLAUDE.md and ./AGENTS.md — wherever the user invoked the skill from.

References

• references/state-matrix.md — full decision table with rationale per state. WHEN TO READ: only when you're unsure how to handle an edge case or want to confirm a branch's behavior. Routine invocations do not need it.
• references/scenarios.feature — Gherkin behavior spec. WHEN TO READ: only when auditing or amending this skill. Not needed for normal execution.

Retrospective

After completing the workflow, reflect on this run:

1. Were there mid-session corrections, rejected outputs, or errors during /init or wiring?
2. Ask the user: "Quick feedback on this run? (1-5 rating, note any issues, or press enter to skip)" If rating < 5, ALWAYS follow up: "Why this rating? (concrete details help me improve)" — record verbatim as Rating reason.
3. If the user provides feedback OR corrections occurred:
   • Create feedback/log.md next to this SKILL.md if missing (header # Feedback Log then a blank line and <!-- Append new entries at the top. Do not edit previous entries. -->).
   • Prepend a new entry per the format in references/skill-improvement-guide.md of the my-skill-factory skill: timestamp, Skill Version (from frontmatter), Task, Outcome, Rating, Rating reason, Corrections, Issues, User Note.
4. If the user skips AND no corrections or issues occurred, end without recording.