Skill Creation (planning + creation + review)

This skill runs three flows: planning (/skill-plan), creation (/skill-create), and review (/skill-review). Keep the main conversation clean; heavy work runs in agents via Agent Runner with registry-based resolution.

Planning Flow (wizard)

1. Confirm goal: new skill package vs update/version bump (capture desired version target if known).
2. Capture responsibilities + success criteria; list primary use cases.
3. Command UX: required args, options, --help text; defaults for --name, behavior of --from (seed from existing skill/plan), and --template (plan skeleton file). Enforce naming convention: file path .claude/commands/<name>.md, frontmatter name: <name> (no slash), user invocation /name (slash added by system), default version 0.1.0.
4. Agents: propose candidate agents, inputs/outputs, fenced JSON envelopes, and registry versions.
5. File layout: commands under .claude/commands, skills under .claude/skills/<name>/SKILL.md, agents under .claude/agents, references/templates under .claude/references (if needed) for easy testing before packaging. Default versions for commands/skills/agents: 0.1.0 unless explicitly overridden.
6. Keep agent set minimal by default; only add extra agents when scope justifies it. Prefer clear roles (e.g., intake, fix, PR) over many micro-agents.
7. Statusing: mark plan as Preliminary, then Proposed after user confirms; generate 40–80 line overview with full plan path when user approves (Approved). Planning must not create artifacts—only write/update a plan file. Creation happens only via /skill-create.

Implementation notes

• Use Agent Runner; resolve agents by name+version from .claude/agents/registry.yaml.
• Store plans by default in plans/<name>.md; allow override when user supplies a path or --template. Do not overwrite request/input files—write to a new plan file/path when invoked with a request doc.
• If --from is set, load referenced artifact(s) and summarize key facts into the plan.
• Maintain concise outputs; omit tool traces.

Agent Runner prompt snippets (planning)

• Planning call template:

Invoke Agent Runner with:
  agent: "skill-planning-agent"
  registry: .claude/agents/registry.yaml
  params:
    goal: "new|update"
    target_name: "<skill name>"
    plan_path: "<plans/path.md>"
    from_paths: [<paths from --from if any>]
    template_path: "<template if provided>"

• Ensure response is fenced JSON with the minimal envelope; include summary, actions, open_questions, plan.path, plan.status.

Agent delegation (planning)

• Invoke skill-planning-agent with collected inputs. Require fenced JSON output with minimal envelope:

```json
{ "success": true, "data": { "summary": "...", "actions": [] }, "error": null }

- If plan incomplete, include open questions and next actions in the overview; otherwise provide summary + full plan path.

## Creation Flow
1) Input: approved plan path.
2) Generate stubs for command/skill/agents/references at version 0.1.0 using naming convention:
   - File path: `.claude/commands/<name>.md`
   - Frontmatter name: `<name>` (no slash)
   - User invocation: `/name` (slash added by system)
3) Populate references listed in the plan (e.g., required reference files).
4) Update registry with new agents and skill dependency constraints (including manage-worktree when git ops are needed).
5) Prepare report/temp directories if absent: `.claude/reports/skill-reviews/`, `.claude/.tmp/skill-reviews/`, `.claude/.prompts/`.

## Review Flow
1) Identify target (name/path) and scope (command|skill|agent|all; default all).
2) Ask user where to write the report (default `.claude/reports/skill-reviews/<target>-report.md`; if unavailable, offer `.claude/.tmp/skill-reviews/`).
3) Ensure the chosen report directory exists (create it if missing) before writing.
4) Invoke `skill-review-agent` to evaluate against `docs/claude-code-skills-agents-guidelines-0.4.md` and registry/version rules.
5) Present concise findings; if `--fix`, include suggested edits/snippets but do not write files.

### Agent delegation (review)
- Agent Runner call template:

Invoke Agent Runner with: agent: "skill-review-agent" registry: .claude/agents/registry.yaml params: target: "" scope: "command|skill|agent|all" report_path: "<.claude/reports/skill-reviews/... or .claude/.tmp fallback>" fix: true|false

- Require fenced JSON output:

{ "success": true, "data": { "issues": [{ "severity": "error", "path": "...", "rule": "..." }], "summary": "..." }, "error": null }

- Ensure checks: version frontmatter present, registry alignment, fenced JSON outputs, minimal envelopes, safety/approval notes, progressive disclosure (SKILL body lean with references).

## Safety
- Creation of plan/review files is allowed; avoid destructive repo changes.
- Explicitly ask before writing reports to a user-provided location; default to temp path to avoid clutter.
- Keep outputs concise; no tool traces in main conversation.
- Base branch/worktree defaults: honor `.claude/config.yaml` if present (`base_branch`, `worktree_root`); otherwise default to `main` and a repo-named worktree root. For git operations, instruct reuse of manage-worktree skill.
- Registry expectations: include manage-worktree dependency when git ops are needed; use constraints like `manage-worktree: "0.x"`. Ensure new agents/skills are added with version 0.1.0 by default.