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:

  {
    "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:

  #!/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