# Implementation Plan: agent-skill-creator v4.0 — Cross-Platform Modernization

> Generated by `/clarity` on 2026-02-26
> Full spec: `.clarity/spec.md`
> Handoff: `.clarity/handoff.md`
> Holdout scenarios: `scenarios/` (59 scenarios covering all 28 FRs + 7 NFRs)

---

## Summary

Modernize agent-skill-creator from a Claude-only meta-skill (v3.2) to a cross-platform skill factory (v4.0) that generates skills compliant with the **Agent Skills Open Standard** (agentskills.io). Skills will work on Claude Code, GitHub Copilot CLI, VS Code Copilot, Cursor, Windsurf, Cline, OpenAI Codex CLI, Gemini CLI, and any future SKILL.md adopter — without modification.

## What Changes

| Area | Before (v3.2) | After (v4.0) |
|------|---------------|--------------|
| SKILL.md | 4,116 lines (monolith) | <500 lines + references/ |
| marketplace.json | Non-standard fields (Issue #5) | Official fields only, optional |
| Naming | `-cskill` suffix mandatory | Standard kebab-case, no suffix |
| Platforms | 4 (Claude Code/Desktop/Web/API) | 8+ (all SKILL.md adopters) |
| Validation | None | Spec compliance + security scan |
| Install UX | Manual per-platform | `install.sh` auto-detects platform |
| Phase 5 output | marketplace.json first | SKILL.md first (primary file) |

## What Stays the Same

- 5-phase pipeline (Discovery → Design → Architecture → Detection → Implementation)
- AgentDB integration (optional, graceful degradation)
- Simple skill vs Complex suite architecture support
- Desktop/Web .zip export and API .zip export
- All activation trigger phrases

## Implementation Steps (8 steps, ~3 phases)

### Phase A: Fix the Meta-Skill Itself

**Step 1** — Restructure SKILL.md: 4,116 → <500 lines with progressive disclosure to `references/`
**Step 2** — Fix marketplace.json: Strip non-standard fields (fixes Issue #5)

### Phase B: Update the Skill Generation Pipeline

**Step 3** — Update Phase 5: SKILL.md-first (not marketplace.json), spec-compliant output, validation + security scan
**Step 4** — Remove `-cskill` naming convention everywhere (code, docs, examples, rename `article-to-prototype-cskill/`)

### Phase C: Add Cross-Platform Tooling

**Step 5** — Create `install.sh` template: Auto-detects Claude Code, Copilot, Cursor, Windsurf, Cline, Codex, Gemini
**Step 6** — Create `validate.py` + `security_scan.py`: Spec validation + OWASP-lite security checks
**Step 7** — Update export system: Multi-platform install guide, validation before export
**Step 8** — Update all documentation: README v4.0, MIGRATION.md, CHANGELOG, cross-platform guide

## Key Deliverables

1. `.clarity/spec.md` — Full specification (28 FRs, 7 NFRs, data model, API contracts)
2. `.clarity/handoff.md` — Self-contained implementation prompt for any AI coding agent
3. `scenarios/SC-001..SC-059` — 59 holdout test scenarios for independent evaluation
4. `.clarity/context.md` — Research context and ecosystem analysis

## Open Questions (4)

1. Should the tool offer direct publishing to SkillsMP/SkillHub?
2. Should `install.sh` support `--uninstall`?
3. Should validation check that referenced files exist?
4. Should Cursor export generate `.mdc` or rely on native SKILL.md support?