admin-valentin/agent-skill-creator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: v4.0 Cross-Platform Modernization — Agent Skills Open Standard compliance

Browse source 
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>
This commit is contained in:
francylisboacharuto 2026-02-26 14:52:09 -03:00
parent 79dc635009
commit bac2b27bb8
135 changed files with 8535 additions and 8642 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

92
.clarity/context.md Normal file
View file

@ -0,0 +1,92 @@
# 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.

318
.clarity/handoff.md Normal file
View file

@ -0,0 +1,318 @@
# Implementation Handoff: agent-skill-creator v4.0 — Cross-Platform Modernization
> Generated by `/clarity` on 2026-02-26
> Spec: `.clarity/spec.md`
## IMPORTANT RULES FOR THE IMPLEMENTING AGENT
1. **Read `.clarity/spec.md` thoroughly** before writing any code.
2. **Do NOT read the `scenarios/` directory.** Those are holdout tests for independent evaluation.
3. Follow the implementation order below. Do not skip ahead.
4. Ask clarifying questions if any requirement is ambiguous — do not guess.
---
## Tech Stack
| Layer | Technology | Notes |
|-------|-----------|-------|
| Language | Python 3.14 | User's environment, use `uv run` for execution |
| Shell scripts | Bash (POSIX-compatible) | For install.sh, must work on macOS/Linux/WSL |
| Config | YAML frontmatter + JSON | Standard formats only |
| Package manager | uv | For Python deps; no new heavy deps needed |
| Linter | ruff | User's preferred linter |
| VCS | git | All changes tracked |
---
## Implementation Order
Complete each step fully before moving to the next. There are 8 steps organized into 3 phases: restructure the meta-skill itself, update the skill generation pipeline, and add cross-platform tooling.
### Step 1: Restructure the Meta-Skill's Own SKILL.md
The current `SKILL.md` is 4,116 lines. It must be restructured into a <500-line SKILL.md with content split into reference files.
- [ ] Read the current `SKILL.md` in full and identify sections that can be moved to `references/`
- [ ] Create a new SKILL.md (<500 lines) with only:
- Spec-compliant frontmatter (`name`, `description` ≤1024 chars, `license`, `metadata` with `author` and `version`, `compatibility`)
- "When to Use This Skill" section (activation triggers)
- "Overview" section (5-phase pipeline summary)
- "Core Workflow" (concise step-by-step)
- "Architecture Decision" (simple vs suite — brief, reference to `references/architecture-guide.md`)
- "Output Format" (what the generated skill directory looks like)
- Cross-references to `references/` for all detailed content
- [ ] Move detailed content into reference files:
- `references/pipeline-phases.md` — Detailed Phase 1-5 instructions (the bulk of the current SKILL.md)
- `references/architecture-guide.md` — Simple vs Suite decision logic, directory structures
- `references/templates-guide.md` — Template-based creation (financial, climate, e-commerce)
- `references/interactive-mode.md` — Interactive wizard documentation
- `references/multi-agent-guide.md` — Batch/suite creation docs
- `references/agentdb-integration.md` — AgentDB learning system docs
- [ ] Keep existing reference files that are still relevant (phase1-discovery.md through phase4-detection.md, activation guides)
- [ ] Delete or merge redundant reference files
- [ ] Verify the new SKILL.md is <500 lines and <5,000 tokens for the body
**Critical**: The `name` field must be `agent-skill-creator` (matches directory name). The `description` must be ≤1024 characters and include all activation keywords.
### Step 2: Fix marketplace.json (Issue #5)
The current `.claude-plugin/marketplace.json` has non-standard fields that break Claude Code installation.
- [ ] Read the current `.claude-plugin/marketplace.json`
- [ ] Strip ALL non-standard fields. Keep ONLY:
```json
{
"name": "agent-skill-creator",
"plugins": [
{
"name": "agent-skill-creator-plugin",
"description": "<EXACT copy of SKILL.md frontmatter description>",
"source": "./",
"skills": ["./"]
}
]
}
```
- [ ] Remove these non-standard fields: `owner`, `metadata`, `compatibility`, `templates`, `capabilities`, `activation`, `usage`, `test_queries`
- [ ] Validate the JSON is syntactically correct
- [ ] Verify `plugins[0].description` exactly matches the `description` in SKILL.md frontmatter
### Step 3: Update Phase 5 (Implementation) to Generate Standard-Compliant Skills
This is the most impactful change. The pipeline's output must change.
- [ ] Update `references/phase5-implementation.md` (or the new `references/pipeline-phases.md`):
- **Remove** the mandate to create `marketplace.json` first for simple skills
- **Change** the implementation order to: SKILL.md first (primary file), then scripts, references, assets, install.sh, README.md
- **Add** validation step at the end
- **Add** security scan step at the end
- [ ] Update the generated SKILL.md template:
- Frontmatter must include: `name`, `description` (≤1024 chars), `license` (default: MIT), `metadata` (author, version)
- Optional: `compatibility`, `allowed-tools`
- Body must be <500 lines with references for detail
- [ ] Update the generated directory structure template:
```
{skill-name}/ # No -cskill suffix
├── SKILL.md # <500 lines, spec-compliant
├── scripts/ # Functional Python code
├── references/ # Detailed documentation
├── assets/ # Templates, schemas, data
├── install.sh # Cross-platform installer
└── README.md # Multi-platform install instructions
```
- [ ] Remove ALL mentions of `-cskill` suffix from the generation pipeline
- [ ] Remove ALL mentions of mandatory `marketplace.json` for simple skills
- [ ] For complex suites: marketplace.json is OPTIONAL and must contain ONLY official fields
### Step 4: Remove -cskill Naming Convention
- [ ] Update `docs/NAMING_CONVENTIONS.md` — replace -cskill convention with standard kebab-case naming:
- Names must be 1-64 characters
- Lowercase letters, numbers, and hyphens only
- Must not start or end with hyphen
- Must not contain consecutive hyphens
- Must match parent directory name
- [ ] Update `references/phase3-architecture.md` — remove -cskill from all examples and templates
- [ ] Update `README.md` — remove all -cskill references
- [ ] Rename `article-to-prototype-cskill/` → `article-to-prototype/`
- Update its SKILL.md frontmatter `name` field to `article-to-prototype`
- Update its `.claude-plugin/marketplace.json` if present
- Update its README.md
- [ ] Search entire codebase for remaining `-cskill` references and update them
- [ ] Update all example directory names in documentation
### Step 5: Create the Cross-Platform Install Script
Create `scripts/install-template.sh` — a template that gets customized and included in every generated skill as `install.sh`.
- [ ] Write `scripts/install-template.sh`:
```bash
#!/usr/bin/env bash
# Cross-platform installer for Agent Skills
# Detects the user's AI coding tool and installs to the correct location
set -euo pipefail
SKILL_NAME="{{SKILL_NAME}}" # Replaced during generation
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# Parse arguments
PLATFORM=""
PROJECT_LEVEL=false
CUSTOM_PATH=""
DRY_RUN=false
while [[ $# -gt 0 ]]; do
case $1 in
--platform) PLATFORM="$2"; shift 2 ;;
--project) PROJECT_LEVEL=true; shift ;;
--path) CUSTOM_PATH="$2"; shift 2 ;;
--dry-run) DRY_RUN=true; shift ;;
-h|--help) show_help; exit 0 ;;
*) echo "Unknown option: $1"; exit 1 ;;
esac
done
# Platform detection logic
# Install to detected or specified location
# Validate SKILL.md before installing
# Report success with next-steps instructions
```
- [ ] Implement platform detection:
- Check for `~/.claude/` → Claude Code
- Check for `~/.copilot/` or `.github/` → GitHub Copilot
- Check for `~/.cursor/` or `.cursor/` → Cursor
- Check for `~/.windsurf/` → Windsurf
- Check for `~/.cline/` or `.clinerules/` → Cline
- Check for `~/.codex/` → OpenAI Codex CLI
- Check for `~/.gemini/` → Gemini CLI
- Fallback: prompt user or use `--platform` flag
- [ ] Implement `--project` flag for project-level installation (`.claude/skills/`, `.github/skills/`, etc.)
- [ ] Implement `--dry-run` flag (show what would happen without doing it)
- [ ] Implement SKILL.md validation before copying
- [ ] Print success message with platform-specific activation instructions
- [ ] Handle errors: permission denied, directory doesn't exist, invalid SKILL.md
### Step 6: Create Validation and Security Scanning Scripts
- [ ] Create `scripts/validate.py`:
- Validate frontmatter: `name` (1-64 chars, lowercase+hyphens, no start/end hyphen, no consecutive hyphens)
- Validate frontmatter: `description` (1-1024 chars, non-empty)
- Validate: directory name matches `name` field
- Validate: SKILL.md exists and starts with `---` frontmatter
- Validate: SKILL.md body <500 lines (warning, not error)
- Validate: optional fields have correct types if present
- Validate: referenced files in SKILL.md body exist
- Return structured result: `{"valid": bool, "errors": [], "warnings": []}`
- [ ] Create `scripts/security_scan.py`:
- Scan for hardcoded API keys (regex patterns for common key formats: `sk-`, `AKIA`, `ghp_`, `glpat-`, etc.)
- Scan for `.env` files included in skill directory
- Scan for `credentials.json`, `secrets.json`, `api_keys.json`
- Scan for `eval()`, `exec()`, `subprocess.call(shell=True)` in Python scripts
- Scan for `os.system()` with string concatenation (shell injection)
- Scan for `__import__` dynamic imports
- Return structured result: `{"clean": bool, "issues": []}`
- [ ] Integrate both into the generation pipeline (Phase 5 runs them after file creation)
### Step 7: Update the Export System
- [ ] Update `scripts/export_utils.py`:
- Keep existing Desktop/Web and API export functionality (backwards compatible)
- Add validation step before export (call `validate.py`)
- Add security scan before export (call `security_scan.py`)
- Remove `-cskill` from any hardcoded name handling
- Update the generated installation guide to include instructions for ALL platforms (Claude Code, Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI)
- Add optional `--platform` parameter for platform-specific export
- [ ] Update `references/cross-platform-guide.md`:
- Expand from 4 Anthropic platforms to all 8+ platforms
- Add installation paths for each platform
- Add the Agent Skills Open Standard as the unifying reference
- Remove references to marketplace.json as a universal requirement
- [ ] Update `references/export-guide.md` (if it exists) with new platform targets
### Step 8: Update Documentation and README
- [ ] Update `README.md`:
- Update version to 4.0
- Add "Cross-Platform Compatible" badge/note at top
- List all supported platforms (Claude Code, Copilot CLI, VS Code Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI)
- Remove all `-cskill` references
- Update installation instructions for all platforms
- Add "Agent Skills Open Standard" compliance note
- Update architecture diagrams (no -cskill, no mandatory marketplace.json)
- Add "Migration from v3.x" section pointing to MIGRATION.md
- [ ] Create `MIGRATION.md`:
- How to update from v3.x to v4.0
- Breaking changes: -cskill suffix removed, marketplace.json simplified
- How to migrate existing generated skills (rename dirs, update frontmatter, fix marketplace.json)
- Automated migration: mention that the tool can help migrate with "Migrate this skill to the new standard"
- [ ] Update `docs/CHANGELOG.md`:
- Add v4.0 entry with all changes
- Note breaking changes
- Note new features (cross-platform, validation, security scan, install.sh)
- [ ] Update `docs/CLAUDE_SKILLS_ARCHITECTURE.md`:
- Reference the Agent Skills Open Standard
- Update directory structures (no -cskill)
- Add cross-platform compatibility information
---
## Tests to Write
Write tests for these behaviors (derived from the spec, not from holdout scenarios):
| Test | Covers | Type |
|------|--------|------|
| Validate SKILL.md frontmatter with valid name/description passes | FR-001 | Unit |
| Validate SKILL.md frontmatter with name >64 chars fails | FR-001 | Unit |
| Validate SKILL.md frontmatter with empty description fails | FR-001 | Unit |
| Validate name matches directory name | FR-002 | Unit |
| Validate SKILL.md body >500 lines produces warning | FR-003 | Unit |
| Generated skill has no marketplace.json (simple skill) | FR-005 | Integration |
| Generated skill name has no -cskill suffix | FR-007 | Integration |
| Security scan detects hardcoded API key | FR-013 | Unit |
| Security scan detects .env file in skill | FR-013 | Unit |
| Security scan detects shell injection pattern | FR-014 | Unit |
| install.sh detects Claude Code platform | FR-015, FR-016 | Integration |
| install.sh detects Copilot platform | FR-015, FR-016 | Integration |
| install.sh --dry-run produces no side effects | FR-015 | Unit |
| install.sh --platform cursor installs to .cursor/rules/ | FR-017 | Integration |
| Generated README has multi-platform install section | FR-018 | Integration |
| Export system still generates Desktop .zip | FR-019 | Integration |
| Export system still generates API .zip <8MB | FR-019 | Integration |
| Meta-skill SKILL.md is <500 lines | FR-004, FR-021 | Unit |
| Generated skill works on SKILL.md standard without modification | FR-028, NFR-001 | Integration |
---
## Definition of Done
All of the following must be true:
- [ ] The meta-skill's own SKILL.md is <500 lines with spec-compliant frontmatter
- [ ] `.claude-plugin/marketplace.json` contains ONLY official fields
- [ ] No `-cskill` suffix appears anywhere in the codebase (code, docs, examples)
- [ ] `article-to-prototype-cskill/` renamed to `article-to-prototype/` with updated frontmatter
- [ ] Generated skills produce spec-compliant SKILL.md (passes validation)
- [ ] Generated skills include `install.sh` for cross-platform installation
- [ ] Generated README.md includes install instructions for 5+ platforms
- [ ] `scripts/validate.py` checks all spec rules and returns structured results
- [ ] `scripts/security_scan.py` catches hardcoded keys and injection patterns
- [ ] Export system updated with validation, security scan, and multi-platform install guide
- [ ] `references/cross-platform-guide.md` covers 8+ platforms
- [ ] `MIGRATION.md` created with v3.x → v4.0 migration guide
- [ ] `README.md` updated for v4.0 with all platform support
- [ ] No hardcoded secrets or credentials in any file
- [ ] All Python files pass `ruff check`
- [ ] `install.sh` template works on macOS and Linux
---
## Explicit Exclusions
Do NOT implement these (they are out of scope):
- Building a skill marketplace or registry
- Converting `.cursorrules` or `.windsurfrules` into SKILL.md
- MCP server integration
- GUI or web interface
- Rewriting AgentDB integration
- Supporting platforms that haven't adopted SKILL.md standard
- Publishing automation to SkillsMP/SkillHub (just make skills compatible)
---
## Reference Files
- Specification: `.clarity/spec.md`
- Project context: `.clarity/context.md`
- Agent Skills Open Standard: https://agentskills.io/specification
- Current codebase: All files in the repository root

65
.clarity/plan.md Normal file
View file

@ -0,0 +1,65 @@
# Implementation Plan: agent-skill-creator v4.0 — Cross-Platform Modernization
> Generated by `/clarity` on 2026-02-26
> Full spec: `.clarity/spec.md`
> Handoff: `.clarity/handoff.md`
> Holdout scenarios: `scenarios/` (59 scenarios covering all 28 FRs + 7 NFRs)
---
## Summary
Modernize agent-skill-creator from a Claude-only meta-skill (v3.2) to a cross-platform skill factory (v4.0) that generates skills compliant with the **Agent Skills Open Standard** (agentskills.io). Skills will work on Claude Code, GitHub Copilot CLI, VS Code Copilot, Cursor, Windsurf, Cline, OpenAI Codex CLI, Gemini CLI, and any future SKILL.md adopter — without modification.
## What Changes
| Area | Before (v3.2) | After (v4.0) |
|------|---------------|--------------|
| SKILL.md | 4,116 lines (monolith) | <500 lines + references/ |
| marketplace.json | Non-standard fields (Issue #5) | Official fields only, optional |
| Naming | `-cskill` suffix mandatory | Standard kebab-case, no suffix |
| Platforms | 4 (Claude Code/Desktop/Web/API) | 8+ (all SKILL.md adopters) |
| Validation | None | Spec compliance + security scan |
| Install UX | Manual per-platform | `install.sh` auto-detects platform |
| Phase 5 output | marketplace.json first | SKILL.md first (primary file) |
## What Stays the Same
- 5-phase pipeline (Discovery → Design → Architecture → Detection → Implementation)
- AgentDB integration (optional, graceful degradation)
- Simple skill vs Complex suite architecture support
- Desktop/Web .zip export and API .zip export
- All activation trigger phrases
## Implementation Steps (8 steps, ~3 phases)
### Phase A: Fix the Meta-Skill Itself
**Step 1** — Restructure SKILL.md: 4,116 → <500 lines with progressive disclosure to `references/`
**Step 2** — Fix marketplace.json: Strip non-standard fields (fixes Issue #5)
### Phase B: Update the Skill Generation Pipeline
**Step 3** — Update Phase 5: SKILL.md-first (not marketplace.json), spec-compliant output, validation + security scan
**Step 4** — Remove `-cskill` naming convention everywhere (code, docs, examples, rename `article-to-prototype-cskill/`)
### Phase C: Add Cross-Platform Tooling
**Step 5** — Create `install.sh` template: Auto-detects Claude Code, Copilot, Cursor, Windsurf, Cline, Codex, Gemini
**Step 6** — Create `validate.py` + `security_scan.py`: Spec validation + OWASP-lite security checks
**Step 7** — Update export system: Multi-platform install guide, validation before export
**Step 8** — Update all documentation: README v4.0, MIGRATION.md, CHANGELOG, cross-platform guide
## Key Deliverables
1. `.clarity/spec.md` — Full specification (28 FRs, 7 NFRs, data model, API contracts)
2. `.clarity/handoff.md` — Self-contained implementation prompt for any AI coding agent
3. `scenarios/SC-001..SC-059` — 59 holdout test scenarios for independent evaluation
4. `.clarity/context.md` — Research context and ecosystem analysis
## Open Questions (4)
1. Should the tool offer direct publishing to SkillsMP/SkillHub?
2. Should `install.sh` support `--uninstall`?
3. Should validation check that referenced files exist?
4. Should Cursor export generate `.mdc` or rely on native SKILL.md support?

394
.clarity/spec.md Normal file
View file

@ -0,0 +1,394 @@
# 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?

115
.claude-plugin/marketplace.json
View file

@ -1,124 +1,11 @@
{
"name": "agent-skill-creator",
"owner": {
"name": "Agent Skill Creator",
"email": "agrolisboa@gmail.com"
},
"metadata": {
"description": " Agent Skill Creator - Meta-skill for autonomous agent generation with multi-agent support, templates, and interactive configuration. Supports single agents, multi-agent suites, transcript processing, template-based creation, and batch agent creation.",
"version": "3.0.0",
"created": "2025-10-18",
"updated": "2025-10-23",
"language": "en-US",
"features": [
"multi-agent-support",
"template-system",
"transcript-processing",
"interactive-configuration",
"batch-creation",
"enhanced-validation"
]
},
"plugins": [
{
"name": "agent-skill-creator-plugin",
"description": "This enhanced meta skill should be used when the user asks to create an CLAUDE CODE agent SKILL(S), automate a repetitive workflow, create a custom skill, or needs advanced agent creation capabilities. Activates with phrases like every day, daily I have to, I need to repeat, create agent for, automate workflow, create skill for, need to automate, turn process into agent. Supports single agents, multi-agent suites, transcript processing, template-based creation, and interactive configuration. Claude will use the enhanced protocol to research APIs, define analyses, structure everything, implement functional code, and create complete skills autonomously with optional user guidance.",
"description": "Create cross-platform agent skills from workflow descriptions. Activates when users ask to create an agent, automate a repetitive workflow, create a custom skill, or need advanced agent creation. Triggers on phrases like create agent for, automate workflow, create skill for, every day I have to, daily I need to, turn process into agent, need to automate, create a cross-platform skill, validate this skill, export this skill, migrate this skill. Supports single skills, multi-agent suites, transcript processing, template-based creation, interactive configuration, cross-platform export, and spec validation.",
"source": "./",
"strict": false,
"skills": ["./"]
}
],
"compatibility": {
"minimum_claude_version": "1.0.0",
"backward_compatible": true,
"deprecated_versions": []
},
"templates": {
"enabled": true,
"directory": "./templates/",
"available": [
"financial-analysis",
"climate-analysis",
"e-commerce-analytics"
]
},
"capabilities": {
"single_agent_creation": true,
"multi_agent_suite": true,
"batch_creation": true,
"template_based": true,
"transcript_processing": true,
"interactive_mode": true,
"preview_system": true
},
"activation": {
"keywords": [
"create an agent for",
"create a skill for",
"create agent for",
"create skill for",
"automate workflow",
"automate this process",
"automate a repetitive workflow",
"every day I have to",
"daily I have to",
"I need to repeat",
"need to automate",
"turn process into agent",
"turn workflow into agent",
"turn this into agent",
"develop an agent for",
"develop a skill for",
"convert this transcript into agent",
"convert this codebase into SKILL"
],
"patterns": [
"(?i)(create|build|develop|make)\\s+(an?\\s+)?(agent|skill)\\s+(for|to|that)",
"(?i)(automate|automation)\\s+(this\\s+)?(workflow|process|task|repetitive)",
"(?i)(every day|daily|repeatedly)\\s+(I|we)\\s+(have to|need to|do|must)",
"(?i)(turn|convert|transform)\\s+(this\\s+)?(process|workflow|task)\\s+into\\s+(an?\\s+)?agent",
"(?i)need\\s+to\\s+automate",
"(?i)(create|need)\\s+a\\s+custom\\s+skill",
"(?i)I\\s+(repeatedly|constantly|always)\\s+(need to|have to|do)"
]
},
"usage": {
"example": "Create an agent for processing daily invoice PDFs and updating the database",
"input_types": [
"workflow_description",
"repetitive_task_description",
"automation_request"
],
"output_types": [
"complete_skill",
"multi_agent_suite",
"functional_code"
],
"when_to_use": [
"User explicitly asks to create an agent or skill",
"User describes a repetitive workflow that takes significant time",
"User wants to automate a manual process",
"User says phrases like 'every day I have to' or 'daily I need to'",
"User wants to turn a described process into an automated agent"
],
"when_not_to_use": [
"User is asking general programming questions",
"User wants to use an existing skill (not create a new one)",
"User is asking for code snippets without automation context",
"User is asking about how skills work (documentation questions)",
"User wants to modify or debug existing code without creating new agent"
]
},
"test_queries": [
"Create an agent for processing CSV files daily",
"Create a skill for analyzing stock market data",
"Automate this workflow: download PDFs, extract data, update spreadsheet",
"Every day I have to manually check emails and categorize them. Automate this.",
"I need to repeat this task: fetch API data, transform it, store in database",
"Turn this process into an agent: scrape websites, analyze content, generate reports",
"Develop an agent to monitor GitHub repos and send notifications",
"Need to automate invoice processing that I do daily",
"Create a skill that extracts data from PDFs and generates reports",
"Daily I have to download files from FTP and process them. Create an agent for this."
]
}

148
MIGRATION.md Normal file
View file

@ -0,0 +1,148 @@
# Migration Guide: v3.x to v4.0
## Overview
Agent-skill-creator v4.0 brings full compliance with the **Agent Skills Open Standard**, cross-platform support for 8+ platforms, and several breaking changes from v3.x.
## Breaking Changes
### 1. `-cskill` Suffix Removed
**Before (v3.x):**
```
pdf-text-extractor-cskill/
financial-analysis-suite-cskill/
```
**After (v4.0):**
```
pdf-text-extractor/
financial-analysis-suite/
```
**Migration:**
```bash
# Rename directory
mv my-skill-cskill my-skill
# Update SKILL.md frontmatter
# Change: name: my-skill-cskill
# To: name: my-skill
# Update marketplace.json (if present)
# Change: "name": "my-skill-cskill"
# To: "name": "my-skill"
```
### 2. marketplace.json Simplified
Non-standard fields have been removed. Simple skills no longer need marketplace.json at all.
**Before (v3.x):**
```json
{
"name": "my-skill-cskill",
"owner": { ... },
"metadata": { ... },
"plugins": [{ ... }],
"compatibility": { ... },
"templates": { ... },
"capabilities": { ... },
"activation": { ... },
"usage": { ... },
"test_queries": [...]
}
```
**After (v4.0):**
```json
{
"name": "my-skill",
"plugins": [{
"name": "my-skill-plugin",
"description": "...",
"source": "./",
"skills": ["./"]
}]
}
```
**Migration:**
- For simple skills: Delete `.claude-plugin/marketplace.json` entirely
- For complex suites: Strip to only `name` and `plugins` fields
### 3. SKILL.md Frontmatter Updated
**Before (v3.x):** Only `name` and `description` required.
**After (v4.0):** Additional recommended fields:
```yaml
---
name: my-skill
description: >-
Description here (<=1024 chars)
license: MIT
metadata:
author: Your Name
version: 1.0.0
---
```
### 4. SKILL.md Body Size Limit
Generated SKILL.md files must now be **under 500 lines**. Move detailed content to `references/` files.
### 5. install.sh Added
Generated skills now include an `install.sh` cross-platform installer script.
## How to Migrate Existing Skills
### Automated Migration
Ask the agent-skill-creator to migrate:
```
"Migrate this skill to the new standard"
"Update my-skill to v4 format"
```
### Manual Migration Steps
1. **Rename directory** (remove `-cskill` suffix)
2. **Update SKILL.md frontmatter**:
- Remove `-cskill` from `name` field
- Add `license`, `metadata` fields
- Ensure `description` is <=1024 characters
3. **Simplify marketplace.json** (or delete for simple skills)
4. **Add install.sh** (copy from `scripts/install-template.sh` and customize)
5. **Update README.md** with multi-platform install instructions
6. **Validate**: Run `python3 scripts/validate.py ./my-skill/`
7. **Security scan**: Run `python3 scripts/security_scan.py ./my-skill/`
## Updating the Meta-Skill
If you have agent-skill-creator installed:
```bash
cd agent-skill-creator
git pull
```
The meta-skill will work immediately. No reinstallation required. The same trigger phrases and workflows still work.
## What Didn't Change
- The 5-phase pipeline (Discovery, Design, Architecture, Detection, Implementation)
- AgentDB integration (still optional)
- Support for both simple skills and complex suites
- Desktop/Web .zip export and Claude API export
- All activation trigger phrases
## New Features in v4.0
- **Cross-platform support**: Skills work on Claude Code, Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI
- **install.sh**: Auto-detect platform and install to the correct location
- **Spec validation**: `scripts/validate.py` checks compliance with the Agent Skills Open Standard
- **Security scanning**: `scripts/security_scan.py` detects hardcoded keys and injection patterns
- **Lean SKILL.md**: Under 500 lines with progressive disclosure via references/

2414
README.md
View file

File diff suppressed because it is too large Load diff

4250
SKILL.md
View file

File diff suppressed because it is too large Load diff

113
article-to-prototype-cskill/.claude-plugin/marketplace.json
View file

@ -1,113 +0,0 @@
{
"name": "article-to-prototype-cskill",
"version": "1.0.0",
"type": "skill",
"description": "Autonomously extracts technical content from articles (PDF, web, markdown, notebooks) and generates functional prototypes/POCs in the appropriate programming language",
"author": "Agent-Skill-Creator",
"keywords": [
"article",
"paper",
"pdf",
"web",
"notebook",
"extraction",
"prototype",
"poc",
"implementation",
"code-generation",
"multi-format",
"multi-language"
],
"activation": {
"keywords": [
"extract from article",
"implement from paper",
"create prototype from",
"read article and build",
"parse pdf and implement",
"parse url and implement",
"article to code",
"paper to prototype",
"implement algorithm from",
"build from documentation"
],
"patterns": [
"(?i)(extract|parse|read)\\s+(from\\s+)?(article|paper|pdf|url|notebook)",
"(?i)(implement|build|create|generate)\\s+(from\\s+)?(article|paper|documentation)",
"(?i)(prototype|poc)\\s+from\\s+(article|paper)"
]
},
"capabilities": [
"pdf-extraction",
"web-scraping",
"notebook-parsing",
"markdown-processing",
"content-analysis",
"algorithm-detection",
"language-inference",
"code-generation",
"prototype-creation",
"multi-language-support"
],
"supported_formats": [
"pdf",
"url",
"html",
"markdown",
"ipynb",
"txt"
],
"supported_languages": [
"python",
"javascript",
"typescript",
"rust",
"go",
"julia",
"java",
"cpp"
],
"dependencies": {
"python": ">=3.8",
"pip": [
"PyPDF2>=3.0.0",
"pdfplumber>=0.10.0",
"requests>=2.31.0",
"beautifulsoup4>=4.12.0",
"trafilatura>=1.6.0",
"nbformat>=5.9.0",
"mistune>=3.0.0",
"anthropic>=0.18.0"
]
},
"features": [
"multi-format-extraction",
"intelligent-analysis",
"language-detection",
"prototype-generation",
"agentdb-integration"
],
"usage": {
"example": "Extract algorithms from this PDF and implement them in Python",
"input_types": [
"file_path",
"url",
"text"
],
"output_types": [
"code",
"prototype",
"documentation"
]
},
"metadata": {
"category": "code-generation",
"subcategory": "prototype-creation",
"complexity": "medium",
"estimated_lines": 1800,
"created_by": "agent-skill-creator",
"architecture": "simple-skill",
"agentdb_enabled": true,
"learning_enabled": true
}
}

11
article-to-prototype/.claude-plugin/marketplace.json Normal file
View file

@ -0,0 +1,11 @@
{
"name": "article-to-prototype",
"plugins": [
{
"name": "article-to-prototype-plugin",
"description": "Autonomously extracts technical content from articles (PDF, web, markdown, notebooks) and generates functional prototypes and proof-of-concept implementations in the appropriate programming language. Activates with phrases like extract from article, implement from paper, create prototype from, article to code, paper to prototype, parse pdf and implement, build from documentation.",
"source": "./",
"skills": ["./"]
}
]
}

0
article-to-prototype-cskill/DECISIONS.md → article-to-prototype/DECISIONS.md
View file

4
article-to-prototype-cskill/README.md → article-to-prototype/README.md
View file

@ -33,7 +33,7 @@ The Article-to-Prototype Skill bridges the gap between technical documentation a
### Install Dependencies
```bash
cd article-to-prototype-cskill
cd article-to-prototype
pip install -r requirements.txt
```
@ -93,7 +93,7 @@ python scripts/main.py papers/dijkstra.pdf
**Output:**
```
article-to-prototype-cskill/output/
article-to-prototype/output/
├── src/
│ ├── main.py # Dijkstra implementation
│ └── graph.py # Graph data structure

27
article-to-prototype-cskill/SKILL.md → article-to-prototype/SKILL.md
View file

@ -1,12 +1,18 @@
# Article-to-Prototype Skill
**Version:** 1.0.0
**Type:** Simple Skill
**Architecture:** Simple Skill (Single focused objective)
**Created by:** Agent-Skill-Creator v2.1
**AgentDB Integration:** Enabled
---
name: article-to-prototype
description: >-
Autonomously extracts technical content from articles (PDF, web, markdown,
notebooks) and generates functional prototypes and proof-of-concept
implementations in the appropriate programming language. Activates with
phrases like extract from article, implement from paper, create prototype
from, article to code, paper to prototype, parse pdf and implement,
build from documentation.
license: MIT
metadata:
author: Agent-Skill-Creator
version: 1.0.0
---
# Article-to-Prototype Skill
## Table of Contents
@ -1975,8 +1981,7 @@ Test suite includes sample articles:
```bash
# Clone the skill
cd article-to-prototype-cskill
cd article-to-prototype
# Install Python dependencies
pip install -r requirements.txt
@ -2059,4 +2064,4 @@ With AgentDB integration, the skill learns and improves with every use, becoming
**Version:** 1.0.0
**Last Updated:** 2025-10-23
**License:** MIT
**Support:** https://github.com/agent-skill-creator/article-to-prototype-cskill
**Support:** https://github.com/agent-skill-creator/article-to-prototype

0
article-to-prototype-cskill/assets/examples/sample_input.md → article-to-prototype/assets/examples/sample_input.md
View file

0
article-to-prototype-cskill/assets/prompts/analysis_prompt.txt → article-to-prototype/assets/prompts/analysis_prompt.txt
View file

0
article-to-prototype-cskill/references/analysis-methodology.md → article-to-prototype/references/analysis-methodology.md
View file

0
article-to-prototype-cskill/references/extraction-patterns.md → article-to-prototype/references/extraction-patterns.md
View file

0
article-to-prototype-cskill/references/generation-rules.md → article-to-prototype/references/generation-rules.md
View file

0
article-to-prototype-cskill/requirements.txt → article-to-prototype/requirements.txt
View file

0
article-to-prototype-cskill/scripts/__init__.py → article-to-prototype/scripts/__init__.py
View file

0
article-to-prototype-cskill/scripts/analyzers/__init__.py → article-to-prototype/scripts/analyzers/__init__.py
View file

0
article-to-prototype-cskill/scripts/analyzers/code_detector.py → article-to-prototype/scripts/analyzers/code_detector.py
View file

0
article-to-prototype-cskill/scripts/analyzers/content_analyzer.py → article-to-prototype/scripts/analyzers/content_analyzer.py
View file

0
article-to-prototype-cskill/scripts/extractors/__init__.py → article-to-prototype/scripts/extractors/__init__.py
View file

0
article-to-prototype-cskill/scripts/extractors/markdown_extractor.py → article-to-prototype/scripts/extractors/markdown_extractor.py
View file

0
article-to-prototype-cskill/scripts/extractors/notebook_extractor.py → article-to-prototype/scripts/extractors/notebook_extractor.py
View file

0
article-to-prototype-cskill/scripts/extractors/pdf_extractor.py → article-to-prototype/scripts/extractors/pdf_extractor.py
View file

0
article-to-prototype-cskill/scripts/extractors/web_extractor.py → article-to-prototype/scripts/extractors/web_extractor.py
View file

0
article-to-prototype-cskill/scripts/generators/__init__.py → article-to-prototype/scripts/generators/__init__.py
View file

0
article-to-prototype-cskill/scripts/generators/language_selector.py → article-to-prototype/scripts/generators/language_selector.py
View file

0
article-to-prototype-cskill/scripts/generators/prototype_generator.py → article-to-prototype/scripts/generators/prototype_generator.py
View file

0
article-to-prototype-cskill/scripts/main.py → article-to-prototype/scripts/main.py
View file

94
docs/CHANGELOG.md
View file

@ -5,6 +5,100 @@ All notable changes to Agent Creator will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/).
## [4.0.0] - February 2026
### MAJOR: Cross-Platform Modernization & Agent Skills Open Standard Compliance
**Full compliance with the Agent Skills Open Standard. Skills now work on 8+ platforms.**
### Breaking Changes
#### `-cskill` Suffix Removed
- All generated skill names now use standard kebab-case (e.g., `stock-analyzer` not `stock-analyzer-cskill`)
- `article-to-prototype-cskill/` renamed to `article-to-prototype/`
- See `MIGRATION.md` for migration guide
#### marketplace.json Simplified (Fixes Issue #5)
- Stripped to ONLY official fields: `name`, `plugins[].name`, `plugins[].description`, `plugins[].source`, `plugins[].skills`
- Removed non-standard fields: `owner`, `metadata`, `compatibility`, `templates`, `capabilities`, `activation`, `usage`, `test_queries`
- Simple skills no longer need marketplace.json at all
#### SKILL.md Restructured
- Meta-skill SKILL.md: 4,116 lines reduced to 272 lines
- Generated SKILL.md must be <500 lines with progressive disclosure via `references/`
### Added
#### Cross-Platform Support (8+ Platforms)
- **Claude Code**: `~/.claude/skills/` or `.claude/skills/`
- **GitHub Copilot**: `.github/skills/`
- **Cursor**: `.cursor/rules/`
- **Windsurf**: `.windsurf/skills/`
- **Cline**: `.clinerules/`
- **OpenAI Codex CLI**: `.codex/skills/`
- **Gemini CLI**: `.gemini/skills/`
#### Cross-Platform Install Script (`scripts/install-template.sh`)
- Auto-detect platform from directory structure
- `--platform` flag for explicit selection
- `--project` flag for project-level install
- `--dry-run` flag for preview
- `--path` flag for custom location
- SKILL.md validation before install
#### Spec Validation (`scripts/validate.py`)
- Validates frontmatter: name (1-64 chars, kebab-case), description (1-1024 chars)
- Checks directory name matches `name` field
- Warns on missing `license`, `metadata` fields
- Warns on SKILL.md body exceeding 500 lines
- Checks referenced files exist
- JSON output with `--json` flag
#### Security Scanning (`scripts/security_scan.py`)
- Detects hardcoded API keys (OpenAI, AWS, GitHub, GitLab, Slack, generic)
- Detects `.env`, `credentials.json`, `secrets.json` files
- Detects dangerous Python patterns: `eval()`, `exec()`, `os.system()`, `shell=True`, `__import__()`
- JSON output with `--json` flag
#### SKILL.md Frontmatter Enhancements
- `license` field (recommended)
- `metadata.author` and `metadata.version` fields (recommended)
- `compatibility` field (optional)
#### Documentation
- `MIGRATION.md`: v3.x to v4.0 migration guide
- `references/pipeline-phases.md`: Consolidated Phase 1-5 instructions
- `references/architecture-guide.md`: Simple vs Suite decision framework
- `references/templates-guide.md`: Template-based creation docs
- `references/interactive-mode.md`: Interactive wizard docs
- `references/multi-agent-guide.md`: Suite creation docs
- `references/agentdb-integration.md`: AgentDB learning system docs
### Enhanced
#### Export System
- Validation and security scan run before export
- Installation guide now covers all 8+ platforms
- Removed -cskill from name handling
#### Cross-Platform Guide
- Expanded from 4 Anthropic platforms to 8+ platforms
- Installation paths for each platform documented
- Agent Skills Open Standard as the unifying reference
#### Phase 5 Pipeline
- SKILL.md created first (not marketplace.json)
- Validation step added after file generation
- Security scan step added after file generation
- No mandatory marketplace.json for simple skills
### Removed
- `-cskill` suffix requirement from naming conventions
- Non-standard marketplace.json fields
- Mandatory marketplace.json for simple skills
---
## [3.2.0] - October 2025
### 🎯 **MAJOR: Cross-Platform Export System**

62
docs/CLAUDE_SKILLS_ARCHITECTURE.md
View file

@ -165,59 +165,59 @@ To avoid confusion:
## ✅ **Correct Terms**
| Situation | Correct Term | Example (with -cskill convention) |
| Situation | Correct Term | Example (standard kebab-case) |
|----------|---------------|--------------------------------|
| Single file with capability | **Simple Skill** | `pdf-generator-cskill/SKILL.md` |
| Specialized sub-capability | **Component Skill** | `data-extraction-cskill/SKILL.md` |
| Set of capabilities | **Skill Suite** | `financial-analysis-suite-cskill/` |
| Single file with capability | **Simple Skill** | `pdf-generator/SKILL.md` |
| Specialized sub-capability | **Component Skill** | `data-extraction/SKILL.md` |
| Set of capabilities | **Skill Suite** | `financial-analysis-suite/` |
| Organizational file | **Marketplace Plugin** | `marketplace.json` |
| Complete system | **Skill Ecosystem** | Suite + Marketplace + Resources |
## 🏷️ **Naming Convention: The "-cskill" Suffix**
## 🏷️ **Naming Convention: Standard Kebab-Case (Agent Skills Open Standard)**
### **Purpose of the "-cskill" Suffix**
- **Clear Identification**: Immediately indicates it's a Claude Skill
- **Defined Origin**: Created by Agent-Skill-Creator
- **Consistent Standard**: Professional convention across all documentation
- **Avoids Confusion**: Distinguishes from manual skills or other sources
- **Easy Organization**: Simple identification and grouping
### **Purpose of Standard Kebab-Case Naming**
- **Clear Identification**: Descriptive names immediately convey the skill's purpose
- **Open Standard**: Follows the v4.0 Agent Skills Open Standard for interoperability
- **Consistent Standard**: Professional convention across all documentation and platforms
- **Simplicity**: No unnecessary suffixes -- the name speaks for itself
- **Easy Organization**: Simple identification and grouping by domain
### **Naming Rules**
**1. Standard Format**
```
{descriptive-description}-cskill/
{descriptive-name}/
```
**2. Simple Skills**
```
pdf-text-extractor-cskill/
csv-data-cleaner-cskill/
weekly-report-generator-cskill/
image-converter-cskill/
pdf-text-extractor/
csv-data-cleaner/
weekly-report-generator/
image-converter/
```
**3. Complex Skill Suites**
```
financial-analysis-suite-cskill/
e-commerce-automation-cskill/
research-workflow-cskill/
business-intelligence-cskill/
financial-analysis-suite/
e-commerce-automation/
research-workflow/
business-intelligence/
```
**4. Component Skills (within suites)**
```
data-acquisition-cskill/
technical-analysis-cskill/
reporting-generator-cskill/
user-interface-cskill/
data-acquisition/
technical-analysis/
reporting-generator/
user-interface/
```
**5. Formatting**
- ✅ Always lowercase
- ✅ Use hyphens to separate words
- ✅ Use hyphens to separate words (kebab-case)
- ✅ Descriptive and clear
- ✅ End with "-cskill"
- ✅ No unnecessary suffixes
- ❌ No underscores or spaces
- ❌ No special characters (except hyphens)
@ -225,11 +225,11 @@ user-interface-cskill/
| User Requirement | Generated Name |
|---------------------|-------------|
| "Extract text from PDF documents" | `pdf-text-extractor-cskill/` |
| "Clean CSV data automatically" | `csv-data-cleaner-cskill/` |
| "Complete financial analysis platform" | `financial-analysis-suite-cskill/` |
| "Generate weekly status reports" | `weekly-report-generator-cskill/` |
| "Automate e-commerce workflows" | `e-commerce-automation-cskill/` |
| "Extract text from PDF documents" | `pdf-text-extractor/` |
| "Clean CSV data automatically" | `csv-data-cleaner/` |
| "Complete financial analysis platform" | `financial-analysis-suite/` |
| "Generate weekly status reports" | `weekly-report-generator/` |
| "Automate e-commerce workflows" | `e-commerce-automation/` |
## 🎯 **Golden Rule**

26
docs/DECISION_LOGIC.md
View file

@ -108,7 +108,7 @@ Complex Suite Path:
# Decision confirmed: Create Simple Skill
architecture = "simple"
base_name = generate_descriptive_name(requirements)
skill_name = f"{base_name}-cskill" # Apply naming convention
skill_name = base_name # Standard kebab-case naming
files_to_create = [
"SKILL.md",
"scripts/ (if needed)",
@ -123,9 +123,9 @@ marketplace_json = False # Single skill doesn't need manifest
# Decision confirmed: Create Complex Skill Suite
architecture = "complex_suite"
base_name = generate_descriptive_name(requirements)
suite_name = f"{base_name}-cskill" # Apply naming convention
suite_name = base_name # Standard kebab-case naming
components = identify_components(requirements)
component_names = [f"{comp}-cskill" for comp in components]
component_names = list(components)
files_to_create = [
".claude-plugin/marketplace.json",
f"{component}/SKILL.md" for component in component_names,
@ -140,10 +140,10 @@ marketplace_json = True # Suite needs organization manifest
# Decision confirmed: Create Hybrid Architecture
architecture = "hybrid"
base_name = generate_descriptive_name(requirements)
skill_name = f"{base_name}-cskill" # Apply naming convention
skill_name = base_name # Standard kebab-case naming
main_skill = "primary_skill.md"
optional_components = identify_optional_components(requirements)
component_names = [f"{comp}-cskill" for comp in optional_components]
component_names = list(optional_components)
files_to_create = [
"SKILL.md", # Main orchestrator
"scripts/components/", # Optional sub-components
@ -170,16 +170,18 @@ def generate_descriptive_name(user_requirements):
base_name = sanitize_filename(base_name)
return base_name
def apply_cskill_convention(base_name):
"""Apply -cskill naming convention"""
if not base_name.endswith("-cskill"):
return f"{base_name}-cskill"
def apply_naming_convention(base_name):
"""Apply standard kebab-case naming convention"""
# Ensure valid kebab-case format
base_name = base_name.lower().strip()
base_name = re.sub(r'[^a-z0-9-]', '-', base_name)
base_name = re.sub(r'-+', '-', base_name).strip('-')
return base_name
# Examples of naming logic:
# "extract text from PDF" → "pdf-text-extractor-cskill"
# "financial analysis with reporting" → "financial-analysis-suite-cskill"
# "clean CSV data" → "csv-data-cleaner-cskill"
# "extract text from PDF" → "pdf-text-extractor"
# "financial analysis with reporting" → "financial-analysis-suite"
# "clean CSV data" → "csv-data-cleaner"
```
## 🎯 **Decision Documentation**

15
docs/INTERNAL_FLOW_ANALYSIS.md
View file

@ -189,8 +189,7 @@ ANALYSIS RESULT:
✅ Multiple domains of expertise
DECISION: Complex Skill Suite
GENERATED NAME: financial-analysis-suite-cskill
```
GENERATED NAME: financial-analysis-suite```
#### **3.2 Component Structure Definition**
```python
@ -467,10 +466,10 @@ if __name__ == "__main__":
After approximately **45-90 minutes** of autonomous processing, the user will have:
```
financial-analysis-suite-cskill/
financial-analysis-suite/
├── .claude-plugin/
│ └── marketplace.json ← Suite manifest
├── data-acquisition-cskill/
├── data-acquisition/
│ ├── SKILL.md ← Component skill 1
│ ├── scripts/
│ │ ├── fetch_data.py ← Functional code
@ -479,17 +478,17 @@ financial-analysis-suite-cskill/
│ ├── references/
│ │ └── api_documentation.md ← Documentation
│ └── assets/
├── technical-analysis-cskill/
├── technical-analysis/
│ ├── SKILL.md ← Component skill 2
│ ├── scripts/
│ │ ├── indicators.py ← Technical calculations
│ │ ├── signals.py ← Signal generation
│ │ └── backtester.py ← Historical tests
│ └── references/
├── visualization-cskill/
├── visualization/
│ ├── SKILL.md ← Component skill 3
│ └── scripts/chart_generator.py
├── reporting-cskill/
├── reporting/
│ ├── SKILL.md ← Component skill 4
│ └── scripts/report_generator.py
├── shared/
@ -502,7 +501,7 @@ financial-analysis-suite-cskill/
└── test_installation.py ← Automatic test
```
**Note:** All components use the "-cskill" convention to identify that they were created by Agent-Skill-Creator.
**Note:** All components use standard kebab-case naming per the Agent Skills Open Standard.
## 🚀 **How to Use the Created Skill**

397
docs/NAMING_CONVENTIONS.md
View file

@ -1,374 +1,97 @@
# Naming Conventions: The "-cskill" Suffix
# Naming Conventions
## 🎯 **Purpose and Overview**
## Overview
This document establishes the mandatory naming convention for all Claude Skills created by Agent-Skill-Creator, using the "-cskill" suffix to ensure clear identification and professional consistency.
All skills created by Agent-Skill-Creator follow standard kebab-case naming per the Agent Skills Open Standard. The `name` field in SKILL.md frontmatter must match the parent directory name exactly.
## 🏷️ **The "-cskill" Suffix**
## Rules
### **Meaning**
- **CSKILL** = **C**laude **SKILL**
- Indicates the skill was automatically created by Agent-Skill-Creator
- Differentiates from manually created skills or other tools
### Required Format
### **Benefits**
✅ **Immediate Identification**
- Anyone sees "-cskill" and immediately knows it's a Claude Skill
- Instant recognition of origin (Agent-Skill-Creator)
✅ **Easy Organization**
- Easy to filter and find skills created by the creator
- Logical grouping in file systems
- Efficient search with consistent pattern
✅ **Professionalism**
- Professional and standardized naming convention
- Clarity in communication about origin and type
- Organized and intentional appearance
✅ **Avoids Confusion**
- No ambiguity about what's a skill vs plugin
- Clear distinction between manual vs automated skills
- Prevention of name conflicts
## 📋 **Naming Rules**
### **1. Mandatory Format**
```
{descriptive-description}-cskill/
{descriptive-name}/
```
### **2. Base Name Structure**
### Character Rules
#### **Simple Skills (Single Objective)**
```
{action}-{object}-csskill/
```
- **Allowed**: Lowercase letters (`a-z`), numbers (`0-9`), hyphens (`-`)
- **Length**: 1-64 characters
- Must **not** start or end with a hyphen
- Must **not** contain consecutive hyphens (`--`)
- Must match the parent directory name exactly
**Examples:**
- `pdf-text-extractor-cskill/`
- `csv-data-cleaner-cskill/`
- `image-converter-cskill/`
- `email-automation-cskill/`
- `report-generator-cskill/`
### Examples
#### **Complex Skill Suites (Multiple Components)**
```
{domain}-analysis-suite-cskill/
{domain}-automation-cskill/
{domain}-workflow-cskill/
```
**Simple Skills:**
- `pdf-text-extractor/`
- `csv-data-cleaner/`
- `weekly-report-generator/`
- `stock-analyzer/`
**Examples:**
- `financial-analysis-suite-cskill/`
- `e-commerce-automation-cskill/`
- `research-workflow-cskill/`
- `business-intelligence-cskill/`
**Complex Suites:**
- `financial-analysis-suite/`
- `e-commerce-automation/`
- `research-workflow/`
#### **Component Skills (Within Suites)**
```
{functionality}-{domain}-cskill/
```
**Component Skills (within suites):**
- `data-acquisition/`
- `technical-analysis/`
- `reporting-generator/`
**Examples:**
- `data-acquisition-cskill/`
- `technical-analysis-cskill/`
- `reporting-generator-cskill/`
- `user-interface-cskill/`
## Name Generation
### **3. Formatting Rules**
When creating a skill name from user input:
✅ **REQUIRED:**
- Always lowercase
- Use hyphens (-) to separate words
- End with "-cskill"
- Be descriptive and clear
- Use only alphanumeric characters and hyphens
❌ **PROHIBITED:**
- Uppercase letters
- Underscores (_)
- Whitespace
- Special characters (!@#$%&*)
- Numbers at the beginning
- Non-standard abbreviations
### **4. Recommended Length**
- **Minimum:** 10 characters (ex: `pdf-tool-cskill`)
- **Ideal:** 20-40 characters (ex: `financial-analysis-suite-cskill`)
- **Maximum:** 60 characters (justified exceptions)
## 🔧 **Name Generation Process**
### **Agent-Skill-Creator Automatic Logic**
1. **Extract key concepts** from the user's description
2. **Build descriptive name** using `{action}-{object}` or `{domain}-{purpose}` pattern
3. **Sanitize**: lowercase, replace spaces/underscores with hyphens, strip special characters
4. **Validate**: check length (1-64), no leading/trailing hyphens, no consecutive hyphens
```python
def generate_skill_name(user_requirements, complexity):
"""
Generates skill name following -cskill convention
"""
import re
# 1. Extract key concepts from user input
concepts = extract_key_concepts(user_requirements)
# 2. Create base name based on complexity
if complexity == "simple":
base_name = create_simple_name(concepts)
elif complexity == "complex_suite":
base_name = create_suite_name(concepts)
else: # hybrid
base_name = create_hybrid_name(concepts)
# 3. Sanitize and format
base_name = sanitize_name(base_name)
# 4. Apply -cskill convention
skill_name = f"{base_name}-cskill"
return skill_name
def create_simple_name(concepts):
"""Creates name for simple skills"""
if len(concepts) == 1:
return f"{concepts[0]}-tool"
elif len(concepts) == 2:
return f"{concepts[1]}-{concepts[0]}"
else:
return "-".join(concepts[:2])
def create_suite_name(concepts):
"""Creates name for complex suites"""
if len(concepts) <= 2:
return f"{concepts[0]}-automation"
else:
return f"{concepts[0]}-{'-'.join(concepts[1:3])}-suite"
def sanitize_name(name):
"""Sanitizes name to valid format"""
# Convert to lowercase
name = name.lower()
# Replace spaces and underscores with hyphens
def generate_skill_name(user_input: str) -> str:
"""Generate a valid skill name from user input."""
name = user_input.lower()
name = re.sub(r'[\s_]+', '-', name)
# Remove special characters
name = re.sub(r'[^a-z0-9-]', '', name)
# Remove multiple hyphens
name = re.sub(r'-+', '-', name)
# Remove hyphens at start/end
name = name.strip('-')
return name
return name[:64]
```
### **Transformation Examples**
## Validation
| User Input | Type | Extracted Concepts | Generated Name |
|------------------|------|-------------------|-------------|
| "Extract text from PDF" | Simple | ["extract", "text", "pdf"] | `pdf-text-extractor-cskill/` |
| "Clean CSV data automatically" | Simple | ["clean", "csv", "data"] | `csv-data-cleaner-cskill/` |
| "Complete financial analysis platform" | Suite | ["financial", "analysis", "platform"] | `financial-analysis-suite-cskill/` |
| "Automate e-commerce workflows" | Suite | ["automate", "ecommerce", "workflows"] | `ecommerce-automation-cskill/` |
| "Generate weekly status reports" | Simple | ["generate", "weekly", "reports"] | `weekly-report-generator-cskill/` |
## 📚 **Practical Examples by Domain**
### **Finance and Investments**
```
financial-analysis-suite-cskill/
portfolio-optimizer-cskill/
market-data-fetcher-cskill/
risk-calculator-cskill/
trading-signal-generator-cskill/
```
### **Data Analysis**
```
data-visualization-cskill/
statistical-analysis-cskill/
etl-pipeline-cskill/
data-cleaner-cskill/
dashboard-generator-cskill/
```
### **Document Automation**
```
pdf-processor-cskill/
word-automation-cskill/
excel-report-generator-cskill/
presentation-creator-cskill/
document-converter-cskill/
```
### **E-commerce and Sales**
```
inventory-tracker-cskill/
sales-analytics-cskill/
customer-data-processor-cskill/
order-automation-cskill/
price-monitor-cskill/
```
### **Research and Academia**
```
literature-review-cskill/
citation-manager-cskill/
research-data-collector-cskill/
academic-paper-generator-cskill/
survey-analyzer-cskill/
```
### **Productivity and Office**
```
email-automation-cskill/
calendar-manager-cskill/
task-tracker-cskill/
note-organizer-cskill/
meeting-scheduler-cskill/
```
## 🔍 **Validation and Quality**
### **Automatic Verification**
```python
def validate_skill_name(skill_name):
"""
Validates if name follows -cskill convention
"""
import re
# 1. Check -cskill suffix
if not skill_name.endswith("-cskill"):
return False, "Missing -cskill suffix"
# 2. Check lowercase format
if skill_name != skill_name.lower():
return False, "Must be lowercase"
# 3. Check valid characters
if not re.match(r'^[a-z0-9-]+-cskill$', skill_name):
return False, "Contains invalid characters"
# 4. Check length
if len(skill_name) < 10 or len(skill_name) > 60:
return False, "Invalid length"
# 5. Check consecutive hyphens
if '--' in skill_name:
return False, "Contains consecutive hyphens"
return True, "Valid naming convention"
def validate_skill_name(name: str) -> tuple[bool, str]:
"""Validate a skill name against the Agent Skills Open Standard."""
if not name:
return False, "Name cannot be empty"
if len(name) > 64:
return False, f"Name too long: {len(name)} chars (max 64)"
if not re.match(r'^[a-z0-9]([a-z0-9-]*[a-z0-9])?$', name):
return False, "Must be lowercase alphanumeric with hyphens, no leading/trailing hyphens"
if '--' in name:
return False, "Must not contain consecutive hyphens"
return True, "Valid"
```
### **Quality Checklist**
## Migration from v3.x
For each generated name, verify:
Skills created with v3.x used a `-cskill` suffix (e.g., `stock-analyzer-cskill/`). This suffix has been removed in v4.0 to comply with the Agent Skills Open Standard.
- [ ] **Ends with "-cskill"** ✓
- [ ] **Is in lowercase** ✓
- [ ] **Uses only hyphens as separators** ✓
- [ ] **Is descriptive and clear** ✓
- [ ] **Has no special characters** ✓
- [ ] **Appropriate length (10-60 characters)** ✓
- [ ] **Easy to pronounce and remember** ✓
- [ ] **Reflects main functionality** ✓
- [ ] **Is unique in ecosystem** ✓
To migrate:
## 🚀 **Best Practices**
```bash
# Rename directory
mv stock-analyzer-cskill stock-analyzer
### **1. Be Descriptive**
```
✅ good: pdf-text-extractor-cskill
❌ bad: tool-cskill
# Update SKILL.md frontmatter name field
# name: stock-analyzer
✅ good: financial-analysis-suite-cskill
❌ bad: finance-cskill
# Update marketplace.json name field (if present)
```
### **2. Keep It Simple**
```
✅ good: csv-data-cleaner-cskill
❌ bad: automated-csv-data-validation-and-cleaning-tool-cskill
✅ good: email-automation-cskill
❌ bad: professional-email-marketing-automation-workflow-cskill
```
### **3. Be Consistent**
```
✅ good: data-acquisition-cskill, data-processing-cskill, data-visualization-cskill
❌ bad: get-data-cskill, process-cskill, visualize-cskill
```
### **4. Think About the User**
```
✅ good: weekly-report-generator-cskill (clear what it does)
❌ bad: wrk-gen-cskill (abbreviated, confusing)
```
## 🔄 **Migration and Legacy**
### **Existing Skills Without "-cskill"**
If you have existing skills without the suffix:
1. **Add the suffix immediately**
```bash
mv old-skill-name old-skill-name-cskill
```
2. **Update internal references**
- Update SKILL.md
- Modify marketplace.json
- Update documentation
3. **Test functionality**
- Verify skill still works
- Confirm correct installation
### **Migration Documentation**
For each migrated skill, document:
```markdown
## Migration History
- **Original Name**: `old-name`
- **New Name**: `old-name-cskill`
- **Migration Date**: YYYY-MM-DD
- **Reason**: Apply -cskill naming convention
- **Impact**: None, purely cosmetic change
```
## 📖 **Quick Reference Guide**
### **To Create New Name:**
1. **Identify main objective** (ex: "extract PDF text")
2. **Extract key concepts** (ex: extract, pdf, text)
3. **Build base name** (ex: pdf-text-extractor)
4. **Add suffix** (ex: pdf-text-extractor-cskill)
### **To Validate Existing Name:**
1. **Check "-cskill" suffix**
2. **Confirm lowercase format**
3. **Check valid characters**
4. **Evaluate descriptiveness**
### **To Troubleshoot:**
- **Name too short**: Add descriptor
- **Name too long**: Remove secondary words
- **Confusing name**: Use clearer synonyms
- **Name conflict**: Add differentiator
## ✅ **Convention Summary**
**Formula:** `{descriptive-description}-cskill/`
**Essential Rules:**
- ✅ Always end with "-cskill"
- ✅ Always lowercase
- ✅ Use hyphens as separators
- ✅ Be descriptive and clear
**Results:**
- 🎯 Immediate identification as Claude Skill
- 🏗️ Clear origin (Agent-Skill-Creator)
- 📁 Easy organization
- 🔍 Efficient search
- 💬 Clear communication
**This convention ensures professional consistency and eliminates any confusion about the origin and type of created skills!**
See `MIGRATION.md` for full migration instructions.

122
docs/PIPELINE_ARCHITECTURE.md
View file

@ -18,13 +18,13 @@ Uma skill Claude é **conhecimento especializado** que foi:
```
Fonte de Conhecimento Skill Claude Capacidade
├─────────────────────────┬───────────────────────────────┬───────────────────────────────┬─────────────────┐
│ Artigo sobre análise │ → │ financial-analysis-cskill │ → │ Analisa dados │
│ Artigo sobre análise │ → │ financial-analysis │ → │ Analisa dados │
│ financeira │ │ (expertise capturada) │ │ de mercado │
│ │ │ │ │ automatica │
│ Manual de procedimento│ → │ business-process-cskill │ → │ Executa │
│ Manual de procedimento│ → │ business-process │ → │ Executa │
│ empresarial │ │ (expertise capturada) │ │ workflows │
│ │ │ │ │ padronizados │
│ Tutorial técnico │ → │ tutorial-system-cskill │ → │ Guia usuários │
│ Tutorial técnico │ → │ tutorial-system │ → │ Guia usuários │
│ passo a passo │ │ (expertise capturada) │ │ interativos │
└─────────────────────────┴───────────────────────────────┴─────────────────────────────┴─────────────────┘
```
@ -82,13 +82,13 @@ Entrada Bruta → [Etapa 1] → [Etapa 2] → [Etapa 3] → Saída Final
#### **Data Processing Pipeline**
```
data-processing-pipeline-cskill/
├── data-ingestion-cskill/ ← Coleta de dados brutos
data-processing-pipeline/
├── data-ingestion/ ← Coleta de dados brutos
│ └── output: dados_crudos.json
├── data-transformation-cskill/ ← Limpeza e estruturação
├── data-transformation/ ← Limpeza e estruturação
│ ├── input: dados_crudos.json
│ └── output: dados_limpos.json
└── data-analysis-cskill/ ← Análise e insights
└── data-analysis/ ← Análise e insights
├── input: dados_limpos.json
└── output: insights.json
```
@ -99,22 +99,22 @@ data-processing-pipeline-cskill/
#### **Research Pipeline Acadêmica**
```
research-workflow-cskill/
├── problem-definition-cskill/ ← Definição do problema
research-workflow/
├── problem-definition/ ← Definição do problema
│ └── output: research_scope.json
├── literature-search-cskill/ ← Busca de literatura
├── literature-search/ ← Busca de literatura
│ ├── input: research_scope.json
│ └── output: articles_found.json
├── data-collection-cskill/ ← Coleta de dados
├── data-collection/ ← Coleta de dados
│ ├── input: articles_found.json
│ └── output: experimental_data.json
├── analysis-engine-cskill/ ← Análise estatística
├── analysis-engine/ ← Análise estatística
│ ├── input: experimental_data.json
│ └── output: statistical_results.json
├── visualization-cskill/ ← Visualização dos resultados
├── visualization/ ← Visualização dos resultados
│ ├── input: statistical_results.json
│ └── output: charts.json
└── report-generation-cskill/ ← Geração de relatório
└── report-generation/ ← Geração de relatório
├── input: charts.json
└── output: research_report.pdf
```
@ -123,19 +123,19 @@ research-workflow-cskill/
#### **Business Intelligence Pipeline**
```
business-intelligence-cskill/
├── data-sources-cskill/ ← Conexão com fontes
business-intelligence/
├── data-sources/ ← Conexão com fontes
│ └── output: raw_data.json
├── etl-process-cskill/ ← Transformação ETL
├── etl-process/ ← Transformação ETL
│ ├── input: raw_data.json
│ └── output: processed_data.json
├── analytics-engine-cskill/ ← Análise de negócios
├── analytics-engine/ ← Análise de negócios
│ ├── input: processed_data.json
│ └── output: kpi_metrics.json
├── dashboard-cskill/ ← Criação de dashboards
├── dashboard/ ← Criação de dashboards
│ ├── input: kpi_metrics.json
│ └── output: dashboard.json
└── alert-system-cskill/ Sistema de alertas
└── alert-system/ Sistema de alertas
├── input: kpi_metrics.json
└── output: alerts.json
```
@ -287,16 +287,16 @@ def decide_architecture_with_pipeline(article_content, pipeline_detection):
}
```
### **Fase 4: Geração de Pipeline com "-cskill"**
### **Fase 4: Geração de Pipeline com Kebab-Case Naming**
```python
def create_pipeline_skill(analysis_result):
"""
Cria uma pipeline skill com convenção -cskill
Cria uma pipeline skill com convenção standard kebab-case
"""
# Nome base para pipeline
base_name = generate_pipeline_name(analysis_result['stages'])
skill_name = f"{base_name}-pipeline-cskill"
skill_name = f"{base_name}-pipeline"
# Estrutura para pipeline
directory_structure = create_pipeline_directory_structure(skill_name, analysis_result['stages'])
@ -316,16 +316,16 @@ def create_pipeline_skill(analysis_result):
### **1. E-commerce Analytics Pipeline**
```
ecommerce-analytics-pipeline-cskill/
├── sales-data-ingestion-cskill/
ecommerce-analytics-pipeline/
├── sales-data-ingestion/
│ └── Coleta dados de vendas de múltiplas fontes
├── data-enrichment-cskill/
├── data-enrichment/
│ └── Enriquece com dados de clientes
├── customer-analytics-cskill/
├── customer-analytics/
│ └── Análise de comportamento
├── reporting-dashboard-cskill/
├── reporting-dashboard/
│ └── Dashboard em tempo real
└── alert-engine-cskill/
└── alert-engine/
└── Alertas de métricas importantes
Fluxo: `Vendas → Enriquecimento → Análise → Dashboard → Alertas`
@ -333,16 +333,16 @@ Fluxo: `Vendas → Enriquecimento → Análise → Dashboard → Alertas`
### **2. Content Creation Pipeline**
```
content-creation-pipeline-cskill/
├── content-research-cskill/
content-creation-pipeline/
├── content-research/
│ └── Pesquisa de tendências e tópicos
├── content-generation-cskill/
├── content-generation/
│ └── Geração de conteúdo baseado em IA
├── content-optimization-cskill/
├── content-optimization/
│ └── SEO e otimização
├── publishing-platform-cskill/
├── publishing-platform/
│ └── Publicação em múltiplos canais
└── analytics-tracking-cskill/
└── analytics-tracking/
└── Monitoramento de performance
Fluxo: `Pesquisa → Geração → Otimização → Publicação → Análise`
@ -350,16 +350,16 @@ Fluxo: `Pesquisa → Geração → Otimização → Publicação → Análise`
### **3. Risk Management Pipeline**
```
risk-management-cskill/
├── risk-identification-cskill/
risk-management/
├── risk-identification/
│ └── Identificação de riscos potenciais
├── data-collection-cskill/
├── data-collection/
│ └── Coleta de dados de risco
├── risk-assessment-cskill/
├── risk-assessment/
│ └── Análise e classificação
├── mitigation-strategies-cskill/
├── mitigation-strategies/
│ └── Estratégias de mitigação
└── monitoring-dashboard-cskill/
└── monitoring-dashboard/
└── Dashboard de risco em tempo real
Fluxo: `Identificação → Coleta → Avaliação → Mitigação → Monitoramento`
@ -367,18 +367,18 @@ Fluxo: `Identificação → Coleta → Avaliação → Mitigação → Monitoram
### **4. HR Automation Pipeline**
```
hr-automation-cskill/
├── candidate-sourcing-cskill/
hr-automation/
├── candidate-sourcing/
│ └── Fontes de candidatos
├── resume-screening-cskill/
├── resume-screening/
│ └── Triagem inicial de currículos
├── interview-scheduling-cskill/
├── interview-scheduling/
│ └️ Agendamento de entrevistas
├── interview-evaluation-cskill/
├── interview-evaluation/
│ └️ Avaliação de candidatos
├── offer-management-cskill/
├── offer-management/
│ └️ Gestão de ofertas
└── onboarding-automation-cskill/
└── onboarding-automation/
└️ Processo de integração
Fluxo: `Fontes → Triagem → Entrevistas → Avaliação → Contratação → Onboarding`
@ -442,22 +442,22 @@ Fluxo: `Fontes → Triagem → Entrevistas → Avaliação → Contratação →
### **Abordagens Híbridas:**
```python
# Pipeline com componentes opcionais
data-pipeline-with-options-cskill/
├── core-pipeline-cskill/ ← Pipeline principal
│ ├── data-ingestion-cskill/
│ └── data-transformation-cskill/
│ └── data-analysis-cskill/
├── optional-ml-cskill/ ← Componente opcional
data-pipeline-with-options/
├── core-pipeline/ ← Pipeline principal
│ ├── data-ingestion/
│ └── data-transformation/
│ └── data-analysis/
├── optional-ml/ ← Componente opcional
│ └── Machine learning avançado
├── optional-reporting-cskill/ ← Componente opcional
├── optional-reporting/ ← Componente opcional
│ └── Relatórios executivos
# Múltiplas pipelines interconectadas
orchestrated-pipeline-cskill/
├── data-pipeline-cskill/
├── analytics-pipeline-cskill/
├── reporting-pipeline-cskill/
└── alerting-pipeline-cskill/
orchestrated-pipeline/
├── data-pipeline/
├── analytics-pipeline/
├── reporting-pipeline/
└── alerting-pipeline/
```
## 🎯 **Casos de Uso Ideais para Pipeline Skills**
@ -510,4 +510,4 @@ orchestrated-pipeline-cskill/
**Skills Claude são a materialização de expertise reutilizível** capturada de fontes especializadas. Quando essa expertise assume a forma de fluxos sequenciais (pipelines), elas representam transformações **end-to-end** que entregam valor completo, desde dados brutos até insights acionáveis.
**A convenção "-cskill" assegura que essa expertise capturada seja organizada, profissional e facilmente identificável, permitindo que usuários e organizações beneficiem da automação de processos complexos de ponta a ponta, transformando conhecimento especializado em capacidade prática escalável.**
**The standard kebab-case naming convention ensures that captured expertise is organized, professional, and easily identifiable, enabling users and organizations to benefit from end-to-end automation of complex processes, transforming specialized knowledge into scalable practical capability.**

2
docs/README.md
View file

@ -81,7 +81,7 @@ Decision framework for agent creation:
### **[NAMING_CONVENTIONS.md](NAMING_CONVENTIONS.md)**
Naming standards and conventions:
- "-cskill" suffix explained
- Standard kebab-case naming convention
- Naming patterns for skills
- Directory structure conventions
- Best practices

6
exports/README.md
View file

@ -63,9 +63,9 @@ skill-name-{variant}-v{version}_INSTALL.md
```
**Examples:**
- `financial-analysis-cskill-desktop-v1.0.0.zip`
- `financial-analysis-cskill-api-v1.0.0.zip`
- `financial-analysis-cskill-desktop-v1.0.0_INSTALL.md`
- `financial-analysis-desktop-v1.0.0.zip`
- `financial-analysis-api-v1.0.0.zip`
- `financial-analysis-desktop-v1.0.0_INSTALL.md`
### Version Numbering

7
references/ACTIVATION_BEST_PRACTICES.md
View file

@ -675,8 +675,7 @@ and chart patterns. Generates buy and sell signals based on technical indicators
## 🎓 Learning from Examples
### Excellent Example: stock-analyzer-cskill
### Excellent Example: stock-analyzer
**What makes it excellent:**
✅ **Complete keyword coverage (15 keywords)**
@ -718,7 +717,7 @@ Convergence Divergence), Bollinger Bands..."
**Result:** 98% activation reliability
**Location:** `references/examples/stock-analyzer-cskill/`
**Location:** `references/examples/stock-analyzer/`
---
@ -735,7 +734,7 @@ Convergence Divergence), Bollinger Bands..."
- **README Template**: `templates/README-activation-template.md`
### Examples
- **Complete Example**: `examples/stock-analyzer-cskill/`
- **Complete Example**: `examples/stock-analyzer/`
---

253
references/agentdb-integration.md Normal file
View file

@ -0,0 +1,253 @@
# AgentDB Integration
## Overview
AgentDB is an invisible learning system that improves skill creation quality over time. It operates behind the scenes during every skill creation episode, recording decisions, outcomes, and patterns. The user never interacts with AgentDB directly -- they simply get progressively better skill outputs as the system accumulates experience.
**Key principle**: AgentDB is always optional. The skill creator works identically with or without AgentDB installed. When available, it provides enhanced intelligence. When absent, the system falls back to its standard pipeline with zero degradation.
## What AgentDB Does
AgentDB provides three learning mechanisms:
### Reflexion Memory
Stores complete creation episodes (what was attempted, what worked, what failed) and retrieves relevant past experiences when facing similar tasks.
- After creating a financial analysis skill, AgentDB remembers which API scored highest, which analysis patterns the user liked, and which configurations caused issues.
- The next time someone requests a financial skill, the system retrieves these episodes and uses them to make better Phase 1 and Phase 2 decisions.
### Causal Reasoning
Tracks cause-and-effect relationships between creation decisions and outcomes.
- "Using Alpha Vantage with rate limiting causes 23% fewer API errors than without"
- "Including a comprehensive report function causes 40% higher user satisfaction"
- These causal links accumulate over time and influence template selection and configuration defaults.
### Skill Extraction
Identifies reusable patterns from successful creations and stores them as transferable skills.
- A caching strategy that worked well for NOAA data gets extracted and applied to other API-heavy skills.
- A report generation pattern that received positive feedback gets promoted to a template default.
## Integration Points in the 5-Phase Pipeline
AgentDB hooks into each phase of the creation pipeline transparently.
### Phase 1: Discovery
**Without AgentDB**: System researches APIs via WebSearch, compares options, selects the highest-scoring candidate.
**With AgentDB**: Before researching, the system queries reflexion memory for past discovery episodes in the same domain. If a previous creation already evaluated NOAA vs. Open-Meteo for climate data, the system reuses that evaluation (with a freshness check) instead of repeating the research from scratch.
```
AgentDB query: "What APIs were selected for climate/weather domains?"
Result: NOAA selected 3 times (avg score 8.7/10), Open-Meteo selected 2 times (9.1/10)
Effect: Open-Meteo is pre-ranked higher, saving 5-10 minutes of research
```
### Phase 2: Design
**Without AgentDB**: System designs 4-6 analyses based on domain best practices and API capabilities.
**With AgentDB**: Causal reasoning identifies which analysis patterns have the highest success rates for the domain. Reflexion memory recalls which analyses users requested most frequently.
```
AgentDB query: "What analyses work best for financial skills?"
Result: Technical indicators (92% retention), sector comparison (87%),
portfolio tracking (85%), news sentiment (61%)
Effect: News sentiment is deprioritized; technical indicators are designed first
```
### Phase 3: Architecture
**Without AgentDB**: System chooses simple vs. complex architecture based on scope.
**With AgentDB**: Historical data on suite sizes vs. maintainability informs the decision. If past suites with 4+ components had refactoring issues, the system might recommend splitting differently.
```
AgentDB query: "What architecture works best for 3-workflow skills?"
Result: Simple skill chosen 8/10 times, suite chosen 2/10. Simple had
fewer maintenance issues (causal link: simple -> 30% less rework)
Effect: Simple skill recommended with higher confidence
```
### Phase 4: Detection
**Without AgentDB**: System generates description and keywords based on domain analysis.
**With AgentDB**: Extracted skills from past successful activations inform keyword selection. If "stock analysis" activated more reliably than "equity research" in past skills, the former is prioritized.
```
AgentDB query: "What keywords had highest activation rates for finance?"
Result: "stock analysis" (98%), "market data" (95%), "portfolio" (93%),
"equity research" (72%), "securities" (68%)
Effect: High-activation keywords prioritized in description
```
### Phase 5: Implementation
**Without AgentDB**: System creates all files following the standard pipeline.
**With AgentDB**: Learned improvements from past creations are applied. If a specific error-handling pattern reduced runtime failures, it is included automatically. After creation, the episode is stored for future learning.
```
AgentDB action: Store episode
- Domain: climate
- Template used: climate-analysis
- APIs: Open-Meteo + NOAA
- Analyses: 5 implemented
- Validation: passed (10/10)
- Security: passed (clean)
- User satisfaction: pending
```
## Learning Progression
AgentDB's value grows with usage. Here is what to expect at different stages.
### First Creation (No History)
- AgentDB has no past episodes to draw from
- Behavior is identical to running without AgentDB
- The creation episode is stored for future reference
- No noticeable difference in output quality
### After 5+ Creations
- Reflexion memory has enough episodes to identify domain patterns
- API selection benefits from past evaluations (fewer redundant searches)
- Common analysis patterns are recognized and reused
- Estimated time savings: 10-15% per creation
### After 10+ Creations
- Causal reasoning has enough data to identify reliable cause-effect links
- Template matching improves as keyword effectiveness data accumulates
- Architecture decisions are informed by maintenance outcomes
- Skill extraction produces reusable patterns across domains
- Estimated time savings: 20-30% per creation
### After 30+ Days of Usage
- Nightly learner has processed all episodes and extracted high-confidence patterns
- Cross-domain insights emerge (e.g., "caching improves all API-heavy skills by 25%")
- Template recommendations reach high accuracy (>90% user acceptance)
- The system begins suggesting proactive improvements to existing skills
- Estimated time savings: 30-40% per creation
## Graceful Fallback
AgentDB availability is checked once at initialization. If unavailable, the system operates in fallback mode with zero user-visible impact.
### Detection Order
1. Check for native `agentdb` CLI in PATH
2. Check for `npx @anthropic-ai/agentdb` availability
3. Attempt automatic installation via npm (if npm is available)
4. If all checks fail, enter fallback mode silently
### Fallback Behavior
| Feature | With AgentDB | Without AgentDB (Fallback) |
|---------|-------------|---------------------------|
| Phase 1 Discovery | Informed by past episodes | Full research from scratch |
| Phase 2 Design | Ranked by historical success | Standard domain analysis |
| Phase 3 Architecture | Data-driven recommendation | Heuristic-based recommendation |
| Phase 4 Detection | Keywords ranked by activation history | Keywords from domain analysis |
| Phase 5 Implementation | Learned patterns applied | Standard patterns applied |
| Episode storage | Saved for future learning | Not stored (nothing to store to) |
| Output quality | Progressively improving | Consistently good (baseline) |
### Error Tolerance
If AgentDB is available but encounters errors during operation:
- First 3 errors: Logged silently, operation retried with fallback
- After 3 errors: AgentDB is disabled for the remainder of the session
- Next session: AgentDB is re-initialized (errors do not persist across sessions)
No AgentDB error ever surfaces to the user or interrupts the creation pipeline.
## Privacy and Performance
### All Local
- AgentDB stores all data locally in `~/.agentdb/`
- No data is transmitted to external servers
- No telemetry, analytics, or usage tracking
- The user's creation history stays on their machine
### No External Dependencies at Runtime
- AgentDB is an npm package, but once installed it runs locally
- If npm is unavailable, AgentDB simply does not install (fallback mode)
- The skill creator itself has zero npm dependencies -- AgentDB is purely optional
### Performance Impact
| Operation | Without AgentDB | With AgentDB | Overhead |
|-----------|----------------|--------------|----------|
| Initialization | 0ms | 50-200ms (one-time check) | Negligible |
| Phase 1 query | N/A | 10-50ms | Negligible |
| Phase 5 store | N/A | 20-100ms | Negligible |
| Disk usage | 0 | 1-10 MB (grows with usage) | Minimal |
AgentDB operations are asynchronous where possible and never block the main creation pipeline.
## Technical Implementation
### Bridge Architecture
The integration uses a bridge pattern (`integrations/agentdb_bridge.py`) that isolates all AgentDB operations behind a clean interface:
```python
from integrations.agentdb_bridge import enhance_agent_creation
# Called internally during skill creation -- never by the user
intelligence = enhance_agent_creation(
user_input="Create a climate analysis skill",
domain="climate"
)
# intelligence.template_choice -> "climate-analysis" (or None in fallback)
# intelligence.success_probability -> 0.87 (or 0.0 in fallback)
# intelligence.learned_improvements -> ["Use Open-Meteo over NOAA for forecasts"]
```
### Module Functions
| Function | Purpose |
|----------|---------|
| `enhance_agent_creation(input, domain)` | Pre-creation intelligence gathering |
| `enhance_template(template, domain)` | Template improvement from learned patterns |
| `store_agent_experience(name, experience)` | Post-creation episode recording |
| `get_agent_learning_summary(name)` | Internal progress tracking |
### Configuration
AgentDB auto-configures on first use. The configuration lives at `~/.agentdb/config.json`:
```json
{
"reflexion": {
"auto_save": true,
"compression": true
},
"causal": {
"auto_track": true,
"utility_model": "outcome_based"
},
"skills": {
"auto_extract": true,
"success_threshold": 0.8
},
"nightly_learner": {
"enabled": true,
"schedule": "2:00 AM"
}
}
```
No user action is required to create or maintain this configuration. The bridge handles everything automatically.

654
references/architecture-guide.md Normal file
View file

@ -0,0 +1,654 @@
# Architecture Decision Guide
**Version:** 4.0
**Purpose:** Comprehensive guide for choosing the right architecture when creating agent skills, including directory structures, naming conventions, sizing patterns, and performance strategies.
---
## 1. Architecture Decision Framework
Before creating any skill, determine whether it should be a **Simple Skill** or a **Complex Suite**. This decision drives the entire directory structure, file organization, and whether a `marketplace.json` is needed.
### 1.1 Decision Criteria
| Factor | Simple Skill | Complex Suite |
|--------|-------------|---------------|
| **Number of workflows** | 1-2 related workflows | 3+ distinct workflows |
| **Code complexity** | <1000 lines total | >2000 lines total |
| **SKILL.md files** | 1 | Multiple (one per component) |
| **Maintenance scope** | Single developer | Team or multi-concern |
| **Domain breadth** | Single domain focus | Spans multiple sub-domains |
| **Deployment** | Install as one unit | Components may be used independently |
| **marketplace.json** | **Not needed** | Optional (official fields only) |
### 1.2 Decision Flowchart
Follow this logic sequentially:
```
START
|
v
How many distinct workflows does this skill address?
|
+-- 1-2 workflows --> Does the total code exceed 2000 lines?
| |
| +-- No --> SIMPLE SKILL
| +-- Yes --> Can it be split into independent sub-skills?
| |
| +-- No --> SIMPLE SKILL (large)
| +-- Yes --> COMPLEX SUITE
|
+-- 3+ workflows --> Are the workflows tightly coupled?
|
+-- Yes (shared state/data) --> SIMPLE SKILL (organized)
+-- No (independent concerns) --> COMPLEX SUITE
```
### 1.3 Decision Examples
| User Request | Decision | Rationale |
|-------------|----------|-----------|
| "Analyze stock prices with technical indicators" | Simple Skill | Single domain, 1-2 workflows (fetch + analyze) |
| "Format markdown tables" | Simple Skill | Single workflow, <500 lines |
| "Full-stack web dev with frontend, backend, deployment" | Complex Suite | 3 independent sub-domains |
| "USDA agriculture data with 6 analysis types" | Simple Skill (organized) | Multiple analyses but single domain, shared data pipeline |
| "Financial suite: stock analysis, portfolio tracking, tax reporting" | Complex Suite | 3 distinct workflows, each usable independently |
---
## 2. Simple Skill Structure
A Simple Skill is a single, self-contained agent skill that follows the Agent Skills Open Standard. It has one SKILL.md file and no `marketplace.json`.
### 2.1 Standard Directory Layout
```
skill-name/
├── SKILL.md # <500 lines, spec-compliant frontmatter
├── scripts/ # Functional Python code
├── references/ # Detailed documentation (loaded on demand)
├── assets/ # Templates, schemas, data files
├── install.sh # Cross-platform auto-detect installer
└── README.md # Multi-platform installation instructions
```
**Key rule:** NO `.claude-plugin/marketplace.json` for simple skills. The SKILL.md file is the sole manifest and activation mechanism.
### 2.2 SKILL.md Frontmatter (Required)
```yaml
---
name: skill-name # 1-64 chars, lowercase + hyphens, must match directory
description: >- # 1-1024 chars, activation keywords included
Description with domain keywords for agent discovery...
license: MIT # or appropriate license
metadata:
author: Author Name
version: 1.0.0
compatibility: >- # optional, use when platform-specific features exist
Works on all platforms supporting the SKILL.md standard.
---
```
### 2.3 File Responsibilities
| File/Directory | Purpose | Required? |
|---------------|---------|-----------|
| `SKILL.md` | Primary skill definition, frontmatter, instructions | Yes |
| `scripts/` | Executable Python code (functional, no placeholders) | Yes (if skill has code) |
| `references/` | Detailed documentation, API guides, methodology docs | Recommended |
| `assets/` | Configuration files, templates, schemas, static data | Optional |
| `install.sh` | Cross-platform installer script | Yes |
| `README.md` | Installation instructions for 5+ platforms | Yes |
### 2.4 Why No marketplace.json for Simple Skills
Per the Agent Skills Open Standard and FR-005:
- SKILL.md is the universal discovery mechanism across all 26+ platforms
- `marketplace.json` is a Claude Code-specific plugin manifest, not part of the standard
- Simple skills activate via their SKILL.md `description` field alone
- Adding `marketplace.json` to a simple skill creates a non-standard structure that may confuse other platforms
- Skills placed in `~/.claude/skills/` or `.claude/skills/` are discovered automatically by Claude Code without `marketplace.json`
---
## 3. Complex Suite Structure
A Complex Suite bundles multiple related but independently usable skills under a single parent directory. It optionally includes a `marketplace.json` for Claude Code plugin registration.
### 3.1 Standard Directory Layout
```
suite-name/
├── .claude-plugin/
│ └── marketplace.json # ONLY official fields (see below)
├── component-1/
│ ├── SKILL.md # Independent skill definition
│ ├── scripts/
│ └── references/
├── component-2/
│ ├── SKILL.md # Independent skill definition
│ ├── scripts/
│ └── references/
├── shared/ # Shared utilities, data, config
│ ├── utils.py
│ └── config.json
├── install.sh # Installs all components
└── README.md # Suite-level documentation
```
### 3.2 marketplace.json Schema (Official Fields Only)
When a Complex Suite includes a `marketplace.json`, it must contain **only** the official Claude Code fields. No custom or non-standard fields are permitted.
```json
{
"name": "suite-name",
"plugins": [
{
"name": "component-1",
"description": "What component-1 does",
"source": "component-1/SKILL.md",
"skills": ["component-1"]
},
{
"name": "component-2",
"description": "What component-2 does",
"source": "component-2/SKILL.md",
"skills": ["component-2"]
}
]
}
```
**Allowed top-level fields:**
- `name` (string): The suite name
- `plugins` (array): List of plugin entries
**Allowed fields per plugin entry:**
- `name` (string): Component skill name
- `description` (string): What the component does
- `source` (string): Relative path to the component's SKILL.md
- `skills` (array of strings): Skill identifiers
**Forbidden fields** (non-standard, will cause validation failure):
- `version` -- use `metadata.version` in SKILL.md instead
- `author` -- use `metadata.author` in SKILL.md instead
- `repository` -- not part of the official schema
- `tags` -- not part of the official schema
- Any other custom fields
### 3.3 When to Use marketplace.json
| Scenario | Include marketplace.json? |
|----------|--------------------------|
| Simple skill (1 SKILL.md) | No |
| Complex suite for Claude Code distribution | Yes (optional) |
| Complex suite targeting only non-Claude platforms | No |
| Suite where components must be independently discoverable in Claude Code | Yes |
### 3.4 Component Independence
Each component in a Complex Suite should be independently functional:
- Each component has its own `SKILL.md` with valid frontmatter
- Each component can be installed separately if extracted from the suite
- Shared resources in `shared/` are optional enhancements, not hard dependencies
- Each component's `name` field matches its directory name
---
## 4. Naming Convention
All skill and suite names follow standard kebab-case per the Agent Skills Open Standard.
### 4.1 Rules
| Rule | Requirement |
|------|-------------|
| Length | 1-64 characters |
| Characters | Lowercase letters (`a-z`), numbers (`0-9`), hyphens (`-`) |
| Format | kebab-case |
| First character | Must be a letter or number (not a hyphen) |
| Last character | Must be a letter or number (not a hyphen) |
| Consecutive hyphens | Not allowed (`my--skill` is invalid) |
| Directory match | The `name` field in SKILL.md frontmatter must exactly match the parent directory name |
### 4.2 The -cskill Suffix Is Deprecated
The `-cskill` suffix convention from earlier versions is **removed** as of v4.0. Do not append `-cskill` to any generated skill name.
| Old (deprecated) | New (standard) |
|-------------------|----------------|
| `article-to-prototype-cskill` | `article-to-prototype` |
| `stock-analyzer-cskill` | `stock-analyzer` |
| `csv-data-cleaner-cskill` | `csv-data-cleaner` |
If a user requests the `-cskill` suffix, inform them it is deprecated and generate the skill without it.
### 4.3 Naming Pattern
Use the format `domain-objective` or `domain-objective-type`:
```
{domain}-{objective}[-{qualifier}]
```
**Examples:**
- `stock-analyzer` -- domain: stock, objective: analyzer
- `csv-data-cleaner` -- domain: csv-data, objective: cleaner
- `nass-usda-agriculture` -- domain: nass-usda, objective: agriculture
- `noaa-climate-analysis` -- domain: noaa-climate, objective: analysis
- `financial-analysis-suite` -- complex suite covering financial analysis
**Guidelines:**
- Be descriptive but concise
- Prefer shorter names when possible (aim for under 30 characters)
- Include the primary domain for discoverability
- Avoid generic names like `my-skill` or `tool-1`
### 4.4 Naming Validation
A valid name passes all of these checks:
```python
import re
def validate_skill_name(name: str) -> tuple[bool, list[str]]:
errors = []
if not name:
errors.append("Name is required")
if len(name) > 64:
errors.append(f"Name exceeds 64 chars ({len(name)})")
if name != name.lower():
errors.append("Name must be lowercase")
if not re.match(r'^[a-z0-9][a-z0-9-]*[a-z0-9]$', name) and len(name) > 1:
errors.append("Name must start/end with letter or number, contain only a-z, 0-9, hyphens")
if '--' in name:
errors.append("Consecutive hyphens not allowed")
if name.endswith('-cskill'):
errors.append("The -cskill suffix is deprecated; remove it")
return (len(errors) == 0, errors)
```
---
## 5. Directory Sizing Patterns
Choose a sizing pattern based on the skill's complexity. These patterns apply to both Simple Skills and individual components within a Complex Suite.
### 5.1 Small Agent Pattern
**When to use:** Single workflow, 1-2 scripts, <500 total lines of code.
```
skill-name/
├── SKILL.md # <200 lines
├── scripts/
│ └── main.py # 200-400 lines, single entry point
├── references/
│ └── guide.md # API docs, methodology
├── assets/
│ └── config.json # Minimal configuration
├── install.sh
└── README.md
```
**Characteristics:**
- One main script handles the entire workflow
- Minimal configuration
- Single reference document
- Estimated total: 500-800 lines across all files
**Examples:** markdown-table-formatter, url-shortener, json-validator
### 5.2 Medium Agent Pattern
**When to use:** 2-3 workflows, 3-5 scripts, 500-2000 total lines of code.
```
skill-name/
├── SKILL.md # 200-400 lines
├── scripts/
│ ├── fetch.py # Data acquisition (200-300 lines)
│ ├── parse.py # Data processing (150-200 lines)
│ ├── analyze.py # Analysis logic (300-500 lines)
│ └── utils/
│ ├── cache.py # Cache management (100-150 lines)
│ └── validators.py # Input validation (100-150 lines)
├── references/
│ ├── api-guide.md # ~1500 words
│ └── methodology.md # ~2000 words
├── assets/
│ └── config.json
├── install.sh
└── README.md
```
**Characteristics:**
- Separation of concerns: fetch, parse, analyze
- Utility modules for cross-cutting concerns (caching, validation)
- Multiple reference documents
- Estimated total: 1000-2500 lines across all files
**Examples:** stock-analyzer, weather-dashboard, csv-data-cleaner
### 5.3 Large Agent Pattern
**When to use:** 3+ workflows within a single domain, 6+ scripts, 2000+ total lines of code. Still a Simple Skill if all workflows share a single domain and data pipeline.
```
skill-name/
├── SKILL.md # 400-500 lines (at the limit)
├── scripts/
│ ├── core/
│ │ ├── fetch_source_a.py # 200-300 lines
│ │ ├── fetch_source_b.py # 200-300 lines
│ │ ├── parse_source_a.py # 150-200 lines
│ │ ├── parse_source_b.py # 150-200 lines
│ │ └── analyze.py # 400-600 lines
│ ├── models/
│ │ ├── forecasting.py # 200-300 lines
│ │ └── ml_models.py # 200-300 lines
│ └── utils/
│ ├── cache_manager.py # 100-150 lines
│ ├── rate_limiter.py # 100-150 lines
│ └── validators.py # 100-150 lines
├── references/
│ ├── api/
│ │ ├── source-a-guide.md
│ │ └── source-b-guide.md
│ ├── methods/
│ │ └── analysis-methods.md
│ └── troubleshooting.md
├── assets/
│ ├── config.json
│ └── metadata.json
├── install.sh
└── README.md
```
**Characteristics:**
- Sub-directories within `scripts/` for organization (core, models, utils)
- Multiple data sources with dedicated fetch/parse scripts
- Dedicated models directory for analysis/ML logic
- Organized reference documentation
- Estimated total: 2500-5000 lines across all files
**Examples:** nass-usda-agriculture, conab-crop-yield-analysis, noaa-climate-analysis
### 5.4 Sizing Comparison Table
| Aspect | Small | Medium | Large |
|--------|-------|--------|-------|
| Total code lines | <500 | 500-2000 | 2000+ |
| Script files | 1 | 3-5 | 6+ |
| Script sub-dirs | None | `utils/` | `core/`, `models/`, `utils/` |
| Reference files | 1 | 2-3 | 4+ (may use sub-dirs) |
| Asset files | 0-1 | 1 | 2+ |
| SKILL.md length | <200 lines | 200-400 lines | 400-500 lines |
| Typical domains | Formatters, validators | Data analyzers, dashboards | Multi-source analysis, forecasting |
---
## 6. Performance Strategy
All generated skills should incorporate performance considerations appropriate to their size and use case.
### 6.1 Caching Strategy
Cache API responses and computed results to avoid redundant work and reduce API usage.
**Cache TTL Decision Logic:**
| Data Type | TTL | Rationale |
|-----------|-----|-----------|
| Historical data (past years) | 365 days (effectively permanent) | Historical data does not change |
| Current-year data | 7 days | May be revised/updated |
| Metadata (lists, enums) | 365 days | Rarely changes |
| Real-time data | 1-60 minutes | Freshness required |
| User preferences | Session-scoped | Per-execution only |
**Implementation Pattern:**
```python
import json
import hashlib
from pathlib import Path
from datetime import datetime, timedelta
class FileCache:
"""Simple file-based cache with TTL support."""
def __init__(self, cache_dir: str = "data/cache"):
self.cache_dir = Path(cache_dir)
self.cache_dir.mkdir(parents=True, exist_ok=True)
def _key_path(self, key: str) -> Path:
hashed = hashlib.sha256(key.encode()).hexdigest()[:16]
return self.cache_dir / f"{hashed}.json"
def get(self, key: str, ttl: timedelta) -> dict | None:
path = self._key_path(key)
if not path.exists():
return None
data = json.loads(path.read_text())
cached_at = datetime.fromisoformat(data["cached_at"])
if datetime.now() - cached_at > ttl:
return None # Expired
return data["value"]
def set(self, key: str, value: dict) -> None:
path = self._key_path(key)
path.write_text(json.dumps({
"cached_at": datetime.now().isoformat(),
"value": value
}, indent=2))
def get_or_fetch(self, key: str, ttl: timedelta, fetch_fn) -> dict:
cached = self.get(key, ttl)
if cached is not None:
return cached
value = fetch_fn()
self.set(key, value)
return value
```
**Cache Location:** Store cache files under `data/cache/` within the skill directory. This keeps cache local and avoids polluting system directories.
**Graceful Degradation:** If the cache file is corrupted or unreadable, log a warning and proceed without cache (fetch fresh data).
### 6.2 Rate Limiting Strategy
Protect against API rate limit exhaustion with proactive tracking.
**Rate Limiter Pattern:**
```python
import json
from pathlib import Path
from datetime import datetime, timedelta
class RateLimiter:
"""File-based rate limiter with persistent counter."""
def __init__(
self,
max_requests: int,
period: timedelta,
counter_file: str = "data/cache/rate_limit.json"
):
self.max_requests = max_requests
self.period = period
self.counter_file = Path(counter_file)
self.counter_file.parent.mkdir(parents=True, exist_ok=True)
def _load(self) -> dict:
if not self.counter_file.exists():
return {"requests": [], "period_start": datetime.now().isoformat()}
return json.loads(self.counter_file.read_text())
def _save(self, data: dict) -> None:
self.counter_file.write_text(json.dumps(data, indent=2))
def _prune_old(self, data: dict) -> dict:
cutoff = (datetime.now() - self.period).isoformat()
data["requests"] = [r for r in data["requests"] if r > cutoff]
return data
def allow_request(self) -> bool:
data = self._prune_old(self._load())
count = len(data["requests"])
if count >= self.max_requests:
return False
if count > self.max_requests * 0.9:
remaining = self.max_requests - count
print(f"WARNING: Rate limit nearly reached ({count}/{self.max_requests}), {remaining} requests remaining")
return True
def record_request(self) -> None:
data = self._prune_old(self._load())
data["requests"].append(datetime.now().isoformat())
self._save(data)
```
**Rate Limit Configuration:** Define rate limits in `assets/config.json` so they can be adjusted without code changes:
```json
{
"rate_limit": {
"max_requests_per_day": 1000,
"warn_threshold_percent": 90
}
}
```
### 6.3 Optimization Techniques
**For Small Agents:**
- Keep it simple. A single script with basic caching is sufficient.
- Avoid premature optimization.
**For Medium Agents:**
- File-based caching for API responses.
- Rate limiter for external APIs.
- Lazy loading of reference data (only load when a specific analysis is requested).
**For Large Agents:**
- All Medium optimizations, plus:
- Batch API requests where the API supports it.
- Parallel processing for independent data sources (use `concurrent.futures`).
- Tiered caching: in-memory for hot data, file-based for cold data.
- Progress reporting for long-running operations.
**General Rules:**
- Never make the same API call twice in a single execution -- always check cache first.
- Use exponential backoff for transient API failures (start at 1 second, max 3 retries).
- Log all API calls with timestamps for debugging rate limit issues.
- Keep cached data in `data/cache/` and provide a way to clear it (`--clear-cache` flag or a function).
### 6.4 Error Handling Strategy
Every script must handle errors gracefully:
```python
import sys
from pathlib import Path
def safe_api_call(url: str, params: dict, retries: int = 3) -> dict:
"""Make an API call with retry logic and graceful error handling."""
import urllib.request
import urllib.error
import json
import time
for attempt in range(retries):
try:
query = "&".join(f"{k}={v}" for k, v in params.items())
full_url = f"{url}?{query}" if params else url
req = urllib.request.Request(full_url)
with urllib.request.urlopen(req, timeout=30) as response:
return json.loads(response.read().decode())
except urllib.error.HTTPError as e:
if e.code == 429: # Rate limited
wait = 2 ** attempt
print(f"Rate limited. Retrying in {wait}s...")
time.sleep(wait)
elif e.code >= 500: # Server error
wait = 2 ** attempt
print(f"Server error ({e.code}). Retrying in {wait}s...")
time.sleep(wait)
else:
print(f"HTTP error {e.code}: {e.reason}")
return {"error": str(e), "code": e.code}
except urllib.error.URLError as e:
print(f"Network error: {e.reason}")
if attempt < retries - 1:
time.sleep(2 ** attempt)
else:
return {"error": f"Network error after {retries} attempts: {e.reason}"}
except Exception as e:
return {"error": f"Unexpected error: {str(e)}"}
return {"error": f"Failed after {retries} retries"}
```
### 6.5 SKILL.md Size Management
The SKILL.md body must stay under 500 lines. Use progressive disclosure:
| Content Type | Where It Goes |
|-------------|---------------|
| Activation triggers, overview, core workflow | `SKILL.md` body (required) |
| API documentation, endpoint details | `references/api-guide.md` |
| Analysis methodology, formulas | `references/methodology.md` |
| Troubleshooting, FAQs | `references/troubleshooting.md` |
| Domain context, terminology | `references/domain-context.md` |
| Configuration schema documentation | `references/config-guide.md` |
Reference content from SKILL.md using `See references/filename.md for details.` directives. The agent will load referenced files on demand, reducing initial context consumption.
---
## 7. Architecture Checklist
Use this checklist before proceeding to implementation (Phase 5):
### Decision
- [ ] Determined Simple Skill vs Complex Suite
- [ ] Justified the decision based on workflow count, code size, and domain scope
### Naming
- [ ] Name is 1-64 characters, kebab-case
- [ ] Name matches the parent directory
- [ ] No `-cskill` suffix
- [ ] Name is descriptive and includes the primary domain
### Structure
- [ ] Directory layout matches the chosen sizing pattern (Small/Medium/Large)
- [ ] SKILL.md planned at <500 lines
- [ ] Scripts have clear separation of concerns
- [ ] References planned for detailed content
- [ ] `install.sh` included
- [ ] `README.md` planned with multi-platform install instructions
- [ ] No `marketplace.json` for Simple Skills
- [ ] If Complex Suite with `marketplace.json`, only official fields used
### Performance
- [ ] Cache strategy defined (what to cache, TTL for each data type)
- [ ] Rate limiting planned for external APIs
- [ ] Error handling approach defined (retries, backoff, fallbacks)
- [ ] SKILL.md size managed via progressive disclosure to `references/`
### Documentation
- [ ] Architecture decisions documented
- [ ] Script responsibilities defined (input, output, line count estimate)
- [ ] Reference files planned (topic, estimated word count)
- [ ] Asset files planned (config structure, metadata)

602
references/cross-platform-guide.md
View file

@ -1,469 +1,273 @@
# Cross-Platform Compatibility Guide
**Version:** 3.2
**Purpose:** Complete compatibility matrix for Claude Skills across all platforms
**Version:** 4.0
**Purpose:** Complete compatibility matrix for Agent Skills across all platforms supporting the Agent Skills Open Standard
---
## 🎯 Overview
## Overview
This guide explains how skills created by agent-skill-creator work across **four Claude platforms**, their differences, and how to optimize for each.
Skills created by agent-skill-creator are compliant with the **Agent Skills Open Standard** and work across all platforms that support the SKILL.md format. As of v4.0, this includes 8+ major platforms.
### The Four Platforms
### Supported Platforms
1. **Claude Code** (CLI) - Command-line tool for developers
2. **Claude Desktop** (Native App) - Desktop application
3. **claude.ai** (Web) - Browser-based interface
4. **Claude API** - Programmatic integration
| Platform | Type | SKILL.md Location |
|----------|------|-------------------|
| **Claude Code** | CLI | `~/.claude/skills/` or `.claude/skills/` |
| **GitHub Copilot CLI** | CLI | `.github/skills/` |
| **VS Code Copilot** | IDE Extension | `.github/skills/` |
| **Cursor** | IDE | `.cursor/rules/` |
| **Windsurf** | IDE | `.windsurf/skills/` |
| **Cline** | VS Code Extension | `.clinerules/` |
| **OpenAI Codex CLI** | CLI | `.codex/skills/` |
| **Gemini CLI** | CLI | `.gemini/skills/` |
| **Claude Desktop** | Desktop App | .zip upload |
| **claude.ai** | Web | .zip upload |
| **Claude API** | API | Programmatic upload |
### The Unifying Standard
All these platforms read the same SKILL.md format:
```yaml
---
name: skill-name
description: What the skill does and when to activate it
license: MIT
metadata:
author: Author Name
version: 1.0.0
---
# Skill content here...
```
A skill created once works everywhere without modification.
---
## 📊 Compatibility Matrix
## Installation by Platform
### Core Functionality
### Claude Code
| Feature | Claude Code | Claude Desktop | claude.ai | Claude API |
|---------|-------------|----------------|-----------|------------|
| **SKILL.md support** | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| **Python scripts** | ✅ Full | ✅ Full | ✅ Full | ⚠️ Limited* |
| **References/docs** | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| **Assets/templates** | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| **requirements.txt** | ✅ Full | ✅ Full | ✅ Full | ⚠️ Limited* |
\* API has execution constraints (no network, no pip install at runtime)
### Installation & Distribution
| Feature | Claude Code | Claude Desktop | claude.ai | Claude API |
|---------|-------------|----------------|-----------|------------|
| **Installation method** | Plugin/directory | Manual .zip | Manual .zip | API upload |
| **Marketplace support** | ✅ Yes | ❌ No | ❌ No | ❌ No |
| **marketplace.json** | ✅ Used | ❌ Ignored | ❌ Ignored | ❌ Not used |
| **Auto-updates** | ✅ Via git/plugins | ❌ Manual | ❌ Manual | ✅ Via API |
| **Version control** | ✅ Native git | ⚠️ Manual | ⚠️ Manual | ✅ Programmatic |
| **Team sharing** | ✅ Via plugins | ❌ Individual | ❌ Individual | ✅ Via API |
### Technical Specifications
| Specification | Claude Code | Claude Desktop | claude.ai | Claude API |
|---------------|-------------|----------------|-----------|------------|
| **Max skill size** | No limit | ~10MB recommended | ~10MB recommended | 8MB hard limit |
| **Skills per user** | Unlimited | Platform limit | Platform limit | 8 per request |
| **Execution environment** | Full | Full | Full | Sandboxed |
| **Network access** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |
| **Package install** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |
| **File system access** | ✅ Yes | ✅ Yes | ✅ Yes | ⚠️ Limited |
---
## 🔍 Platform Details
### Claude Code (CLI)
**Best for:** Developers, power users, teams with git workflows
**Strengths:**
- ✅ Native skill support (no export needed)
- ✅ Plugin marketplace distribution
- ✅ Git-based version control
- ✅ Automatic updates
- ✅ Full execution environment
- ✅ No size limits
- ✅ Team collaboration via plugins
**Installation:**
```bash
# Method 1: Plugin marketplace
/plugin marketplace add ./skill-name-cskill
# Using install.sh (recommended)
./install.sh
# Method 2: Personal skills
~/.claude/skills/skill-name-cskill/
# Manual: User-level
cp -r skill-name/ ~/.claude/skills/skill-name/
# Method 3: Project skills
.claude/skills/skill-name-cskill/
# Manual: Project-level
cp -r skill-name/ .claude/skills/skill-name/
```
**Workflow:**
1. Create skill with agent-skill-creator
2. Install via plugin command
3. Use immediately
4. Update via git pull
**Best for:** Developers, power users, teams with git workflows.
**Optimal for:**
- Development workflows
- Team projects
- Version-controlled skills
- Complex skill suites
- Rapid iteration
### GitHub Copilot
---
```bash
# Using install.sh
./install.sh --platform copilot
### Claude Desktop (Native App)
**Best for:** Individual users, desktop workflows, offline use
**Strengths:**
- ✅ Native app performance
- ✅ Offline capability
- ✅ Full skill functionality
- ✅ System integration
- ✅ Privacy (local execution)
**Limitations:**
- ❌ No marketplace
- ❌ Manual .zip upload required
- ❌ Individual installation (no team sharing)
- ❌ Manual updates
**Installation:**
```
1. Locate exported .zip package
2. Open Claude Desktop
3. Go to: Settings → Capabilities → Skills
4. Click: Upload skill
5. Select the .zip file
6. Wait for confirmation
# Manual: Project-level
cp -r skill-name/ .github/skills/skill-name/
```
**Workflow:**
1. Export: Create Desktop package
2. Upload: Manual .zip upload
3. Update: Re-upload new version
4. Share: Send .zip to colleagues
**Best for:** GitHub-integrated workflows, VS Code users.
**Optimal for:**
- Personal productivity
- Privacy-sensitive work
- Offline usage
- Desktop-integrated workflows
### Cursor
---
```bash
# Using install.sh
./install.sh --platform cursor
### claude.ai (Web Interface)
**Best for:** Quick access, browser-based work, cross-device
**Strengths:**
- ✅ No installation required
- ✅ Access from any browser
- ✅ Cross-device availability
- ✅ Always up-to-date interface
- ✅ Full skill functionality
**Limitations:**
- ❌ No marketplace
- ❌ Manual .zip upload required
- ❌ Individual installation
- ❌ Manual updates
- ❌ Requires internet connection
**Installation:**
```
1. Visit https://claude.ai
2. Log in to account
3. Click profile → Settings
4. Navigate to: Skills
5. Click: Upload skill
6. Select the .zip file
7. Confirm upload
# Manual
cp -r skill-name/ .cursor/rules/skill-name/
```
**Workflow:**
1. Export: Create Desktop package (same as Desktop)
2. Upload: Via web interface
3. Update: Re-upload new version
4. Share: Send .zip to colleagues
**Best for:** Cursor IDE users. Cursor reads SKILL.md natively alongside its `.mdc` rules.
**Optimal for:**
- Browser-based workflows
- Quick skill access
- Multi-device usage
- Casual/infrequent use
### Windsurf
---
```bash
# Using install.sh
./install.sh --platform windsurf
### Claude API (Programmatic)
# Manual
cp -r skill-name/ .windsurf/skills/skill-name/
```
**Best for:** Production apps, automation, enterprise integration
**Best for:** Windsurf IDE users.
**Strengths:**
- ✅ Programmatic control
- ✅ Version management via API
- ✅ Automated deployment
- ✅ CI/CD integration
- ✅ Workspace-level sharing
- ✅ Production scalability
### Cline
**Limitations:**
- ⚠️ 8MB size limit (hard)
- ⚠️ No network access in execution
- ⚠️ No pip install at runtime
- ⚠️ Sandboxed environment
- ⚠️ Max 8 skills per request
```bash
# Using install.sh
./install.sh --platform cline
# Manual
cp -r skill-name/ .clinerules/skill-name/
```
**Best for:** Cline extension users in VS Code.
### OpenAI Codex CLI
```bash
# Using install.sh
./install.sh --platform codex
# Manual
cp -r skill-name/ .codex/skills/skill-name/
```
**Best for:** Codex CLI users.
### Gemini CLI
```bash
# Using install.sh
./install.sh --platform gemini
# Manual
cp -r skill-name/ .gemini/skills/skill-name/
```
**Best for:** Gemini CLI users.
### Claude Desktop / claude.ai (Web)
These platforms use .zip upload instead of directory copying:
1. Export: `python scripts/export_utils.py ./skill-name --variant desktop`
2. Open Claude Desktop or claude.ai
3. Go to Settings > Skills > Upload skill
4. Select the .zip file
### Claude API
**Installation:**
```python
import anthropic
client = anthropic.Anthropic(api_key="your-key")
client = anthropic.Anthropic()
# Upload skill
with open('skill-api-v1.0.0.zip', 'rb') as f:
skill = client.skills.create(
file=f,
name="skill-name"
)
with open('skill-name-api-v1.0.0.zip', 'rb') as f:
skill = client.skills.create(file=f, name="skill-name")
# Use in requests
response = client.messages.create(
model="claude-sonnet-4",
messages=[{"role": "user", "content": query}],
messages=[{"role": "user", "content": "Your query here"}],
container={"type": "custom_skill", "skill_id": skill.id},
betas=["code-execution-2025-08-25", "skills-2025-10-02"]
)
```
**Workflow:**
1. Export: Create API package (optimized)
2. Upload: Programmatic via API
3. Deploy: Integrate in production
4. Update: Upload new version
5. Manage: Version control via API
---
**Optimal for:**
- Production applications
- Automated workflows
- Enterprise integration
- Scalable deployments
- CI/CD pipelines
## Compatibility Matrix
### Core Functionality
| Feature | CLI Platforms | Desktop/Web | Claude API |
|---------|-------------|-------------|------------|
| **SKILL.md support** | Full | Full | Full |
| **Python scripts** | Full | Full | Sandboxed* |
| **References/docs** | Full | Full | Full |
| **Assets/templates** | Full | Full | Full |
| **install.sh** | Full | N/A | N/A |
\* API: No network access, no pip install at runtime
### Technical Specifications
| Specification | CLI Platforms | Desktop/Web | Claude API |
|---------------|-------------|-------------|------------|
| **Max skill size** | No limit | ~10MB | 8MB hard limit |
| **Network access** | Yes | Yes | No |
| **Package install** | Yes | Yes | No |
| **File system** | Full | Full | Limited |
| **Updates** | git pull | Re-upload | API upload |
---
## 🔄 Migration Between Platforms
## Platform-Specific Notes
### Code → Desktop/Web
### marketplace.json
**Scenario:** Developed in Claude Code, share with Desktop users
- **Required by**: Claude Code (for plugin marketplace distribution only)
- **Not needed by**: All other platforms
- **Recommendation**: For simple skills, do not include `marketplace.json`. Only add it for complex skill suites that need Claude Code plugin distribution.
- **Format**: If included, use ONLY official fields: `name`, `plugins[].name`, `plugins[].description`, `plugins[].source`, `plugins[].skills`
### Skill Activation
All platforms that support the SKILL.md standard use the `description` field in frontmatter as the primary activation mechanism. The description should contain:
- Clear explanation of when to use the skill
- Domain-specific keywords
- Example trigger phrases
No platform-specific activation configuration is needed.
### File Structure
The standard skill directory works on all platforms:
```
skill-name/
├── SKILL.md # Required - primary skill definition
├── scripts/ # Optional - executable code
├── references/ # Optional - detailed documentation
├── assets/ # Optional - templates, schemas, data
├── install.sh # Optional - cross-platform installer
└── README.md # Recommended - install instructions
```
---
## Migration Between Platforms
### CLI Platform to CLI Platform
Skills are directly portable. Just copy the directory to the target platform's skill location:
**Process:**
```bash
# 1. Export Desktop package
"Export my-skill for Desktop"
# From Claude Code to Copilot
cp -r ~/.claude/skills/my-skill/ .github/skills/my-skill/
# 2. Share .zip file
# From Cursor to Cline
cp -r .cursor/rules/my-skill/ .clinerules/my-skill/
```
### CLI Platform to Desktop/Web
Export as .zip:
```bash
python scripts/export_utils.py ./my-skill --variant desktop
# Output: exports/my-skill-desktop-v1.0.0.zip
# 3. Desktop users upload
# Settings → Skills → Upload skill
```
**Considerations:**
- ✅ Full functionality preserved
- ✅ All scripts/docs included
- ⚠️ No auto-updates (manual)
- ⚠️ Each user uploads separately
### CLI Platform to API
### Code → API
Export as optimized .zip:
**Scenario:** Deploy production skill via API
**Process:**
```bash
# 1. Export API package (optimized)
"Export my-skill for API"
# 2. Upload programmatically
python deploy_skill.py
# 3. Integrate in production
# Use skill_id in API requests
```
**Considerations:**
- ⚠️ Size limit: < 8MB
- ⚠️ No network access
- ⚠️ No runtime pip install
- ✅ Automated deployment
- ✅ Version management
### Desktop/Web → Code
**Scenario:** Import skill to Claude Code
**Process:**
```bash
# 1. Unzip package
unzip skill-name-desktop-v1.0.0.zip -d skill-name-cskill/
# 2. Install in Claude Code
/plugin marketplace add ./skill-name-cskill
# 3. Optional: Add to git
git add skill-name-cskill/
git commit -m "Import skill from Desktop"
```
**Considerations:**
- ✅ Full functionality
- ✅ Can add version control
- ✅ Can share via plugins
- ⚠️ marketplace.json may be missing (create if needed)
---
## 🎯 Optimization Strategies
### For Desktop/Web
**Goal:** Complete, user-friendly package
**Strategy:**
- ✅ Include all documentation
- ✅ Include examples and references
- ✅ Keep README comprehensive
- ✅ Add usage instructions
- ✅ Include all assets
**Package characteristics:**
- Size: 2-5 MB typical
- Focus: User experience
- Documentation: Complete
### For API
**Goal:** Small, execution-focused package
**Strategy:**
- ⚠️ Minimize size (< 8MB)
- ⚠️ Remove heavy docs
- ⚠️ Remove examples
- ✅ Keep essential scripts
- ✅ Keep SKILL.md lean
**Package characteristics:**
- Size: 0.5-2 MB typical
- Focus: Execution efficiency
- Documentation: Minimal
---
## 🛠️ Platform-Specific Issues
### Claude Code Issues
**Issue:** Plugin not loading
- Check marketplace.json syntax
- Verify plugin path correct
- Run `/plugin list` to debug
**Issue:** Skill not activating
- Check SKILL.md frontmatter
- Verify activation patterns
- Test with explicit queries
### Desktop/Web Issues
**Issue:** Upload fails
- Check file size < 10MB
- Verify .zip format correct
- Try re-exporting package
**Issue:** Skill doesn't activate
- Check name ≤ 64 chars
- Check description ≤ 1024 chars
- Verify frontmatter valid
### API Issues
**Issue:** Size limit exceeded
- Export API variant (optimized)
- Remove large files
- Compress assets
**Issue:** Skill execution fails
- No network calls allowed
- No pip install at runtime
- Check sandboxing constraints
**Issue:** Beta headers missing
```python
# REQUIRED headers
betas=[
"code-execution-2025-08-25",
"skills-2025-10-02"
]
python scripts/export_utils.py ./my-skill --variant api
# Output: exports/my-skill-api-v1.0.0.zip (< 8MB)
```
---
## 📋 Feature Comparison
## Best Practices
### What Works Everywhere
✅ **Universal Features:**
- SKILL.md core functionality
- Basic Python scripts (with constraints)
- Text-based references
- Asset files (templates, prompts)
- Markdown documentation
### Platform-Specific Features
**Claude Code Only:**
- marketplace.json distribution
- Plugin marketplace
- Git-based updates
- .claude-plugin/ directory
**API Only:**
- Programmatic upload
- Workspace-level sharing
- Version control via API
- Automated deployment
**Desktop/Web Only:**
- Native app integration (Desktop)
- Browser access (Web)
- Offline capability (Desktop)
1. **Develop once, deploy everywhere**: Create and test in your preferred CLI tool, then install on other platforms.
2. **Use install.sh**: Include the cross-platform installer for easy deployment.
3. **Keep SKILL.md lean**: Under 500 lines, detailed content in `references/`.
4. **Test activation**: Verify the `description` triggers correctly on your target platform.
5. **Include README.md**: Document installation instructions for all platforms.
6. **No platform hacks**: Avoid platform-specific code or configuration. The standard format works everywhere.
---
## 🎓 Best Practices
### Development Workflow
**Recommended:** Develop in Claude Code, export for others
```
Claude Code (Development)
↓
Create & Test Locally
↓
Export Desktop Package → Share with Desktop users
Export API Package → Deploy to production
```
### Distribution Strategy
**For Teams:**
- **Developers**: Claude Code via plugins
- **Others**: Desktop/Web via .zip
- **Production**: API via programmatic deployment
**For Open Source:**
- **Primary**: Claude Code marketplace
- **Releases**: Export packages for Desktop/Web
- **Documentation**: Installation guides for all platforms
---
## 📚 Related Documentation
- **Export Guide**: `export-guide.md` - How to export skills
- **Main README**: `../README.md` - Agent-skill-creator overview
- **API Documentation**: Claude API docs (official)
---
**Generated by:** agent-skill-creator v3.2
**Last updated:** October 2025
**Generated by:** agent-skill-creator v4.0
**Standard:** Agent Skills Open Standard (agentskills.io/specification)

0
references/examples/exports/stock-analyzer-cskill-api-v1.0.0.zip → references/examples/exports/stock-analyzer-api-v1.0.0.zip
View file

0
references/examples/exports/stock-analyzer-cskill-desktop-v1.0.0.zip → references/examples/exports/stock-analyzer-desktop-v1.0.0.zip
View file

6
references/examples/exports/stock-analyzer-cskill-v1.0.0_INSTALL.md → references/examples/exports/stock-analyzer-v1.0.0_INSTALL.md
View file

@ -1,4 +1,4 @@
# stock-analyzer-cskill - Installation Guide
# stock-analyzer - Installation Guide
**Version:** v1.0.0
**Generated:** 2025-10-24 12:56:28
@ -9,7 +9,7 @@
### Desktop/Web Package
**File:** `stock-analyzer-cskill-desktop-v1.0.0.zip`
**File:** `stock-analyzer-desktop-v1.0.0.zip`
**Size:** 0.01 MB
**Files:** 4 files included
@ -17,7 +17,7 @@
### API Package
**File:** `stock-analyzer-cskill-api-v1.0.0.zip`
**File:** `stock-analyzer-api-v1.0.0.zip`
**Size:** 0.01 MB
**Files:** 4 files included

255
references/examples/stock-analyzer-cskill/.claude-plugin/marketplace.json
View file

@ -1,255 +0,0 @@
{
"name": "stock-analyzer-cskill",
"owner": {
"name": "Agent Creator",
"email": "noreply@example.com"
},
"metadata": {
"description": "Technical stock analysis using RSI, MACD, Bollinger Bands and other indicators",
"version": "1.0.0",
"created": "2025-10-23",
"updated": "2025-10-23",
"language": "en-US",
"features": [
"Technical indicator calculation",
"Buy/sell signal generation",
"Multi-stock comparison",
"Chart pattern recognition"
]
},
"plugins": [
{
"name": "stock-analyzer-plugin",
"description": "Comprehensive technical analysis tool for stocks and ETFs. Analyzes price movements, volume patterns, and momentum indicators including RSI (Relative Strength Index), MACD (Moving Average Convergence Divergence), Bollinger Bands, moving averages, and chart patterns. Generates buy and sell signals based on technical indicators. Compares multiple stocks for relative strength analysis. Monitors stock performance and tracks price alerts. Perfect for traders needing technical analysis, chart interpretation, momentum tracking, volatility assessment, and comparative stock evaluation using proven technical analysis methods and trading indicators.",
"source": "./",
"strict": false,
"skills": ["./"]
}
],
"activation": {
"_comment": "Layer 1: Enhanced keywords (65 keywords for 98% reliability)",
"keywords": [
"_comment": "Category 1: Core capabilities (15 keywords)",
"analyze stock",
"stock analysis",
"technical analysis for",
"RSI indicator",
"MACD indicator",
"Bollinger Bands",
"buy signal for",
"sell signal for",
"compare stocks",
"stock comparison",
"monitor stock",
"track stock price",
"chart pattern",
"moving average for",
"stock momentum",
"_comment": "Category 2: Synonym variations (15 keywords)",
"evaluate stock",
"research equity",
"review security",
"examine ticker",
"technical indicators",
"chart analysis",
"signal analysis",
"trade signal",
"investment signal",
"stock evaluation",
"performance comparison",
"price tracking",
"market monitoring",
"pattern recognition",
"trend analysis",
"_comment": "Category 3: Direct variations (12 keywords)",
"analyze stock with RSI",
"technical analysis using MACD",
"evaluate Bollinger Bands",
"buy signal based on indicators",
"sell signal using technical analysis",
"compare stocks by performance",
"monitor stock with alerts",
"track price movements",
"analyze chart patterns",
"moving average crossover",
"stock volatility analysis",
"momentum trading signals",
"_comment": "Category 4: Domain-specific (8 keywords)",
"oversold RSI condition",
"overbought MACD signal",
"Bollinger Band squeeze",
"moving average convergence",
"divergence pattern analysis",
"support resistance levels",
"breakout pattern detection",
"volume price analysis",
"_comment": "Category 5: Natural language (15 keywords)",
"how to analyze stock",
"what can I analyze stocks with",
"can you evaluate this stock",
"help me research technical indicators",
"I need to analyze RSI",
"show me stock analysis",
"stock with this indicator",
"get technical analysis",
"process stock data here",
"work with these stocks",
"analyze this ticker",
"evaluate this equity",
"compare these securities",
"track market data",
"chart analysis help"
],
"_comment": "Layer 2: Enhanced pattern matching (12 patterns for 98% coverage)",
"patterns": [
"_comment": "Pattern 1: Enhanced stock analysis",
"(?i)(analyze|evaluate|research|review|examine|study|assess)\\s+(and\\s+)?(compare|track|monitor)\\s+(stock|equity|security|ticker)\\s+(using|with|via)\\s+(technical|chart|indicator)\\s+(analysis|indicators|data)",
"_comment": "Pattern 2: Enhanced technical analysis",
"(?i)(technical|chart)\\s+(analysis|indicators?|studies?|examination)\\s+(for|of|on|in)\\s+(stock|equity|security|ticker)\\s+(using|with|based on)\\s+(RSI|MACD|Bollinger|moving average|momentum|volatility)",
"_comment": "Pattern 3: Enhanced signal generation",
"(?i)(generate|create|provide|show|give)\\s+(buy|sell|hold|trading)\\s+(signal|recommendation|suggestion|alert|notification)\\s+(for|of|based on)\\s+(technical|chart|indicator)\\s+(analysis|data|patterns)",
"_comment": "Pattern 4: Enhanced stock comparison",
"(?i)(compare|comparison|rank|ranking)\\s+(multiple\\s+)?(stock|equity|security)\\s+(performance|analysis|technical|metrics)\\s+(using|by|based on)\\s+(RSI|MACD|indicators|technical analysis)",
"_comment": "Pattern 5: Enhanced monitoring workflow",
"(?i)(every|daily|weekly|regularly)\\s+(I|we)\\s+(have to|need to|should)\\s+(monitor|track|watch|analyze)\\s+(stock|equity|market)\\s+(prices|performance|technical|data)",
"_comment": "Pattern 6: Enhanced transformation",
"(?i)(turn|convert|transform|change)\\s+(stock\\s+)?(price|market)\\s+(data|information)\\s+into\\s+(technical|chart|indicator)\\s+(analysis|signals|insights)",
"_comment": "Pattern 7: Technical operations",
"(?i)(technical analysis|chart analysis|indicator calculation|signal generation|pattern recognition|trend analysis|volatility assessment|momentum analysis)\\s+(for|of|to|from)\\s+(stock|equity|security|ticker)",
"_comment": "Pattern 8: Business operations",
"(?i)(investment analysis|trading analysis|portfolio evaluation|market research|stock screening|technical screening|signal analysis)\\s+(for|in|from)\\s+(trading|investment|portfolio|decisions)",
"_comment": "Pattern 9: Natural language questions",
"(?i)(how to|what can I|can you|help me|I need to)\\s+(analyze|evaluate|research)\\s+(this|that|the)\\s+(stock|equity|security)\\s+(using|with)\\s+(technical|chart)\\s+(analysis|indicators)",
"_comment": "Pattern 10: Conversational commands",
"(?i)(analyze|evaluate|research|show me|give me)\\s+(technical|chart)\\s+(analysis|indicators?)\\s+(for|of|on)\\s+(this|that|the)\\s+(stock|equity|security|ticker)",
"_comment": "Pattern 11: Domain-specific actions",
"(?i)(RSI|MACD|Bollinger|moving average|momentum|volatility|crossover|divergence|breakout|squeeze)\\s+.*\\s+(analysis|signal|indicator|pattern|condition|level)",
"_comment": "Pattern 12: Multi-indicator analysis",
"(?i)(analyze|evaluate|research)\\s+(stock|equity|security)\\s+(using|with|based on)\\s+(multiple\\s+)?(RSI\\s+and\\s+MACD|technical\\s+indicators|chart\\s+patterns|momentum\\s+analysis)"
]
},
"capabilities": {
"technical_analysis": true,
"signal_generation": true,
"stock_comparison": true,
"monitoring": true
},
"usage": {
"example": "Analyze AAPL stock using RSI and MACD indicators",
"input_types": [
"Stock ticker symbols",
"Technical indicator names",
"Time periods and ranges",
"Comparison requests"
],
"output_types": [
"Technical analysis reports",
"Buy/sell signals with reasoning",
"Comparative stock rankings",
"Chart pattern interpretations"
],
"when_to_use": [
"User asks for technical analysis of specific stocks",
"User mentions technical indicators like RSI, MACD, Bollinger Bands",
"User wants buy or sell signals based on technical analysis",
"User wants to compare multiple stocks using technical metrics",
"User mentions chart patterns or momentum analysis",
"User asks to monitor or track stock prices with alerts",
"User requests moving average analysis or volatility assessment"
],
"when_not_to_use": [
"User asks for fundamental analysis (P/E ratios, earnings, financials)",
"User wants news or sentiment analysis about stocks",
"User asks for stock recommendations without technical context",
"User wants to execute trades or access brokerage accounts",
"User asks general questions about how stock markets work",
"User wants portfolio management or allocation advice",
"User asks about options, futures, or derivatives analysis"
]
},
"test_queries": [
"_comment": "Core capability tests (8 queries)",
"Analyze AAPL stock using RSI indicator",
"What's the technical analysis for MSFT?",
"Show me MACD and Bollinger Bands for TSLA",
"Is there a buy signal for NVDA based on technical indicators?",
"Compare AAPL vs MSFT using RSI and momentum",
"Track GOOGL stock price and alert me on RSI oversold",
"What's the moving average analysis for SPY?",
"Analyze chart patterns for AMD stock",
"_comment": "Synonym variation tests (8 queries)",
"Evaluate AAPL equity with technical indicators",
"Research MSFT security using chart analysis",
"Review TSLA ticker with RSI and MACD studies",
"Examine NVDA security for overbought conditions",
"Study GOOGL equity performance metrics",
"Assess SPY technical examination results",
"Show me AMD indicator calculations",
"Provide QQQ signal analysis",
"_comment": "Natural language tests (10 queries)",
"How to analyze stock with RSI?",
"What can I analyze stocks with?",
"Can you evaluate this stock for me?",
"Help me research technical indicators for AAPL",
"I need to analyze MACD for MSFT",
"Show me stock analysis for TSLA",
"Get technical analysis for NVDA",
"Process stock data here for GOOGL",
"Work with these stocks: AAPL, MSFT, TSLA",
"Chart analysis help for AMD please",
"_comment": "Domain-specific tests (8 queries)",
"Check for oversold RSI condition on AAPL",
"Look for MACD divergence in MSFT",
"Bollinger Band squeeze pattern for TSLA",
"Moving average crossover signals for NVDA",
"Support resistance levels analysis for GOOGL",
"Breakout pattern detection for SPY",
"Volume price analysis for AMD",
"RSI overbought signal for QQQ",
"_comment": "Complex workflow tests (6 queries)",
"Daily I need to analyze technical indicators for my portfolio",
"Every week I have to compare stock performance using RSI",
"Regularly we must monitor market volatility with Bollinger Bands",
"Convert this price data into technical analysis signals",
"Turn stock market information into trading indicators",
"Technical analysis of QQQ with buy/sell signals",
"_comment": "Multi-indicator tests (6 queries)",
"Analyze AAPL using RSI and MACD together",
"Technical analysis with multiple indicators for MSFT",
"Chart patterns and momentum analysis for TSLA",
"Stock evaluation using RSI, MACD, and Bollinger Bands",
"Compare technical indicators across multiple stocks",
"Research equity with comprehensive technical analysis"
]
}

12
references/examples/stock-analyzer/.claude-plugin/marketplace.json Normal file
View file

@ -0,0 +1,12 @@
{
"name": "stock-analyzer",
"plugins": [
{
"name": "stock-analyzer-plugin",
"description": "Comprehensive technical analysis tool for stocks and ETFs. Analyzes price movements, volume patterns, and momentum indicators including RSI (Relative Strength Index), MACD (Moving Average Convergence Divergence), Bollinger Bands, moving averages, and chart patterns. Generates buy and sell signals based on technical indicators. Compares multiple stocks for relative strength analysis. Monitors stock performance and tracks price alerts. Perfect for traders needing technical analysis, chart interpretation, momentum tracking, volatility assessment, and comparative stock evaluation using proven technical analysis methods and trading indicators.",
"source": "./",
"skills": ["./"]
}
]
}

4
references/examples/stock-analyzer-cskill/README.md → references/examples/stock-analyzer/README.md
View file

@ -24,10 +24,10 @@ A comprehensive technical analysis skill for stocks and ETFs. Analyzes price mov
```bash
# Clone or copy the skill to your Claude Code skills directory
cp -r stock-analyzer-cskill ~/.claude/skills/
cp -r stock-analyzer ~/.claude/skills/
# Install Python dependencies
cd ~/.claude/skills/stock-analyzer-cskill
cd ~/.claude/skills/stock-analyzer
pip install -r requirements.txt
```

2
references/examples/stock-analyzer-cskill/SKILL.md → references/examples/stock-analyzer/SKILL.md
View file

@ -186,7 +186,7 @@ evaluation using proven technical analysis methods and trading indicators.
### Component Structure
```
stock-analyzer-cskill/
stock-analyzer/
├── .claude-plugin/
│ └── marketplace.json # Activation & metadata
├── scripts/

0
references/examples/stock-analyzer-cskill/requirements.txt → references/examples/stock-analyzer/requirements.txt
View file

0
references/examples/stock-analyzer-cskill/scripts/main.py → references/examples/stock-analyzer/scripts/main.py
View file

35
references/export-guide.md
View file

@ -1,6 +1,6 @@
# Cross-Platform Export Guide
**Version:** 3.2
**Version:** 4.0
**Purpose:** Complete guide to exporting agent-skill-creator skills for use across all Claude platforms
---
@ -49,7 +49,7 @@ The export system creates **optimized .zip packages** with:
After creating a skill, agent-skill-creator will prompt:
```
✅ Skill created: financial-analysis-cskill/
✅ Skill created: financial-analysis/
📦 Export Options:
1. Desktop/Web (.zip for manual upload)
@ -60,9 +60,9 @@ After creating a skill, agent-skill-creator will prompt:
Choice: 3
🔨 Creating export packages...
✅ Desktop package: exports/financial-analysis-cskill-desktop-v1.0.0.zip
✅ API package: exports/financial-analysis-cskill-api-v1.0.0.zip
📄 Installation guide: exports/financial-analysis-cskill-v1.0.0_INSTALL.md
✅ Desktop package: exports/financial-analysis-desktop-v1.0.0.zip
✅ API package: exports/financial-analysis-api-v1.0.0.zip
📄 Installation guide: exports/financial-analysis-v1.0.0_INSTALL.md
```
### On-Demand Export
@ -81,16 +81,16 @@ Using the export script directly:
```bash
# Export both variants
python scripts/export_utils.py ./my-skill-cskill
python scripts/export_utils.py ./my-skill
# Export only Desktop variant
python scripts/export_utils.py ./my-skill-cskill --variant desktop
python scripts/export_utils.py ./my-skill --variant desktop
# Export with specific version
python scripts/export_utils.py ./my-skill-cskill --version 2.0.1
python scripts/export_utils.py ./my-skill --version 2.0.1
# Export to custom directory
python scripts/export_utils.py ./my-skill-cskill --output-dir ./dist
python scripts/export_utils.py ./my-skill --output-dir ./dist
```
---
@ -263,14 +263,14 @@ exports/
```
**Components:**
- `skill-name`: Directory name (e.g., `financial-analysis-cskill`)
- `skill-name`: Directory name (e.g., `financial-analysis`)
- `variant`: `desktop` or `api`
- `version`: Semantic version (e.g., `v1.0.0`)
**Examples:**
- `stock-analyzer-cskill-desktop-v1.0.0.zip`
- `stock-analyzer-cskill-api-v1.0.0.zip`
- `stock-analyzer-cskill-v1.0.0_INSTALL.md`
- `stock-analyzer-desktop-v1.0.0.zip`
- `stock-analyzer-api-v1.0.0.zip`
- `stock-analyzer-v1.0.0_INSTALL.md`
---
@ -406,8 +406,7 @@ git clone repo-url
**Fix:**
```bash
# Check path exists
ls -la ./my-skill-cskill
ls -la ./my-skill
# Use absolute path
python scripts/export_utils.py /full/path/to/skill
```
@ -483,9 +482,9 @@ python scripts/export_utils.py ./skill --output-dir ./dist
Export multiple skills:
```bash
# Loop through skills
for skill in *-cskill; do
python scripts/export_utils.py "./$skill"
# Loop through skill directories
for skill in */; do
[ -f "$skill/SKILL.md" ] && python scripts/export_utils.py "./$skill"
done
# Or via agent-skill-creator

263
references/interactive-mode.md Normal file
View file

@ -0,0 +1,263 @@
# Interactive Configuration Mode
## Overview
Interactive mode provides a step-by-step wizard for configuring skill creation when the user wants explicit control over each decision. While the standard pipeline runs autonomously (the system researches, decides, and implements), interactive mode pauses at each decision point and asks the user for input or confirmation.
## When to Use Interactive Mode
| Situation | Why Interactive Mode Helps |
|-----------|---------------------------|
| Complex projects with multiple APIs | User can weigh trade-offs with full context |
| User has strong preferences | Avoids rework from autonomous decisions that miss user intent |
| High-stakes or production-critical skills | Every decision is reviewed before proceeding |
| Learning how the pipeline works | Step-by-step walkthrough teaches the creation process |
| Domain expertise the system lacks | User provides insider knowledge at each phase |
Interactive mode is **not** recommended for straightforward requests where the user trusts the system to make good decisions. For simple skills, the autonomous pipeline is faster and produces equivalent results.
## Starting Interactive Mode
### Commands
```
"Create a skill for [objective] interactively"
"Create a skill for [objective] with interactive mode"
"Walk me through creating a skill for [objective]"
"I want to configure each step for a [domain] skill"
```
### Resuming a Paused Session
If a session is interrupted, the system can resume from the last completed step:
```
"Resume the skill creation we started"
"Continue where we left off on the [skill-name] skill"
```
### Learning Mode
A variant of interactive mode that explains each phase as it runs:
```
"Create a skill for [objective] and explain each step"
"Teach me how to create a [domain] skill"
```
## Wizard Steps
### Step 1: Requirements Gathering
The wizard begins by collecting structured requirements from the user.
**System prompt**:
```
I'll help you create a skill for [objective]. Let me ask a few
questions to understand your requirements.
1. What data sources or APIs should this skill use?
(e.g., specific API, any free API, I'm not sure)
2. What are the main tasks this skill should perform?
(e.g., fetch data, analyze trends, generate reports)
3. How often will this skill run?
(e.g., on-demand, daily, weekly)
4. What output format do you need?
(e.g., text summary, PDF report, CSV data, HTML dashboard)
5. Any constraints I should know about?
(e.g., must be free, must support specific regions, rate limits)
```
**User response example**:
```
1. Use NOAA for historical data, Open-Meteo for forecasts
2. Compare current weather to 10-year averages, flag anomalies
3. Weekly automated runs plus on-demand
4. PDF report with charts
5. Must be free, focus on US agricultural regions
```
### Step 2: Workflow Analysis
The system analyzes the requirements and presents its understanding for confirmation.
**System prompt**:
```
Based on your requirements, here's what I understand:
Domain: Climate / Agriculture
Primary API: NOAA Climate Data Online
- Historical data (10+ year coverage)
- Free, 1,000 requests/day
- API key required (NOAA_API_KEY)
Secondary API: Open-Meteo
- Forecast data (16-day outlook)
- Free, no API key, 10,000 requests/day
Planned analyses:
1. Current vs. historical temperature comparison
2. Precipitation anomaly detection
3. Growing degree day calculations
4. Weekly trend summary with charts
Output: PDF report with embedded charts
Does this look correct? Would you like to change anything?
```
### Step 3: Strategy Selection
The system presents architecture options and asks the user to choose.
**System prompt**:
```
For this skill, I recommend the following architecture:
Option A: Simple Skill (recommended)
- Single SKILL.md + scripts + references
- 4 Python scripts (~600 lines total)
- Best for: single-developer maintenance
Option B: Complex Suite
- Separate skills for data fetching and analysis
- Shared reference library
- Best for: team maintenance or future expansion
I recommend Option A because the scope is focused and the
total code size is under 1,000 lines.
Which option do you prefer? [A/B]
```
### Step 4: Preview and Refinement
Before creating files, the system shows a preview of what will be generated.
**System prompt**:
```
Here's the complete plan before I create any files:
Directory: climate-agriculture-analysis/
├── SKILL.md (~120 lines)
├── scripts/
│ ├── fetch_noaa.py (historical data retrieval)
│ ├── fetch_openmeto.py (forecast retrieval)
│ ├── analyze_climate.py (comparison + anomaly detection)
│ └── generate_report.py (PDF generation)
├── references/
│ ├── api-guide.md (NOAA + Open-Meteo documentation)
│ └── methodology.md (analysis methods explained)
├── assets/
│ └── report_template.html
├── install.sh (cross-platform installer)
└── README.md (installation for 7+ platforms)
SKILL.md frontmatter:
name: climate-agriculture-analysis
description: >-
Analyze climate data for US agricultural regions using NOAA
historical records and Open-Meteo forecasts. Compare current
conditions to 10-year averages, detect anomalies...
license: MIT
metadata:
author: [your name]
version: 1.0.0
Shall I proceed with creation? Or would you like to modify
anything in this plan?
```
### Step 5: Creation
The system creates all files, reporting progress as it goes.
**System output**:
```
Creating skill: climate-agriculture-analysis
[1/10] Created directory structure
[2/10] Written SKILL.md (118 lines, spec-compliant)
[3/10] Written scripts/fetch_noaa.py (145 lines)
[4/10] Written scripts/fetch_openmeto.py (98 lines)
[5/10] Written scripts/analyze_climate.py (187 lines)
[6/10] Written scripts/generate_report.py (156 lines)
[7/10] Written references/api-guide.md
[8/10] Written references/methodology.md
[9/10] Generated install.sh (cross-platform)
[10/10] Written README.md (multi-platform instructions)
```
### Step 6: Validation
The system runs spec validation and security scanning, then reports results.
**System output**:
```
Running validation...
Spec Compliance:
[PASS] Frontmatter: name format valid (lowercase + hyphens)
[PASS] Frontmatter: description length (287 chars <= 1024)
[PASS] Frontmatter: name matches directory
[PASS] SKILL.md body: 118 lines (< 500 limit)
[PASS] Required files: SKILL.md present
[PASS] License field: MIT
Security Scan:
[PASS] No hardcoded API keys detected
[PASS] No .env files in skill directory
[PASS] No eval() or exec() calls
[PASS] No shell injection patterns
Result: 10/10 checks passed. Skill is ready for installation.
Would you like to install it now? Run: ./install.sh
```
## Advanced Configuration Options
### Skipping Phases
In interactive mode, users can skip phases they want to handle themselves:
```
"Create a skill interactively but skip API research -- I'll provide the API details"
"Skip the design phase, I already know what analyses I want"
```
### Partial Interactivity
Users can make only specific phases interactive:
```
"Create a skill autonomously but let me review the architecture before you build"
"Auto-create but pause before generating the SKILL.md frontmatter"
```
### Exporting the Configuration
After completing the wizard, users can export the configuration for reuse:
```
"Save this configuration as a template for future skills"
```
This creates a custom template file (see `references/templates-guide.md`) that can be reused for similar skills without re-answering all the wizard questions.
## Interactive Mode vs. Autonomous Mode
| Aspect | Autonomous | Interactive |
|--------|-----------|-------------|
| Speed | Faster (no pauses) | Slower (waits for input) |
| Control | System decides | User decides |
| Suitable for | Well-defined domains | Ambiguous or complex requirements |
| Discovery | System researches and selects | System researches, user confirms |
| Architecture | System chooses optimal | User picks from options |
| Output | Same quality | Same quality, user-validated |
Both modes produce the same output structure. The difference is whether the user participates in decisions or trusts the system to make them autonomously.

234
references/multi-agent-guide.md Normal file
View file

@ -0,0 +1,234 @@
# Multi-Agent Suite Creation
## Overview
A multi-agent suite is a collection of related skills that work together as a unified system. Instead of creating one monolithic skill, the suite splits responsibilities across multiple focused skills that share references and coordinate through a common integration layer.
The 5-phase pipeline applies to each component skill, but Phase 3 (Architecture) makes the critical decision: simple skill vs. complex suite.
## When to Use Batch Creation
| Scenario | Single Skill | Multi-Agent Suite |
|----------|-------------|-------------------|
| 1-2 distinct workflows | Recommended | Overkill |
| 3+ distinct workflows | Unwieldy | Recommended |
| Total code > 2,000 lines | Hard to maintain | Organized by component |
| Team maintenance | Single owner ok | Multiple contributors benefit |
| Shared data sources across workflows | Duplicated logic | Shared reference layer |
| Independent scaling of capabilities | Not possible | Each skill evolves independently |
**Rule of thumb**: If you find yourself describing more than two unrelated tasks in a single skill description, you need a suite.
## Suite Creation Process
### Step 1: Analyze Relationships
The system examines the user's requirements and identifies distinct workflow clusters.
```
User: "I need to track our e-commerce store -- monitor sales,
analyze customer behavior, track inventory levels, and
generate executive reports."
Analysis:
Cluster 1: Sales Monitoring (revenue, orders, conversion)
Cluster 2: Customer Analytics (segmentation, cohorts, churn)
Cluster 3: Inventory Tracking (stock levels, reorder alerts)
Cluster 4: Executive Reporting (aggregated dashboards)
Shared resources: Shopify API connection, date utilities,
report generation templates
```
### Step 2: Determine Structure
Based on the cluster analysis, the system designs the suite directory:
```
ecommerce-suite/
├── SKILL.md # Suite-level overview (<500 lines)
├── .claude-plugin/
│ └── marketplace.json # Suite manifest (official fields only)
├── skills/
│ ├── sales-monitor/
│ │ ├── SKILL.md # Sales-specific instructions
│ │ └── scripts/
│ │ └── monitor_sales.py
│ ├── customer-analytics/
│ │ ├── SKILL.md # Customer-specific instructions
│ │ └── scripts/
│ │ └── analyze_customers.py
│ ├── inventory-tracker/
│ │ ├── SKILL.md # Inventory-specific instructions
│ │ └── scripts/
│ │ └── track_inventory.py
│ └── executive-reports/
│ ├── SKILL.md # Reporting instructions
│ └── scripts/
│ └── generate_reports.py
├── shared/
│ ├── api_client.py # Shared Shopify API connection
│ ├── date_utils.py # Common date handling
│ └── report_templates/ # Shared report assets
│ └── executive_template.html
├── references/
│ └── api-guide.md # Shared API documentation
├── install.sh # Installs entire suite
└── README.md # Multi-platform instructions
```
### Step 3: Create Individual Skills
Each component skill goes through Phases 1-5 independently, but with awareness of the shared resources:
1. **Discovery** -- Each skill identifies its specific API endpoints (e.g., sales-monitor uses Shopify Orders API, inventory-tracker uses Shopify Inventory API).
2. **Design** -- Each skill defines its own analyses, scoped to its cluster.
3. **Architecture** -- Each skill follows the simple skill structure within the suite.
4. **Detection** -- Each skill gets its own description and keywords for independent activation.
5. **Implementation** -- Each skill references shared utilities from `shared/`.
### Step 4: Integration Layer
The suite-level `SKILL.md` serves as the orchestration layer. It describes how the component skills relate and when to invoke which one:
```markdown
# E-commerce Suite
## Component Skills
This suite contains four specialized skills:
- **sales-monitor**: Activate for revenue, orders, and conversion queries
- **customer-analytics**: Activate for segmentation, cohort, and churn queries
- **inventory-tracker**: Activate for stock levels, reorder, and supply queries
- **executive-reports**: Activate for dashboards, summaries, and executive briefings
## Cross-Skill Workflows
When the user asks for a "full store overview" or "weekly executive summary",
invoke executive-reports which aggregates data from all three other skills.
```
## Suite-Level marketplace.json
For complex suites that need Claude Code plugin registration, a `marketplace.json` is generated with **only official fields**:
```json
{
"name": "ecommerce-suite",
"plugins": [
{
"name": "sales-monitor",
"description": "Monitor e-commerce sales, revenue trends, order volumes, and conversion rates using Shopify data.",
"source": "./skills/sales-monitor/",
"skills": ["./skills/sales-monitor/"]
},
{
"name": "customer-analytics",
"description": "Analyze customer behavior, segmentation, cohort retention, and churn patterns from e-commerce data.",
"source": "./skills/customer-analytics/",
"skills": ["./skills/customer-analytics/"]
},
{
"name": "inventory-tracker",
"description": "Track inventory stock levels, predict reorder points, and alert on low-stock items.",
"source": "./skills/inventory-tracker/",
"skills": ["./skills/inventory-tracker/"]
},
{
"name": "executive-reports",
"description": "Generate executive dashboards and PDF summaries aggregating sales, customer, and inventory data.",
"source": "./skills/executive-reports/",
"skills": ["./skills/executive-reports/"]
}
]
}
```
**Important**: The marketplace.json uses ONLY the official fields: `name` and `plugins` at the top level, and `name`, `description`, `source`, `skills` per plugin entry. No `version`, `author`, `repository`, `tags`, `icon`, or other non-standard fields.
## Suite Examples
### Financial Suite
**User request**: "Create a suite for comprehensive financial analysis -- stock tracking, portfolio management, and market research."
```
financial-suite/
├── SKILL.md
├── .claude-plugin/marketplace.json
├── skills/
│ ├── stock-tracker/ # Real-time and historical price data
│ ├── portfolio-manager/ # Holdings, allocation, performance
│ └── market-research/ # Sector analysis, news sentiment
├── shared/
│ ├── market_data_client.py # Alpha Vantage + Yahoo Finance
│ └── financial_utils.py # Common calculations (returns, ratios)
├── references/
├── install.sh
└── README.md
```
### E-commerce Suite
**User request**: "I manage an online store and need to track everything -- sales, customers, inventory, and generate weekly reports."
(See the detailed structure in the Suite Creation Process section above.)
### Climate Suite
**User request**: "Build a climate analysis system with historical trend analysis, forecast monitoring, and extreme event alerting."
```
climate-suite/
├── SKILL.md
├── .claude-plugin/marketplace.json
├── skills/
│ ├── historical-trends/ # Long-term climate data analysis
│ ├── forecast-monitor/ # Short-term forecast tracking
│ └── extreme-events/ # Severe weather alerting
├── shared/
│ ├── climate_data_client.py # NOAA + Open-Meteo connections
│ └── geo_utils.py # Geographic region handling
├── references/
├── install.sh
└── README.md
```
## Benefits of Suite Creation
### Time Efficiency
Creating a suite through the batch process is significantly faster than creating individual skills separately:
| Approach | API Research | Shared Code | Integration | Total |
|----------|-------------|-------------|-------------|-------|
| 4 separate skills | 4x (redundant) | 0 (duplicated) | Manual | ~4 hours |
| 1 suite (batch) | 1x (shared) | 1x (reused) | Automatic | ~1.5 hours |
### Built-in Integration
Component skills within a suite share:
- API client code (no duplicated connection logic)
- Utility functions (date handling, formatting, calculations)
- Reference documentation (API guides written once)
- Report templates (consistent styling across outputs)
### Independent Maintenance
Each component skill can be:
- Updated independently without affecting others
- Tested in isolation
- Replaced with an improved version
- Extended with new analyses
The suite structure makes it possible to update the inventory-tracker without touching the sales-monitor, while still sharing the underlying Shopify API client.
### Marketplace Discoverability
Each plugin entry in `marketplace.json` has its own description and keywords. This means a suite's individual components can be discovered by different searches:
- "track sales" finds the sales-monitor plugin
- "customer churn" finds the customer-analytics plugin
- "inventory alerts" finds the inventory-tracker plugin
The suite functions as both a single installable unit and a collection of independently discoverable capabilities.

48
references/phase3-architecture.md
View file

@ -8,9 +8,9 @@
### Step 1: Define Agent Name
Based on domain and objective, create descriptive name:
Based on domain and objective, create a descriptive kebab-case name per the Agent Skills Open Standard.
**Format**: `domain-objective-type`
**Format**: `{domain}-{objective}` or `{action}-{object}`
**Examples**:
- US Agriculture → `nass-usda-agriculture`
@ -19,10 +19,12 @@ Based on domain and objective, create descriptive name:
- Brazil CONAB → `conab-crop-yield-analysis`
**Rules**:
- lowercase
- hyphens to separate words
- maximum 50 characters
- descriptive but concise
- 1-64 characters
- Lowercase letters, numbers, and hyphens only
- Must not start or end with a hyphen
- Must not contain consecutive hyphens
- Must match parent directory name
- Descriptive but concise
### Step 2: Directory Structure
@ -30,24 +32,22 @@ Based on domain and objective, create descriptive name:
**Option A - Simple** (small agents):
```
agent-name/
├── .claude-plugin/
│ └── marketplace.json ← REQUIRED for installation!
├── SKILL.md
skill-name/
├── SKILL.md ← Primary file, spec-compliant frontmatter
├── scripts/
│ └── main.py
├── references/
│ └── guide.md
└── assets/
└── config.json
├── assets/
│ └── config.json
├── install.sh ← Cross-platform installer
└── README.md ← Multi-platform install instructions
```
**Option B - Organized** (medium agents):
```
agent-name/
├── .claude-plugin/
│ └── marketplace.json ← REQUIRED for installation!
├── SKILL.md
skill-name/
├── SKILL.md ← Primary file, spec-compliant frontmatter
├── scripts/
│ ├── fetch.py
│ ├── parse.py
@ -58,16 +58,16 @@ agent-name/
├── references/
│ ├── api-guide.md
│ └── methodology.md
└── assets/
└── config.json
├── assets/
│ └── config.json
├── install.sh
└── README.md
```
**Option C - Complete** (complex agents):
```
agent-name/
├── .claude-plugin/
│ └── marketplace.json ← REQUIRED for installation!
├── SKILL.md
skill-name/
├── SKILL.md ← Primary file, spec-compliant frontmatter
├── scripts/
│ ├── core/
│ │ ├── fetch_[source].py
@ -89,6 +89,8 @@ agent-name/
├── assets/
│ ├── config.json
│ └── metadata.json
├── install.sh
├── README.md
└── data/
├── raw/
├── processed/
@ -96,6 +98,8 @@ agent-name/
└── analysis/
```
**Note**: Simple skills do NOT need `.claude-plugin/marketplace.json`. For complex skill suites with multiple component skills, an optional `marketplace.json` with ONLY official fields may be added.
**Choose based on**:
- Number of scripts (1-2 → A, 3-5 → B, 6+ → C)
- Analysis complexity

5
references/phase4-detection.md
View file

@ -1049,13 +1049,12 @@ description: |
## 🎯 Complete Example: Robust Detection Implementation
### Example Skill: stock-analyzer-cskill
### Example Skill: stock-analyzer
**marketplace.json:**
```json
{
"name": "stock-analyzer-cskill",
"name": "stock-analyzer",
"description": "Technical stock analysis using indicators",
"activation": {

1037
references/phase5-implementation.md
View file

File diff suppressed because it is too large Load diff

1360
references/pipeline-phases.md Normal file
View file

File diff suppressed because it is too large Load diff

209
references/templates-guide.md Normal file
View file

@ -0,0 +1,209 @@
# Template-Based Creation System
## Overview
The template-based creation system accelerates skill creation by providing pre-built scaffolds for common domains. Instead of starting from Phase 1 (Discovery) with a blank slate, templates provide a curated starting point with known-good APIs, proven analysis patterns, and tested configurations. The 5-phase pipeline still runs, but Phase 1 and Phase 2 are pre-populated with vetted decisions.
## Available Templates
### Financial Analysis
**Template ID**: `financial-analysis`
**Target domain**: Stock market, portfolio analysis, economic indicators
| Component | Details |
|-----------|---------|
| Primary API | Alpha Vantage (free tier, 500 requests/day) |
| Secondary API | Yahoo Finance via `yfinance` (unofficial, unlimited) |
| Pre-built analyses | Technical indicators (RSI, MACD, SMA), price trends, volume analysis, sector comparison |
| Output formats | Tabular summaries, time-series data, PDF reports |
| Authentication | API key via environment variable `ALPHA_VANTAGE_KEY` |
**Pre-configured scripts**:
- `scripts/fetch_market_data.py` -- OHLCV data retrieval with rate limiting
- `scripts/analyze_technicals.py` -- RSI, MACD, Bollinger Bands calculations
- `scripts/generate_report.py` -- PDF/HTML report generation
### Climate Analysis
**Template ID**: `climate-analysis`
**Target domain**: Weather patterns, historical climate data, forecasting
| Component | Details |
|-----------|---------|
| Primary API | Open-Meteo (free, no API key, 10,000 requests/day) |
| Secondary API | NOAA Climate Data Online (free, API key, 1,000 requests/day) |
| Pre-built analyses | Temperature trends, precipitation patterns, extreme events, historical comparisons |
| Output formats | Time-series data, geographic summaries, PDF reports |
| Authentication | Open-Meteo: none. NOAA: API key via `NOAA_API_KEY` |
**Pre-configured scripts**:
- `scripts/fetch_climate_data.py` -- Multi-source data retrieval with caching
- `scripts/analyze_trends.py` -- Statistical trend analysis and anomaly detection
- `scripts/generate_report.py` -- Climate summary report generation
### E-commerce Analytics
**Template ID**: `ecommerce-analytics`
**Target domain**: Sales tracking, customer behavior, revenue analysis
| Component | Details |
|-----------|---------|
| Primary API | Google Analytics Data API (free tier) |
| Secondary APIs | Stripe API (transaction data), Shopify Admin API (store data) |
| Pre-built analyses | Revenue trends, conversion funnels, customer segmentation, product performance |
| Output formats | Dashboard data, CSV exports, PDF reports |
| Authentication | OAuth2 (Google), API key (Stripe/Shopify) |
**Pre-configured scripts**:
- `scripts/fetch_analytics.py` -- Multi-platform data aggregation
- `scripts/analyze_sales.py` -- Revenue, conversion, and cohort analysis
- `scripts/generate_dashboard.py` -- HTML dashboard and PDF report
## Template Matching Process
When a user describes their workflow, the system matches it to the best template through a two-step process.
### Step 1: Keyword Extraction
The system extracts domain-relevant keywords from the user's request:
```
User: "I need to analyze stock performance and generate weekly reports"
Extracted keywords:
- Domain: ["stock", "performance", "reports"]
- Actions: ["analyze", "generate"]
- Frequency: ["weekly"]
- Implied domain: finance
```
### Step 2: Similarity Scoring
Each template is scored against the extracted keywords:
| Template | Keyword Match | Domain Match | Action Match | Total Score |
|----------|--------------|--------------|--------------|-------------|
| Financial Analysis | 3/3 | 1.0 | 0.9 | 0.95 |
| Climate Analysis | 0/3 | 0.0 | 0.4 | 0.10 |
| E-commerce Analytics | 1/3 | 0.2 | 0.6 | 0.30 |
**Selection threshold**: A template is suggested when its score exceeds 0.70. Below that threshold, the system falls back to the standard 5-phase pipeline with full discovery.
## Template Usage
### Direct Request
Explicitly ask for a template:
```
User: "Create a financial analysis skill using the financial template"
Result: System loads the financial-analysis template, pre-populates
Phase 1 (Alpha Vantage + Yahoo Finance) and Phase 2 (technical
indicators), then proceeds through Phases 3-5.
```
### Auto-Detection
Describe your workflow and let the system match:
```
User: "Every week I check weather trends for the Pacific Northwest
and compare them to historical averages"
Result: System detects climate-analysis template (score: 0.92),
confirms with user, then proceeds with Open-Meteo + NOAA as
pre-selected data sources.
```
### Customization After Selection
Templates are starting points, not rigid constraints. After selection, the user can customize any aspect:
```
User: "Use the financial template but replace Alpha Vantage with
IEX Cloud and add cryptocurrency support"
Result: System loads financial-analysis template, swaps the primary
API to IEX Cloud, adds crypto endpoints to Phase 2 design, then
proceeds through Phases 3-5 with the modifications.
```
## Creating Custom Templates
Custom templates follow the same structure as built-in ones. Place them in `references/templates/custom/`.
### Template File Structure
```
references/templates/custom/
└── my-template/
├── template.json # Template definition
├── phase1-config.md # Pre-populated Discovery decisions
├── phase2-config.md # Pre-populated Design decisions
└── scripts/ # Starter scripts (optional)
└── fetch_data.py
```
### Template Definition (template.json)
```json
{
"id": "my-custom-template",
"name": "My Custom Template",
"domain": "logistics",
"keywords": ["shipping", "tracking", "delivery", "freight", "supply chain"],
"apis": [
{
"name": "ShipEngine",
"url": "https://www.shipengine.com/docs/",
"auth": "api_key",
"free_tier": true,
"rate_limit": "500/day"
}
],
"analyses": [
"shipment_tracking",
"delivery_performance",
"cost_optimization",
"route_analysis"
],
"output_formats": ["tabular", "pdf", "csv"]
}
```
### Registering the Template
After creating the template files, register it by adding an entry to `references/templates/registry.json`:
```json
{
"templates": [
{"id": "financial-analysis", "path": "references/templates/financial/", "builtin": true},
{"id": "climate-analysis", "path": "references/templates/climate/", "builtin": true},
{"id": "ecommerce-analytics", "path": "references/templates/ecommerce/", "builtin": true},
{"id": "my-custom-template", "path": "references/templates/custom/my-template/", "builtin": false}
]
}
```
### Template Best Practices
1. **Include at least 10 keywords** to ensure reliable matching during auto-detection.
2. **Document API quirks** in `phase1-config.md` so the pipeline does not rediscover known gotchas.
3. **Provide working starter scripts** when possible -- this accelerates Phase 5 significantly.
4. **Test the template** by running a full creation cycle and verifying the output passes validation.
5. **Keep APIs current** -- review rate limits and endpoints periodically, since free tiers change.
## Template vs. Full Pipeline
| Scenario | Recommended Approach |
|----------|---------------------|
| Domain matches a built-in template | Use template (saves 30-50% of creation time) |
| Domain is adjacent to a template | Use template with customization |
| Entirely new domain | Full 5-phase pipeline from scratch |
| User explicitly requests no template | Full 5-phase pipeline |
| User provides a transcript of their workflow | Full pipeline with transcript processing |
Templates are an optimization, not a replacement. The 5-phase pipeline always runs. Templates simply pre-populate the early phases with proven decisions.

2
references/templates/marketplace-robust-template.json
View file

@ -1,7 +1,7 @@
{
"_comment": "Robust Activation Template - Replace all {{placeholders}} with actual values",
"name": "{{skill-name-cskill}}",
"name": "{{skill-name}}",
"owner": {
"name": "Agent Creator",
"email": "noreply@example.com"

10
references/tools/activation-tester.md
View file

@ -477,15 +477,13 @@ class ActivationMonitor:
```bash
# Run full test suite
./run-full-test-suite.sh \
/path/to/stock-analyzer-cskill \
/path/to/stock-analyzer \
/output/test-results
# Quick validation
./quick-validation.sh /path/to/stock-analyzer-cskill
./quick-validation.sh /path/to/stock-analyzer
# Monitor performance
./performance-benchmark.sh stock-analyzer-cskill
```
./performance-benchmark.sh stock-analyzer```
### **Example 2: Integration with Development Workflow**
@ -503,7 +501,7 @@ jobs:
- name: Run Activation Tests
run: |
./references/tools/activation-tester/scripts/run-full-test-suite.sh \
./references/examples/stock-analyzer-cskill \
./references/examples/stock-analyzer \
./test-results
- name: Upload Test Results
uses: actions/upload-artifact@v2

5
references/tools/test-automation-scripts.sh
View file

@ -692,9 +692,8 @@ Commands:
help Show this help message
Examples:
$0 full-test-suite ./references/examples/stock-analyzer-cskill ./test-results
$0 quick-validation ./references/examples/stock-analyzer-cskill
$0 full-test-suite ./references/examples/stock-analyzer ./test-results
$0 quick-validation ./references/examples/stock-analyzer
Environment Variables:
RESULTS_DIR Directory for test results (default: ./test-results)
TEMP_DIR Temporary directory for test files (default: /tmp/activation-tests)

30
scenarios/SC-001-valid-frontmatter-happy.scenario.md Normal file
View file

@ -0,0 +1,30 @@
# SC-001: Valid SKILL.md Frontmatter Generation
> Covers: 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)
> Type: Happy Path
## Given
- The meta-skill is invoked with a workflow description: "Create a skill for processing daily CSV files"
- The pipeline completes all 5 phases successfully
## When
- Phase 5 (Implementation) generates the SKILL.md file
## Then
- The generated SKILL.md begins with a YAML frontmatter block delimited by `---`
- The `name` field is present, lowercase, uses only hyphens as separators, and is <=64 characters (e.g., `csv-daily-processor`)
- The `description` field is present and is between 1 and 1024 characters
- The frontmatter block is valid YAML that can be parsed without errors
## Verification Method
**Method**: Automated test
**Steps**:
1. Run the meta-skill with input: "Create a skill for processing daily CSV files"
2. Read the generated `SKILL.md` file
3. Parse the YAML frontmatter between the `---` delimiters using Python `yaml.safe_load()`
4. Assert `name` is present, matches regex `^[a-z][a-z0-9-]*[a-z0-9]$`, and `len(name) <= 64`
5. Assert `description` is present and `1 <= len(description) <= 1024`
**Expected evidence**: YAML frontmatter parses successfully. `name` is a valid lowercase-kebab string <=64 chars. `description` is a non-empty string <=1024 chars. No YAML parsing errors.

32
scenarios/SC-002-invalid-frontmatter-missing-name.scenario.md Normal file
View file

@ -0,0 +1,32 @@
# SC-002: Validation Fails When Frontmatter Missing Name
> Covers: FR-001, FR-011, FR-012 — Generated SKILL.md MUST have valid frontmatter; Validation MUST check name format
> Type: Failure
## Given
- A skill directory `test-skill/` exists with a SKILL.md that has frontmatter missing the `name` field:
```yaml
---
description: "A test skill"
---
```
## When
- The validation function `validate_skill("test-skill/")` is invoked
## Then
- The validation result `valid` is `False`
- The `errors` list contains a message indicating the `name` field is missing
- The validation does NOT pass silently
## Verification Method
**Method**: Automated test
**Steps**:
1. Create a temporary directory `test-skill/` with a SKILL.md containing only a `description` field in frontmatter
2. Call `validate_skill("test-skill/")`
3. Assert `result.valid is False`
4. Assert any item in `result.errors` contains the substring `name`
**Expected evidence**: `valid: False`, `errors` list includes an entry like `"Missing required field: name"`.

31
scenarios/SC-003-invalid-frontmatter-missing-description.scenario.md Normal file
View file

@ -0,0 +1,31 @@
# SC-003: Validation Fails When Frontmatter Missing Description
> Covers: FR-001, FR-011, FR-012 — Generated SKILL.md MUST have valid frontmatter; Validation MUST check description length
> Type: Failure
## Given
- A skill directory `test-skill/` exists with a SKILL.md that has frontmatter missing the `description` field:
```yaml
---
name: test-skill
---
```
## When
- The validation function `validate_skill("test-skill/")` is invoked
## Then
- The validation result `valid` is `False`
- The `errors` list contains a message indicating the `description` field is missing
## Verification Method
**Method**: Automated test
**Steps**:
1. Create a temporary directory `test-skill/` with a SKILL.md containing only a `name` field in frontmatter
2. Call `validate_skill("test-skill/")`
3. Assert `result.valid is False`
4. Assert any item in `result.errors` contains the substring `description`
**Expected evidence**: `valid: False`, `errors` list includes an entry like `"Missing required field: description"`.

27
scenarios/SC-004-name-matches-directory.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-004: Generated SKILL.md Name Matches Parent Directory
> Covers: FR-002 — Generated SKILL.md `name` field MUST match the parent directory name
> Type: Happy Path
## Given
- The meta-skill is invoked with: "Create a skill for weather alerts"
- Phase 3 creates a directory named `weather-alerts/`
## When
- Phase 5 generates the SKILL.md inside `weather-alerts/`
## Then
- The `name` field in SKILL.md frontmatter is exactly `weather-alerts`
- The directory name and the `name` field are identical strings
## Verification Method
**Method**: Automated test
**Steps**:
1. Run the meta-skill to generate a skill
2. Read the parent directory name of the generated SKILL.md
3. Parse the YAML frontmatter and extract the `name` field
4. Assert `name == parent_directory_name`
**Expected evidence**: `name: weather-alerts` in frontmatter, parent directory is `weather-alerts/`. Both strings are identical.

27
scenarios/SC-005-name-directory-mismatch-fails-validation.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-005: Validation Fails When Name Does Not Match Directory
> Covers: FR-002, FR-012 — Validation MUST check directory name match
> Type: Failure
## Given
- A skill directory named `my-skill/` exists
- The SKILL.md inside has `name: different-skill` in frontmatter
## When
- The validation function `validate_skill("my-skill/")` is invoked
## Then
- The validation result `valid` is `False`
- The `errors` list contains a message about name/directory mismatch
## Verification Method
**Method**: Automated test
**Steps**:
1. Create directory `my-skill/` with SKILL.md containing `name: different-skill`
2. Call `validate_skill("my-skill/")`
3. Assert `result.valid is False`
4. Assert `result.errors` contains a message referencing directory name mismatch
**Expected evidence**: `valid: False`, error message like `"name 'different-skill' does not match directory name 'my-skill'"`.

28
scenarios/SC-006-skillmd-under-500-lines.scenario.md Normal file
View file

@ -0,0 +1,28 @@
# SC-006: Generated SKILL.md Is Under 500 Lines
> Covers: FR-003 — Generated SKILL.md body MUST be <500 lines, with detailed content in `references/`
> Type: Happy Path
## Given
- The meta-skill is invoked with a complex workflow description that would produce substantial documentation
- Input: "Create a skill for managing a full CI/CD pipeline with build, test, deploy stages, rollback procedures, monitoring integration, and multi-environment support"
## When
- Phase 5 generates the SKILL.md and all supporting files
## Then
- The generated SKILL.md file has fewer than 500 lines total
- A `references/` directory exists alongside SKILL.md containing detailed documentation
- The SKILL.md body contains cross-reference pointers (e.g., `See references/deployment-guide.md`) to the detailed content
## Verification Method
**Method**: Automated test
**Steps**:
1. Run the meta-skill with the complex workflow description
2. Count the lines in the generated SKILL.md: `wc -l skill-name/SKILL.md`
3. Verify `references/` directory exists and contains at least one file
4. Grep for cross-reference patterns in SKILL.md: `grep -c 'references/' skill-name/SKILL.md`
**Expected evidence**: SKILL.md line count is less than 500. `references/` directory contains one or more `.md` files. SKILL.md body contains at least one reference to `references/`.

26
scenarios/SC-007-skillmd-over-500-lines-fails.scenario.md Normal file
View file

@ -0,0 +1,26 @@
# SC-007: Validation Fails When SKILL.md Exceeds 500 Lines
> Covers: FR-003, FR-011 — Validation MUST check generated SKILL.md is <500 lines
> Type: Failure
## Given
- A skill directory `verbose-skill/` exists
- The SKILL.md inside contains 650 lines (valid frontmatter but excessive body content)
## When
- The validation function `validate_skill("verbose-skill/")` is invoked
## Then
- The validation result reports a warning or error about SKILL.md exceeding 500 lines
- The `errors` or `warnings` list contains a message about line count
## Verification Method
**Method**: Automated test
**Steps**:
1. Create directory `verbose-skill/` with a SKILL.md that has valid frontmatter and 650 lines of body content
2. Call `validate_skill("verbose-skill/")`
3. Assert that `result.errors` or `result.warnings` contains a message about exceeding 500 lines
**Expected evidence**: Validation output includes a message like `"SKILL.md exceeds 500 lines (650 lines found)"`.

27
scenarios/SC-008-metaskill-own-skillmd-under-500.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-008: Meta-Skill's Own SKILL.md Is Under 500 Lines
> Covers: FR-004, FR-021 — The meta-skill's own SKILL.md MUST be <500 lines
> Type: Happy Path
## Given
- The agent-skill-creator repository has been updated to v4.0
- The meta-skill's own SKILL.md exists at `agent-skill-creator/SKILL.md`
## When
- The file is inspected for line count
## Then
- The meta-skill's SKILL.md has fewer than 500 lines
- Detailed content that was previously in the monolithic SKILL.md (4,116 lines) has been moved to `references/`
- The SKILL.md body contains cross-references to files in `references/`
## Verification Method
**Method**: CLI command
**Steps**:
1. Run: `wc -l /Users/francylisboacharuto/agent-skill-creator/SKILL.md`
2. Run: `ls /Users/francylisboacharuto/agent-skill-creator/references/`
3. Run: `grep -c 'references/' /Users/francylisboacharuto/agent-skill-creator/SKILL.md`
**Expected evidence**: Line count output is less than 500. `references/` contains multiple files. Grep shows at least 3 cross-references.

27
scenarios/SC-009-no-marketplace-json-simple-skill.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-009: Simple Generated Skills Do Not Include marketplace.json
> Covers: FR-005 — Generated skills MUST NOT include `.claude-plugin/marketplace.json` for simple skills
> Type: Happy Path
## Given
- The meta-skill is invoked to create a simple (single-skill) skill
- Input: "Create a skill for formatting markdown tables"
## When
- Phase 5 generates the complete skill directory
## Then
- The generated skill directory does NOT contain a `.claude-plugin/` subdirectory
- The generated skill directory does NOT contain a `marketplace.json` file at any level
- The skill activates solely via its SKILL.md file
## Verification Method
**Method**: CLI command
**Steps**:
1. Run the meta-skill to generate a simple skill
2. Run: `find markdown-table-formatter/ -name "marketplace.json" -o -name ".claude-plugin" | wc -l`
3. Verify the count is 0
**Expected evidence**: `find` returns 0 results. No `.claude-plugin/` directory or `marketplace.json` file exists anywhere in the generated skill directory.

29
scenarios/SC-010-marketplace-json-complex-suite.scenario.md Normal file
View file

@ -0,0 +1,29 @@
# SC-010: Complex Skill Suite May Include Standard marketplace.json
> Covers: FR-006 — Generated skills for complex suites MAY include a marketplace.json with ONLY official Claude Code fields
> Type: Happy Path
## Given
- The meta-skill is invoked to create a complex skill suite with multiple sub-skills
- Input: "Create a skill suite for full-stack web development with separate skills for frontend, backend, and deployment"
## When
- Phase 5 generates the complete skill suite directory
## Then
- If a `.claude-plugin/marketplace.json` is generated, it contains ONLY official fields: `name`, `plugins[].name`, `plugins[].description`, `plugins[].source`, `plugins[].skills`
- No non-standard fields are present (no `version`, no `author`, no `repository`, no `tags`)
- The JSON is valid and parseable
## Verification Method
**Method**: Automated test
**Steps**:
1. Run the meta-skill with the complex suite input
2. If `.claude-plugin/marketplace.json` exists, parse it with `json.load()`
3. Assert all keys are in the official set: `{"name", "plugins"}`
4. For each plugin, assert keys are subset of: `{"name", "description", "source", "skills"}`
5. Assert no extra keys exist at any level
**Expected evidence**: JSON parses cleanly. Only official fields present. No non-standard fields like `version`, `author`, `repository`, or `tags`.

29
scenarios/SC-011-no-cskill-suffix.scenario.md Normal file
View file

@ -0,0 +1,29 @@
# SC-011: Generated Skill Names Do Not Use -cskill Suffix
> Covers: FR-007 — The `-cskill` naming suffix MUST be removed from all generated skill names
> Type: Happy Path
## Given
- The meta-skill is invoked with: "Create a skill for code review automation"
## When
- Phase 3 (Architecture) generates the directory structure
- Phase 5 (Implementation) generates all files
## Then
- The generated directory name does NOT end with `-cskill` (e.g., `code-review-automation/` not `code-review-automation-cskill/`)
- The `name` field in SKILL.md frontmatter does NOT contain `-cskill`
- No file content references the `-cskill` suffix as a naming convention
## Verification Method
**Method**: CLI command
**Steps**:
1. Run the meta-skill to generate the skill
2. Run: `ls -d */` to see generated directory name
3. Assert directory name does not end with `-cskill`
4. Run: `grep -r "cskill" code-review-automation/ | wc -l`
5. Assert count is 0
**Expected evidence**: Directory is named `code-review-automation/` (not `code-review-automation-cskill/`). Grep for "cskill" returns 0 matches.

27
scenarios/SC-012-cskill-suffix-rejected.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-012: User Requesting -cskill Suffix Gets Deprecation Notice
> Covers: FR-007 — Edge case from Section 2.3: User requests -cskill suffix
> Type: Edge Case
## Given
- The meta-skill is invoked with: "Create a skill called my-tool-cskill for file conversion"
## When
- The meta-skill processes the name and enters Phase 3 (Architecture)
## Then
- The user is informed that the `-cskill` suffix is deprecated and will not be used
- The generated directory and `name` field use `my-tool` or `file-conversion` (without `-cskill`)
- A warning message is displayed to the user about the deprecation
## Verification Method
**Method**: Manual test
**Steps**:
1. Invoke the meta-skill with: "Create a skill called my-tool-cskill for file conversion"
2. Observe the meta-skill's output during Phase 3
3. Verify a deprecation notice is displayed
4. Check the generated directory name does not end in `-cskill`
**Expected evidence**: Output contains a message like "The -cskill suffix is deprecated" or "Generating without -cskill suffix". Generated directory is `my-tool/` or `file-conversion/`, not `my-tool-cskill/`.

27
scenarios/SC-013-license-field-present.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-013: Generated Skills Include License Field
> Covers: FR-008 — Generated skills MUST include `license` field in frontmatter
> Type: Happy Path
## Given
- The meta-skill is invoked to create a skill
- Input: "Create a skill for API health monitoring"
## When
- Phase 5 generates the SKILL.md
## Then
- The SKILL.md frontmatter includes a `license` field
- The license value is a recognized SPDX identifier (e.g., `MIT`, `Apache-2.0`, `ISC`)
## Verification Method
**Method**: Automated test
**Steps**:
1. Run the meta-skill to generate the skill
2. Parse the YAML frontmatter of the generated SKILL.md
3. Assert `license` key is present in frontmatter
4. Assert value is a non-empty string
**Expected evidence**: Frontmatter contains `license: MIT` (or another valid SPDX identifier).

34
scenarios/SC-014-metadata-author-version.scenario.md Normal file
View file

@ -0,0 +1,34 @@
# SC-014: Generated Skills Include Metadata with Author and Version
> Covers: FR-009 — Generated skills MUST include `metadata` field with `author` and `version`
> Type: Happy Path
## Given
- The meta-skill is invoked to create a skill
- Input: "Create a skill for database migration management"
## When
- Phase 5 generates the SKILL.md
## Then
- The SKILL.md frontmatter includes a `metadata` mapping
- The `metadata` contains an `author` field with a non-empty string
- The `metadata` contains a `version` field (e.g., `1.0.0`)
## Verification Method
**Method**: Automated test
**Steps**:
1. Run the meta-skill to generate the skill
2. Parse the YAML frontmatter of the generated SKILL.md
3. Assert `metadata` key is present and is a dict
4. Assert `metadata.author` is a non-empty string
5. Assert `metadata.version` is a non-empty string matching semver pattern `^\d+\.\d+\.\d+`
**Expected evidence**: Frontmatter contains:
```yaml
metadata:
author: "Some Author"
version: "1.0.0"
```

29
scenarios/SC-015-compatibility-field-platform-specific.scenario.md Normal file
View file

@ -0,0 +1,29 @@
# SC-015: Compatibility Field Included When Platform-Specific Features Used
> Covers: FR-010 — Generated skills SHOULD include `compatibility` field when platform-specific features are used
> Type: Happy Path
## Given
- The meta-skill is invoked to create a skill that uses platform-specific features
- Input: "Create a skill that uses Claude Code's allowed-tools feature to restrict tool access to only Bash and Read"
## When
- Phase 5 generates the SKILL.md
## Then
- The SKILL.md frontmatter includes a `compatibility` field
- The `compatibility` value describes which platforms or features are required (<=500 chars)
- The `allowed-tools` experimental field is also present in frontmatter
## Verification Method
**Method**: Automated test
**Steps**:
1. Run the meta-skill with the platform-specific input
2. Parse the YAML frontmatter
3. Assert `compatibility` key is present
4. Assert `len(compatibility) <= 500`
5. Assert the value references the platform-specific constraint
**Expected evidence**: Frontmatter contains `compatibility: "Requires Claude Code for allowed-tools support"` (or similar). Length is <=500 chars.

33
scenarios/SC-016-validation-all-spec-rules.scenario.md Normal file
View file

@ -0,0 +1,33 @@
# SC-016: Validation Checks All Official Spec Rules
> Covers: FR-011, FR-012, NFR-003 — Validation MUST check every generated skill against official spec rules
> Type: Happy Path
## Given
- A fully valid skill directory `valid-skill/` exists with:
- `name: valid-skill` (matches directory)
- `description: "A valid test skill for verification"` (<=1024 chars)
- Valid YAML frontmatter structure
- SKILL.md body <500 lines
## When
- The validation function `validate_skill("valid-skill/")` is invoked
## Then
- The validation result `valid` is `True`
- The `errors` list is empty
- The `warnings` list may contain non-blocking suggestions
- All spec rules have been checked (name format, description length, frontmatter structure, directory name match)
## Verification Method
**Method**: Automated test
**Steps**:
1. Create a fully compliant skill directory `valid-skill/` with correct frontmatter
2. Call `validate_skill("valid-skill/")`
3. Assert `result.valid is True`
4. Assert `len(result.errors) == 0`
5. Verify the function checks at minimum: name format, description length, frontmatter structure, directory match
**Expected evidence**: `valid: True`, `errors: []`. Function returns a ValidationResult with all four required check categories evaluated.

32
scenarios/SC-017-validation-invalid-name-format.scenario.md Normal file
View file

@ -0,0 +1,32 @@
# SC-017: Validation Fails on Invalid Name Format
> Covers: FR-012 — Validation MUST check name format (lowercase+hyphens only)
> Type: Failure
## Given
- A skill directory `My_Skill/` exists with SKILL.md containing:
```yaml
---
name: My_Skill
description: "A skill with invalid name format"
---
```
## When
- The validation function `validate_skill("My_Skill/")` is invoked
## Then
- The validation result `valid` is `False`
- The `errors` list contains a message about invalid name format (uppercase letters and underscores not allowed)
## Verification Method
**Method**: Automated test
**Steps**:
1. Create directory `My_Skill/` with SKILL.md containing `name: My_Skill`
2. Call `validate_skill("My_Skill/")`
3. Assert `result.valid is False`
4. Assert `result.errors` contains a message about name format violation
**Expected evidence**: `valid: False`, error message like `"name 'My_Skill' contains invalid characters. Must be lowercase alphanumeric and hyphens only."`.

30
scenarios/SC-018-security-scan-hardcoded-key.scenario.md Normal file
View file

@ -0,0 +1,30 @@
# SC-018: Security Scan Detects Hardcoded API Key
> Covers: FR-013 — Security scan MUST check for hardcoded API keys, secrets, and .env files
> Type: Happy Path
## Given
- A generated skill directory `leaky-skill/` contains a script `scripts/main.py` with:
```python
API_KEY = "sk-proj-abc123def456ghi789jkl012mno345pqr678stu901vwx234"
```
## When
- The security scan is run as part of validation (or independently)
## Then
- The security scan fails
- The `security` list in the validation result contains a finding about the hardcoded API key
- The finding identifies the file (`scripts/main.py`) and the pattern matched
## Verification Method
**Method**: Automated test
**Steps**:
1. Create `leaky-skill/scripts/main.py` with a hardcoded API key string
2. Call `validate_skill("leaky-skill/")` or the dedicated security scan function
3. Assert `result.security` is non-empty
4. Assert a security finding references `scripts/main.py` and mentions "hardcoded" or "API key" or "secret"
**Expected evidence**: Security findings list includes an entry like `"Hardcoded secret detected in scripts/main.py: possible API key on line 1"`.

29
scenarios/SC-019-security-scan-env-file.scenario.md Normal file
View file

@ -0,0 +1,29 @@
# SC-019: Security Scan Detects .env File in Skill Directory
> Covers: FR-013 — Security scan MUST check for .env files
> Type: Failure
## Given
- A generated skill directory `env-skill/` contains a `.env` file with:
```
DATABASE_URL=postgres://user:password@host:5432/db
SECRET_KEY=supersecretvalue123
```
## When
- The security scan is run on `env-skill/`
## Then
- The security scan reports a finding about the `.env` file
- The `security` list contains a warning that `.env` files should not be included in skills
## Verification Method
**Method**: Automated test
**Steps**:
1. Create `env-skill/` with a valid SKILL.md and a `.env` file containing secrets
2. Run the security scan
3. Assert security findings reference the `.env` file
**Expected evidence**: Security finding like `"Sensitive file detected: .env should not be included in skill directory"`.

29
scenarios/SC-020-security-scan-clean-skill.scenario.md Normal file
View file

@ -0,0 +1,29 @@
# SC-020: Security Scan Passes on Clean Skill
> Covers: FR-013 — Security scan MUST check for hardcoded secrets (negative case: no findings)
> Type: Happy Path
## Given
- A generated skill directory `clean-skill/` contains:
- SKILL.md with valid frontmatter
- `scripts/main.py` using environment variables: `os.environ.get("API_KEY")`
- No `.env` files
- No hardcoded secrets
## When
- The security scan is run on `clean-skill/`
## Then
- The security scan passes with no findings
- The `security` list in the validation result is empty
## Verification Method
**Method**: Automated test
**Steps**:
1. Create `clean-skill/` with SKILL.md and scripts using `os.environ.get()` for all secrets
2. Run the security scan
3. Assert `result.security` is empty or `len(result.security) == 0`
**Expected evidence**: `security: []` -- no security issues found.

30
scenarios/SC-021-security-scan-shell-injection.scenario.md Normal file
View file

@ -0,0 +1,30 @@
# SC-021: Security Scan Detects Shell Injection Patterns
> Covers: FR-014 — Security scan SHOULD check for shell injection patterns in generated scripts
> Type: Happy Path
## Given
- A generated skill directory `unsafe-skill/` contains `scripts/runner.py` with:
```python
import subprocess
user_input = input("Enter filename: ")
subprocess.call(f"cat {user_input}", shell=True)
```
## When
- The security scan is run on `unsafe-skill/`
## Then
- The security scan identifies a shell injection risk
- The `security` list contains a finding about `subprocess.call` with `shell=True` and unsanitized input
## Verification Method
**Method**: Automated test
**Steps**:
1. Create `unsafe-skill/scripts/runner.py` with `subprocess.call(..., shell=True)` using f-string interpolation
2. Run the security scan
3. Assert security findings reference shell injection or `shell=True`
**Expected evidence**: Security finding like `"Potential shell injection in scripts/runner.py: subprocess.call with shell=True and string interpolation"`.

29
scenarios/SC-022-install-sh-generated.scenario.md Normal file
View file

@ -0,0 +1,29 @@
# SC-022: Generated Skills Include install.sh
> Covers: FR-015 — Generated skills MUST include an `install.sh` script that auto-detects the platform
> Type: Happy Path
## Given
- The meta-skill is invoked with: "Create a skill for log analysis"
## When
- Phase 5 generates the complete skill directory
## Then
- An `install.sh` file exists in the root of the generated skill directory
- The file is executable (`chmod +x`)
- The script contains platform auto-detection logic (checks for `~/.claude/`, `~/.github/`, etc.)
- Running `./install.sh --dry-run` shows what would happen without making changes
## Verification Method
**Method**: CLI command
**Steps**:
1. Run the meta-skill to generate the skill
2. Run: `test -f log-analysis/install.sh && echo "EXISTS" || echo "MISSING"`
3. Run: `test -x log-analysis/install.sh && echo "EXECUTABLE" || echo "NOT EXECUTABLE"`
4. Run: `grep -c "auto-detect\|platform\|claude\|copilot\|cursor" log-analysis/install.sh`
5. Run: `./log-analysis/install.sh --dry-run`
**Expected evidence**: File exists and is executable. Script contains platform detection strings. Dry run outputs detected platform and intended installation path without making changes.

27
scenarios/SC-023-install-sh-primary-platforms.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-023: install.sh Supports Primary Platform Paths
> Covers: FR-016 — install.sh MUST support ~/.claude/skills/, ~/.github/skills/, .claude/skills/, .github/skills/
> Type: Happy Path
## Given
- A generated skill `log-analysis/` with a valid `install.sh`
- The test environment has `~/.claude/` directory present
## When
- `./install.sh --platform claude-code` is run
## Then
- The skill is copied to `~/.claude/skills/log-analysis/`
- The SKILL.md and all supporting files are present in the destination
- Exit code is 0
## Verification Method
**Method**: CLI command
**Steps**:
1. Run: `./log-analysis/install.sh --platform claude-code`
2. Run: `test -f ~/.claude/skills/log-analysis/SKILL.md && echo "INSTALLED" || echo "FAILED"`
3. Run: `echo $?` after install to check exit code
**Expected evidence**: Exit code 0. File `~/.claude/skills/log-analysis/SKILL.md` exists. All skill files are present in the destination.

27
scenarios/SC-024-install-sh-project-level.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-024: install.sh Supports Project-Level Installation
> Covers: FR-016 — install.sh MUST support .claude/skills/ (project) and .github/skills/ (project)
> Type: Happy Path
## Given
- A generated skill `log-analysis/` with a valid `install.sh`
- The current directory is a project root (e.g., `/tmp/my-project/`)
## When
- `./install.sh --project` is run from `/tmp/my-project/`
## Then
- The skill is copied to `.claude/skills/log-analysis/` relative to the current directory
- If `.claude/` does not exist, it is created
- Exit code is 0
## Verification Method
**Method**: CLI command
**Steps**:
1. Create a temp project directory: `mkdir -p /tmp/my-project && cd /tmp/my-project`
2. Run: `path/to/log-analysis/install.sh --project`
3. Run: `test -f /tmp/my-project/.claude/skills/log-analysis/SKILL.md && echo "INSTALLED" || echo "FAILED"`
**Expected evidence**: Exit code 0. `.claude/skills/log-analysis/SKILL.md` exists relative to the project root.

27
scenarios/SC-025-install-sh-extended-platforms.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-025: install.sh Supports Extended Platforms and Custom Path
> Covers: FR-017 — install.sh SHOULD support .cursor/rules/, .codex/skills/, and custom paths via --path
> Type: Happy Path
## Given
- A generated skill `log-analysis/` with a valid `install.sh`
## When
- `./install.sh --platform cursor` is run
- Alternatively, `./install.sh --path /custom/skills/path/` is run
## Then
- For `--platform cursor`: skill is copied to `.cursor/rules/log-analysis/`
- For `--path /custom/skills/path/`: skill is copied to `/custom/skills/path/log-analysis/`
- Exit code is 0 in both cases
## Verification Method
**Method**: CLI command
**Steps**:
1. Run: `./log-analysis/install.sh --path /tmp/custom-skills/`
2. Run: `test -f /tmp/custom-skills/log-analysis/SKILL.md && echo "INSTALLED" || echo "FAILED"`
3. Verify exit code is 0
**Expected evidence**: Exit code 0. Skill files exist at the custom path. SKILL.md is present.

27
scenarios/SC-026-install-sh-platform-not-detected.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-026: install.sh Falls Back When No Platform Detected
> Covers: FR-015, Edge case from 2.3 — install.sh target platform not detected: fall back to interactive prompt
> Type: Edge Case
## Given
- A generated skill with a valid `install.sh`
- The system has NONE of the standard platform directories (`~/.claude/`, `~/.github/`, `.cursor/`, etc.)
## When
- `./install.sh` is run without `--platform` or `--path` flags
## Then
- The script does NOT silently fail
- The script outputs a message listing available platforms and asks the user to specify one
- Exit code is 2 (Platform not detected)
## Verification Method
**Method**: CLI command
**Steps**:
1. In a clean environment without any platform directories, run: `./install.sh`
2. Check the output for a prompt or platform list
3. Check exit code: `echo $?`
**Expected evidence**: Exit code 2. Output contains a message like "No supported platform detected. Please specify with --platform or --path." Lists available platform options.

29
scenarios/SC-027-install-sh-validation-fails.scenario.md Normal file
View file

@ -0,0 +1,29 @@
# SC-027: install.sh Exits 1 When SKILL.md Is Invalid
> Covers: FR-015 — install.sh exit code 1: Validation failed (SKILL.md invalid)
> Type: Failure
## Given
- A skill directory with an invalid SKILL.md (missing required `name` field)
- The `install.sh` script exists in the directory
## When
- `./install.sh --platform claude-code` is run
## Then
- The install script detects the invalid SKILL.md before copying
- The script exits with code 1
- An error message about SKILL.md validation failure is displayed
- No files are copied to the destination
## Verification Method
**Method**: CLI command
**Steps**:
1. Create a skill directory with an invalid SKILL.md (missing `name`)
2. Run: `./install.sh --platform claude-code`
3. Check exit code: `echo $?`
4. Verify destination directory does not exist
**Expected evidence**: Exit code 1. Output includes "Validation failed" or "Invalid SKILL.md". No files copied to `~/.claude/skills/`.

26
scenarios/SC-028-install-sh-permission-denied.scenario.md Normal file
View file

@ -0,0 +1,26 @@
# SC-028: install.sh Exits 3 on Permission Denied
> Covers: FR-015 — install.sh exit code 3: Permission denied
> Type: Failure
## Given
- A valid skill directory with `install.sh`
- The target directory `/root/protected/skills/` exists but is not writable by the current user
## When
- `./install.sh --path /root/protected/skills/` is run
## Then
- The install script detects the permission issue
- The script exits with code 3
- An error message about insufficient permissions is displayed
## Verification Method
**Method**: CLI command
**Steps**:
1. Run: `./install.sh --path /root/protected/skills/`
2. Check exit code: `echo $?`
**Expected evidence**: Exit code 3. Output includes "Permission denied" or "Cannot write to target directory".

27
scenarios/SC-029-install-sh-dry-run.scenario.md Normal file
View file

@ -0,0 +1,27 @@
# SC-029: install.sh Dry Run Shows Actions Without Executing
> Covers: FR-015 — install.sh --dry-run support
> Type: Happy Path
## Given
- A valid skill directory `log-analysis/` with `install.sh`
- `~/.claude/` directory exists
## When
- `./install.sh --dry-run` is run
## Then
- The script outputs what it would do (detected platform, source path, destination path)
- No files are actually copied
- Exit code is 0
## Verification Method
**Method**: CLI command
**Steps**:
1. Run: `./log-analysis/install.sh --dry-run`
2. Capture output
3. Verify no files were created: `test -d ~/.claude/skills/log-analysis/ && echo "EXISTS" || echo "NOT CREATED"`
**Expected evidence**: Output shows "Would install to ~/.claude/skills/log-analysis/" (or similar). Destination directory does not exist after dry run. Exit code 0.

33
scenarios/SC-030-readme-multiplatform-instructions.scenario.md Normal file
View file

@ -0,0 +1,33 @@
# SC-030: Generated README.md Includes Multi-Platform Installation
> Covers: FR-018, FR-026 — README MUST include installation instructions for at least 5 platforms with copy-paste commands
> Type: Happy Path
## Given
- The meta-skill is invoked with: "Create a skill for git commit message generation"
## When
- Phase 5 generates the README.md
## Then
- The generated README.md contains a "Cross-Platform Installation" section (or equivalent)
- The section includes copy-paste commands for at least 5 platforms:
- Claude Code
- GitHub Copilot
- Cursor
- Windsurf
- Cline (or Codex CLI, or Gemini CLI)
- Each platform section includes the exact shell command to install
## Verification Method
**Method**: CLI command
**Steps**:
1. Run the meta-skill to generate the skill
2. Run: `grep -i "claude code\|copilot\|cursor\|windsurf\|cline\|codex\|gemini" git-commit-generator/README.md | wc -l`
3. Assert count >= 5
4. Run: `grep -c "install\|cp\|copy\|mkdir" git-commit-generator/README.md`
5. Assert count >= 5 (at least one command per platform)
**Expected evidence**: README.md contains a "Cross-Platform Installation" section. At least 5 distinct platforms are listed with shell commands like `cp -r` or `./install.sh --platform`.

28
scenarios/SC-031-export-desktop-zip.scenario.md Normal file
View file

@ -0,0 +1,28 @@
# SC-031: Export System Produces Desktop/Web .zip Package
> Covers: FR-019 — Export system MUST continue to support Desktop/Web .zip variant
> Type: Happy Path
## Given
- A valid skill directory `log-analysis/` exists with all required files
- The export system (`scripts/export_utils.py`) is available
## When
- `export_skill("log-analysis/", variants=["desktop"])` is called
## Then
- A `.zip` file is generated for the Desktop/Web variant
- The zip contains the SKILL.md and all supporting files
- The zip is a valid archive that can be extracted
## Verification Method
**Method**: Automated test
**Steps**:
1. Call `export_skill("log-analysis/", variants=["desktop"])`
2. Assert the returned dict contains a path to a `.zip` file
3. Run: `unzip -t <output.zip>` to verify archive integrity
4. Assert SKILL.md is present in the archive listing
**Expected evidence**: A `.zip` file is produced. `unzip -t` reports "No errors detected". Archive contains `SKILL.md`.

28
scenarios/SC-032-export-api-zip.scenario.md Normal file
View file

@ -0,0 +1,28 @@
# SC-032: Export System Produces API .zip Package Under 8MB
> Covers: FR-019 — Export system MUST continue to support API .zip variant
> Type: Happy Path
## Given
- A valid skill directory `log-analysis/` exists with all required files
- The export system (`scripts/export_utils.py`) is available
## When
- `export_skill("log-analysis/", variants=["api"])` is called
## Then
- A `.zip` file is generated for the API variant
- The zip file size is less than 8MB
- The zip contains an optimized subset of files suitable for API consumption
## Verification Method
**Method**: Automated test
**Steps**:
1. Call `export_skill("log-analysis/", variants=["api"])`
2. Assert the returned dict contains a path to a `.zip` file
3. Check file size: `os.path.getsize(zip_path) < 8 * 1024 * 1024`
4. Run: `unzip -t <output.zip>` to verify integrity
**Expected evidence**: A `.zip` file is produced. File size is less than 8,388,608 bytes (8MB). `unzip -t` reports no errors.

26
scenarios/SC-033-export-platform-flag.scenario.md Normal file
View file

@ -0,0 +1,26 @@
# SC-033: Export System Supports --platform Flag for Cursor
> Covers: FR-020 — Export system SHOULD add a --platform flag to generate platform-specific output
> Type: Happy Path
## Given
- A valid skill directory `log-analysis/` exists
- The export system supports the `platform` parameter
## When
- `export_skill("log-analysis/", platform="cursor")` is called
## Then
- The export generates a Cursor-compatible output (e.g., an `.mdc` file or Cursor-formatted directory)
- The output contains the SKILL.md content adapted for Cursor's rule format
## Verification Method
**Method**: Automated test
**Steps**:
1. Call `export_skill("log-analysis/", platform="cursor")`
2. Check that the output contains a `.mdc` file or Cursor-specific format
3. Verify the content includes the original skill instructions
**Expected evidence**: An `.mdc` file or Cursor-compatible output is produced. Content preserves the skill's instructions.

37
scenarios/SC-034-phase3-standard-directory-structure.scenario.md Normal file
View file

@ -0,0 +1,37 @@
# SC-034: Phase 3 Generates Standard-Compliant Directory Structure
> Covers: FR-022 — Phase 3 (Architecture) MUST generate standard-compliant directory structures (no -cskill suffix)
> Type: Happy Path
## Given
- The meta-skill is invoked with: "Create a skill for API rate limiting management"
## When
- Phase 3 (Architecture) completes and proposes the directory structure
## Then
- The proposed directory name is `api-rate-limiter/` (or similar, without `-cskill`)
- The structure includes: `SKILL.md`, `scripts/`, `references/`, `install.sh`, `README.md`
- No `.claude-plugin/` directory is proposed for a simple skill
- The structure matches the Agent Skills Open Standard layout
## Verification Method
**Method**: Manual test
**Steps**:
1. Run the meta-skill and observe Phase 3 output
2. Verify the directory name does not contain `-cskill`
3. Verify the proposed structure includes all standard files: SKILL.md, install.sh, README.md
4. Verify scripts/ and references/ directories are proposed
**Expected evidence**: Phase 3 output shows a directory like:
```
api-rate-limiter/
SKILL.md
scripts/
references/
install.sh
README.md
```
No `-cskill` suffix. No `marketplace.json`.

28
scenarios/SC-035-phase5-skillmd-first.scenario.md Normal file
View file

@ -0,0 +1,28 @@
# SC-035: Phase 5 Creates SKILL.md as the First and Primary File
> Covers: FR-023 — Phase 5 (Implementation) MUST create SKILL.md as the first and primary file
> Type: Happy Path
## Given
- The meta-skill has completed Phases 1-4 for a "data pipeline orchestrator" skill
## When
- Phase 5 (Implementation) begins generating files
## Then
- SKILL.md is the first file created in the implementation sequence
- SKILL.md contains spec-compliant frontmatter (`name`, `description` at minimum)
- marketplace.json is NOT created before or instead of SKILL.md
- The SKILL.md is the primary file that defines the skill's behavior
## Verification Method
**Method**: Manual test
**Steps**:
1. Run the meta-skill and observe Phase 5 output
2. Verify the first file mentioned/created is SKILL.md
3. Verify SKILL.md has valid frontmatter
4. Verify marketplace.json is NOT created for this simple skill
**Expected evidence**: Phase 5 log shows "Creating SKILL.md..." as the first file operation. The generated SKILL.md has valid `name` and `description` frontmatter fields.

35
scenarios/SC-036-phase5-runs-validation.scenario.md Normal file
View file

@ -0,0 +1,35 @@
# SC-036: Phase 5 Runs Validation After Generating All Files
> Covers: FR-024 — Phase 5 MUST run validation after generating all files
> Type: Happy Path
## Given
- The meta-skill has completed Phases 1-4
- Phase 5 has generated all files (SKILL.md, scripts, references, install.sh, README.md)
## When
- Phase 5 reaches the validation step (step h in the pipeline)
## Then
- The validation function is invoked automatically on the generated skill directory
- The validation result is reported to the user
- If validation passes, Phase 5 continues to the security scan
- If validation fails, the user is informed of the specific errors
## Verification Method
**Method**: Manual test
**Steps**:
1. Run the meta-skill to completion
2. Observe Phase 5 output for validation step
3. Verify a validation report is shown (pass/fail with details)
**Expected evidence**: Phase 5 output includes a validation report section, such as:
```
Validation: PASSED
- name format: OK
- description length: OK
- directory match: OK
- line count: OK
```

Some files were not shown because too many files have changed in this diff Show more