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

Specification: agent-skill-creator v4.0 — Cross-Platform Modernization

Generated by /clarity on 2026-02-26 Status: DRAFT

1. System Overview

One-liner: A meta-skill that autonomously creates cross-platform Agent Skills from workflow descriptions, compliant with the Agent Skills Open Standard.

Primary user: Developers and professionals who want to convert repetitive workflows into reusable AI agent skills that work across Claude Code, GitHub Copilot, Cursor, Windsurf, Cline, and 20+ other platforms.

Project type: Brownfield delta

1.1 Goals

• G1: Full compliance with the Agent Skills Open Standard (agentskills.io/specification)
• G2: Skills generated by this tool work on ALL platforms that support the SKILL.md standard without modification
• G3: Fix all known bugs (Issue #5: non-standard marketplace.json)
• G4: Restructure the meta-skill itself to follow the standard (<500 lines SKILL.md, progressive disclosure)
• G5: Provide cross-platform installation support (auto-detect platform, install to correct location)
• G6: Add validation pipeline using the official spec rules
• G7: Add security scanning to generated skills (no hardcoded secrets, no injection vectors)
• G8: Make generated skills easy to publish to marketplaces (SkillsMP, SkillHub, skills.sh)

1.2 Non-Goals (Explicit Exclusions)

• NG1: Building a skill marketplace or registry (use existing ones)
• NG2: Converting existing .cursorrules or .windsurfrules files into SKILL.md (out of scope)
• NG3: MCP server integration (MCP is a tool protocol, not a skill format — orthogonal concern)
• NG4: GUI or web interface for skill creation (this remains a CLI/agent skill)
• NG5: Rewriting the AgentDB integration system (it works, keep it optional)
• NG6: Supporting platforms that have NOT adopted the SKILL.md standard (e.g., Aider's CONVENTIONS.md)

---

1A. Current State

Existing Architecture

The project is a meta-skill (a skill that creates other skills) structured as:

agent-skill-creator/
├── SKILL.md                          # 4,116 lines (8x recommended max)
├── .claude-plugin/marketplace.json   # Non-standard fields (Issue #5)
├── scripts/export_utils.py           # Desktop/Web/API export
├── integrations/                     # AgentDB learning (optional)
├── references/                       # 22 reference files (520 KB)
├── docs/                             # 13 doc files (184 KB)
├── article-to-prototype-cskill/      # Example generated skill
└── exports/                          # Export output directory

Relevant Files / Modules

File/Module	Purpose	Will Change?
SKILL.md	Meta-skill definition (4,116 lines)	Yes — restructure to <500 lines
.claude-plugin/marketplace.json	Plugin manifest (non-standard)	Yes — fix or remove
scripts/export_utils.py	Cross-platform export	Yes — add new platform targets
references/phase5-implementation.md	Implementation guide for generated skills	Yes — remove marketplace.json mandate
references/cross-platform-guide.md	Platform compatibility matrix	Yes — expand to 26+ platforms
docs/NAMING_CONVENTIONS.md	-cskill suffix rules	Yes — remove -cskill convention
README.md	Project documentation	Yes — update for v4.0
article-to-prototype-cskill/	Example skill	Yes — rename, update to standard
integrations/	AgentDB system	No
references/phase1-discovery.md	Phase 1 guide	Minor updates
references/phase2-design.md	Phase 2 guide	Minor updates
references/phase3-architecture.md	Phase 3 guide	Yes — remove -cskill, update structure
references/phase4-detection.md	Phase 4 guide	Minor updates
references/activation-*.md	Activation pattern guides	No

---

1B. Delta Specification

What Changes

1. SKILL.md restructured: 4,116 → <500 lines. Detailed content moved to references/.
2. marketplace.json fixed: Strip to official fields only, or remove for simple skill mode.
3. -cskill suffix eliminated: All naming conventions, templates, docs, and examples updated.
4. Cross-platform skill generation: Generated skills include an install.sh script and platform-specific instructions.
5. Validation pipeline added: Every generated skill validated against the official spec.
6. Security scanning added: Check for hardcoded secrets, shell injection, suspicious patterns.
7. New platform targets: Generated installation guides cover Claude Code, Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI.
8. Export system expanded: Beyond .zip packages, add direct-install-to-platform support.

What Must NOT Change

• The 5-phase pipeline (Discovery → Design → Architecture → Detection → Implementation) — this is the core differentiator
• AgentDB integration — works fine, keep optional
• The ability to create both simple skills and complex skill suites
• Support for Claude Desktop/Web .zip export and Claude API export

Migration Requirements

• Existing users who installed via /plugin marketplace add ./ must be able to update via git pull and have the tool work
• The example skill (article-to-prototype-cskill/) must be renamed and updated as a reference migration
• A MIGRATION.md guide for users of v3.x

---

2. Functional Requirements

ID	Requirement	Priority	Notes
FR-001	Generated SKILL.md files MUST have valid frontmatter per the Agent Skills spec (name ≤64 chars lowercase+hyphens, description ≤1024 chars, both required)	MUST	Core spec compliance
FR-002	Generated SKILL.md name field MUST match the parent directory name	MUST	Spec rule
FR-003	Generated SKILL.md body MUST be <500 lines, with detailed content in references/	MUST	Progressive disclosure
FR-004	The meta-skill's own SKILL.md MUST be <500 lines	MUST	Practice what you preach
FR-005	Generated skills MUST NOT include .claude-plugin/marketplace.json for simple skills	MUST	Fixes Issue #5
FR-006	Generated skills for complex suites MAY include a marketplace.json with ONLY official Claude Code fields	SHOULD	Multi-skill plugin support
FR-007	The -cskill naming suffix MUST be removed from all generated skill names	MUST	Standard compliance
FR-008	Generated skills MUST include license field in frontmatter	SHOULD	Marketplace discoverability
FR-009	Generated skills MUST include metadata field with author and version	SHOULD	Marketplace discoverability
FR-010	Generated skills SHOULD include compatibility field when platform-specific features are used	SHOULD	Spec recommendation
FR-011	A validation function MUST check every generated skill against the official spec rules	MUST	Quality gate
FR-012	Validation MUST check: name format, description length, frontmatter structure, directory name match	MUST	Spec rules
FR-013	A security scan MUST check generated skills for hardcoded API keys, secrets, and .env files	MUST	Ecosystem security
FR-014	A security scan SHOULD check for shell injection patterns in generated scripts	SHOULD	OWASP compliance
FR-015	Generated skills MUST include an install.sh script that auto-detects the platform and installs to the correct location	MUST	Cross-platform UX
FR-016	The install script MUST support: ~/.claude/skills/, ~/.github/skills/, .claude/skills/ (project), .github/skills/ (project)	MUST	Primary platforms
FR-017	The install script SHOULD support: .cursor/rules/, .codex/skills/, custom paths via --path flag	SHOULD	Extended platforms
FR-018	Generated skills MUST include a README.md with installation instructions for at least 5 platforms	MUST	Cross-platform documentation
FR-019	The export system MUST continue to support Desktop/Web .zip and API .zip variants	MUST	Backwards compatibility
FR-020	The export system SHOULD add a --platform flag to generate platform-specific output (e.g., --platform cursor generates .mdc file)	COULD	Nice-to-have
FR-021	The meta-skill MUST restructure its own content: <500 line SKILL.md with references in references/	MUST	Self-compliance
FR-022	Phase 3 (Architecture) MUST generate standard-compliant directory structures (no -cskill suffix)	MUST	Pipeline update
FR-023	Phase 5 (Implementation) MUST create SKILL.md as the first and primary file (not marketplace.json)	MUST	Standard alignment
FR-024	Phase 5 MUST run validation after generating all files	MUST	Quality gate
FR-025	Phase 5 SHOULD run security scan after generating all files	SHOULD	Security
FR-026	Generated README.md MUST include a "Cross-Platform Installation" section with copy-paste commands for each platform	MUST	UX
FR-027	The meta-skill MUST preserve the 5-phase pipeline as the core creation methodology	MUST	Core differentiator
FR-028	Generated skills MUST work on any platform that supports the SKILL.md standard without modification	MUST	Portability

2.1 Core Workflow

Skill Creation Pipeline (Updated):

1. User describes a workflow to automate (e.g., "Create a skill for processing daily CSV files")
2. Phase 1: Discovery — Research APIs, tools, data sources (unchanged)
3. Phase 2: Design — Define use cases, analyses, methodologies (unchanged)
4. Phase 3: Architecture — Structure the skill directory using the Agent Skills standard:

   skill-name/              # No -cskill suffix
   ├── SKILL.md             # <500 lines, spec-compliant frontmatter
   ├── scripts/             # Executable code
   ├── references/          # Detailed docs (loaded on demand)
   ├── assets/              # Templates, schemas, data files
   ├── install.sh           # Cross-platform installer
   └── README.md            # With multi-platform install instructions
   

5. Phase 4: Detection — Generate description with domain keywords for agent discovery (unchanged conceptually, but description now ≤1024 chars)
6. Phase 5: Implementation — Create all files in this order: a. Create directory structure b. Write SKILL.md with spec-compliant frontmatter (PRIMARY FILE) c. Write scripts (functional Python code) d. Write references (detailed documentation) e. Write assets (templates, configs) f. Generate install.sh (cross-platform installer) g. Write README.md (with multi-platform install instructions) h. Run validation against official spec i. Run security scan j. Report results to user

2.2 Secondary Flows

Flow: Cross-Platform Export

1. User asks to export a skill for a specific platform
2. System generates the appropriate output:
   • Claude Code: Standard directory (copy to ~/.claude/skills/ or .claude/skills/)
   • GitHub Copilot: Standard directory (copy to .github/skills/)
   • Cursor: Generate .mdc rule file from SKILL.md content (optional)
   • Desktop/Web: .zip package
   • API: Optimized .zip (<8MB)
3. System generates platform-specific installation guide

Flow: Validate Existing Skill

1. User asks to validate an existing skill directory
2. System runs spec validation (frontmatter, naming, structure)
3. System runs security scan
4. System reports pass/fail with specific issues and fix suggestions

Flow: Migrate Legacy Skill

1. User has a skill with -cskill suffix or non-standard marketplace.json
2. System renames directory, updates frontmatter, removes/fixes marketplace.json
3. System validates the migrated skill

2.3 Edge Cases & Error Handling

Condition	Expected Behavior
Skill name exceeds 64 chars	Truncate intelligently, warn user, suggest alternative
Description exceeds 1024 chars	Summarize, move detail to SKILL.md body, warn user
Name contains uppercase or special chars	Auto-convert to lowercase kebab-case
Name starts/ends with hyphen	Auto-strip, warn user
Name has consecutive hyphens	Collapse to single hyphen, warn user
Directory name doesn't match name field	Rename directory to match, warn user
Generated script contains hardcoded API key	Fail security scan, replace with env var reference, warn user
SKILL.md body exceeds 500 lines	Move excess to references/, add cross-references
User requests -cskill suffix	Inform user it's deprecated, generate without suffix
Platform directory doesn't exist (e.g., no .claude/)	Create it, or inform user to create manually
install.sh target platform not detected	Fall back to interactive prompt asking user which platform
Complex skill suite needs marketplace.json	Generate with ONLY official fields (name, plugins[].name, plugins[].description, plugins[].source, plugins[].skills)

---

3. Non-Functional Requirements

ID	Requirement	Target	Notes
NFR-001	Generated skills must be valid on all SKILL.md-standard platforms	100% compliance	Zero platform-specific hacks
NFR-002	Meta-skill SKILL.md context consumption	<5,000 tokens for body	Progressive disclosure
NFR-003	Validation must cover all spec rules	100% of agentskills.io rules	Use skills-ref as reference
NFR-004	Security scan must catch OWASP top patterns	Hardcoded secrets, injection	Not a full SAST tool
NFR-005	install.sh must work on macOS, Linux, and WSL	3 OS families	bash-compatible
NFR-006	Generated skills must not require any tool-specific configuration to activate	Zero-config activation	SKILL.md description is the only activation mechanism
NFR-007	Backwards compatibility with v3.x workflows	Users can git pull and use immediately	No breaking changes to user-facing invocation

---

4. Data Model

4.1 Entities

SkillManifest (the generated SKILL.md frontmatter):

name: string          # 1-64 chars, lowercase+hyphens, required
description: string   # 1-1024 chars, required
license: string       # optional
compatibility: string # 1-500 chars, optional
metadata:             # optional
  author: string
  version: string
allowed-tools: string # space-delimited, experimental, optional

SkillDirectory (the generated output):

{name}/
├── SKILL.md           # Required. <500 lines.
├── scripts/           # Optional. Self-contained executable code.
├── references/        # Optional. On-demand documentation.
├── assets/            # Optional. Templates, schemas, data.
├── install.sh         # New. Cross-platform installer.
└── README.md          # Required. Multi-platform install instructions.

PlatformTarget (where skills can be installed):

claude-code:      ~/.claude/skills/{name}/ or .claude/skills/{name}/
copilot:          .github/skills/{name}/ or ~/.copilot/skills/{name}/
cursor:           .cursor/rules/{name}/ (or .mdc export)
windsurf:         .windsurf/skills/{name}/
cline:            .clinerules/{name}/
codex:            .codex/skills/{name}/
gemini:           .gemini/skills/{name}/
generic:          user-specified --path

4.2 Data Flow

User workflow description
    ↓
Phase 1: Discovery (API research)
    ↓
Phase 2: Design (use case analysis)
    ↓
Phase 3: Architecture (directory structure, spec-compliant)
    ↓
Phase 4: Detection (description + keywords, ≤1024 chars)
    ↓
Phase 5: Implementation
    ├── Generate SKILL.md (spec-compliant, <500 lines)
    ├── Generate scripts/ (functional Python)
    ├── Generate references/ (detailed docs)
    ├── Generate assets/ (templates, configs)
    ├── Generate install.sh (cross-platform)
    ├── Generate README.md (multi-platform instructions)
    ├── Run spec validation → pass/fail
    └── Run security scan → pass/fail
    ↓
Output: Complete, validated, cross-platform skill directory

---

5. API / Interface Contracts

5.1 Activation Interface (User → Meta-Skill)

Trigger phrases (unchanged):

• "Create a skill for [objective]"
• "Automate this workflow: [description]"
• "Every day I [repetitive task], automate this"
• "Create an agent for [objective]"

New trigger phrases:

• "Create a cross-platform skill for [objective]"
• "Validate this skill: [path]"
• "Export this skill for [platform]"
• "Migrate this skill to the new standard"

5.2 install.sh Interface

# Auto-detect platform and install to user-level skills
./install.sh

# Install to specific platform
./install.sh --platform claude-code
./install.sh --platform copilot
./install.sh --platform cursor

# Install to project-level (current directory)
./install.sh --project

# Install to custom path
./install.sh --path /custom/path/

# Dry run (show what would happen)
./install.sh --dry-run

Exit codes:

• 0: Success
• 1: Validation failed (SKILL.md invalid)
• 2: Platform not detected
• 3: Permission denied (can't write to target)

5.3 Validation Interface

# In scripts/validate.py
def validate_skill(skill_path: str) -> ValidationResult:
    """
    Validate a skill directory against the Agent Skills Open Standard.

    Returns:
        ValidationResult with:
        - valid: bool
        - errors: list[str]    # spec violations (must fix)
        - warnings: list[str]  # recommendations (should fix)
        - security: list[str]  # security issues found
    """

5.4 Export Interface (Updated)

# In scripts/export_utils.py (updated)
def export_skill(
    skill_path: str,
    variants: list[str] = ['desktop', 'api'],
    platform: str = None,          # NEW: 'cursor', 'copilot', etc.
    version_override: str = None,
    output_dir: str = None
) -> dict:

---

6. Technical Constraints

• Stack: Python 3.14, uv package manager, bash for install.sh
• Dependencies: stdlib only for core (pathlib, json, re, zipfile, subprocess). No new external packages required.
• Compatibility: macOS (primary), Linux, WSL. install.sh must be POSIX-compatible bash.
• Spec compliance: Must pass skills-ref validate (if available) or equivalent internal validation
• Size: Generated SKILL.md <500 lines. Meta-skill SKILL.md <500 lines. API packages <8MB.
• No breaking changes: Users who git pull must not have their existing workflow broken.

---

7. Assumptions

• [ASSUMPTION] The Agent Skills Open Standard at agentskills.io/specification is the authoritative source of truth for the SKILL.md format
• [ASSUMPTION] All 26+ platforms that adopted the standard read SKILL.md identically — there are no platform-specific parsing differences in the frontmatter
• [ASSUMPTION] GitHub Copilot reads skills from .github/skills/ in addition to .claude/skills/ (confirmed by GitHub docs Dec 2025)
• [ASSUMPTION] Cursor supports SKILL.md natively alongside its .mdc rules (confirmed by Cursor docs)
• [ASSUMPTION] Users prefer a single install.sh over platform-specific install scripts
• [ASSUMPTION] The -cskill suffix removal is non-controversial — no user has expressed attachment to it
• [ASSUMPTION] The article-to-prototype-cskill/ example can be renamed to article-to-prototype/ without breaking existing users (it's an example, not an installed dependency)
• [ASSUMPTION] marketplace.json can be eliminated for simple skills without losing functionality — Claude Code can discover skills via SKILL.md alone when placed in ~/.claude/skills/ or .claude/skills/
• [ASSUMPTION] Security scanning only needs to catch obvious patterns (hardcoded keys, .env files, eval() calls, shell injection) — it's a first-pass filter, not a comprehensive SAST tool

---

8. Open Questions

• Q1: Should the tool offer to publish generated skills to SkillsMP or SkillHub directly? (Would require API integration with those platforms)
• Q2: Should install.sh also handle uninstallation (./install.sh --uninstall)?
• Q3: Should the validation system also check that referenced files in SKILL.md body actually exist in the skill directory?
• Q4: For Cursor users, should the export generate a .mdc file that wraps the SKILL.md content in Cursor's format, or just rely on Cursor's native SKILL.md support?