import-claude-skill

name	import-claude-skill
description	Analyze a Claude Code skill bundle and generate a full-fidelity GitHub incident for Codex import work via github-incident-from-observation. Use when the user asks to import, convert, port, or create an implementation incident for a Claude Code skill, including related hooks, subagents, and commands.

Import Claude Skill

Use this skill to analyze a Claude Code skill bundle and create a GitHub work-order incident for the Codex import. This skill is incident-first: it does not copy, convert, sync, or edit runtime files during use.

Inputs

• claude_skill_location is required. Accept a path to a Claude skill directory or its SKILL.md.
• mode is optional: real or eval. Default to real.
• severity is optional: critical, high, medium, or low. Default to medium.

Workflow

1. Run scripts/analyze_claude_skill.py --claude-skill-location <path> from the repo root. Add --eval only when the user requested eval mode. The script writes:
   • tmp/import-claude-skill/<skill-name>/analysis.json
   • tmp/import-claude-skill/<skill-name>/observation.md
2. Read the generated observation markdown and verify that it lists:
   • the normalized Claude skill path;
   • paired source/runtime Claude skill paths, when present;
   • related agents, hooks, and commands;
   • the agent conversion analysis (agent_conversion) — one entry per related top-level Claude agent with source path, source/runtime pair status, parsed frontmatter, body feature flags, tools, model, skill preload array, referenced files, handoff/work-contract indicators, matching Codex agent path, existing Codex metadata, and a decision of convert / already-present / update-existing / exclude / blocked, rendered as the ## Agent conversion analysis section;
   • the hook configuration analysis (hook_settings) — one entry per related Claude settings hook with its event, matcher, command path and basename, timeout, source setting path and line, the Codex-surface comparison (codex_compatible, codex_hook_exists, codex_registration_exists), and a decision of convert / already-present / exclude / blocked, rendered as the ## Hook configuration analysis section;
   • the command replacement analysis (command_conversion) — one entry per related top-level Claude command with the source path, command name, parsed frontmatter, argument-hint, Skill(command="...") invocation targets, referenced Claude agents, command references directory, checked Codex command/prompt paths, destination paths when a supported Codex source/runtime surface exists, and a decision of convert-to-existing-surface / unsupported-no-surface / exclude / blocked, rendered as the ## Command replacement analysis section;
   • the import strategy decision (import_strategy) — a deterministic object with selected, rejected, and evidence, rendered as the ## Import strategy section;
   • evidence gates: analysis_status, analysis_blockers, validation_results, duplicate_scan, compliance_reference_status, rendered as validation, duplicate-preflight, and compliance-reference sections;
   • proposed Codex targets;
   • compliance blockers, including loader-invalid frontmatter and descriptions over 1024 characters;
   • the remediation plan (remediation_plan) — always present in analysis.json, empty when no blockers exist, and rendered as the ## Remediation plan section grouped by file;
   • Codex skill quality findings for prompt-engineering and authoring best practices;
   • exact acceptance criteria and validation commands.
3. If analysis failed, stop and report the error. Do not guess a skill name or target.
4. Delegate to $github-incident-from-observation with:

observation_text=<contents of tmp/import-claude-skill/<skill-name>/observation.md>
label_type=enhancement
severity=<severity>
originating_work=import-claude-skill <claude_skill_location>
related=codex-skills-compliance workflow artifacts

5. Let $github-incident-from-observation own preview, duplicate scan, recurrence handling, approval, and posting.

Guardrails

• Do not call gh issue create from this skill.
• Do not edit Claude source/runtime files.
• Do not edit Codex source/runtime files.
• Do not invent a Codex command or prompt install surface. If the analyzer finds Claude commands and no supported Codex command/prompt source/runtime surface exists, command_conversion[].decision must be unsupported-no-surface and destination_paths must be empty.
• Keep generated incidents full-fidelity, zero-ambiguity, and non-aspirational.

Analysis Contract

• Hard blockers must include Codex loader contract failures: invalid YAML frontmatter, missing or non-string name, invalid lowercase-hyphenated name, folder/name mismatch, missing or non-string description, and description longer than 1024 characters.
• Hard blockers must continue to include Claude runtime paths, Claude provider tool-call notation, unsupported auxiliary docs, source/runtime mirror drift, and non-Codex Claude frontmatter fields.
• analysis.json must always include remediation_plan; when no blockers exist it is an empty list.
• Each remediation_plan item must include path, line_start, line_end, blocker_type, old_text, status, and rule_id.
• remediation_plan[].status is exactly one of auto-rewrite, manual-decision, or blocked.
• auto-rewrite entries must include exact replacement_text. manual-decision and blocked entries must not invent replacement text; they must include a concrete decision_question.
• Advisory quality findings must identify prompt-engineering and skill-authoring gaps without turning them into loader blockers. These include missing trigger boundaries, missing inputs/outputs, missing validation or done criteria, missing trigger-test examples, oversized monolithic SKILL.md files without bundled-resource routing, deprecated command/custom-prompt patterns, and missing agents/openai.yaml when provider/tool metadata needs Codex metadata.
• Generated observations must render both blocker and advisory sections so the downstream GitHub incident can separate required remediation from accepted advisory tradeoffs.
• Generated observations must include the remediation plan grouped by file with line numbers, blocker type, status, rule id, old text, deterministic replacement text when present, and decision question when present.
• Generated observations must include the hook configuration analysis: the analyzer parses the Claude settings files (.claude/settings.json, src/claude/settings.json), emits hook_settings in analysis.json (one entry per settings hook related to the skill, with event/matcher/command/basename/timeout/source-path/line and the Codex-surface comparison), and renders a ## Hook configuration analysis section so each related hook carries a convert / already-present / exclude / blocked decision rather than an unwired file reference.
• Generated observations must include the command replacement analysis: the analyzer parses each related top-level Claude command file, emits command_conversion in analysis.json (always a list, empty when no related commands exist), and renders a ## Command replacement analysis section so each related command carries the checked Codex command/prompt paths, any computed destination paths, invocation targets, and the exact conversion decision.
• Generated observations must include the agent conversion analysis: the analyzer parses each related top-level Claude agent file, emits agent_conversion in analysis.json (one entry per related top-level Claude agent with parsed frontmatter, body feature flags, tools, model, skill preloads, referenced files, handoff/work-contract indicators, matching Codex agent path, existing Codex metadata, and the conversion decision), and renders a ## Agent conversion analysis section so each related agent carries a convert / already-present / update-existing / exclude / blocked decision plus the exact metadata-change or blocker/exclusion reason.
• Generated observations must include the import strategy decision: the analyzer emits import_strategy.selected, import_strategy.rejected, and import_strategy.evidence in analysis.json, and renders a ## Import strategy section. The selected strategy is exactly one of codex-owned-copy, generated-mirror, symlink, or blocked.
• import_strategy.evidence.file_inventory records every Claude skill bundle file or symlink with repo-relative path, tree-relative path, suffix, mode_octal, executable bit, symlink metadata, size, SHA-256 for regular files, and binary detection. Executable helpers and binary files select blocked until a packageability decision exists.
• generated-mirror is selected only when both Codex target skill trees contain .devforgeai-generated-mirror and no higher-priority blocking evidence exists. Without both markers, generated-mirror is rejected with generated-mirror-marker-missing.
• Symlink evidence records symlink_target; unsupported symlinks reject the symlink strategy with symlink-not-packageable.

Import mode

The analyzer classifies every run by inspecting the Codex target trees (src/codex/skills/<name> and .codex/skills/<name>) and comparing them, byte-for-byte (SHA-256), against the Claude source/runtime trees. It writes schema_version: "2.0", an import_mode field, and a target_conflicts object to analysis.json.

• import_mode is exactly one of:
  • new-import — neither Codex target exists; this is a fresh import.
  • update-existing — both Codex targets exist but differ from the Claude source; target_conflicts.changed_files lists the differing paths and target_conflicts.claude_vs_codex_diff carries each path's claude_sha256 / codex_sha256.
  • blocked-conflict — the two Codex mirror copies (src/codex vs .codex) disagree, or exactly one of them exists (asymmetric mirror); target_conflicts.codex_mirror_drift lists the drift.
  • no-op-current — the Codex targets are byte-identical to the Claude source; no update is needed.
• target_conflicts always carries codex_source_exists, codex_runtime_exists, codex_mirror_drift, claude_vs_codex_diff, changed_files, and a one-line reason.
• The classification is a byte-identity drift check, not a semantic-lag detector: a correctly-transformed Codex skill is never byte-identical to its Claude source (Claude runtime paths and tool-call notation are stripped during import), so an already-imported skill normally reports update-existing.
• Generated observations must render an ## Import mode section that states the selected import_mode and the exact evidence used (changed files, mirror drift, or "no Codex target").

Grounding References

The analyzer embeds these compliance references in every observation:

• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/codex-skills-compliance-workflow.html
• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/progress.md
• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/manifest.json
• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/00-baseline-inventory.md
• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/01-compliance-contract.md
• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/02-category-map.md
• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/03-conversion-log.md
• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/04-packaging-log.md
• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/05-validation-log.md
• worktrees/codex-skills-compliance/tmp/codex-skills-compliance/06-handoff.md