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

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.