agent-skill-creator/MIGRATION.md

Migration Guide: v3.x to v4.0

Overview

Agent-skill-creator v4.0 brings full compliance with the Agent Skills Open Standard, cross-platform support for 8+ platforms, and several breaking changes from v3.x.

Breaking Changes

1. -cskill Suffix Removed

Before (v3.x):

pdf-text-extractor-cskill/
financial-analysis-suite-cskill/

After (v4.0):

pdf-text-extractor/
financial-analysis-suite/

Migration:

# Rename directory
mv my-skill-cskill my-skill

# Update SKILL.md frontmatter
# Change: name: my-skill-cskill
# To:     name: my-skill

# Update marketplace.json (if present)
# Change: "name": "my-skill-cskill"
# To:     "name": "my-skill"

2. marketplace.json Simplified

Non-standard fields have been removed. Simple skills no longer need marketplace.json at all.

Before (v3.x):

{
  "name": "my-skill-cskill",
  "owner": { ... },
  "metadata": { ... },
  "plugins": [{ ... }],
  "compatibility": { ... },
  "templates": { ... },
  "capabilities": { ... },
  "activation": { ... },
  "usage": { ... },
  "test_queries": [...]
}

After (v4.0):

{
  "name": "my-skill",
  "plugins": [{
    "name": "my-skill-plugin",
    "description": "...",
    "source": "./",
    "skills": ["./"]
  }]
}

Migration:

• For simple skills: Delete .claude-plugin/marketplace.json entirely
• For complex suites: Strip to only name and plugins fields

3. SKILL.md Frontmatter Updated

Before (v3.x): Only name and description required.

After (v4.0): Additional recommended fields:

---
name: my-skill
description: >-
  Description here (<=1024 chars)  
license: MIT
metadata:
  author: Your Name
  version: 1.0.0
---

4. SKILL.md Body Size Limit

Generated SKILL.md files must now be under 500 lines. Move detailed content to references/ files.

5. install.sh Added

Generated skills now include an install.sh cross-platform installer script.

How to Migrate Existing Skills

Automated Migration

Ask the agent-skill-creator to migrate:

"Migrate this skill to the new standard"
"Update my-skill to v4 format"

Manual Migration Steps

1. Rename directory (remove -cskill suffix)
2. Update SKILL.md frontmatter:
   • Remove -cskill from name field
   • Add license, metadata fields
   • Ensure description is <=1024 characters
3. Simplify marketplace.json (or delete for simple skills)
4. Add install.sh (copy from scripts/install-template.sh and customize)
5. Update README.md with multi-platform install instructions
6. Validate: Run python3 scripts/validate.py ./my-skill/
7. Security scan: Run python3 scripts/security_scan.py ./my-skill/

Updating the Meta-Skill

If you have agent-skill-creator installed:

cd agent-skill-creator
git pull

The meta-skill will work immediately. No reinstallation required. The same trigger phrases and workflows still work.

What Didn't Change

• The 5-phase pipeline (Discovery, Design, Architecture, Detection, Implementation)
• AgentDB integration (still optional)
• Support for both simple skills and complex suites
• Desktop/Web .zip export and Claude API export
• All activation trigger phrases

New Features in v4.0

• Cross-platform support: Skills work on Claude Code, Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI
• install.sh: Auto-detect platform and install to the correct location
• Spec validation: scripts/validate.py checks compliance with the Agent Skills Open Standard
• Security scanning: scripts/security_scan.py detects hardcoded keys and injection patterns
• Lean SKILL.md: Under 500 lines with progressive disclosure via references/