agent-skill-creator/.clarity/handoff.md

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

> Generated by `/clarity` on 2026-02-26
> Spec: `.clarity/spec.md`

## IMPORTANT RULES FOR THE IMPLEMENTING AGENT

1. **Read `.clarity/spec.md` thoroughly** before writing any code.
2. **Do NOT read the `scenarios/` directory.** Those are holdout tests for independent evaluation.
3. Follow the implementation order below. Do not skip ahead.
4. Ask clarifying questions if any requirement is ambiguous — do not guess.

---

## Tech Stack

| Layer | Technology | Notes |
|-------|-----------|-------|
| Language | Python 3.14 | User's environment, use `uv run` for execution |
| Shell scripts | Bash (POSIX-compatible) | For install.sh, must work on macOS/Linux/WSL |
| Config | YAML frontmatter + JSON | Standard formats only |
| Package manager | uv | For Python deps; no new heavy deps needed |
| Linter | ruff | User's preferred linter |
| VCS | git | All changes tracked |

---

## Implementation Order

Complete each step fully before moving to the next. There are 8 steps organized into 3 phases: restructure the meta-skill itself, update the skill generation pipeline, and add cross-platform tooling.

### Step 1: Restructure the Meta-Skill's Own SKILL.md

The current `SKILL.md` is 4,116 lines. It must be restructured into a <500-line SKILL.md with content split into reference files.

- [ ] Read the current `SKILL.md` in full and identify sections that can be moved to `references/`
- [ ] Create a new SKILL.md (<500 lines) with only:
  - Spec-compliant frontmatter (`name`, `description` ≤1024 chars, `license`, `metadata` with `author` and `version`, `compatibility`)
  - "When to Use This Skill" section (activation triggers)
  - "Overview" section (5-phase pipeline summary)
  - "Core Workflow" (concise step-by-step)
  - "Architecture Decision" (simple vs suite — brief, reference to `references/architecture-guide.md`)
  - "Output Format" (what the generated skill directory looks like)
  - Cross-references to `references/` for all detailed content
- [ ] Move detailed content into reference files:
  - `references/pipeline-phases.md` — Detailed Phase 1-5 instructions (the bulk of the current SKILL.md)
  - `references/architecture-guide.md` — Simple vs Suite decision logic, directory structures
  - `references/templates-guide.md` — Template-based creation (financial, climate, e-commerce)
  - `references/interactive-mode.md` — Interactive wizard documentation
  - `references/multi-agent-guide.md` — Batch/suite creation docs
  - `references/agentdb-integration.md` — AgentDB learning system docs
- [ ] Keep existing reference files that are still relevant (phase1-discovery.md through phase4-detection.md, activation guides)
- [ ] Delete or merge redundant reference files
- [ ] Verify the new SKILL.md is <500 lines and <5,000 tokens for the body

**Critical**: The `name` field must be `agent-skill-creator` (matches directory name). The `description` must be ≤1024 characters and include all activation keywords.

### Step 2: Fix marketplace.json (Issue #5)

The current `.claude-plugin/marketplace.json` has non-standard fields that break Claude Code installation.

- [ ] Read the current `.claude-plugin/marketplace.json`
- [ ] Strip ALL non-standard fields. Keep ONLY:
  ```json
  {
    "name": "agent-skill-creator",
    "plugins": [
      {
        "name": "agent-skill-creator-plugin",
        "description": "<EXACT copy of SKILL.md frontmatter description>",
        "source": "./",
        "skills": ["./"]
      }
    ]
  }
  ```
- [ ] Remove these non-standard fields: `owner`, `metadata`, `compatibility`, `templates`, `capabilities`, `activation`, `usage`, `test_queries`
- [ ] Validate the JSON is syntactically correct
- [ ] Verify `plugins[0].description` exactly matches the `description` in SKILL.md frontmatter

### Step 3: Update Phase 5 (Implementation) to Generate Standard-Compliant Skills

This is the most impactful change. The pipeline's output must change.

- [ ] Update `references/phase5-implementation.md` (or the new `references/pipeline-phases.md`):
  - **Remove** the mandate to create `marketplace.json` first for simple skills
  - **Change** the implementation order to: SKILL.md first (primary file), then scripts, references, assets, install.sh, README.md
  - **Add** validation step at the end
  - **Add** security scan step at the end
- [ ] Update the generated SKILL.md template:
  - Frontmatter must include: `name`, `description` (≤1024 chars), `license` (default: MIT), `metadata` (author, version)
  - Optional: `compatibility`, `allowed-tools`
  - Body must be <500 lines with references for detail
- [ ] Update the generated directory structure template:
  ```
  {skill-name}/              # No -cskill suffix
  ├── SKILL.md               # <500 lines, spec-compliant
  ├── scripts/               # Functional Python code
  ├── references/            # Detailed documentation
  ├── assets/                # Templates, schemas, data
  ├── install.sh             # Cross-platform installer
  └── README.md              # Multi-platform install instructions
  ```
- [ ] Remove ALL mentions of `-cskill` suffix from the generation pipeline
- [ ] Remove ALL mentions of mandatory `marketplace.json` for simple skills
- [ ] For complex suites: marketplace.json is OPTIONAL and must contain ONLY official fields

### Step 4: Remove -cskill Naming Convention

- [ ] Update `docs/NAMING_CONVENTIONS.md` — replace -cskill convention with standard kebab-case naming:
  - Names must be 1-64 characters
  - Lowercase letters, numbers, and hyphens only
  - Must not start or end with hyphen
  - Must not contain consecutive hyphens
  - Must match parent directory name
- [ ] Update `references/phase3-architecture.md` — remove -cskill from all examples and templates
- [ ] Update `README.md` — remove all -cskill references
- [ ] Rename `article-to-prototype-cskill/` → `article-to-prototype/`
  - Update its SKILL.md frontmatter `name` field to `article-to-prototype`
  - Update its `.claude-plugin/marketplace.json` if present
  - Update its README.md
- [ ] Search entire codebase for remaining `-cskill` references and update them
- [ ] Update all example directory names in documentation

### Step 5: Create the Cross-Platform Install Script

Create `scripts/install-template.sh` — a template that gets customized and included in every generated skill as `install.sh`.

- [ ] Write `scripts/install-template.sh`:
  ```bash
  #!/usr/bin/env bash
  # Cross-platform installer for Agent Skills
  # Detects the user's AI coding tool and installs to the correct location

  set -euo pipefail

  SKILL_NAME="{{SKILL_NAME}}"  # Replaced during generation
  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

  # Parse arguments
  PLATFORM=""
  PROJECT_LEVEL=false
  CUSTOM_PATH=""
  DRY_RUN=false

  while [[ $# -gt 0 ]]; do
    case $1 in
      --platform) PLATFORM="$2"; shift 2 ;;
      --project) PROJECT_LEVEL=true; shift ;;
      --path) CUSTOM_PATH="$2"; shift 2 ;;
      --dry-run) DRY_RUN=true; shift ;;
      -h|--help) show_help; exit 0 ;;
      *) echo "Unknown option: $1"; exit 1 ;;
    esac
  done

  # Platform detection logic
  # Install to detected or specified location
  # Validate SKILL.md before installing
  # Report success with next-steps instructions
  ```
- [ ] Implement platform detection:
  - Check for `~/.claude/` → Claude Code
  - Check for `~/.copilot/` or `.github/` → GitHub Copilot
  - Check for `~/.cursor/` or `.cursor/` → Cursor
  - Check for `~/.windsurf/` → Windsurf
  - Check for `~/.cline/` or `.clinerules/` → Cline
  - Check for `~/.codex/` → OpenAI Codex CLI
  - Check for `~/.gemini/` → Gemini CLI
  - Fallback: prompt user or use `--platform` flag
- [ ] Implement `--project` flag for project-level installation (`.claude/skills/`, `.github/skills/`, etc.)
- [ ] Implement `--dry-run` flag (show what would happen without doing it)
- [ ] Implement SKILL.md validation before copying
- [ ] Print success message with platform-specific activation instructions
- [ ] Handle errors: permission denied, directory doesn't exist, invalid SKILL.md

### Step 6: Create Validation and Security Scanning Scripts

- [ ] Create `scripts/validate.py`:
  - Validate frontmatter: `name` (1-64 chars, lowercase+hyphens, no start/end hyphen, no consecutive hyphens)
  - Validate frontmatter: `description` (1-1024 chars, non-empty)
  - Validate: directory name matches `name` field
  - Validate: SKILL.md exists and starts with `---` frontmatter
  - Validate: SKILL.md body <500 lines (warning, not error)
  - Validate: optional fields have correct types if present
  - Validate: referenced files in SKILL.md body exist
  - Return structured result: `{"valid": bool, "errors": [], "warnings": []}`

- [ ] Create `scripts/security_scan.py`:
  - Scan for hardcoded API keys (regex patterns for common key formats: `sk-`, `AKIA`, `ghp_`, `glpat-`, etc.)
  - Scan for `.env` files included in skill directory
  - Scan for `credentials.json`, `secrets.json`, `api_keys.json`
  - Scan for `eval()`, `exec()`, `subprocess.call(shell=True)` in Python scripts
  - Scan for `os.system()` with string concatenation (shell injection)
  - Scan for `__import__` dynamic imports
  - Return structured result: `{"clean": bool, "issues": []}`

- [ ] Integrate both into the generation pipeline (Phase 5 runs them after file creation)

### Step 7: Update the Export System

- [ ] Update `scripts/export_utils.py`:
  - Keep existing Desktop/Web and API export functionality (backwards compatible)
  - Add validation step before export (call `validate.py`)
  - Add security scan before export (call `security_scan.py`)
  - Remove `-cskill` from any hardcoded name handling
  - Update the generated installation guide to include instructions for ALL platforms (Claude Code, Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI)
  - Add optional `--platform` parameter for platform-specific export

- [ ] Update `references/cross-platform-guide.md`:
  - Expand from 4 Anthropic platforms to all 8+ platforms
  - Add installation paths for each platform
  - Add the Agent Skills Open Standard as the unifying reference
  - Remove references to marketplace.json as a universal requirement

- [ ] Update `references/export-guide.md` (if it exists) with new platform targets

### Step 8: Update Documentation and README

- [ ] Update `README.md`:
  - Update version to 4.0
  - Add "Cross-Platform Compatible" badge/note at top
  - List all supported platforms (Claude Code, Copilot CLI, VS Code Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI)
  - Remove all `-cskill` references
  - Update installation instructions for all platforms
  - Add "Agent Skills Open Standard" compliance note
  - Update architecture diagrams (no -cskill, no mandatory marketplace.json)
  - Add "Migration from v3.x" section pointing to MIGRATION.md

- [ ] Create `MIGRATION.md`:
  - How to update from v3.x to v4.0
  - Breaking changes: -cskill suffix removed, marketplace.json simplified
  - How to migrate existing generated skills (rename dirs, update frontmatter, fix marketplace.json)
  - Automated migration: mention that the tool can help migrate with "Migrate this skill to the new standard"

- [ ] Update `docs/CHANGELOG.md`:
  - Add v4.0 entry with all changes
  - Note breaking changes
  - Note new features (cross-platform, validation, security scan, install.sh)

- [ ] Update `docs/CLAUDE_SKILLS_ARCHITECTURE.md`:
  - Reference the Agent Skills Open Standard
  - Update directory structures (no -cskill)
  - Add cross-platform compatibility information

---

## Tests to Write

Write tests for these behaviors (derived from the spec, not from holdout scenarios):

| Test | Covers | Type |
|------|--------|------|
| Validate SKILL.md frontmatter with valid name/description passes | FR-001 | Unit |
| Validate SKILL.md frontmatter with name >64 chars fails | FR-001 | Unit |
| Validate SKILL.md frontmatter with empty description fails | FR-001 | Unit |
| Validate name matches directory name | FR-002 | Unit |
| Validate SKILL.md body >500 lines produces warning | FR-003 | Unit |
| Generated skill has no marketplace.json (simple skill) | FR-005 | Integration |
| Generated skill name has no -cskill suffix | FR-007 | Integration |
| Security scan detects hardcoded API key | FR-013 | Unit |
| Security scan detects .env file in skill | FR-013 | Unit |
| Security scan detects shell injection pattern | FR-014 | Unit |
| install.sh detects Claude Code platform | FR-015, FR-016 | Integration |
| install.sh detects Copilot platform | FR-015, FR-016 | Integration |
| install.sh --dry-run produces no side effects | FR-015 | Unit |
| install.sh --platform cursor installs to .cursor/rules/ | FR-017 | Integration |
| Generated README has multi-platform install section | FR-018 | Integration |
| Export system still generates Desktop .zip | FR-019 | Integration |
| Export system still generates API .zip <8MB | FR-019 | Integration |
| Meta-skill SKILL.md is <500 lines | FR-004, FR-021 | Unit |
| Generated skill works on SKILL.md standard without modification | FR-028, NFR-001 | Integration |

---

## Definition of Done

All of the following must be true:

- [ ] The meta-skill's own SKILL.md is <500 lines with spec-compliant frontmatter
- [ ] `.claude-plugin/marketplace.json` contains ONLY official fields
- [ ] No `-cskill` suffix appears anywhere in the codebase (code, docs, examples)
- [ ] `article-to-prototype-cskill/` renamed to `article-to-prototype/` with updated frontmatter
- [ ] Generated skills produce spec-compliant SKILL.md (passes validation)
- [ ] Generated skills include `install.sh` for cross-platform installation
- [ ] Generated README.md includes install instructions for 5+ platforms
- [ ] `scripts/validate.py` checks all spec rules and returns structured results
- [ ] `scripts/security_scan.py` catches hardcoded keys and injection patterns
- [ ] Export system updated with validation, security scan, and multi-platform install guide
- [ ] `references/cross-platform-guide.md` covers 8+ platforms
- [ ] `MIGRATION.md` created with v3.x → v4.0 migration guide
- [ ] `README.md` updated for v4.0 with all platform support
- [ ] No hardcoded secrets or credentials in any file
- [ ] All Python files pass `ruff check`
- [ ] `install.sh` template works on macOS and Linux

---

## Explicit Exclusions

Do NOT implement these (they are out of scope):

- Building a skill marketplace or registry
- Converting `.cursorrules` or `.windsurfrules` into SKILL.md
- MCP server integration
- GUI or web interface
- Rewriting AgentDB integration
- Supporting platforms that haven't adopted SKILL.md standard
- Publishing automation to SkillsMP/SkillHub (just make skills compatible)

---

## Reference Files

- Specification: `.clarity/spec.md`
- Project context: `.clarity/context.md`
- Agent Skills Open Standard: https://agentskills.io/specification
- Current codebase: All files in the repository root