Migrate Claude distribution from legacy commands/ to standard skills/ format

[ktwu01]

Problem

The current npm install -g @scienceintelligence/researchskills-extract distribution uses postinstall hooks to copy files into legacy Claude Code paths:

• Bootstrap command → ~/.claude/commands/researchskills-extract.md
• 12 helper scripts → ~/.claude/utils/
• Extracted skills → ~/.claude/commands/researchskills/<slug>.md (frontmatter stripped)

Claude Code now recommends SKILL.md-based skills in ~/.claude/skills/ for new work. The current approach has concrete downsides:

1. Legacy path: ~/.claude/commands/ is legacy; ~/.claude/skills/ with SKILL.md is the current standard
2. Metadata loss: store-local.js:128 strips YAML frontmatter for Claude, losing skill metadata that the platform can use
3. Hidden side effects: postinstall hooks silently mutate ~/.claude/ and ~/.codex/ directories, which is surprising and hard to audit
4. Collision risk: Helper scripts copied to shared ~/.claude/utils/ namespace can collide with other tools
5. Aging worse: As Claude Code's skill ecosystem matures, this pattern will fall further behind

Note: The Codex CLI side already uses a proper SKILL.md directory structure (~/.codex/skills/researchskills-extract/SKILL.md), so only the Claude Code side needs migration.

Proposed Changes (incremental)

Phase 1: Migrate to skills/ format

• Move bootstrap from ~/.claude/commands/researchskills-extract.md to ~/.claude/skills/researchskills-extract/SKILL.md
• Colocate helper scripts in the skill directory (~/.claude/skills/researchskills-extract/scripts/) instead of ~/.claude/utils/
• Update extracted skill output from ~/.claude/commands/researchskills/<slug>.md to ~/.claude/skills/researchskills/<slug>/SKILL.md
• Preserve YAML frontmatter for Claude (stop stripping in store-local.js)

Phase 2: Replace postinstall with explicit install

• Replace hidden postinstall.js hook with an explicit install command or npx flow
• Keep cache management and version invalidation logic
• Keep dual-platform (Claude + Codex) support

Phase 3 (optional): Evaluate plugin marketplace

• Consider publishing as a Claude Code plugin for discoverability
• Assess UX tradeoffs (namespaced invocation, etc.)

Files to Change

• researchskills-extract/scripts/postinstall.js — change install targets
• researchskills-extract/scripts/postuninstall.js — change cleanup targets
• researchskills-extract/scripts/store-local.js — stop stripping frontmatter, change output paths
• researchskills-extract/commands/researchskills-extract.md — update script paths referenced in pipeline
• readme.md — update installation instructions

Context

• Codex CLI review confirmed this is medium priority, not urgent breakage
• The extraction pipeline itself (scan, classify, extract, clean, score, upload) is unaffected — only the distribution/installation mechanism changes
• Codex side is already using proper SKILL.md format, so Claude side should match

Priority

Medium — current system works but will age poorly as Claude Code's ecosystem evolves.