# Clarity Context: agent-skill-creator v4.0 Modernization

> Generated by `/clarity` on 2026-02-26
> Sources: Local codebase, agentskills.io/specification, ecosystem research (Feb 2026)

## Sources Analyzed

| Source | Type | Key Extraction |
|--------|------|----------------|
| `/Users/francylisboacharuto/agent-skill-creator/` | Local codebase | Full architecture, all files, git history |
| `agentskills.io/specification` | Web (official spec) | SKILL.md format, frontmatter rules, validation |
| GitHub ecosystem research | Web search | 26+ platform adoption, marketplaces, competitors |
| GitHub Issue #5 | Issue | Non-standard marketplace.json breaking installs |
| Anthropic blog + docs | Web | Agent Skills open standard (Dec 2025) |
| GitHub Copilot docs | Web | SKILL.md adoption, `.github/skills/` paths |
| Cursor docs | Web | `.cursor/rules/*.mdc` format, SKILL.md support |
| Windsurf docs | Web | `.windsurfrules` format, SKILL.md support |
| Cline docs | Web | `.clinerules/` format, SKILL.md support |

## System Understanding

### Current Architecture (v3.2, October 2025)

**Purpose:** A meta-skill for Claude Code that autonomously creates complete Agent Skills from user workflow descriptions through a 5-phase pipeline (Discovery → Design → Architecture → Detection → Implementation).

**Tech stack:** Python 3.x, pure Markdown/JSON config, no package manager (standalone scripts)

**Key files:**
- `SKILL.md` (4,116 lines) — The meta-skill definition. 8x the recommended 500-line max.
- `.claude-plugin/marketplace.json` (124 lines) — Non-standard plugin manifest with custom fields (`activation`, `capabilities`, `templates`, `usage`, `test_queries`) that break Claude Code installation.
- `scripts/export_utils.py` (767 lines) — Cross-platform export to Desktop/Web/API .zip packages.
- `integrations/` (2,849 lines) — AgentDB learning system (optional, graceful degradation).
- `references/` (520 KB, 22 files) — Phase guides, activation patterns, cross-platform docs.
- `docs/` (184 KB, 13 files) — Architecture, naming, changelog, user guides.
- `article-to-prototype-cskill/` (244 KB) — Example generated skill.

**Distribution model:**
- Claude Code: Plugin marketplace install (`/plugin marketplace add ./`)
- Claude Desktop/Web: Manual .zip upload via export system
- Claude API: Programmatic .zip upload (8MB limit)

### Critical Problems

1. **Non-standard marketplace.json (Issue #5):** Custom fields cause installation failures. Claude Code rejects unknown schema fields.
2. **SKILL.md is 4,116 lines:** The official spec recommends <500 lines with progressive disclosure. Current file consumes excessive context window.
3. **Only targets Anthropic platforms:** No support for GitHub Copilot (CLI or VS Code), Cursor, Windsurf, Cline, OpenAI Codex CLI, or Gemini CLI.
4. **`-cskill` naming convention is non-standard:** No other tool in the ecosystem uses this suffix. It adds friction and violates ecosystem norms.
5. **Generated skills also use non-standard marketplace.json:** The skills this tool creates inherit the same non-standard format, causing downstream installation issues for all users.
6. **No validation against official spec:** The ecosystem now has `skills-ref validate` but this tool doesn't use it.
7. **Cross-platform guide only covers 4 Anthropic platforms:** Missing the 22+ other platforms that adopted the SKILL.md standard since Dec 2025.

## Inferred Intent

The user wants to modernize agent-skill-creator to:

1. **Align with the Agent Skills Open Standard** (agentskills.io/specification) — fix all spec violations
2. **Generate cross-platform skills** that work on Claude Code, GitHub Copilot CLI, VS Code Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI, and any future SKILL.md adopter
3. **Fix the marketplace.json bug** — Issue #5 is the most reported problem
4. **Make skills easy to install** across all platforms with clear, platform-specific instructions
5. **Make skills easy to update and maintain** with proper versioning and validation
6. **Keep the core value proposition** — converting workflow descriptions into production-ready skills autonomously

## Key Constraints

- **Must follow Agent Skills Open Standard** (the spec at agentskills.io/specification)
- **SKILL.md frontmatter rules:** `name` ≤64 chars, lowercase+hyphens, no start/end hyphen, no consecutive hyphens; `description` ≤1024 chars
- **Progressive disclosure:** ~100 tokens metadata at startup, <5,000 tokens for full SKILL.md body, resources loaded on demand
- **SKILL.md body recommended <500 lines** — detailed content goes to `references/`, `scripts/`, `assets/`
- **Directory name must match `name` field** in frontmatter
- **Python 3.14 preferred** (user's environment), `uv` as package manager
- **No new heavy dependencies** — user prefers stdlib + lightweight packages
- **Backwards compatibility:** Existing users of the skill should be able to update without breaking their workflows

## Assumptions

- [ASSUMPTION] The user wants to keep the 5-phase pipeline as the core creation methodology (it's the key differentiator vs competitors)
- [ASSUMPTION] AgentDB integration can remain optional — it's a nice-to-have, not blocking cross-platform work
- [ASSUMPTION] The `-cskill` suffix should be fully removed, not just made optional, since no platform ecosystem uses it
- [ASSUMPTION] The `marketplace.json` file should be eliminated for generated skills — the standard requires only SKILL.md
- [ASSUMPTION] Export system should be expanded to generate platform-specific installation configs (`.cursor/rules/`, `.github/skills/`, etc.) in addition to .zip packages
- [ASSUMPTION] The tool should add `skills-ref validate` as a post-creation validation step
- [ASSUMPTION] Skills generated should work on ALL platforms that adopted the open standard without any platform-specific modifications to SKILL.md itself
- [ASSUMPTION] The existing `article-to-prototype-cskill/` example should be updated to the new standard as a reference
- [ASSUMPTION] Security scanning (no hardcoded keys, no shell injection) should be added to the validation pipeline given the ecosystem's security concerns (Snyk ToxicSkills report)

## Ambiguities

1. **Should marketplace.json be kept for Claude Code plugin suites?** Claude Code's plugin system uses marketplace.json for multi-skill plugins. The standard doesn't define this. Best guess: Keep marketplace.json ONLY for complex multi-skill suites that need Claude Code plugin distribution, but strip it to only official fields. For simple skills, eliminate it entirely.

2. **How deep should Cursor/Windsurf native format support go?** These tools have their own formats (`.mdc`, `.windsurfrules`) alongside SKILL.md support. Best guess: Generate SKILL.md as the primary output (works everywhere), with optional export to native formats as a convenience feature.

3. **Should the tool generate platform-specific installation scripts?** E.g., a `install.sh` that detects the platform and copies to the right location. Best guess: Yes, a simple install script that detects `.claude/skills/`, `.github/skills/`, `.cursor/rules/`, etc.