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):
```yaml
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

```bash
# 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

```python
# 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)

```python
# 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?