bac2b27bb8
BREAKING CHANGES: - Remove -cskill suffix from all skill names (use standard kebab-case) - Simplify marketplace.json to only official fields (fixes Issue #5) - SKILL.md body must be <500 lines (progressive disclosure via references/) New features: - Cross-platform support for 8+ platforms (Claude Code, Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI) - scripts/install-template.sh: Auto-detect platform installer with --dry-run - scripts/validate.py: Spec compliance checker for generated skills - scripts/security_scan.py: Security scanner for hardcoded keys and dangerous patterns - MIGRATION.md: v3.x to v4.0 migration guide - 6 new reference files for progressive disclosure from lean SKILL.md Key changes: - SKILL.md: 4,116 → 272 lines with spec-compliant YAML frontmatter - marketplace.json: Stripped to {name, plugins} only - article-to-prototype-cskill/ → article-to-prototype/ - stock-analyzer-cskill/ → stock-analyzer/ - Export system integrates validation + security scanning - README.md rewritten for all supported platforms - Phase 5 pipeline outputs SKILL.md-first, spec-compliant skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
92 lines
7 KiB
Markdown
92 lines
7 KiB
Markdown
# 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.
|