diff --git a/.clarity/context.md b/.clarity/context.md new file mode 100644 index 0000000..7cfbede --- /dev/null +++ b/.clarity/context.md @@ -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. diff --git a/.clarity/handoff.md b/.clarity/handoff.md new file mode 100644 index 0000000..f84f9f1 --- /dev/null +++ b/.clarity/handoff.md @@ -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": "", + "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 diff --git a/.clarity/plan.md b/.clarity/plan.md new file mode 100644 index 0000000..8dc7445 --- /dev/null +++ b/.clarity/plan.md @@ -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? diff --git a/.clarity/spec.md b/.clarity/spec.md new file mode 100644 index 0000000..b729aa1 --- /dev/null +++ b/.clarity/spec.md @@ -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? diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f32d011..83ea021 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -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." ] } diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..ddc84aa --- /dev/null +++ b/MIGRATION.md @@ -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/ diff --git a/README.md b/README.md index 9d86e10..9150de7 100644 --- a/README.md +++ b/README.md @@ -1,2143 +1,457 @@ -# Agent Creator v2.1 - Transform Workflows into Intelligent Agents +# Agent Skill Creator v4.0 -**Stop doing repetitive work manually. Create intelligent agents that learn and improve automatically.** +**Create Cross-Platform Agent Skills from Workflow Descriptions** -*From "takes 2 hours daily" to "takes 5 minutes" - in minutes, not weeks.* +[![Agent Skills Open Standard](https://img.shields.io/badge/Agent%20Skills-Open%20Standard-blue)](https://github.com/anthropics/agent-skills-spec) +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) +[![Version](https://img.shields.io/badge/version-4.0.0-brightgreen)]() + +> Works on **8+ platforms**: Claude Code, GitHub Copilot, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI, and any platform supporting the Agent Skills Open Standard. --- -## 🎯 **Who This Is For** +## What It Does -### **🏢 Business Owners & Entrepreneurs** -- **Problem**: "I spend 3 hours daily updating spreadsheets and reports" -- **Solution**: Automated agents that work while you focus on growth -- **ROI**: 1000%+ return in the first month +Agent Skill Creator is a **meta-skill** -- a skill that creates other skills. Describe a repetitive workflow in natural language, and it generates a complete, validated, cross-platform agent skill through an autonomous 5-phase pipeline. -### **💼 Professionals & Consultants** -- **Problem**: "Manual data collection and analysis is eating my billable hours" -- **Solution**: Specialized agents that deliver insights instantly -- **Value**: Scale your services without scaling your time +**Input**: A workflow description like *"Every day I download stock data, analyze trends, and create reports"* -### **🔬 Researchers & Academics** -- **Problem**: "Literature review and data analysis takes weeks of manual work" -- **Solution**: Research agents that gather, analyze, and synthesize information -- **Impact**: Focus on discovery, not data wrangling - -### **👨‍💻 Developers & Tech Teams** -- **Problem**: "We need to automate workflows but lack time to build tools" -- **Solution**: Production-ready agents in minutes, not months -- **Benefit**: Ship automation faster than ever before +**Output**: A ready-to-install skill directory with functional scripts, documentation, cross-platform installer, and spec-compliant SKILL.md. --- -## ⚡ **What It Does - The Magic Explained** +## Quick Start -### **You Simply Describe What You Do Repeatedly:** -``` -"Every day I download stock market data, analyze trends, -and create reports. This takes 2 hours." -``` - -### **Claude Code Creates an Agent That:** -🤖 **Automatically downloads** stock market data from reliable APIs -🤖 **Analyzes** trends using proven financial indicators -🤖 **Generates** professional reports -🤖 **Stores** results in your preferred format -🤖 **Learns** from each use to get better over time - -### **Result:** 2-hour daily task → 5-minute automated process - ---- - -## 📊 **Real-World Impact: Proven Results** - -### **📈 Performance Metrics** -| Task Type | Manual Time | Agent Time | Time Saved | Monthly Hours Saved | -|-----------|-------------|------------|------------|-------------------| -| Financial Analysis | 2h/day | 5min/day | **96%** | **48h** | -| Inventory Management | 1.5h/day | 3min/day | **97%** | **36h** | -| Research Data Collection | 8h/week | 20min/week | **95%** | **7h** | -| Report Generation | 3h/week | 10min/week | **94%** | **2.5h** | - -### **💰 Business ROI Examples** -- **Restaurant Owner**: $3,000/month saved on manual inventory work -- **Financial Analyst**: 20 more clients handled with same time investment -- **Research Scientist**: 2 publications per year instead of 1 -- **E-commerce Manager**: 30% increase in analysis frequency - ---- - -## 🏗️ **Claude Skills Architecture: Understanding What We Create** - -### **🎯 Important Clarification: Skills vs Plugins** - -The Agent Creator creates **Claude Skills** - which come in different architectural patterns. This eliminates the common confusion between skills and plugins. - -#### **📋 Two Types of Skills We Create** - -**1. Simple Skills** (Single focused capability) -``` -task-automator-cskill/ -├── SKILL.md ← One comprehensive skill file -├── scripts/ ← Supporting code -└── references/ ← Documentation -``` -*Perfect for: Single workflow, focused automation, quick development* - -**2. Complex Skill Suites** (Multiple specialized capabilities) -``` -business-platform-cskill/ -├── .claude-plugin/ -│ └── marketplace.json ← Organizes component skills -├── data-processor-cskill/SKILL.md ← Component 1 -├── analysis-engine-cskill/SKILL.md ← Component 2 -└── reporting-cskill/SKILL.md ← Component 3 -``` -*Perfect for: Complex workflows, team projects, enterprise solutions* - -#### **🏷️ Naming Convention: "-cskill" Suffix** - -**All created skills use the "-cskill" suffix:** -- **Purpose**: Identifies immediately as Claude Skill created by Agent-Skill-Creator -- **Format**: `{descrição-descritiva}-cskill/` -- **Examples**: `pdf-text-extractor-cskill/`, `financial-analysis-suite-cskill/` - -**Benefits:** -- ✅ Clear identification of origin and type -- ✅ Professional naming standard -- ✅ Easy organization and discovery -- ✅ Eliminates confusion with manual skills - -**Learn more**: [Complete Naming Guide](docs/NAMING_CONVENTIONS.md) - -#### **🎯 How We Choose the Right Architecture** - -The Agent Creator automatically decides based on: -- **Number of objectives** (single vs multiple) -- **Workflow complexity** (linear vs branching) -- **Domain expertise** (single vs specialized) -- **Code complexity** (simple vs extensive) -- **Maintenance needs** (individual vs team) - -#### **📚 Learn More** - -- **[Complete Architecture Guide](docs/CLAUDE_SKILLS_ARCHITECTURE.md)** - Comprehensive understanding -- **[Decision Logic Framework](docs/DECISION_LOGIC.md)** - How we choose architectures -- **[Naming Conventions Guide](docs/NAMING_CONVENTIONS.md)** - Complete -cskill naming rules -- **[Examples](examples/)** - See simple vs complex skill examples -- **[Internal Flow Analysis](docs/INTERNAL_FLOW_ANALYSIS.md)** - How creation works behind the scenes - -**✅ Key Takeaway:** We ALWAYS create valid Claude Skills with "-cskill" suffix - just with the right architecture for your specific needs! - ---- - -## 🏗️ **Understanding Marketplaces vs Skills vs Plugins** - -### **🎯 Critical Distinction: What Are You Installing?** - -Many users get confused about what they're installing. Let's clarify the hierarchy: - -``` -MARKETPLACE (Container/Distribution) -└── PLUGIN (Executor/Manager) - └── SKILL(S) (Actual Functionality) -``` - -### **📚 Analogy: App Store Ecosystem** - -``` -📱 App Store (Marketplace) - └── Instagram App (Plugin) - ├── Stories Feature (Skill 1) - ├── Photo Filters (Skill 2) - └── Direct Messages (Skill 3) -``` - -### **🔍 What Actually Happens When You Install** - -#### **Command:** -```bash -/plugin marketplace add ./agent-skill-creator -``` - -#### **What This REALLY Does:** -✅ **Registers marketplace** in Claude Code's catalog -✅ **Makes plugins** within marketplace discoverable -✅ **Prepares skills** for activation (but doesn't activate them yet) - -❌ **Does NOT** make skills immediately available -❌ **Does NOT** load code into memory -❌ **Does NOT** enable functionality - -#### **The Full Process:** -``` -Step 1: Register Marketplace -/plugin marketplace add ./agent-skill-creator -↓ -Step 2: Claude Auto-loads Plugins -Discovers: agent-skill-creator-plugin -↓ -Step 3: Skills Become Available -"Create an agent for stock analysis" ← Now works! -``` - -### **🏪 Types of Marketplaces in This Codebase** - -#### **1. META-SKILL MARKETPLACE** (This Project) -``` -agent-skill-creator/ ← MARKETPLACE -├── .claude-plugin/marketplace.json ← Configuration -├── SKILL.md ← Meta-skill (creates other skills) -└── references/examples/ ← Example skills created - └── stock-analyzer-cskill/ ← Skill created by Agent Creator - -Purpose: Tool that CREATES other skills -Installation: /plugin marketplace add ./ -``` - -#### **2. INDEPENDENT SKILL MARKETPLACE** -``` -article-to-prototype-cskill/ ← SEPARATE MARKETPLACE -├── .claude-plugin/marketplace.json ← Its own configuration -├── SKILL.md ← Standalone skill -└── scripts/ ← Functional code - -Purpose: Specific functionality (articles → prototypes) -Installation: /plugin marketplace add ./article-to-prototype-cskill -``` - -#### **3. SKILL SUITE MARKETPLACE** (Future Examples) -``` -business-analytics-suite/ ← HYPOTHETICAL SUITE -├── .claude-plugin/marketplace.json ← Central configuration -├── data-analyzer-cskill/SKILL.md ← Component skill 1 -├── report-generator-cskill/SKILL.md ← Component skill 2 -└── dashboard-viewer-cskill/SKILL.md ← Component skill 3 - -Purpose: Multiple related skills in one package -Installation: /plugin marketplace add ./business-analytics-suite -``` - -### **🎯 Visual File Structure** - -``` -Your Project Directory/ -├── agent-skill-creator/ ← Main tool (marketplace) -│ ├── .claude-plugin/marketplace.json -│ ├── SKILL.md ← Meta-skill functionality -│ └── references/examples/ -│ └── stock-analyzer-cskill/ ← Example created skill -│ -├── article-to-prototype-cskill/ ← Independent skill (separate marketplace) -│ ├── .claude-plugin/marketplace.json -│ ├── SKILL.md ← Standalone functionality -│ └── scripts/ -│ -└── other-skills-you-create/ ← Skills you'll create - ├── financial-analyzer-cskill/ ← Each with own marketplace - └── data-processor-cskill/ -``` - -### **🔧 Installation Scenarios** - -#### **Scenario A: Install Agent Creator (Main Tool)** -```bash -/plugin marketplace add ./agent-skill-creator -# Result: Can now create other skills -# Use: "Create an agent for financial analysis" -``` - -#### **Scenario B: Install article-to-prototype Skill** -```bash -cd ./article-to-prototype-cskill -/plugin marketplace add ./ -# Result: Can extract from articles -# Use: "Extract algorithms from this PDF and implement them" -``` - -#### **Scenario C: Both Installed Together** -```bash -/plugin marketplace add ./agent-skill-creator -/plugin marketplace add ./article-to-prototype-cskill -# Result: Both capabilities available -# Can create skills AND extract from articles -``` - -### **📋 Quick Reference Commands** - -| Command | What It Does | Result | -|---------|--------------|--------| -| `/plugin marketplace add ` | Registers marketplace | Marketplace known to Claude | -| `/plugin list` | Shows all installed marketplaces | See what's available | -| `/plugin marketplace remove ` | Removes marketplace | Skills no longer available | - -### **🎭 Key Takeaways** - -1. **Marketplace ≠ Skill**: Marketplace is container, skills are functionality -2. **One marketplace can contain multiple skills** (suites) or just one (independent) -3. **Registration happens first, activation comes after** (usually automatic) -4. **article-to-prototype-cskill is completely independent** from Agent Creator -5. **Each skill directory with `marketplace.json` is installable** as its own marketplace - -**This understanding is crucial for knowing what you're installing and how components relate to each other!** - ---- - -## 🧠 **How Agent Creator Works: The /references Knowledge Base** - -### **🎯 The "Magic" Behind Perfect Agent Creation** - -Ever wonder how Agent Creator consistently produces high-quality, enterprise-ready agents? The secret is in the `/references` directory - a comprehensive knowledge base that guides every step of the creation process. - -### **🔄 Visual Flow: From Request to Perfect Agent** - -``` -User Request - ↓ -Agent Creator Activates - ↓ -Consults /references Knowledge Base ← 🧠 BRAIN OF THE SYSTEM - ↓ -┌─────────────────────────────────────────────────┐ -│ Phase 1: Discovery (phase1-discovery.md) │ -│ Phase 2: Design (phase2-design.md) │ -│ Phase 3: Architecture (phase3-architecture.md) │ -│ Phase 4: Detection (phase4-detection.md) │ -│ Phase 5: Implementation (phase5-implementation.md) │ -│ Phase 6: Testing (phase6-testing.md) │ -│ │ -│ Activation Patterns (activation-patterns-guide.md) │ -│ Quality Standards (quality-standards.md) │ -│ Templates (templates/) │ -│ Examples (examples/) │ -└─────────────────────────────────────────────────┘ - ↓ -Perfect, Production-Ready Agent Created -``` - -### **📚 1. Methodological Guides (The 6-Phase Recipe)** - -#### **Phase Documents (`phase1-discovery.md` to `phase6-testing.md`)** -- **Purpose**: Step-by-step "recipe" documents that guide each creation phase -- **How used**: Agent Creator follows these guides religiously during creation -- **Content**: Detailed instructions, examples, checklists for each phase - -**Practical Example:** -```python -# During agent creation, Agent Creator does: -def phase1_discovery(user_request): - guide = load_reference("phase1-discovery.md") - return guide.research_apis(user_request) - -def phase2_design(user_request, apis_found): - guide = load_reference("phase2-design.md") - return guide.define_use_cases(user_request, apis_found) -``` - -**What each phase covers:** -- **phase1-discovery.md**: How to research and select APIs -- **phase2-design.md**: How to define useful analyses and use cases -- **phase3-architecture.md**: How to structure folders and files -- **phase4-detection.md**: How to create reliable activation systems -- **phase5-implementation.md**: How to write functional, production-ready code -- **phase6-testing.md**: How to validate and test the completed agent - -### **🎯 2. Reliable Activation System (95%+ Success Rate)** - -#### **Activation Guides** -- `activation-patterns-guide.md`: Library of 30+ tested regex patterns -- `activation-testing-guide.md`: 5-phase testing methodology -- `activation-quality-checklist.md`: Quality checklist for 95%+ reliability -- `ACTIVATION_BEST_PRACTICES.md`: Proven strategies and lessons learned - -**How it works in practice:** -```python -# During Phase 4 (Detection), Agent Creator: -patterns_guide = load_reference("activation-patterns-guide.md") -best_practices = load_reference("ACTIVATION_BEST_PRACTICES.md") - -# Applies proven patterns: -activation_system = create_3_layer_activation( - keywords=patterns_guide.get_keywords_for_domain(domain), - patterns=patterns_guide.get_patterns_for_domain(domain), - description=best_practices.create_description(domain) -) -# Result: 95%+ activation reliability achieved -``` - -### **📋 3. Ready Templates (Accelerated Development)** - -#### **Template System** -- `marketplace-robust-template.json`: JSON template for marketplace.json files -- `README-activation-template.md`: Template for READMEs with activation examples -- **Purpose**: Speed up development with pre-built, validated structures - -**Template usage in action:** -```python -# During implementation, Agent Creator: -template = load_template("marketplace-robust-template.json") - -# Replaces placeholders with domain-specific values: -marketplace_json = template.replace("{{skill-name}}", "stock-analyzer-cskill") -marketplace_json = marketplace_json.replace("{{domain}}", "financial analysis") -marketplace_json = marketplace_json.replace("{{capabilities}}", "RSI, MACD, Bollinger Bands") - -# Result: Complete, validated marketplace.json in seconds -``` - -### **🏗️ 4. Complete Examples (Working Reference Implementations)** - -#### **Working Examples** -- `examples/stock-analyzer-cskill/`: Fully functional example agent -- **Content**: Complete code, README, SKILL.md, scripts, tests -- **Purpose**: Practical reference for expected final result - -**Example-driven development:** -```python -# During creation, Agent Creator references: -example_structure = load_example("stock-analyzer-cskill") - -# Copies proven patterns: -file_structure = example_structure.get_directory_layout() -code_patterns = example_structure.get_code_patterns() -documentation_style = example_structure.get_documentation_style() - -# Result: New agent follows proven, successful patterns -``` - -### **✅ 5. Quality Standards (Enterprise-Grade Requirements)** - -#### **Quality Standards** -- `quality-standards.md`: Mandatory quality requirements -- **Rules**: No TODOs, functional code only, useful documentation -- **Purpose**: Ensure enterprise-grade agent production - -**Quality validation in process:** -```python -# During implementation, Agent Creator validates: -def validate_quality(implemented_code): - standards = load_reference("quality-standards.md") - - if not standards.has_functional_code(implemented_code): - return "ERROR: Code contains TODOs or placeholder functions" - - if not standards.has_useful_documentation(implemented_code): - return "ERROR: Documentation lacks practical examples" - - if not standards.has_error_handling(implemented_code): - return "ERROR: Missing error handling patterns" - - return "✅ QUALITY CHECK PASSED" -``` - -### **🔄 Practical Usage Flow** - -**Here's what happens when you request an agent:** - -``` -1. User Says: "Create financial analysis agent for stocks" - -2. Agent Creator: - ├── Loads phase1-discovery.md → Researches financial APIs - ├── Loads phase2-design.md → Defines RSI, MACD analyses - ├── Loads phase3-architecture.md → Creates folder structure - ├── Loads activation-patterns-guide.md → Builds 3-layer activation - ├── Loads marketplace-robust-template.json → Generates marketplace.json - ├── References stock-analyzer-cskill example → Copies proven patterns - ├── Validates against quality-standards.md → Ensures enterprise quality - └── Loads phase6-testing.md → Creates comprehensive tests - -3. Result: Perfect financial analysis agent in 15-60 minutes! -``` - -### **🎯 Key Benefits of the /references System** - -#### **🎯 Consistency** -- Every agent follows the same proven patterns -- Same folder structures, code styles, documentation formats -- Users get predictable, reliable results every time - -#### **🚀 Speed** -- Templates eliminate repetitive setup work -- Examples provide ready-to-copy patterns -- Guides prevent decision paralysis and research time - -#### **🏆 Quality** -- Standards ensure enterprise-grade output -- Patterns are tested and proven to work -- No "TODO" items or placeholder code - -#### **🔧 Maintainability** -- Clear documentation for every decision -- Standardized patterns make updates easy -- Examples show best practices clearly - -#### **📈 Continuous Improvement** -- Every successful creation adds to the knowledge base -- Failed attempts inform better patterns -- The system gets smarter with each use - -### **🎭 Connecting to Previous Sections** - -- **Marketplace Understanding**: `/references` guides how marketplace.json files are created -- **Activation System**: References enable the 95%+ reliability mentioned earlier -- **Skill Types**: References help decide between simple vs complex skill architectures -- **Installation Examples**: Skills in `references/examples/` demonstrate independent marketplace installation - ---- - -**The `/references` directory is the accumulated intelligence that makes Agent Creator so consistently brilliant - it's not magic, it's methodical, proven expertise built into every step of the process!** - ---- - -## 🚀 **Get Started in 2 Minutes** - -### **Step 1: Install Agent Creator** -```bash -# In Claude Code terminal -/plugin marketplace add FrancyJGLisboa/agent-skill-creator -``` - -### **Step 2: Verify Installation** -```bash -/plugin list -# You should see: ✓ agent-skill-creator -``` - -**💡 Understanding What Just Happened:** -- ✅ Agent Creator marketplace is now **registered** in Claude Code -- ✅ Agent Creator meta-skill is **available** for use -- ✅ You can now **create other skills** using the meta-skill - -### **Step 3: Create Your First Agent** -```bash -# Just describe what you do repeatedly: -"Automate my daily financial analysis - download stock data, -calculate technical indicators, generate reports" -``` - -**That's it!** Your agent will be created in **15-90 minutes** automatically. - ---- - -### **🎯 Optional: Install Independent Skills** - -If you also want to use the `article-to-prototype-cskill` (mentioned in the hierarchy section): +### Install ```bash -# Navigate to the independent skill directory -cd ./article-to-prototype-cskill - -# Install its separate marketplace -/plugin marketplace add ./ - -# Verify both are installed -/plugin list -# Should show both: ✓ agent-skill-creator AND ✓ article-to-prototype-cskill +# Clone and install as a Claude Code skill +git clone https://github.com/user/agent-skill-creator.git +cp -r agent-skill-creator/ ~/.claude/skills/agent-skill-creator/ ``` -**Now you have:** -- ✅ Agent Creator (creates new skills) -- ✅ Article-to-Prototype (extracts from articles and generates code) +### Use + +Just describe what you need in your agent: + +``` +"Create a skill for analyzing stock market data" + +"Every day I process CSV files manually, automate this" + +"Create a cross-platform skill for weather alerts" + +"Validate this skill for spec compliance" + +"Export this skill for Cursor and Copilot" +``` + +The skill creator activates automatically when it detects these patterns and walks through the full pipeline. --- -## 🎭 **Real Stories: How Others Are Using It** +## Supported Platforms -### **🍽️ Maria - Restaurant Owner** -**Before:** "I spent 2 hours daily updating inventory, sales, and customer data in spreadsheets. It was tedious and error-prone." +Generated skills work on any platform that supports the Agent Skills Open Standard: -**After:** "Now I just say 'Update restaurant data' and my agent does everything in 3 minutes. I save 60 hours per month and make better business decisions!" +| Platform | Install Location | Notes | +|----------|-----------------|-------| +| **Claude Code** | `~/.claude/skills/` or `.claude/skills/` | Global or per-project | +| **GitHub Copilot** | `.github/skills/` | Repository-level | +| **Cursor** | `.cursor/rules/` | Workspace rules | +| **Windsurf** | `.windsurf/skills/` | Workspace skills | +| **Cline** | `.clinerules/` | Rule-based skills | +| **Codex CLI** | `.codex/skills/` | OpenAI Codex CLI | +| **Gemini CLI** | `.gemini/skills/` | Google Gemini CLI | -**Agent Created:** Restaurant Management Suite (4 specialized agents) +Each generated skill includes an `install.sh` script that auto-detects your platform and installs to the correct location. --- -### **💰 David - Financial Analyst** -**Before:** "I spent 4 hours daily collecting stock data, calculating indicators, and writing reports. I couldn't handle more clients." +## How It Works -**After:** "My financial analysis agent does all the work in 8 minutes. I now handle 20 clients instead of 5, with better analysis quality." +The creator runs a **5-phase autonomous pipeline**: -**Agent Created:** Comprehensive Financial Analysis System +``` +Phase 1: DISCOVERY Research APIs, data sources, tools, and domain knowledge + | +Phase 2: DESIGN Define use cases, analyses, methodologies, and outputs + | +Phase 3: ARCHITECTURE Structure skill directory (simple skill vs. complex suite) + | +Phase 4: DETECTION Generate description + keywords for reliable activation + | +Phase 5: IMPLEMENTATION Create all files, run validation, run security scan +``` + +### Phase Details + +| Phase | What Happens | Key Output | +|-------|-------------|------------| +| **Discovery** | Researches the domain, identifies APIs and data sources, maps user needs | Domain model, API list, data sources | +| **Design** | Defines use cases, analysis methods, output formats | Use case specs, methodology docs | +| **Architecture** | Decides simple skill vs. complex suite, plans directory structure | Architecture decision, file plan | +| **Detection** | Crafts SKILL.md description and activation keywords for reliable triggering | SKILL.md frontmatter, trigger phrases | +| **Implementation** | Generates all code, docs, installer; validates and scans for security issues | Complete skill directory | + +For full pipeline documentation, see [references/pipeline-phases.md](references/pipeline-phases.md). --- -### **🔬 Dr. Sarah - Research Scientist** -**Before:** "Literature review for my climate research took 3 weeks of manual work. I could only do 2 studies per year." +## Architecture: Simple Skill vs. Complex Suite -**After:** "My research agent finds and analyzes papers in 45 minutes. I've published 6 papers this year and am more productive than ever." +The creator automatically decides the right architecture based on scope: -**Agent Created**: Climate Research Analysis System +### Simple Skill + +For focused, single-domain tasks (e.g., "analyze CSV files", "extract text from PDFs"). + +``` +stock-analyzer/ + SKILL.md # Under 500 lines, spec-compliant + scripts/ + analyze.py + fetch_data.py + references/ + api-guide.md + assets/ + report-template.html + install.sh + README.md +``` + +### Complex Suite + +For multi-domain workflows requiring coordinated agents (e.g., "full financial analysis pipeline with data collection, analysis, and reporting"). + +``` +financial-analysis-suite/ + SKILL.md # Suite orchestrator, under 500 lines + scripts/ + orchestrator.py + data_collector.py + analyzer.py + report_generator.py + references/ + architecture-guide.md + api-reference.md + assets/ + templates/ + schemas/ + install.sh + README.md +``` + +For detailed architecture guidance, see [references/architecture-guide.md](references/architecture-guide.md). --- -### **🛍️ Alex - E-commerce Manager** -**Before:** "Manual product data analysis took 8 hours weekly. I couldn't react quickly to market trends." +## Generated Skill Format -**After:** "My e-commerce analytics agent gives me daily insights in 5 minutes. I've increased sales by 25% through faster trend response." +Every generated skill follows the Agent Skills Open Standard structure: -**Agent Created:** E-commerce Intelligence Suite +``` +skill-name/ + SKILL.md # Main skill file (<500 lines, spec-compliant) + scripts/ # Functional Python code + references/ # Detailed documentation (progressive disclosure) + assets/ # Templates, schemas, config files + install.sh # Cross-platform installer + README.md # Multi-platform install instructions +``` + +### SKILL.md Structure + +The generated SKILL.md includes standard frontmatter: + +```yaml +--- +name: skill-name +description: >- + Concise description of what the skill does (<=1024 chars). + Includes activation trigger phrases. +license: MIT +metadata: + author: Your Name + version: 1.0.0 +compatibility: >- + Works on Claude Code, GitHub Copilot, Cursor, Windsurf, + Cline, Codex CLI, Gemini CLI. +--- +``` + +Followed by sections: When to Use, Overview, Workflow, Implementation Guidelines, and References. --- -## 🧠 **v2.1: Intelligence That Learns** +## Naming Convention -### **The "Magic" Behind the Scenes** -Your agents get smarter automatically, without you doing anything extra: +Skills follow the **Agent Skills Open Standard** naming rules: -#### **📊 Week 1: First-Time Use** -- Agent works perfectly from day one -- Standard functionality you expect -- No learning curve +- **Format**: `kebab-case` (lowercase letters and hyphens only) +- **Length**: 1-64 characters +- **Pattern**: `^[a-z][a-z0-9-]*[a-z0-9]$` +- **No special suffixes** required -#### **📈 After 10 Uses: "The Speed Boost"** -- **40% faster creation** time -- Better API selections based on historical success -- Proven architectural patterns -- You notice: "⚡ Optimized based on similar successful agents" +### Examples -#### **🌟 After 30 Days: "Personal Intelligence"** -- **Personalized suggestions** based on your patterns -- **Predictive insights** about what you'll need -- **Custom optimizations** for your workflow -- You see: "🌟 I notice you prefer comprehensive analysis - shall I include portfolio optimization?" - -### **How Learning Works (Invisible to You):** -- 🧠 **Every creation** is stored as a learning episode -- ⚡ **Success patterns** are identified and reused -- 🎯 **Failures** teach what to avoid -- 🔄 **Continuous improvement** happens automatically - -### **Works Everywhere** -- ✅ **With AgentDB**: Full learning and intelligence -- ✅ **Without AgentDB**: Works perfectly, no learning -- ✅ **Partial AgentDB**: Smart hybrid mode +| Good | Bad | +|------|-----| +| `stock-analyzer` | `Stock_Analyzer` | +| `csv-data-cleaner` | `csv_data_cleaner` | +| `financial-analysis-suite` | `FinancialAnalysis` | +| `weather-alerts` | `weather-alerts-cskill` | --- -## 📚 **Complete Guide: From Novice to Expert** +## Validation and Security -### **🎯 Quick Start: Templates (Fastest Results)** +### Validate a Skill + +Check that a generated skill is compliant with the Agent Skills Open Standard: -#### **Financial Analysis (15-20 minutes)** ```bash -"Create financial analysis agent using financial-analysis template" -``` -**Perfect for**: Stock analysis, portfolio management, market research - -#### **Climate Analysis (20-25 minutes)** -```bash -"Create climate analysis agent using climate-analysis template for temperature anomalies" -``` -**Perfect for**: Environmental research, weather analysis, climate studies - -#### **E-commerce Analytics (25-30 minutes)** -```bash -"Create e-commerce analytics agent using e-commerce-analytics template" -``` -**Perfect for**: Sales tracking, customer analysis, inventory optimization - -### **🏗️ Custom Creation (Total Flexibility)** - -#### **Single Agent Creation** -```bash -"Create an agent for [your specific workflow]" -"Automate this process: [describe your repetitive task]" +python3 scripts/validate.py ./my-skill/ ``` -#### **Multi-Agent Suites (Advanced)** +Validates: +- SKILL.md exists and has valid frontmatter +- Name follows kebab-case convention (1-64 chars) +- Description is under 1024 characters +- SKILL.md is under 500 lines +- Required directory structure is present +- install.sh exists and is executable + +### Security Scan + +Scan for common security issues before sharing or deploying: + ```bash -"Create a financial analysis system with 4 agents: -fundamental analysis, technical analysis, -portfolio management, and risk assessment" +python3 scripts/security_scan.py ./my-skill/ ``` -#### **From Documentation/Transcripts** +Detects: +- Hardcoded API keys, tokens, and secrets +- Potential command injection patterns +- Unsafe file operations +- Credential exposure in configuration files + +--- + +## Cross-Platform Export + +Export skills for different deployment targets: + +### Desktop/Web Export + +Generates a `.zip` archive suitable for sharing or manual installation: + ```bash -"Here's a YouTube transcript about building BI systems, -create agents for all workflows described" +python3 scripts/export_utils.py ./my-skill/ --variant desktop +``` + +### API Export + +Generates a package suitable for Claude API integration: + +```bash +python3 scripts/export_utils.py ./my-skill/ --variant api +``` + +For full export documentation, see [references/export-guide.md](references/export-guide.md). + +--- + +## Example Skill + +The repository includes a complete example skill: + +### article-to-prototype + +Converts academic articles and research papers into functional prototypes. Demonstrates the full skill structure including scripts, references, and cross-platform installer. + +``` +article-to-prototype/ + SKILL.md + scripts/ + article_processor.py + prototype_generator.py + validation_engine.py + references/ + methodology.md + supported-formats.md + assets/ + prototype-templates/ + install.sh + README.md +``` + +See [article-to-prototype/](article-to-prototype/) for the full example. + +--- + +## Project Structure + +The agent-skill-creator repository itself: + +``` +agent-skill-creator/ + SKILL.md # Meta-skill definition (this skill's spec) + README.md # This file + MIGRATION.md # v3.x to v4.0 migration guide + .gitignore + scripts/ + validate.py # Spec compliance validator + security_scan.py # Security scanner + export_utils.py # Cross-platform export tool + install-template.sh # Template for generated install.sh + references/ + pipeline-phases.md # Full 5-phase pipeline docs + architecture-guide.md # Simple skill vs. complex suite + cross-platform-guide.md # Platform-specific details + export-guide.md # Export system documentation + phase1-discovery.md # Phase 1 deep dive + phase2-design.md # Phase 2 deep dive + phase3-architecture.md # Phase 3 deep dive + phase4-detection.md # Phase 4 deep dive + phase5-implementation.md # Phase 5 deep dive + phase6-testing.md # Testing guide + quality-standards.md # Quality standards reference + templates-guide.md # Template system guide + templates/ # Skill templates + tools/ # Validation and scanning tools + examples/ # Example configurations + integrations/ + agentdb_bridge.py # AgentDB integration bridge + agentdb_real_integration.py + fallback_system.py # Graceful degradation system + learning_feedback.py # Learning loop integration + validation_system.py # Integration validation + article-to-prototype/ # Example generated skill + exports/ # Export output directory + docs/ # Additional documentation + CHANGELOG.md # Version history + NAMING_CONVENTIONS.md # Naming rules reference + PIPELINE_ARCHITECTURE.md # Pipeline internals + DECISION_LOGIC.md # Architecture decision logic + CLAUDE_SKILLS_ARCHITECTURE.md ``` --- -## 🔧 **Deep Dive: Understanding the Technology** +## Activation Triggers -### **🤖 The 5-Phase Creation Process** +The skill creator activates when it detects phrases like: -**Phase 1: Discovery** (🔍 Research) -- Identifies best APIs for your domain -- Compares options automatically -- Makes mathematically validated decisions +- "Create an agent for ..." +- "Create a skill for ..." +- "Automate this workflow" +- "Every day I have to ..." +- "I need to automate ..." +- "Create a cross-platform skill for ..." +- "Validate this skill" +- "Export this skill for [platform]" +- "Migrate this skill to v4" -**Phase 2: Design** (🎨 Strategy) -- Defines meaningful analyses -- Specifies methodologies -- Plans user interactions - -**Phase 3: Architecture** (🏗️ Structure) -- Creates optimal folder structure -- Designs scripts and utilities -- Plans performance optimization - -**Phase 4: Detection** (🎯 Activation) -- Determines when agent should activate -- Creates keyword recognition -- Writes optimized descriptions - -**Phase 5: Implementation** (⚙️ Code) -- Writes functional Python code (no TODOs!) -- Creates comprehensive documentation -- Tests installation and functionality - -### **🔒 Production-Ready Quality** - -Every agent created includes: -- ✅ **Complete Code**: 1,500-2,000 lines of production-ready Python -- ✅ **Comprehensive Docs**: 10,000+ words of documentation -- ✅ **Error Handling**: Robust error recovery and retry logic -- ✅ **Type Hints**: Professional code standards -- ✅ **Input Validation**: Parameter checking and sanitization -- ✅ **Testing**: Built-in test suites and validation -- ✅ **Installation**: One-command installation ready +See [references/phase4-detection.md](references/phase4-detection.md) for the full activation pattern reference. --- -## 💡 **Advanced Features & Capabilities** +## AgentDB Integration (Optional) -### **🎮 Interactive Configuration** -```bash -"Help me create an agent with interactive options" -"I want to use the configuration wizard" -"Walk me through creating a financial analysis system" -``` -**Step-by-step guidance** with real-time preview and refinement. +Skills can optionally integrate with AgentDB for persistent learning across sessions: -### **📝 Batch Agent Creation** -```bash -"Create agents for traffic analysis, revenue tracking, -and customer analytics for e-commerce" -``` -**Complete suite** with shared infrastructure and data flow. +- **Learning feedback**: Skills improve based on usage patterns +- **Cross-session memory**: Retain context between conversations +- **Performance metrics**: Track skill effectiveness over time -### **🎭 Transcript Intelligence** -```bash -"Here's a transcript about building automated workflows, -create agents for all processes described" -``` -**Automatic workflow extraction** from YouTube videos and documentation. - -### **🌊 Template System** -Pre-built, battle-tested templates for common domains: -- **Financial Analysis**: Stocks, portfolios, market data -- **Climate Analysis**: Weather, environmental data, anomalies -- **E-commerce**: Sales, inventory, customer analytics -- **Agriculture**: Crop data, yields, weather integration -- **Research**: Literature review, data collection, analysis - -### **📦 Cross-Platform Export (NEW v3.2)** - -**Make your skills work everywhere:** - -Skills created in Claude Code can be exported for all Claude platforms: - -```bash -# Automatic (opt-in after creation) -✅ Skill created: financial-analysis-cskill/ - -📦 Export Options: - 1. Desktop/Web (.zip for manual upload) - 2. API (.zip for programmatic use) - 3. Both (comprehensive package) - 4. Skip (Claude Code only) - -# On-demand export anytime -"Export stock-analyzer for Desktop and API" -"Package my-skill for claude.ai with version 2.0.1" -``` - -**Platform Support:** -- ✅ **Claude Code** - Native (no export needed) -- ✅ **Claude Desktop** - .zip upload (Desktop package) -- ✅ **claude.ai** (Web) - .zip upload (Desktop package) -- ✅ **Claude API** - Programmatic integration (API package) - -**Key Features:** -- **Opt-in**: Choose to export after creation or skip -- **Two Variants**: Desktop (full docs, 2-5 MB) and API (optimized, < 8MB) -- **Versioned**: Auto-detect from git tags or SKILL.md, or specify manually -- **Validated**: Automatic checks for size, structure, and compatibility -- **Guided**: Auto-generated installation instructions for each platform - -**Export Output:** -``` -exports/ -├── skill-name-desktop-v1.0.0.zip # For Desktop/Web -├── skill-name-api-v1.0.0.zip # For API -└── skill-name-v1.0.0_INSTALL.md # Installation guide -``` - -**Learn More:** -- **Export Guide**: `references/export-guide.md` -- **Cross-Platform Guide**: `references/cross-platform-guide.md` +AgentDB is not required. Skills work fully without it. See [references/agentdb-integration.md](references/agentdb-integration.md) for setup details. --- -## 📈 **Success Stories & Case Studies** +## Migration from v3.x -### **🏢 Small Business Transformation** -**Company**: Local Restaurant Chain (3 locations) +If you have skills created with v3.x of agent-skill-creator: -**Challenge**: Manual inventory and sales tracking across multiple locations, taking 4 hours daily. +**Key changes in v4.0:** +- `-cskill` suffix removed from skill names (use standard kebab-case) +- `marketplace.json` simplified (optional for simple skills) +- SKILL.md body limited to 500 lines (move detail to `references/`) +- `install.sh` cross-platform installer added +- Spec validation and security scanning tools added -**Solution**: Multi-agent system with: -- Inventory Management Agent (real-time stock tracking) -- Sales Analytics Agent (daily reports and insights) -- Customer Data Agent (CRM integration) -- Financial Reporting Agent (P&L and cash flow) +**Quick migration:** +```bash +# Rename directory (remove -cskill suffix) +mv my-skill-cskill/ my-skill/ -**Results**: -- ⏰ **Time Saved**: 120 hours/month (4 hours/day × 30 days) -- 💰 **ROI**: $8,400/month saved (based on $70/hour consultant rate) -- 📈 **Revenue Increase**: 15% from better data-driven decisions -- 😊 **Employee Satisfaction**: 40% reduction in manual work complaints +# Update SKILL.md name field +# Validate the migrated skill +python3 scripts/validate.py ./my-skill/ +``` + +For the complete migration guide, see [MIGRATION.md](MIGRATION.md). --- -### **💹 Financial Services Automation** -**Company**: Investment Advisory Firm +## Advanced Features -**Challenge**: Manual market analysis and portfolio rebalancing taking 6 hours daily. +### Interactive Mode -**Solution**: Advanced financial system: -- Market Data Agent (real-time data from multiple APIs) -- Technical Analysis Agent (RSI, MACD, Bollinger Bands) -- Portfolio Optimization Agent (modern portfolio theory) -- Risk Assessment Agent (VaR, stress testing, compliance) +For complex skills, the creator can run in interactive mode, asking clarifying questions before generating: -**Results**: -- ⏰ **Analysis Time**: 6 hours → 20 minutes (95% reduction) -- 💰 **Clients Managed**: 20 → 50 (150% increase) -- 📊 **Accuracy**: 25% improvement in risk-adjusted returns -- 🏆 **Competitive Advantage**: Faster market response time +``` +"Create a skill for financial analysis" (interactive) +``` + +See [references/interactive-mode.md](references/interactive-mode.md). + +### Multi-Agent Suites + +Create coordinated multi-agent systems where specialized agents collaborate: + +``` +"Create a multi-agent suite for end-to-end data pipeline" +``` + +See [references/multi-agent-guide.md](references/multi-agent-guide.md). + +### Template-Based Creation + +Use pre-built templates to accelerate skill creation: + +``` +"Create a skill from the data-analysis template" +``` + +See [references/templates-guide.md](references/templates-guide.md). --- -### **🔬 Research Acceleration** -**Organization**: University Climate Research Lab +## Contributing -**Challenge**: Literature review and data analysis taking weeks per study. - -**Solution**: Research automation system: -- Literature Search Agent (academic databases, citations) -- Data Collection Agent (climate APIs, government data) -- Analysis Agent (statistical modeling, visualization) -- Report Generation Agent (academic formatting, citations) - -**Results**: -- 📚 **Studies Published**: 2 → 6 per year (200% increase) -- ⏰ **Research Time**: 3 weeks → 3 days (93% reduction) -- 🌍 **Global Coverage**: Data from 150+ countries -- 📊 **Impact Factor**: 40% increase in paper citations +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/my-feature`) +3. Make your changes +4. Run validation: `python3 scripts/validate.py ./` +5. Run security scan: `python3 scripts/security_scan.py ./` +6. Submit a pull request --- -## 🔧 **Installation & Setup** +## License -### **📋 Prerequisites** -- ✅ Claude Code CLI installed -- ✅ Python 3.8+ (for agents that will be created) -- ✅ Internet connection (for research phase) -- 🔧 **Optional**: AgentDB CLI for enhanced learning features (automatically installed if missing) - -### **⚡ Quick Installation** -```bash -# Step 1: Install in Claude Code -/plugin marketplace add FrancyJGLisboa/agent-skill-creator - -# Step 2: Verify installation -/plugin list -# Should show: ✓ agent-creator - -# Step 3: Start creating agents! -"Create an agent for [your workflow]" -``` - -### **🚀 AgentDB Enhanced Installation (Recommended)** - -For the latest version with **invisible intelligence enhancement** and **progressive learning**: - -**Final Installation Commands:** - -Now you can complete the installation in your Claude Code with these commands: - -```bash -# 1. Remove the old marketplace entry (if it exists) -/plugin marketplace remove agent-creator-en - -# 2. Install the AgentDB enhanced version from the current directory -/plugin marketplace add ./ - -# 3. Verify the installation -/plugin list -``` - -**📋 What to Expect During Installation:** - -When you run `/plugin marketplace add ./`, you should see: - -```bash -✓ Added agent-creator-enhanced from /path/to/agent-skill-creator -📦 Installing dependencies... -✓ Dependencies installed successfully -🧠 AgentDB integration initialized -✓ Enhanced features activated -``` - -**🔧 Dependency Installation:** - -The enhanced version may require additional dependencies. If prompted: - -```bash -# Install Python dependencies (if required) -pip install requests beautifulsoup4 pandas numpy - -# Install AgentDB CLI (if not already installed) -npm install -g @anthropic-ai/agentdb -``` - -**Expected `/plugin list` Output:** - -After successful installation, you should see: - -```bash -Installed Plugins: -✓ agent-creator-enhanced (v2.1) - AgentDB Enhanced Agent Creator - Features: invisible-intelligence, progressive-learning, mathematical-validation - Status: Active | AgentDB: Connected | Learning: Enabled -``` - -**✅ Installation Verification:** - -Run these verification commands: - -```bash -# Check plugin status -/plugin list -# Should show agent-creator-enhanced with AgentDB features - -# Test AgentDB connection (if available) -agentdb db stats -# Should show database statistics or graceful fallback message - -# Verify enhanced features work -"Create financial analysis agent for stock market data" -``` - -**Test Your Enhanced Agent Creator:** - -Once installed, test it with a simple command: - -```bash -"Create financial analysis agent for stock market data" -``` - -**Expected First-Time Behavior:** - -```bash -🧠 AgentDB Bridge: Auto-configuring invisible intelligence... -✓ AgentDB initialized successfully (invisible mode) -🔍 Researching financial APIs and best practices... -📊 Mathematical validation: 95% confidence for template selection -✅ Enhanced agent creation completed with progressive learning -🎯 Agent ready: financial-analysis-agent/ -``` - -**🛠️ Troubleshooting Common Issues:** - -**Issue 1: AgentDB not found** -```bash -# Solution: Install AgentDB CLI -npm install -g @anthropic-ai/agentdb -# The system will work in fallback mode until AgentDB is available -``` - -**Issue 2: Python dependencies missing** -```bash -# Solution: Install required packages -pip install requests beautifulsoup4 pandas numpy -``` - -**Issue 3: Plugin installation fails** -```bash -# Solution: Check directory and permissions -pwd # Should be in agent-skill-creator directory -ls -la # Should see SKILL.md and other files -``` - -**Issue 4: AgentDB connection errors** -```bash -# Normal behavior - system falls back gracefully -# The enhanced features work offline too! -# AgentDB will auto-connect when available -``` - -**🎯 What Enhanced Features You'll Experience:** - -- **🧠 Invisible Intelligence**: Automatic enhancement happens silently -- **📈 Progressive Learning**: Each use makes the system smarter -- **🧮 Mathematical Validation**: 95% confidence proofs for decisions -- **🛡️ Graceful Fallback**: Works perfectly even offline -- **👤 Dead Simple Experience**: Same easy commands, more power - -**🎯 What You Get with AgentDB Enhanced:** -- 🧠 **Invisible Intelligence**: Automatic enhancement without complexity -- 📈 **Progressive Learning**: Gets smarter with each use -- 🧮 **Mathematical Validation**: 95% confidence proofs for decisions -- 🛡️ **Graceful Fallback**: Works perfectly even offline -- 👤 **Dead Simple Experience**: Same easy interface, more power - -### **✅ Installation Success Checklist** - -Verify your installation is working correctly: - -**[ ] Plugin Installation** -```bash -/plugin list -# ✓ Should show: agent-creator-enhanced (v2.1) -``` - -**[ ] AgentDB Connection (Optional)** -```bash -agentdb db stats -# ✓ Should show database stats OR graceful fallback message -``` - -**[ ] Basic Functionality Test** -```bash -"Create simple test agent" -# ✓ Should create agent without errors -``` - -**[ ] Enhanced Features Test** -```bash -"Create financial analysis agent for stock market data" -# ✓ Should show AgentDB enhancement messages -# ✓ Should provide confidence scores and validation -``` - -**[ ] Progressive Learning Verification** -```bash -# Create 2-3 agents in the same domain -# Notice improved confidence and better recommendations -``` - -**[ ] Fallback Mode Test** -```bash -# Temporarily disable AgentDB (if installed) -# System should still work with fallback intelligence -``` - -### **📊 Expected Performance Improvements** - -After successful installation, you should experience: - -| Feature | Before AgentDB | After AgentDB Enhanced | -|---------|----------------|------------------------| -| **Agent Creation Speed** | Standard | Faster with learned patterns | -| **Template Selection** | Basic matching | 95% confidence validation | -| **Quality Assurance** | Manual checks | Mathematical proofs | -| **Learning Capability** | None | Progressive improvement | -| **Reliability** | Standard | Enhanced with fallbacks | -| **User Experience** | Simple | Same simplicity, more power | - -### **🔍 Monitoring Your Enhanced Agent Creator** - -**Check Learning Progress:** -```bash -# After several uses, check AgentDB stats -agentdb db stats -# Look for increasing episodes and skills count -``` - -**Verify Progressive Enhancement:** -```bash -# Create similar agents over time -# Notice confidence scores improving -# Experience better template recommendations -``` - -**System Health Indicators:** -```bash -# AgentDB should show: -- Increasing episode count (learning from usage) -- Growing skills library (pattern recognition) -- Active causal edges (decision improvement) - -# System should always respond, even offline -# Enhanced features work in all environments -``` - -### **🛠️ Agent Installation (After Creation)** -```bash -# Navigate to created agent directory -cd ./your-agent-name/ - -# Install dependencies (if required) -pip install -r requirements.txt - -# Install agent in Claude Code -/plugin marketplace add ./your-agent-name - -# Start using your agent! -"[Ask questions in your agent's domain]" -``` +MIT License. See [LICENSE](LICENSE) for details. --- -## 🎯 **Usage Examples: Real-World Applications** - -### **💰 Finance & Investment** -```bash -# Stock Analysis -"Create agent for stock technical analysis with RSI, MACD, and Bollinger Bands" - -# Portfolio Management -"Build portfolio optimization agent with modern portfolio theory and risk assessment" - -# Market Research -"Automate market research - analyze competitors, track trends, generate insights" -``` - -### **🏪 E-commerce & Retail** -```bash -# Sales Analytics -"Create e-commerce analytics agent - track sales, customer behavior, inventory optimization" - -# Price Optimization -"Build agent for dynamic pricing based on demand, competition, and inventory" - -# Customer Insights -"Automate customer analysis - segment users, predict churn, personalize offers" -``` - -### **🌾 Agriculture & Environment** -```bash -# Crop Monitoring -"Create agriculture agent - monitor crop yields, weather, soil conditions, predict harvests" - -# Environmental Analysis -"Build climate analysis agent - track temperature anomalies, environmental impact assessment" - -# Resource Management -"Automate resource planning - water usage, fertilizer optimization, sustainability metrics" -``` - -### **🔬 Research & Academia** -```bash -# Literature Review -"Create research agent - search academic databases, summarize papers, manage citations" - -# Data Analysis -"Build data analysis agent - statistical analysis, visualization, report generation" - -# Survey Research -"Automate survey research - collect responses, analyze trends, generate insights" -``` - -### **🏥 Healthcare & Wellness** -```bash -# Patient Data Analysis -"Create healthcare analytics agent - patient outcomes, treatment effectiveness, trend analysis" - -# Medical Research -"Build medical research agent - clinical trial data, literature review, statistical analysis" - -# Wellness Tracking -"Automate wellness monitoring - health metrics, lifestyle analysis, recommendations" -``` - ---- - -## 🧠 **Understanding v2.1: Intelligent Learning** - -### **🎯 What Makes v2.1 Revolutionary** - -**Traditional Tools**: Static code that never improves -**Agent Creator v2.1**: Living agents that learn and evolve - -### **📊 Learning Timeline** - -#### **Day 1: First Agent Creation** -``` -You: "Create financial analysis agent" -→ Standard creation process (60 minutes) -→ Agent works perfectly -→ No visible difference -``` - -#### **Week 1: After 10 Uses** -``` -You: "Create financial analysis agent" -→ 40% faster creation (36 minutes) -→ Better API selection based on success history -→ You see: "⚡ Optimized based on 10 successful similar agents" -``` - -#### **Month 1: Progressive Intelligence** -``` -You: "Create financial analysis agent" -→ Personalized based on your patterns -→ Includes features you didn't explicitly ask for -→ You see: "🌟 I notice you prefer comprehensive analysis - shall I include portfolio optimization?" -``` - -#### **Year 1: Collective Intelligence** -``` -You: "Create financial analysis agent" -→ Benefits from hundreds of successful patterns -→ Industry best practices automatically incorporated -→ You see: "🚀 Enhanced with insights from 500+ successful financial agents" -``` - -### **🔍 How Learning Works (Invisible to You)** - -#### **1. Episode Storage** -Every agent creation is stored as a learning episode: -- What was requested (user input) -- What was created (output quality) -- What worked well (success factors) -- What could be better (improvement opportunities) - -#### **2. Pattern Recognition** -- **Success Patterns**: Identifies what makes agents successful -- **Failure Patterns**: Learns what to avoid -- **User Patterns**: Understands your preferences -- **Domain Patterns**: Builds industry-specific knowledge - -#### **3. Intelligent Enhancement** -- **Template Selection**: Chooses best patterns for your domain -- **API Selection**: Prioritizes historically successful APIs -- **Architecture Decisions**: Uses proven structures -- **Feature Enhancement**: Suggests capabilities you'll need - -### **🎪 The Magic User Experience** - -#### **You Always Get:** -- ✅ **Perfect agents** from day one -- ✅ **Zero learning curve** or setup required -- ✅ **Same simple commands** you already use -- ✅ **Works perfectly** even without AgentDB - -#### **You Gradually Get:** -- ⚡ **Faster creation** (learned optimization) -- 🎯 **Better results** (proven patterns) -- 🌟 **Personalization** (your preferences) -- 🚀 **Advanced features** (industry insights) - ---- - -## 🔧 **Advanced Usage & Customization** - -### **🎨 Custom Template Creation** - -Create your own templates for specialized domains: - -```bash -# Step 1: Create template -"Create template for [your domain] with [key features]" - -# Step 2: Use template repeatedly -"Create agent using [your-template-name] template for [specific need]" -``` - -### **🏗️ Multi-Agent Architecture** - -Build sophisticated agent ecosystems: - -```bash -# Financial Services Ecosystem -"Create financial platform with agents for: -- Market data analysis (real-time prices, news sentiment) -- Portfolio management (rebalancing, risk metrics) -- Trading signals (technical indicators, alerts) -- Regulatory compliance (reporting, monitoring) -- Customer onboarding (KYC, documentation)" -``` - -### **📊 Integration with Existing Systems** - -Connect agents with your current tools: - -```bash -# Integration with Google Sheets -"Create agent that pulls data from our Google Sheets, -analyzes trends, and pushes insights back" - -# Integration with databases -"Build agent that connects to PostgreSQL, -runs complex queries, generates dashboards" - -# Integration with APIs -"Create agent that integrates with Salesforce, -automates lead scoring, updates opportunities" -``` - ---- - -## 📊 **Performance & Quality Metrics** - -### **⚡ Speed Metrics** -| Agent Type | Creation Time | Lines of Code | Documentation | Quality Score | -|------------|---------------|--------------|--------------|--------------| -| **Simple** | 15-30 min | 800-1,200 | 5,000 words | 9.2/10 | -| **Template-based** | 10-20 min | 1,000-1,500 | 6,000 words | 9.5/10 | -| **Custom** | 45-90 min | 1,500-2,500 | 8,000 words | 9.0/10 | -| **Multi-agent** | 60-120 min | 3,000-6,000 | 15,000 words | 9.3/10 | - -### **🎯 Quality Standards** -Every agent includes: -- ✅ **100% Functional Code**: No TODOs, no placeholder text -- ✅ **Production Ready**: Error handling, logging, validation -- ✅ **Professional Documentation**: Usage examples, troubleshooting -- ✅ **Installation Ready**: One-command setup and testing -- ✅ **Type Safety**: Modern Python with type hints -- ✅ **Testing Framework**: Built-in validation and examples - -### **📈 Success Metrics** -- ✅ **95%+ Success Rate**: Agents work as specified -- ✅ **90%+ User Satisfaction**: High-quality, reliable automation -- ✅ **85%+ Time Savings**: Significant reduction in manual work -- ✅ **100% Backward Compatible**: Works with existing Claude Code - ---- - -## 🛠️ **Technical Architecture** - -### **🧩 Core Components** -``` -Agent Creator v2.1 -├── 📋 Discovery Engine -│ ├── API Research (WebSearch, WebFetch) -│ ├── Option Comparison (automated analysis) -│ └── Decision Engine (mathematical validation) -├── 🎨 Design System -│ ├── Use Case Analysis (pattern recognition) -│ ├── Methodology Specification (best practices) -│ └── User Interaction Design (intuitive interfaces) -├── 🏗️ Architecture Generator -│ ├── Structure Planning (optimal organization) -│ ├── Script Generation (functional code) -│ └── Performance Optimization (caching, validation) -├── 🎯 Detection Engine -│ ├── Keyword Analysis (activation patterns) -│ ├── Description Generation (marketplace.json) -│ └── Intent Recognition (user intent mapping) -├── ⚙️ Implementation Engine -│ ├── Code Generation (Python, configurations) -│ ├── Documentation Writing (comprehensive guides) -│ ├── Testing Framework (validation, examples) -│ └── Package Generation (installation ready) -└── 🧠 Intelligence Layer (v2.1) - ├── AgentDB Integration (learning memory) - ├── Pattern Recognition (success identification) - ├── Progressive Enhancement (continuous improvement) - └── Personalization Engine (user preferences) -``` - -### **🔧 Integration Architecture** -``` -User Input - ↓ -Agent Creator v2.1 - ↓ -┌─────────────────┐ ┌──────────────────┐ -│ Claude Code │ │ AgentDB │ -│ (Execution) │ │ (Learning) │ -└─────────────────┘ └──────────────────┘ - ↓ ↓ -Enhanced Decision Making Pattern Storage - ↓ ↓ -Intelligent Agent ← Learned Patterns -``` - -### **📦 Package Structure** -``` -agent-name/ -├── .claude-plugin/ -│ └── marketplace.json ← Claude Code integration -├── SKILL.md ← Complete agent orchestration -├── scripts/ -│ ├── fetch_data.py ← API clients and data sources -│ ├── analyze_data.py ← Business logic and analytics -│ ├── utils/ -│ │ ├── cache_manager.py ← Performance optimization -│ │ ├── validators.py ← Data quality assurance -│ │ └── helpers.py ← Common utilities -├── tests/ -│ ├── test_*.py ← Functional tests -│ └── examples/ ← Usage examples -├── references/ -│ ├── api-guide.md ← API documentation -│ ├── analysis-methods.md ← Methodology explanations -│ └── troubleshooting.md ← Problem solving -├── assets/ -│ ├── config.json ← Runtime configuration -│ └── metadata.json ← Agent metadata -├── requirements.txt ← Python dependencies -├── DECISIONS.md ← Decision justification -└── README.md ← User guide and documentation -``` - ---- - -## 🔍 **Troubleshooting & Support** - -### **❓ Common Questions** - -#### **Q: How is this different from ChatGPT or other AI tools?** -**A:** Agent Creator creates complete, production-ready code that you can install and use independently. ChatGPT gives you code snippets you need to implement yourself. - -#### **Q: Do I need programming skills?** -**A:** No! That's the whole point. Just describe what you do, and Agent Creator handles all the technical implementation. - -#### **Q: Can agents connect to my existing systems?** -**A:** Yes! Agents can integrate with APIs, databases, Google Sheets, and most business systems. - -#### **Q: How secure are the created agents?** -**A:** Very secure. Agents use proper authentication, input validation, and follow security best practices. - -#### **Q: Can I modify agents after creation?** -**A:** Absolutely! Agents are fully customizable. You can modify them, extend them, or combine them. - -#### **Q: What if the agent doesn't work as expected?** -**A:** Comprehensive documentation and troubleshooting guides are included. Plus, v2.1 learns from issues to improve future agents. - -### **🚨 Installation Issues** - -#### **Error: "Repository not found"** -```bash -❌ /plugin marketplace add FrancyJGLisboa/agent-skill-creator -✅ /plugin marketplace add FrancyJGLisboa/agent-skill-creator -# Note: Repository name is agent-skill-creator (not agent-creator) -``` - -#### **Error: "Permission denied"** -- Verify you have internet connection -- Check GitHub access permissions -- Try again in a few minutes - -#### **Error: "Module not found"** -- Ensure Claude Code is updated -- Restart Claude Code and try again -- Check Python installation - -### **🛠️ Advanced Troubleshooting** - -#### **Agent Creation Issues** -```bash -# Check Claude Code version -/claude version - -# Check installed plugins -/plugin list - -# Test basic functionality -"Hello! Test agent creation capability" -``` - -#### **Performance Issues** -- Check system resources (memory, CPU) -- Reduce agent complexity if needed -- Consider using templates for faster creation - -#### **API Integration Problems** -- Verify API keys are properly set -- Check API rate limits and quotas -- Test API connectivity independently - -### **📞 Getting Help** - -#### **Documentation Resources** -- [SKILL.md](./SKILL.md) - Complete technical guide -- [templates/](./templates/) - Template documentation -- [integrations/](./integrations/) - Integration guides - -#### **Community Support** -- **GitHub Issues**: Report bugs and request features -- **GitHub Discussions**: Ask questions and share experiences -- **Examples**: Share success stories and use cases - -#### **Professional Support** -- **Consulting**: Custom agent development -- **Training**: Team onboarding and best practices -- **Integration**: Complex system integration - ---- - -## 🎯 **Reliable Skill Activation System (v3.1)** - -### **What Makes Agent Creator Exceptionally Reliable?** - -Agent Creator v3.1 introduces an **Enhanced 4-Layer Activation System** that achieves **99.5%+ activation reliability** - ensuring your created skills activate when needed, and only when needed. - -### **The Problem We Solved** - -Previous versions using 3-Layer Detection achieved ~98% reliability: -- ❌ Skills still missed some valid user requests (false negatives) -- ❌ Context-inappropriate activations occurred (false positives) -- ❌ Complex multi-intent queries were not supported -- ❌ Natural language variations had limited coverage - -### **The Enhanced 4-Layer Solution** - -**Layer 1: Keywords** (Expanded Coverage - 50-80 keywords) -- High-precision activation for explicit requests -- **5 categories**: Core capabilities, Synonyms, Direct variations, Domain-specific, Natural language -- Example: "create an agent for", "automate workflow", "help me create", "I need to automate" - -**Layer 2: Patterns** (Enhanced Matching - 10-15 patterns) -- Captures complex natural language variations -- **Enhanced patterns** for workflow automation, technical operations, business processes -- Example: `(?i)(analyze|evaluate|research)\s+(and\s+)?(compare|track|monitor)\s+(data|information|metrics)\s+(for|of|in)` - -**Layer 3: Description + NLU** (Natural Language Understanding) -- Claude's understanding for edge cases -- 300-500 character description with 60+ keywords -- Fallback coverage for unexpected phrasings - -**Layer 4: Context-Aware Filtering** (NEW - Fase 1 Enhancement) -- **Context analysis**: Domain, task, intent, and conversation understanding -- **Negative filtering**: Prevents activation in inappropriate contexts -- **Relevance scoring**: Mathematical confidence validation for activation decisions - -### **Activation Phrases That Work** - -The Agent Creator skill activates reliably when you say: - -✅ **"Create an agent for [objective]"** -``` -"Create an agent for processing invoices" -"Create an agent for stock analysis" -``` - -✅ **"Automate workflow [description]"** -``` -"Automate workflow for daily reporting" -"Automate my data collection workflow" -``` - -✅ **"Every day I have to [task]"** -``` -"Every day I have to download and process CSV files" -"Daily I need to update spreadsheets manually" -``` - -✅ **"Create a skill for [domain]"** -``` -"Create a skill for technical stock analysis" -"Develop a skill for weather monitoring" -``` - -✅ **"Turn [process] into agent"** -``` -"Turn this manual process into an automated agent" -"Convert this workflow to an agent" -``` - -### **When Agent Creator Does NOT Activate** - -To prevent false positives, the skill will **not** activate for: - -❌ **General programming questions** -``` -"How do I write a for loop?" -"What's the difference between list and tuple?" -``` - -❌ **Using existing skills (not creating new ones)** -``` -"Run the invoice processor skill" -"Use the existing stock analysis agent" -``` - -❌ **Documentation questions** -``` -"How do skills work?" -"Explain what agents are" -``` - -### **Built-In Quality Assurance** - -Every skill created by Agent Creator v3.0 includes: - -✅ **Comprehensive Activation System** -- 10-15 keyword phrases -- 5-7 regex patterns -- Enhanced description with 60+ keywords -- `when_to_use` examples (5+) -- `when_not_to_use` counter-examples (3+) - -✅ **Complete Test Suite** -- 10+ test queries covering all activation layers -- Positive and negative test cases -- Documented expected activation layer for each query - -✅ **Documentation Package** -- README with activation examples -- Troubleshooting guide for activation issues -- Tips for reliable activation - -### **Multi-Intent Detection (NEW - Fase 1 Enhancement)** - -Agent Creator v3.1 now supports complex user queries with multiple intentions: - -**Example Multi-Intent Queries:** -- ✅ "Analyze stock performance, create visualizations, and save results to file" -- ✅ "Compare market data and explain the differences with technical analysis" -- ✅ "Monitor my portfolio in real-time and send alerts on significant changes" - -**Intent Hierarchy:** -- **Primary Intent**: Main goal (analyze, compare, monitor) -- **Secondary Intents**: Additional requirements (visualize, save, explain) -- **Contextual Intents**: Presentation preferences (quick summary, detailed analysis) -- **Meta Intents**: How to interact (teach me, help me decide) - -### **Activation Success Metrics** - -**Agent Creator v3.1:** -- Overall activation reliability: **99.5%** (+1.5% from v3.0) -- Layer 1 (Keywords): **100%** success rate -- Layer 2 (Patterns): **100%** success rate -- Layer 3 (Description): **95%** success rate (+5%) -- Layer 4 (Context): **98%** success rate (NEW) -- False positive rate: **<1%** (NEW - down from 2%) -- Multi-intent support: **95%** accuracy (NEW) - -**Skills Created by Agent Creator:** -- Target reliability: **99.5%+** (increased from 95%) -- Average achieved: **99.2%** (+3.2% improvement) -- Quality grade: **A+** (measured across 100+ test queries) -- Context precision: **85%** (NEW) -- Natural language coverage: **90%** (NEW) - -### **How This Benefits You** - -**For Skill Users:** -- 🎯 Skills activate when you need them -- 🚫 No accidental activations -- 💡 Natural language works reliably -- 📚 Clear documentation on activation phrases - -**For Skill Creators:** -- 📋 Templates with proven patterns -- 🧪 Complete testing methodology -- ✅ Quality checklist for 95%+ reliability -- 📖 Comprehensive guides and examples - -### **Learn More About Activation** - -**For Users:** -- See created skill READMEs for specific activation phrases -- Each skill includes 10+ example queries -- Troubleshooting sections help resolve activation issues - -**For Developers:** -- **Complete Guide**: `references/phase4-detection.md` (Enhanced 4-Layer Detection) -- **Pattern Library**: `references/activation-patterns-guide.md` (Enhanced v3.1 - 10-15 patterns) -- **Testing Guide**: `references/activation-testing-guide.md` (5-phase testing) -- **Quality Checklist**: `references/activation-quality-checklist.md` -- **Templates**: `references/templates/marketplace-robust-template.json` (Context-aware & Multi-intent) -- **Example**: `references/examples/stock-analyzer-cskill/` (65 keywords, 46 test queries) -- **NEW - Fase 1 Documentation**: - - `references/context-aware-activation.md` (Context filtering system) - - `references/multi-intent-detection.md` (Complex query handling) - - `references/synonym-expansion-system.md` (Keyword expansion methodology) - - `references/tools/activation-tester.md` (Automated testing framework) - - `references/tools/intent-analyzer.md` (Intent analysis toolkit) - - `references/claude-llm-protocols-guide.md` (Complete protocol documentation) - ---- - -## 📚 **Documentation & Learning Resources** - -### **📖 Complete Documentation** -- **[SKILL.md](./SKILL.md)** - Technical implementation guide (10,000+ words) -- **[CHANGELOG.md](docs/CHANGELOG.md)** - Version history and updates -- **[AGENTDB_ANALYSIS.md](./AGENTDB_ANALYSIS.md)** - Deep dive into AgentDB integration -- **[templates/](./templates/)** - Template-specific guides - -### **🎓 Learning Path** - -#### **🌱 Beginner (Day 1)** -1. Read this README -2. Install Agent Creator -3. Create your first agent using a template -4. Test basic functionality - -#### **🚀 Intermediate (Week 1)** -1. Try custom agent creation -2. Explore all template options -3. Learn to modify agents -4. Understand the 5-phase process - -#### **🎯 Advanced (Month 1)** -1. Create multi-agent systems -2. Integrate with external APIs -3. Customize templates -4. Optimize performance - -#### **🏆 Expert (Ongoing)** -1. Create custom templates -2. Build agent ecosystems -3. Contribute to Agent Creator -4. Master the integration system - -### **🎮 Interactive Learning** - -#### **🔧 Configuration Wizard** -```bash -"Help me create an agent with interactive options" -"Walk me through creating a financial analysis system" -"I want to use the configuration wizard" -``` - -#### **📝 Template Customization** -```bash -"Show me how to modify the financial analysis template" -"Help me understand the climate analysis template structure" -"Explain how to customize agent behaviors" -``` - -#### **🚀 Advanced Features** -```bash -"Create a multi-agent ecosystem for e-commerce" -"Build agents that communicate with each other" -"Design agents with machine learning capabilities" -``` - ---- - -## 🗺️ **Version History & Roadmap** - -### **📋 Current Version: v3.1 (October 2025)** - -#### **🆕 v3.1 Features (Fase 1 UX Improvements)** -- ✅ **Activation Test Automation**: Automated testing framework for 99.5%+ reliability -- ✅ **Context-Aware Activation**: 4-Layer detection with contextual filtering -- ✅ **Multi-Intent Detection**: Support for complex user queries with multiple goals -- ✅ **Synonym Expansion System**: 50-80 keywords per skill with natural language coverage -- ✅ **Enhanced Pattern Matching**: 10-15 patterns with semantic understanding -- ✅ **False Positive Reduction**: <1% false positive rate (down from 2%) -- ✅ **Protocol Documentation**: Complete Claude LLM creation protocols - -#### **📈 v2.1 Features (Previous)** -- ✅ **AgentDB Integration**: Invisible intelligence that learns from experience -- ✅ **Progressive Enhancement**: Agents get smarter over time -- ✅ **Mathematical Validation**: Proofs for all creation decisions -- ✅ **Graceful Fallback**: Works perfectly with or without AgentDB -- ✅ **Learning Feedback**: Subtle progress indicators -- ✅ **Template Enhancement**: Templates learn from collective usage - -#### **📈 v2.0 Features (Previous)** -- ✅ **Multi-Agent Architecture**: Create agent suites -- ✅ **Template System**: Pre-built templates for common domains -- ✅ **Interactive Configuration**: Step-by-step guidance -- ✅ **Transcript Processing**: Extract workflows from content -- ✅ **Batch Creation**: Multiple agents in one operation - -### **🚀 Roadmap: What's Coming** - -#### **v2.2 (Planned Q4 2025)** -- 🤖 **AI-Powered Template Generation**: Automatic template creation -- 🌐 **Cloud Integration**: Direct deployment to cloud platforms -- 📊 **Advanced Analytics**: Usage patterns and optimization suggestions -- 🔗 **Enhanced MCP Integration**: Native Claude Desktop support - -#### **v2.3 (Planned Q1 2026)** -- 🎯 **Industry Templates**: Specialized templates for healthcare, legal, education -- 🤝 **Team Collaboration**: Multi-user agent creation and sharing -- 📱 **Mobile Integration**: Agent deployment to mobile platforms -- 🔒 **Enterprise Features**: Advanced security and compliance - -#### **v3.0 (Planned Q2 2026)** -- 🌟 **Visual Agent Builder**: Drag-and-drop agent creation -- 🎭 **Natural Language Templates**: Describe templates in plain English -- 🔄 **Agent Marketplace**: Share and discover community agents -- 🏢 **Enterprise Edition**: Advanced features for large organizations - -### **📈 Version Statistics** -| Version | Release Date | Features | Users | Agents Created | Reliability | -|---------|-------------|----------|-------|----------------|------------| -| v1.0 | Oct 2025 | Basic agent creation | 100+ | 500+ | 95% | -| v2.0 | Oct 2025 | Templates, multi-agent, interactive | 300+ | 1,500+ | 98% | -| v2.1 | Oct 2025 | AgentDB integration, learning | 500+ | 3,000+ | 98% | -| v3.1 | Oct 2025 | **Fase 1 UX improvements** | 600+ | 4,000+ | **99.5%** | - -### **🚀 Fase 1 Performance Impact** - -| Metric | Before v3.1 | After v3.1 | Improvement | -|--------|-------------|-------------|------------| -| **Activation Reliability** | 98% | **99.5%** | +1.5% | -| **False Positive Rate** | 2% | **<1%** | -50%+ | -| **Keywords per Skill** | 15-20 | **50-80** | +200% | -| **Patterns per Skill** | 5-7 | **10-15** | +100% | -| **Multi-Intent Support** | 20% | **95%** | +375% | -| **Natural Language Coverage** | 60% | **90%** | +50% | -| **Context Precision** | 60% | **85%** | +42% | -| **Intent Accuracy** | 70% | **95%** | +25% | - ---- - -## 💡 **Best Practices & Tips** - -### **🎯 Agent Creation Best Practices** - -#### **📝 Clear Requirements** -- **Be Specific**: "Analyze stock market data for AAPL, MSFT, GOOG" vs "Analyze stocks" -- **Define Success**: "Generate daily reports with charts" vs "Create reports" -- **Include Context**: "For investment decisions" vs "For fun" - -#### **🔍 Research First** -- Check if templates exist for your domain -- Look at similar agent examples -- Understand API availability and limitations - -#### **🏗️ Start Simple** -- Begin with basic functionality -- Add complexity gradually -- Test at each stage - -#### **📚 Document Everything** -- Clear descriptions of what agents do -- Examples of usage -- Troubleshooting common issues - -### **⚡ Performance Optimization** - -#### **🎯 Template Usage** -- Templates are 80% faster than custom creation -- Start with templates when possible -- Customize as needed - -#### **💾 Data Management** -- Use appropriate caching strategies -- Consider API rate limits -- Plan for data growth - -#### **🔄 Iterative Improvement** -- Start with minimum viable agent -- Add features based on usage -- Monitor performance and user feedback - -### **🔒 Security Best Practices** - -#### **🔑 API Key Management** -- Store API keys securely (environment variables) -- Never commit API keys to repositories -- Rotate keys regularly - -#### **🛡️ Input Validation** -- Validate all user inputs -- Sanitize data before processing -- Handle edge cases gracefully - -#### **🔐 Access Control** -- Implement appropriate authentication -- Limit access to sensitive data -- Monitor agent activities - -### **📊 Monitoring & Maintenance** - -#### **📈 Performance Tracking** -- Monitor agent execution times -- Track error rates and patterns -- Optimize based on usage data - -#### **🔧 Regular Updates** -- Keep dependencies updated -- Monitor for security vulnerabilities -- Test after changes - -#### **📚 Documentation Maintenance** -- Update documentation as agents evolve -- Add new examples and use cases -- Keep troubleshooting guides current - ---- - -## 🤝 **Contributing & Community** - -### **🚀 How to Contribute** - -#### **🐛 Bug Reports** -- Use GitHub Issues to report bugs -- Include detailed reproduction steps -- Provide system information -- Attach relevant logs - -#### **💡 Feature Requests** -- Submit feature requests via GitHub Issues -- Describe the problem clearly -- Explain the desired solution -- Consider user impact - -#### **📝 Documentation** -- Improve existing documentation -- Add new examples and tutorials -- Fix typos and errors -- Translate to other languages - -#### **🔧 Code Contributions** -- Fork the repository -- Create feature branches -- Submit pull requests -- Follow code standards - -### **🌟 Community Guidelines** - -#### **🤝 Be Respectful** -- Treat all community members with respect -- Provide constructive feedback -- Help others learn and grow -- Celebrate contributions - -#### **📚 Share Knowledge** -- Share success stories and use cases -- Help answer questions in discussions -- Create tutorials and guides -- Mentor new contributors - -#### **🎯 Stay Focused** -- Keep discussions relevant to Agent Creator -- Follow issue templates -- Stay on topic in discussions -- Respect project goals - -### **🏆 Recognition** - -#### **🌟 Contributors** -- Recognition in README and documentation -- Special thanks in release notes -- Community spotlight in discussions -- Opportunities for collaboration - -#### **📈 Impact** -- Track contribution metrics -- Highlight popular features and improvements -- Showcase successful projects using Agent Creator -- Demonstrate community growth - ---- - -## 💬 **FAQ - Frequently Asked Questions** - -### **🎯 General Questions** - -#### **Q: What exactly is Agent Creator?** -**A:** Agent Creator is a meta-skill that teaches Claude Code how to create complete, production-ready agents autonomously. You describe what you want to automate, and Agent Creator handles all the technical implementation. - -#### **Q: Do I need to be a programmer to use this?** -**A:** No! That's the entire point. Agent Creator is designed for everyone - business owners, researchers, analysts, and non-technical users. Just describe your workflow in plain language. - -#### **Q: How is this different from ChatGPT?** -**A:** ChatGPT gives you code snippets you implement yourself. Agent Creator creates complete, installable agents that you can use immediately without any programming required. - -#### **Q: Can I create agents for any domain?** -**A:** Yes! Agent Creator can create agents for any domain that has available data sources - finance, agriculture, healthcare, e-commerce, research, and more. - -### **🔧 Technical Questions** - -#### **Q: What programming languages do the created agents use?** -**A:** Agents are created in Python with modern best practices, type hints, and comprehensive error handling. - -#### **Q: Can agents connect to databases and APIs?** -**A:** Yes! Agents can integrate with databases (PostgreSQL, MySQL), REST APIs, Google Sheets, and most data sources. - -#### **Q: Are the created agents secure?** -**A:** Yes. Agents follow security best practices including input validation, secure credential management, and safe data handling. - -#### **Q: Can I modify agents after creation?** -**A:** Absolutely! Agents are fully customizable. You can modify them, extend them, or combine multiple agents. - -### **💰 Business Questions** - -#### **Q: What's the ROI of using Agent Creator?** -**A:** Typical ROI is 1000%+ in the first month. Users report saving 20-40 hours weekly while improving quality and consistency. - -#### **Q: How much time does it really save?** -**A:** Average savings are 90-97% of manual time. A 2-hour daily task typically becomes a 5-minute automated process. - -#### **Q: Can I use this for my business?** -**A:** Yes! Agent Creator is perfect for businesses of all sizes, from solo entrepreneurs to large enterprises. - -#### **Q: What's the total cost?** -**A**: Agent Creator itself is free. The only costs are for the APIs your agents use, many of which have generous free tiers. - -### **🎯 Usage Questions** - -#### **Q: How do I install and set up agents?** -**A:** Installation is simple: `/plugin marketplace add FrancyJGLisboa/agent-skill-creator` in Claude Code, then create agents with natural language commands. - -#### **Q: How do I know what agents to create?** -**A:** Think about any repetitive workflow or manual process. If it takes more than 10 minutes regularly, it's a great candidate for automation. - -#### **Q: Can agents work offline?** -**A:** Yes, once created and installed, agents can work offline. They only need internet access for data that requires it. - -#### **Q: How do I troubleshoot if an agent doesn't work?** -**A:** Each agent includes comprehensive documentation with troubleshooting guides, examples, and contact information for support. - -### **🧠 v2.1 Learning Questions** - -#### **Q: What is AgentDB integration?** -**A:** AgentDB is a learning system that makes agents smarter over time by remembering what works and what doesn't. It's completely invisible to users. - -#### **Q: Do I need to configure AgentDB?** -**A:** No! AgentDB integration is automatic and invisible. It works in the background without any user intervention required. - -#### **Q: What if I don't want AgentDB?** -**A:** Agent Creator works perfectly without AgentDB. You get all the same features, just without the learning capabilities. - -#### **Q: How does the learning work?** -**A:** Every time you create an agent, AgentDB stores the experience. Future creations use this collective knowledge to be faster and better. - ---- - -## 🎉 **Getting Started: Your First Agent** - -### **🚀 Quick Start (3 Minutes)** - -#### **Step 1: Install** -```bash -/plugin marketplace add FrancyJGLisboa/agent-skill-creator -``` - -#### **Step 2: Create** -```bash -"Create agent for tracking my business expenses automatically" -``` - -#### **Step 3: Wait** -*Agent Creator works for 15-60 minutes creating your complete agent* - -#### **Step 4: Use** -```bash -"Track my expenses for last month" -"Generate expense report by category" -"Show me spending trends" -``` - -### **🎯 Template Examples** - -#### **Financial Analysis (15 minutes)** -```bash -"Create financial analysis agent using financial-analysis template" -``` - -#### **Climate Analysis (20 minutes)** -```bash -"Create climate analysis agent for temperature anomalies using climate-analysis template" -``` - -#### **E-commerce Analytics (25 minutes)** -```bash -"Create e-commerce analytics agent using e-commerce-analytics template" -``` - -### **🏗️ Custom Examples** - -#### **Business Process Automation** -```bash -"Automate this workflow: Every morning I check sales data, -create daily reports, and send them to management team. Takes 2 hours." -``` - -#### **Research Automation** -```bash -"Create agent for research automation - collect academic papers, -summarize findings, manage citations, generate literature review." -``` - -#### **Multi-Agent System** -```bash -"Create complete business intelligence system with agents for: -- Sales data analysis and reporting -- Customer behavior analytics -- Inventory tracking and optimization -- Financial reporting and forecasting" -``` - ---- - -## 📞 **Connect & Support** - -### **💬 Community** -- **GitHub Discussions**: [github.com/FrancyJGLisboa/agent-skill-creator/discussions](https://github.com/FrancyJGLisboa/agent-skill-creator/discussions) -- **Issues & Support**: [github.com/FrancyJGLisboa/agent-skill-creator/issues](https://github.com/FrancyJGLisboa/agent-skill-creator/issues) -- **Twitter**: Share your success stories with #AgentCreator - -### **📚 Resources** -- **Documentation**: Complete guides in this repository -- **Examples**: Real-world case studies and templates -- **Community**: Join discussions and share experiences - -### **🎯 Success Stories** -We'd love to hear how Agent Creator is helping you automate work and save time! Share your story in the discussions or create an issue to inspire others. - ---- - -## 🏆 **Start Your Automation Journey Today** - -**Stop doing repetitive work. Start creating intelligent agents that learn and improve.** - -### **🎯 Your First Step** -```bash -/plugin marketplace add FrancyJGLisboa/agent-skill-creator -``` - -### **🚀 Your Second Step** -```bash -"Create agent for [your repetitive workflow]" -``` - -### **⏰ Your Reward** -- **Time Saved**: 20-40 hours per week -- **Quality Improved**: Consistent, error-free automation -- **Stress Reduced**: Reliable, dependable processes -- **Growth Enabled**: Focus on what matters most - ---- - -## 📄 **License** - -Apache 2.0 - Free to use, modify, and distribute. - ---- - -## 🙏 **Credits & Acknowledgments** - -### **🤖 Core Technology** -- Built by Claude Code AI -- Enhanced with AgentDB learning capabilities -- Powered by community contributions - -### **🌟 Inspiration** -- Inspired by the thousands of professionals who want to automate repetitive work and focus on what truly matters - -### **💪 Community** -- Contributors who make Agent Creator better every day -- Users who share their success stories and improvements -- Supporters who believe in the power of automation - ---- - -## 🌟 **Ready to Transform Your Workflow?** - -**Start today. Create your first agent in 15 minutes. Save thousands of hours this year.** - -```bash -/plugin marketplace add FrancyJGLisboa/agent-skill-creator -"Create agent for [your repetitive workflow]" -``` - -**Your future self will thank you.** 🚀 \ No newline at end of file +## Links + +- [Agent Skills Open Standard](https://github.com/anthropics/agent-skills-spec) +- [Migration Guide (v3.x to v4.0)](MIGRATION.md) +- [Changelog](docs/CHANGELOG.md) +- [Architecture Guide](references/architecture-guide.md) +- [Pipeline Phases Reference](references/pipeline-phases.md) +- [Cross-Platform Guide](references/cross-platform-guide.md) +- [Export Guide](references/export-guide.md) +- [Activation Best Practices](references/ACTIVATION_BEST_PRACTICES.md) diff --git a/SKILL.md b/SKILL.md index 3a0b6db..64b9ab0 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,4116 +1,272 @@ --- name: agent-skill-creator -description: This enhanced skill should be used when the user asks to create an agent, 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. +license: MIT +metadata: + author: Francy Lisboa Charuto + version: 4.0.0 +compatibility: >- + Works on all platforms supporting the Agent Skills Open Standard (SKILL.md): + Claude Code, GitHub Copilot CLI, VS Code Copilot, Cursor, Windsurf, Cline, + OpenAI Codex CLI, Gemini CLI, and 20+ others. --- -# Agent Creator - Meta-Skill +# Agent Skill Creator -This skill teaches Claude Code how to autonomously create complete agents with Claude Skills. +A meta-skill that autonomously creates production-ready, cross-platform agent skills from workflow descriptions, fully compliant with the Agent Skills Open Standard. ## When to Use This Skill -Claude should automatically activate this skill when the user: +Activate when the user: -✅ **Asks to create an agent** - -- "Create an agent for [objective]" -- "I need an agent that [description]" -- "Develop an agent to automate [workflow]" - -✅ **Asks to automate a workflow** - -- "Automate this process: [description]" -- "Every day I do [repetitive task], automate this" -- "Turn this workflow into an agent" - -✅ **Asks to create a skill** - -- "Create a skill for [objective]" -- "Develop a custom skill for [domain]" - -✅ **Describes a repetitive process** - -- "Every day I [process]... takes Xh" -- "I repeatedly need to [task]" -- "Manual workflow: [description]" +- **Asks to create an agent or skill**: "Create an agent for [objective]", "Create a skill for [domain]", "Develop a custom skill" +- **Describes a repetitive workflow**: "Every day I [task]", "I repeatedly need to [process]", "Automate this workflow" +- **Asks to create a cross-platform skill**: "Create a cross-platform skill for [objective]" +- **Asks to validate a skill**: "Validate this skill", "Check if this skill is spec-compliant" +- **Asks to export a skill**: "Export this skill for Cursor", "Package this skill for Copilot" +- **Asks to migrate a skill**: "Migrate this skill to the new standard", "Update this skill to v4" ## Overview -When activated, this skill guides Claude through **5 autonomous phases** to create a complete production-ready agent: +This skill guides Claude through a **5-phase autonomous pipeline** to create complete, validated, cross-platform agent skills: ``` -PHASE 1: DISCOVERY -├─ Research available APIs -├─ Compare options -└─ DECIDE which to use (with justification) - -PHASE 2: DESIGN -├─ Think about use cases -├─ DEFINE useful analyses -└─ Specify methodologies - -PHASE 3: ARCHITECTURE -├─ STRUCTURE folders and files -├─ Define necessary scripts -└─ Plan caching and performance - -PHASE 4: DETECTION -├─ DETERMINE keywords -└─ Create precise description - -PHASE 5: IMPLEMENTATION -├─ 🚨 FIRST: Create marketplace.json (MANDATORY!) -├─ Create SKILL.md (5000+ words) -├─ Implement Python scripts (functional!) -├─ Write references (useful!) -├─ Generate configs (real!) -├─ Create README -└─ ✅ FINAL: Test installation +Phase 1: DISCOVERY -> Research APIs, data sources, tools +Phase 2: DESIGN -> Define use cases, analyses, methodologies +Phase 3: ARCHITECTURE -> Structure skill directory (standard-compliant) +Phase 4: DETECTION -> Generate description + keywords for activation +Phase 5: IMPLEMENTATION -> Create all files, validate, security scan ``` -**Output**: Complete agent in subdirectory ready to install. +**Output**: A complete skill directory ready to install on any platform: ---- - -## 🏗️ **Claude Skills Architecture: Understanding What We Create** - -### **Important Terminology Clarification** - -This meta-skill creates **Claude Skills**, which come in different architectural patterns: - -#### **📋 Skill Types We Can Create** - -**1. Simple Skill** (Single focused capability) ``` skill-name/ -├── SKILL.md ← Single comprehensive skill file -├── scripts/ ← Optional supporting code -├── references/ ← Optional documentation -└── assets/ ← Optional templates +├── 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 ``` -*Use when: Single objective, simple workflow, <1000 lines code* -**2. Complex Skill Suite** (Multiple specialized capabilities) -``` -skill-suite/ -├── .claude-plugin/ -│ └── marketplace.json ← Organizes multiple component skills -├── component-1/ -│ └── SKILL.md ← Specialized sub-skill -├── component-2/ -│ └── SKILL.md ← Another specialized sub-skill -└── shared/ ← Shared resources -``` -*Use when: Multiple related workflows, >2000 lines code, team maintenance* +## Core Workflow -#### **🎯 Architecture Decision Process** +### Phase 1: Discovery -During **PHASE 3: ARCHITECTURE**, this skill will: +Research available APIs and data sources for the user's domain. Compare options by cost, rate limits, data quality, and documentation. **Decide** which API to use with justification. -1. **Analyze Complexity Requirements** - - Number of distinct workflows - - Code complexity estimation - - Maintenance considerations +See `references/pipeline-phases.md` for detailed Phase 1 instructions. -2. **Choose Appropriate Architecture** - - Simple task → Simple Skill - - Complex multi-domain task → Skill Suite - - Hybrid requirements → Simple skill with components +### Phase 2: Design -3. **Apply Naming Convention** - - Generate descriptive base name from requirements - - Add "-cskill" suffix to identify as Claude Skill created by Agent-Skill-Creator - - Ensure consistent, professional naming across all created skills +Define 4-6 priority analyses covering 80% of use cases. For each: name, objective, inputs, outputs, methodology. Always include a comprehensive report function. -4. **Document the Decision** - - Create `DECISIONS.md` explaining architecture choice - - Provide rationale for selected pattern - - Include migration path if needed - - Document naming convention applied +See `references/pipeline-phases.md` for detailed Phase 2 instructions. -#### **🏷️ Naming Convention: "-cskill" Suffix** +### Phase 3: Architecture -**All skills created by this Agent-Skill-Creator use the "-cskill" suffix:** +Structure the skill using the Agent Skills Open Standard: -**Simple Skills:** -- `pdf-text-extractor-cskill/` -- `csv-data-cleaner-cskill/` -- `weekly-report-generator-cskill/` +- **Simple Skill**: Single SKILL.md + scripts + references + assets +- **Complex Suite**: Multiple component skills with shared resources -**Complex Skill Suites:** -- `financial-analysis-suite-cskill/` -- `e-commerce-automation-cskill/` -- `research-workflow-cskill/` +**Decision criteria**: Number of workflows, code complexity, maintenance needs. -**Component Skills (within suites):** -- `data-acquisition-cskill/` -- `technical-analysis-cskill/` -- `reporting-generator-cskill/` +See `references/architecture-guide.md` for decision logic and directory structures. -**Purpose of "-cskill" suffix:** -- ✅ **Clear Identification**: Immediately recognizable as a Claude Skill -- ✅ **Origin Attribution**: Created by Agent-Skill-Creator -- ✅ **Consistent Convention**: Professional naming standard -- ✅ **Avoids Confusion**: Distinguishes from manually created skills -- ✅ **Easy Organization**: Simple to identify and group created skills +### Phase 4: Detection -#### **📚 Reference Documentation** +Generate a description (<=1024 chars) with domain keywords for agent discovery. The description is the primary activation mechanism across all platforms. -For complete understanding of Claude Skills architecture, see: -- `docs/CLAUDE_SKILLS_ARCHITECTURE.md` (comprehensive guide) -- `docs/DECISION_LOGIC.md` (architecture decision framework) -- `examples/` (simple vs complex examples) -- `examples/simple-skill/` (minimal example) -- `examples/complex-skill-suite/` (comprehensive example) +See `references/pipeline-phases.md` for detailed Phase 4 instructions. -#### **✅ What We Create** +### Phase 5: Implementation -**ALWAYS creates a valid Claude Skill** - either: -- **Simple Skill** (single SKILL.md) -- **Complex Skill Suite** (multiple component skills with marketplace.json) +Create all files in this order: -**NEVER creates "plugins" in the traditional sense** - we create Skills, which may be organized using marketplace.json for complex suites. +1. Create directory structure +2. Write **SKILL.md** with spec-compliant frontmatter (primary file) +3. Implement Python scripts (functional, no placeholders) +4. Write references (detailed documentation) +5. Write assets (templates, configs) +6. Generate `install.sh` (cross-platform installer) +7. Write `README.md` (multi-platform install instructions) +8. Run **validation** against the official spec +9. Run **security scan** for hardcoded keys and injection patterns +10. Report results to user -This terminology consistency eliminates confusion between Skills and Plugins. +See `references/pipeline-phases.md` for detailed Phase 5 instructions. +### Generated SKILL.md Format + +Every generated skill's SKILL.md must have: + +```yaml --- - -## 🧠 Invisible Intelligence: AgentDB Integration - -### Enhanced Intelligence (v2.1) - -This skill now includes **invisible AgentDB integration** that learns from every agent creation and provides progressively smarter assistance. - -**What happens automatically:** -- 🧠 **Learning Memory**: Stores every creation attempt as episodes -- ⚡ **Progressive Enhancement**: Each creation becomes faster and more accurate -- 🎯 **Smart Validation**: Mathematical proofs for all decisions -- 🔄 **Graceful Operation**: Works perfectly with or without AgentDB - -**User Experience**: Same simple commands, agents get smarter magically! - -### Integration Points - -The AgentDB integration is woven into the 5 phases: - -``` -PHASE 1: DISCOVERY -├─ Research APIs -├─ 🧠 Query AgentDB for similar past successes -├─ Compare options using learned patterns -└─ DECIDE with historical confidence - -PHASE 2: DESIGN -├─ Think about use cases -├─ 🧠 Retrieve successful analysis patterns -├─ DEFINE using proven methodologies -└─ Enhance with learned improvements - -PHASE 3: ARCHITECTURE -├─ STRUCTURE using validated patterns -├─ 🧠 Apply proven architectural decisions -├─ Plan based on success history -└─ Optimize with learned insights - -PHASE 4: DETECTION -├─ DETERMINE keywords using learned patterns -├─ 🧠 Use successful keyword combinations -└─ Create optimized description - -PHASE 5: IMPLEMENTATION -├─ Create marketplace.json -├─ 🧠 Apply proven code patterns -├─ Store episode for future learning -└─ ✅ Complete with enhanced validation -``` - -### Learning Progression - -**First Creation:** -``` -"Create financial analysis agent" -→ Standard agent creation process -→ Episode stored for learning -→ No visible difference to user -``` - -**After 10+ Creations:** -``` -"Create financial analysis agent" -→ 40% faster (learned optimal queries) -→ Better API selection (historical success) -→ Proven architectural patterns -→ User sees: "⚡ Optimized based on similar successful agents" -``` - -**After 30+ Days:** -``` -"Create financial analysis agent" -→ Personalized recommendations based on patterns -→ Predictive insights about user preferences -→ Automatic skill consolidation -→ User sees: "🌟 I notice you prefer comprehensive financial agents - shall I include portfolio optimization?" -``` - +name: skill-name # 1-64 chars, lowercase + hyphens, matches directory +description: >- # 1-1024 chars, activation keywords + Description here... +license: MIT # or appropriate license +metadata: + author: Author Name + version: 1.0.0 --- - -## 🚀 Enhanced Features (v2.0) - -### Multi-Agent Architecture - -The enhanced agent-creator now supports: - -**✅ Single Agent Creation** (Original functionality) -``` -"Create an agent for stock analysis" -→ ./stock-analysis-agent/ ``` -**✅ Multi-Agent Suite Creation** (NEW) +Body must be <500 lines. Move detailed content to `references/`. + +## Architecture Decision + +| Factor | Simple Skill | Complex Suite | +|--------|-------------|---------------| +| Workflows | 1-2 | 3+ distinct | +| Code size | <1000 lines | >2000 lines | +| Maintenance | Single developer | Team | +| Structure | Single SKILL.md | Multiple component SKILL.md files | +| marketplace.json | Not needed | Optional (official fields only) | + +See `references/architecture-guide.md` for detailed decision framework. + +## Cross-Platform Support + +Generated skills work on all platforms supporting the SKILL.md standard: + +| Platform | Install Location | Command | +|----------|-----------------|---------| +| Claude Code | `~/.claude/skills/` or `.claude/skills/` | `./install.sh` or copy | +| GitHub Copilot | `.github/skills/` | `./install.sh --platform copilot` | +| Cursor | `.cursor/rules/` | `./install.sh --platform cursor` | +| Windsurf | `.windsurf/skills/` | `./install.sh --platform windsurf` | +| Cline | `.clinerules/` | `./install.sh --platform cline` | +| Codex CLI | `.codex/skills/` | `./install.sh --platform codex` | +| Gemini CLI | `.gemini/skills/` | `./install.sh --platform gemini` | + +See `references/cross-platform-guide.md` for full platform details. + +## Validation and Security + +After generating a skill, run: + +- **Spec validation**: Checks frontmatter, naming, structure, line count +- **Security scan**: Checks for hardcoded API keys, .env files, injection patterns + +```bash +# Validate a skill +python3 scripts/validate.py path/to/skill/ + +# Security scan +python3 scripts/security_scan.py path/to/skill/ +``` + +## Export System + +Package skills for distribution: + +```bash +# Export for all platforms +python3 scripts/export_utils.py path/to/skill/ + +# Desktop/Web package only +python3 scripts/export_utils.py path/to/skill/ --variant desktop + +# API package only +python3 scripts/export_utils.py path/to/skill/ --variant api +``` + +See `references/export-guide.md` for full export documentation. + +## Template-Based Creation + +Pre-built templates for common domains: + +- **Financial Analysis**: Alpha Vantage/Yahoo Finance, fundamental + technical analysis +- **Climate Analysis**: Open-Meteo/NOAA, anomalies + trends + seasonal patterns +- **E-commerce Analytics**: Google Analytics/Stripe/Shopify, traffic + revenue + cohorts + +See `references/templates-guide.md` for template details and customization. + +## Multi-Agent Suites + +Create multiple related agents in one operation: + ``` "Create a financial analysis suite with 4 agents: -fundamental analysis, technical analysis, -portfolio management, and risk assessment" -→ ./financial-suite/ - ├── fundamental-analysis/ - ├── technical-analysis/ - ├── portfolio-management/ - └── risk-assessment/ +fundamental, technical, portfolio, and risk assessment" ``` -**✅ Transcript Intelligence Processing** (NEW) -``` -"I have a YouTube transcript about e-commerce analytics, -can you create agents based on the workflows described?" -→ Automatically extracts multiple workflows -→ Creates integrated agent suite -``` +See `references/multi-agent-guide.md` for suite creation docs. -**✅ Template-Based Creation** (NEW) -``` -"Create an agent using the financial-analysis template" -→ Uses pre-configured APIs and analyses -→ 80% faster creation -``` +## Interactive Configuration -**✅ Interactive Configuration** (NEW) -``` -"Help me create an agent with preview options" -→ Step-by-step wizard -→ Real-time preview -→ Iterative refinement -``` +Step-by-step wizard for complex projects: -### Enhanced Marketplace.json Support - -**v1.0 Format** (Still supported): -```json -{ - "name": "single-agent", - "plugins": [ - { - "skills": ["./"] - } - ] -} -``` - -**v2.0 Format** (NEW - Multi-skill support): -```json -{ - "name": "agent-suite", - "plugins": [ - { - "name": "fundamental-analysis", - "source": "./fundamental-analysis/", - "skills": ["./SKILL.md"] - }, - { - "name": "technical-analysis", - "source": "./technical-analysis/", - "skills": ["./SKILL.md"] - } - ] -} -``` - ---- - -## Autonomous Creation Protocol - -### Fundamental Principles - -**Autonomy**: - -- ✅ Claude DECIDES which API to use (doesn't ask user) -- ✅ Claude DEFINES which analyses to perform (based on value) -- ✅ Claude STRUCTURES optimally (best practices) -- ✅ Claude IMPLEMENTS complete code (no placeholders) -- ✅ **NEW**: Claude LEARNS from experience (AgentDB integration) - -**Quality**: - -- ✅ Production-ready code (no TODOs) -- ✅ Useful documentation (not "see docs") -- ✅ Real configs (no placeholders) -- ✅ Robust error handling -- ✅ **NEW**: Intelligence validated with mathematical proofs - -**Completeness**: - -- ✅ Complete SKILL.md (5000+ words) -- ✅ Functional scripts (1000+ lines total) -- ✅ References with content (3000+ words) -- ✅ Valid assets/configs -- ✅ README with instructions - -### Requirements Extraction - -When user describes workflow vaguely, extract: - -**From what the user said**: - -- Domain (agriculture? finance? weather?) -- Data source (mentioned? if not, research) -- Main tasks (download? analyze? compare?) -- Frequency (daily? weekly? on-demand?) -- Current time spent (to calculate ROI) - -**🆕 Enhanced Analysis (v2.0)**: - -- **Multi-Agent Detection**: Look for keywords like "suite", "multiple", "separate agents" -- **Transcript Analysis**: Detect if input is a video/transcript requiring workflow extraction -- **Template Matching**: Identify if user wants template-based creation -- **Interactive Preference**: Detect if user wants guidance vs full autonomy -- **Integration Needs**: Determine if agents should communicate with each other - -**🆕 Transcript Processing**: - -When user provides transcripts: -```python -# Enhanced transcript analysis -def analyze_transcript(transcript: str) -> List[WorkflowSpec]: - """Extract multiple workflows from transcripts automatically""" - workflows = [] - - # 1. Identify distinct processes - processes = extract_processes(transcript) - - # 2. Group related steps - for process in processes: - steps = extract_sequence_steps(transcript, process) - apis = extract_mentioned_apis(transcript, process) - outputs = extract_desired_outputs(transcript, process) - - workflows.append(WorkflowSpec( - name=process, - steps=steps, - apis=apis, - outputs=outputs - )) - - return workflows -``` - -**🆕 Multi-Agent Strategy Decision**: - -```python -def determine_creation_strategy(user_input: str, workflows: List[WorkflowSpec]) -> CreationStrategy: - """Decide whether to create single agent, suite, or integrated system""" - - if len(workflows) > 1: - if workflows_are_related(workflows): - return CreationStrategy.INTEGRATED_SUITE - else: - return CreationStrategy.MULTI_AGENT_SUITE - else: - return CreationStrategy.SINGLE_AGENT -``` - -**Questions to ask** (only if critical and not inferable): - -- "Prefer free API or paid is ok?" -- "Need historical data for how many years?" -- "Focus on which geography/country?" -- **🆕 "Create separate agents or integrated suite?"** (if multiple workflows detected) -- **🆕 "Want interactive preview before creation?"** (for complex projects) - -**Rule**: Minimize questions. Infer/decide whenever possible. - -## 🎯 Template-Based Creation (NEW v2.0) - -### Available Templates - -The enhanced agent-creator includes pre-built templates for common domains: - -**📊 Financial Analysis Template** -```json -Domain: Finance & Investments -APIs: Alpha Vantage, Yahoo Finance -Analyses: Fundamental, Technical, Portfolio -Time: 15-20 minutes -``` - -**🌡️ Climate Analysis Template** -```json -Domain: Climate & Environmental -APIs: Open-Meteo, NOAA -Analyses: Anomalies, Trends, Seasonal -Time: 20-25 minutes -``` - -**🛒 E-commerce Analytics Template** -```json -Domain: Business & E-commerce -APIs: Google Analytics, Stripe, Shopify -Analyses: Traffic, Revenue, Cohort, Products -Time: 25-30 minutes -``` - -### Template Matching Process - -```python -def match_template(user_input: str) -> TemplateMatch: - """Automatically suggest best template based on user input""" - - # 1. Extract keywords from user input - keywords = extract_keywords(user_input) - - # 2. Calculate similarity scores with all templates - matches = [] - for template in available_templates: - score = calculate_similarity(keywords, template.keywords) - matches.append((template, score)) - - # 3. Rank by similarity - matches.sort(key=lambda x: x[1], reverse=True) - - # 4. Return best match if confidence > threshold - if matches[0][1] > 0.7: - return TemplateMatch(template=matches[0][0], confidence=matches[0][1]) - else: - return None # No suitable template found -``` - -### Template Usage Examples - -**Direct Template Request:** -``` -"Create an agent using the financial-analysis template" -→ Uses pre-configured structure -→ 80% faster creation -→ Proven architecture -``` - -**Automatic Template Detection:** -``` -"I need to analyze stock performance and calculate RSI, MACD" -→ Detects financial domain -→ Suggests financial-analysis template -→ User confirms or continues custom -``` - -**Template Customization:** -``` -"Use the climate template but add drought analysis" -→ Starts with climate template -→ Adds custom drought analysis -→ Modifies structure accordingly -``` - -## 🚀 Batch Agent Creation (NEW v2.0) - -### Multi-Agent Suite Creation - -The enhanced agent-creator can create multiple agents in a single operation: - -**When to Use Batch Creation:** -- Transcript describes multiple distinct workflows -- User explicitly asks for multiple agents -- Complex system requiring specialized components -- Microservices architecture preferred - -### Batch Creation Process - -```python -def create_agent_suite(user_input: str, workflows: List[WorkflowSpec]) -> AgentSuite: - """Create multiple related agents in one operation""" - - # 1. Analyze workflow relationships - relationships = analyze_workflow_relationships(workflows) - - # 2. Determine optimal structure - if workflows_are_tightly_coupled(workflows): - structure = "integrated_suite" - else: - structure = "independent_agents" - - # 3. Create suite directory - suite_name = generate_suite_name(user_input) - create_suite_directory(suite_name) - - # 4. Create each agent - agents = [] - for workflow in workflows: - agent = create_single_agent(workflow, suite_name) - agents.append(agent) - - # 5. Create integration layer (if needed) - if structure == "integrated_suite": - create_integration_layer(agents, suite_name) - - # 6. Create suite-level marketplace.json - create_suite_marketplace_json(suite_name, agents) - - return AgentSuite(name=suite_name, agents=agents, structure=structure) -``` - -### Batch Creation Examples - -**Financial Suite Example:** -``` -"Create a complete financial analysis system with 4 agents: -1. Fundamental analysis for company valuation -2. Technical analysis for trading signals -3. Portfolio management and optimization -4. Risk assessment and compliance" - -→ ./financial-analysis-suite/ - ├── .claude-plugin/marketplace.json (multi-skill) - ├── fundamental-analysis/ - │ ├── SKILL.md - │ ├── scripts/ - │ └── tests/ - ├── technical-analysis/ - ├── portfolio-management/ - └── risk-assessment/ -``` - -**E-commerce Suite Example:** -``` -"Build an e-commerce analytics system based on this transcript: -- Traffic analysis from Google Analytics -- Revenue tracking from Stripe -- Product performance from Shopify -- Customer cohort analysis -- Automated reporting dashboard" - -→ ./e-commerce-analytics-suite/ - ├── traffic-analysis-agent/ - ├── revenue-tracking-agent/ - ├── product-performance-agent/ - ├── cohort-analysis-agent/ - └── reporting-dashboard-agent/ -``` - -### Multi-Skill Marketplace.json Structure - -**Suite-Level Configuration:** -```json -{ - "name": "financial-analysis-suite", - "metadata": { - "description": "Complete financial analysis system with fundamental, technical, portfolio, and risk analysis", - "version": "1.0.0", - "suite_type": "financial_analysis" - }, - "plugins": [ - { - "name": "fundamental-analysis-plugin", - "description": "Fundamental analysis for company valuation and financial metrics", - "source": "./fundamental-analysis/", - "skills": ["./SKILL.md"] - }, - { - "name": "technical-analysis-plugin", - "description": "Technical analysis with trading indicators and signals", - "source": "./technical-analysis/", - "skills": ["./SKILL.md"] - }, - { - "name": "portfolio-management-plugin", - "description": "Portfolio optimization and management analytics", - "source": "./portfolio-management/", - "skills": ["./SKILL.md"] - }, - { - "name": "risk-assessment-plugin", - "description": "Risk analysis and compliance monitoring", - "source": "./risk-assessment/", - "skills": ["./SKILL.md"] - } - ], - "integrations": { - "data_sharing": true, - "cross_agent_communication": true, - "shared_utils": "./shared/" - } -} -``` - -### Batch Creation Benefits - -**✅ Time Efficiency:** -- Create 4 agents in ~60 minutes (vs 4 hours individually) -- Shared utilities and infrastructure -- Consistent architecture and documentation - -**✅ Integration Benefits:** -- Agents designed to work together -- Shared data structures and formats -- Unified testing and deployment - -**✅ Maintenance Benefits:** -- Single marketplace.json for installation -- Coordinated versioning and updates -- Shared troubleshooting documentation - -### Batch Creation Commands - -**Explicit Multi-Agent Request:** -``` -"Create 3 agents for climate analysis: -1. Temperature anomaly detection -2. Precipitation pattern analysis -3. Extreme weather event tracking - -Make them work together as a system." -``` - -**Transcript-Based Batch Creation:** -``` -"Here's a transcript of a 2-hour tutorial on building -a complete business intelligence system. Create agents -for all the workflows described in the video." -``` - -**Template-Based Batch Creation:** -``` -"Use the e-commerce template to create a full analytics suite: -- Traffic analysis -- Revenue tracking -- Customer analytics -- Product performance -- Marketing attribution" -``` - -## 🎮 Interactive Configuration Wizard (NEW v2.0) - -### When to Use Interactive Mode - -The enhanced agent-creator includes an interactive wizard for: - -- **Complex Projects**: Multi-agent systems, integrations -- **User Preference**: When users want guidance vs full autonomy -- **High-Stakes Projects**: When preview and iteration are important -- **Learning**: Users who want to understand the creation process - -### Interactive Wizard Process - -```python -def interactive_agent_creation(): - """ - Step-by-step guided agent creation with real-time preview - """ - - # Step 1: Welcome and Requirements Gathering - print("🚀 Welcome to Enhanced Agent Creator!") - print("I'll help you create custom agents through an interactive process.") - - user_needs = gather_requirements_interactively() - - # Step 2: Workflow Analysis - print("\n📋 Analyzing your requirements...") - workflows = analyze_and_confirm_workflows(user_needs) - - # Step 3: Strategy Selection - strategy = select_creation_strategy(workflows) - print(f"🎯 Recommended: {strategy.description}") - - # Step 4: Preview and Refinement - while True: - preview = generate_interactive_preview(strategy) - show_preview(preview) - - if user_approves(): - break - else: - strategy = refine_based_on_feedback(strategy, preview) - - # Step 5: Creation - print("\n⚙️ Creating your agent(s)...") - result = execute_creation(strategy) - - # Step 6: Validation and Tutorial - validate_created_agents(result) - provide_usage_tutorial(result) - - return result -``` - -### Interactive Interface Examples - -**Step 1: Requirements Gathering** -``` -🚀 Welcome to Enhanced Agent Creator! - -Let me understand what you want to build: - -1. What's your main goal? - [ ] Automate a repetitive workflow - [ ] Analyze data from specific sources - [ ] Create custom tools for my domain - [ ] Build a complete system with multiple components - -2. What's your domain/industry? - [ ] Finance & Investing - [ ] E-commerce & Business - [ ] Climate & Environment - [ ] Healthcare & Medicine - [ ] Other (please specify): _______ - -3. Do you have existing materials? - [ ] YouTube transcript or video - [ ] Documentation or tutorials - [ ] Existing code/scripts - [ ] Starting from scratch - -Your responses: [Finance & Investing] [Starting from scratch] -``` - -**Step 2: Workflow Analysis** -``` -📋 Based on your input, I detect: - -Domain: Finance & Investing -Potential Workflows: -1. Fundamental Analysis (P/E, ROE, valuation metrics) -2. Technical Analysis (RSI, MACD, trading signals) -3. Portfolio Management (allocation, optimization) -4. Risk Assessment (VaR, drawdown, compliance) - -Which workflows interest you? Select all that apply: -[✓] Technical Analysis -[✓] Portfolio Management -[ ] Fundamental Analysis -[ ] Risk Assessment - -Selected: 2 workflows detected -``` - -**Step 3: Strategy Selection** -``` -🎯 Recommended Creation Strategy: - -Multi-Agent Suite Creation -- Create 2 specialized agents -- Each agent handles one workflow -- Agents can communicate and share data -- Unified installation and documentation - -Estimated Time: 35-45 minutes -Output: ./finance-suite/ (2 agents) - -Options: -[✓] Accept recommendation -[ ] Create single integrated agent -[ ] Use template-based approach -[ ] Customize strategy -``` - -**Step 4: Interactive Preview** -``` -📊 Preview of Your Finance Suite: - -Structure: -./finance-suite/ -├── .claude-plugin/marketplace.json -├── technical-analysis-agent/ -│ ├── SKILL.md (2,100 words) -│ ├── scripts/ (Python, 450 lines) -│ └── tests/ (15 tests) -└── portfolio-management-agent/ - ├── SKILL.md (1,800 words) - ├── scripts/ (Python, 380 lines) - └── tests/ (12 tests) - -Features: -✅ Real-time stock data (Alpha Vantage API) -✅ 10 technical indicators (RSI, MACD, Bollinger...) -✅ Portfolio optimization algorithms -✅ Risk metrics and rebalancing alerts -✅ Automated report generation - -APIs Required: -- Alpha Vantage (free tier available) -- Yahoo Finance (no API key needed) - -Would you like to: -[✓] Proceed with creation -[ ] Modify technical indicators -[ ] Add risk management features -[ ] Change APIs -[ ] See more details -``` - -### Wizard Benefits - -**🎯 User Empowerment:** -- Users see exactly what will be created -- Can modify and iterate before implementation -- Learn about the process and architecture -- Make informed decisions - -**⚡ Efficiency:** -- Faster than custom development -- Better than black-box creation -- Reduces rework and iterations -- Higher satisfaction rates - -**🛡️ Risk Reduction:** -- Preview prevents misunderstandings -- Iterative refinement catches issues early -- Users can validate requirements -- Clear expectations management - -### Interactive Commands - -**Start Interactive Mode:** ``` "Help me create an agent with interactive options" "Walk me through creating a financial analysis system" -"I want to use the configuration wizard" ``` -**Resume from Preview:** -``` -"Show me the preview again before creating" -"Can I modify the preview you showed me?" -"I want to change something in the proposed structure" -``` - -**Learning Mode:** -``` -"Create an agent and explain each step as you go" -"Teach me how agent creation works while building" -"I want to understand the architecture decisions" -``` - -### Wizard Customization Options - -**Advanced Mode:** -``` -⚙️ Advanced Configuration Options: - -1. API Selection Strategy - [ ] Prefer free APIs - [ ] Prioritize data quality - [ ] Minimize rate limits - [ ] Multiple API fallbacks - -2. Architecture Preference - [ ] Modular (separate scripts per function) - [ ] Integrated (all-in-one scripts) - [ ] Hybrid (core + specialized modules) - -3. Testing Strategy - [ ] Basic functionality tests - [ ] Comprehensive test suite - [ ] Integration tests - [ ] Performance benchmarks - -4. Documentation Level - [ ] Minimal (API docs only) - [ ] Standard (complete usage guide) - [ ] Extensive (tutorials + examples) - [ ] Academic (methodology + research) -``` - -**Template Customization:** -``` -🎨 Template Customization: - -Base Template: Financial Analysis -✓ Include technical indicators: RSI, MACD, Bollinger Bands -✓ Add portfolio optimization: Modern Portfolio Theory -✓ Risk metrics: VaR, Maximum Drawdown, Sharpe Ratio - -Additional Features: -[ ] Machine learning predictions -[ ] Sentiment analysis from news -[ ] Options pricing models -[ ] Cryptocurrency support - -Remove Features: -[ ] Fundamental analysis (not needed) -[ ] Economic calendar integration -``` - -## 🧠 Invisible Intelligence: AgentDB Integration (NEW v2.1) - -### What This Means for Users - -**The agent-creator now has "memory" and gets smarter over time - automatically!** - -✅ **No setup required** - AgentDB initializes automatically in the background -✅ **No commands to learn** - You use the exact same natural language commands -✅ **Invisible enhancement** - Agents become more intelligent without you doing anything -✅ **Progressive learning** - Each agent learns from experience and shares knowledge - -### How It Works (Behind the Scenes) - -When you create an agent: -``` -User: "Create agent for financial analysis" - -🤖 Agent-Creator (v2.1): -"✅ Creating financial-analysis-agent with learned intelligence..." -"✅ Using template with 94% historical success rate..." -"✅ Applied 12 learned improvements from similar agents..." -"✅ Mathematical proof: template choice validated with 98% confidence..." -``` - -### Key Benefits (Automatic & Invisible) - -**🧠 Learning Memory:** -- Agents remember what works and what doesn't -- Successful patterns are automatically reused -- Failed approaches are automatically avoided - -**📊 Smart Decisions:** -- Template selection based on real success data -- Architecture optimized from thousands of similar agents -- API choices validated with mathematical proofs - -**🔄 Continuous Improvement:** -- Each agent gets smarter with use -- Knowledge shared across all agents automatically -- Nightly reflection system refines capabilities - -### User Experience: "The Magic Gets Better" - -**First Week:** -``` -"Analyze Tesla stock" -🤖 "📊 Tesla analysis: RSI 65.3, MACD bullish" -``` - -**After One Month:** -``` -"Analyze Tesla stock" -🤖 "📊 Tesla analysis: RSI 65.3, MACD bullish (enhanced with your patterns)" -🤖 "🧠 Pattern detected: You always ask on Mondays - prepared weekly analysis" -🤖 "📈 Added volatility prediction based on your usage patterns" -``` - -### Technical Implementation (Invisible to Users) - -```python -# This happens automatically behind the scenes -class AgentCreatorV21: - def create_agent(self, user_input): - # AgentDB enhancement (invisible) - intelligence = enhance_agent_creation(user_input) - - # Enhanced template selection - template = intelligence.template_choice or self.default_template - - # Learned improvements automatically applied - improvements = intelligence.learned_improvements - - # Create agent with enhanced intelligence - return self.create_with_intelligence(template, improvements) -``` - -### Graceful Fallback - -If AgentDB isn't available (rare), the agent-creator works exactly like v2.0: -``` -"Create agent for financial analysis" -🤖 "✅ Agent created (standard mode)" -``` - -No interruption, no errors, just no learning enhancements. - -### Privacy & Performance - -- ✅ All learning happens locally on your machine -- ✅ No external dependencies required -- ✅ Automatic cleanup and optimization -- ✅ Zero impact on creation speed - ---- - -## 📦 Cross-Platform Export (NEW v3.2) - -### What This Feature Does - -**Automatically package skills for use across all Claude platforms:** - -Skills created in Claude Code can be exported for: -- ✅ **Claude Desktop** - Manual .zip upload -- ✅ **claude.ai** (Web) - Browser-based upload -- ✅ **Claude API** - Programmatic integration - -This makes your skills portable and shareable across all Claude ecosystems. - -### When to Activate Export - -Claude should activate export capabilities when user says: - -✅ **Export requests:** -- "Export [skill-name] for Desktop" -- "Package [skill-name] for claude.ai" -- "Create API package for [skill-name]" -- "Export [skill-name] for all platforms" - -✅ **Cross-platform requests:** -- "Make [skill-name] compatible with Claude Desktop" -- "I need to share [skill-name] with Desktop users" -- "Package [skill-name] as .zip" -- "Create cross-platform version of [skill-name]" - -✅ **Version-specific exports:** -- "Export [skill-name] with version 2.0.1" -- "Package [skill-name] v1.5.0 for API" - -### Export Process - -When user requests export: - -**Step 1: Locate Skill** -```python -# Search common locations -locations = [ - f"./{skill_name}-cskill/", # Current directory - f"references/examples/{skill_name}-cskill/", # Examples - user_specified_path # If provided -] - -skill_path = find_skill(locations) -``` - -**Step 2: Validate Structure** -```python -# Ensure skill is export-ready -valid, issues = validate_skill_structure(skill_path) - -if not valid: - report_issues_to_user(issues) - return -``` - -**Step 3: Execute Export** -```bash -# Run export utility -python scripts/export_utils.py {skill_path} \ - --variant {desktop|api|both} \ - --version {version} \ - --output-dir exports/ -``` - -**Step 4: Report Results** -``` -✅ Export completed! - -📦 Packages created: - - Desktop: exports/{skill}-desktop-v1.0.0.zip (2.3 MB) - - API: exports/{skill}-api-v1.0.0.zip (1.2 MB) - -📄 Installation guide: exports/{skill}-v1.0.0_INSTALL.md - -🎯 Ready for: - ✅ Claude Desktop upload - ✅ claude.ai upload - ✅ Claude API integration -``` - -### Post-Creation Export (Opt-In) - -After successfully creating a skill in PHASE 5, offer export: - -``` -✅ Skill created successfully: {skill-name-cskill}/ - -📦 Cross-Platform Export Options: - -Would you like to create export packages for other Claude platforms? - - 1. Desktop/Web (.zip for manual upload) - 2. API (.zip for programmatic use) - 3. Both (comprehensive package) - 4. Skip (Claude Code only) - -Choice: _ -``` - -**If user chooses 1, 2, or 3:** -- Execute export_utils.py with selected variants -- Report package locations -- Provide next steps for each platform - -**If user chooses 4 or skips:** -- Continue with normal completion -- Skill remains Claude Code only - -### Export Variants - -**Desktop/Web Package** (`*-desktop-*.zip`): -- Complete documentation -- All scripts and assets -- Full references -- Optimized for user experience -- Typical size: 2-5 MB - -**API Package** (`*-api-*.zip`): -- Execution-focused -- Size-optimized (< 8MB) -- Minimal documentation -- Essential scripts only -- Typical size: 0.5-2 MB - -### Version Detection - -Automatically detect version from: - -1. **Git tags** (priority): - ```bash - git describe --tags --abbrev=0 - ``` - -2. **SKILL.md frontmatter**: - ```yaml - --- - name: skill-name - version: 1.2.3 - --- - ``` - -3. **Default**: `v1.0.0` - -**User can override**: -- "Export with version 2.1.0" -- `--version 2.1.0` flag - -### Export Validation - -Before creating packages, validate: - -✅ **Required:** -- SKILL.md exists -- Valid frontmatter (---...---) -- `name:` field present (≤ 64 chars) -- `description:` field present (≤ 1024 chars) - -✅ **Size Checks:** -- Desktop: Reasonable size -- API: < 8MB (hard limit) - -✅ **Security:** -- No .env files -- No credentials.json -- No sensitive data - -If validation fails, report specific issues to user. - -### Installation Guides - -Auto-generate platform-specific guides: - -**File**: `exports/{skill}-v{version}_INSTALL.md` - -**Contents:** -- Package information -- Installation steps for Desktop -- Installation steps for claude.ai -- API integration code examples -- Platform comparison table -- Troubleshooting tips - -### Export Commands Reference - -```bash -# Export both variants (default) -python scripts/export_utils.py ./skill-name-cskill - -# Export only Desktop -python scripts/export_utils.py ./skill-name-cskill --variant desktop - -# Export only API -python scripts/export_utils.py ./skill-name-cskill --variant api - -# With custom version -python scripts/export_utils.py ./skill-name-cskill --version 2.0.1 - -# To custom directory -python scripts/export_utils.py ./skill-name-cskill --output-dir ./releases -``` - -### Documentation References - -Point users to comprehensive guides: -- **Export Guide**: `references/export-guide.md` -- **Cross-Platform Guide**: `references/cross-platform-guide.md` -- **Exports README**: `exports/README.md` - -### Integration with AgentDB - -Export process can leverage AgentDB learning: -- Remember successful export configurations -- Suggest optimal variant based on use case -- Track which exports are most commonly used -- Learn from export failures to improve validation - ---- - -## PHASE 1: Discovery and Research - -**Objective**: DECIDE which API/data source to use with AgentDB intelligence - -### Process - -**1.1 Identify domain and query AgentDB** - -From user input, identify the domain and immediately query AgentDB for learned patterns: - -```python -# Import AgentDB bridge (invisible to user) -from integrations.agentdb_bridge import get_agentdb_bridge - -# Get AgentDB intelligence -bridge = get_agentdb_bridge() -intelligence = bridge.enhance_agent_creation(user_input, domain) - -# Log: AgentDB provides insights if available -if intelligence.learned_improvements: - print(f"🧠 Found {len(intelligence.learned_improvements)} relevant patterns") -``` - -**Domain mapping with AgentDB insights:** -- Agriculture → APIs: USDA NASS, FAO, World Bank Ag -- Finance → APIs: Alpha Vantage, Yahoo Finance, Fed Economic Data -- Weather → APIs: NOAA, OpenWeather, Weather.gov -- Economy → APIs: World Bank, IMF, FRED - -**1.2 Research available APIs with learned preferences** - -For the domain, use WebSearch to find: - -- Available public APIs -- Documentation -- Characteristics (free? rate limits? coverage?) - -**AgentDB Enhancement**: Prioritize APIs that have shown higher success rates: -```python -# AgentDB influences search based on historical success -if intelligence.success_probability > 0.8: - print(f"🎯 High success domain detected - optimizing API selection") -``` - -**Example with AgentDB insights**: - -``` -WebSearch: "US agriculture API free historical data" -WebSearch: "USDA API documentation" -WebFetch: [doc URLs found] - -# AgentDB check: "Has similar domain been successful before?" -# AgentDB provides: "USDA NASS: 94% success rate in agriculture domain" -``` - -**1.3 Compare options with AgentDB validation** - -Create mental table comparing: - -- Data coverage (fit with need) -- Cost (free vs paid) -- Rate limits (sufficient?) -- Data quality (official? reliable?) -- Documentation (good? examples?) -- Ease of use -- **🧠 AgentDB Success Rate** (historical validation) - -**AgentDB Mathematical Validation**: -```python -# AgentDB provides mathematical proof for selection -if intelligence.mathematical_proof: - print(f"📊 API selection validated: {intelligence.mathematical_proof}") -``` - -**1.4 DECIDE with AgentDB confidence** - -Choose 1 API and justify with AgentDB backing: - -**Decision with AgentDB confidence:** -- **Selected API**: [API name] -- **Success Probability**: {intelligence.success_probability:.1%} -- **Mathematical Proof**: {intelligence.mathematical_proof} -- **Learned Improvements**: {intelligence.learned_improvements} - -**Document decision** in separate file: - -```markdown -# Architecture Decisions - -## Selected API: [Name] - -**Justification**: -- ✅ Coverage: [details] -- ✅ Cost: [free/paid] -- ✅ Rate limit: [number] -- ✅ Quality: [official/private] -- ✅ Docs: [quality] - -**Alternatives considered**: -- API X: Rejected because [reason] -- API Y: Rejected because [reason] - -**Conclusion**: [Chosen API] is the best option because [synthesis] -``` - -**1.5 Research technical details** - -Use WebFetch to load API documentation and extract: - -- Base URL -- Main endpoints -- Authentication -- Important parameters -- Response format -- Rate limits -- Request/response examples - -**See** `references/phase1-discovery.md` for complete details. - -## PHASE 2: Analysis Design - -**Objective**: DEFINE which analyses the agent will perform - -### Process - -**2.1 Think about use cases** - -For the described workflow, which questions will the user ask frequently? - -**Brainstorm**: List 10-15 typical questions - -**2.2 Group by analysis type** - -Group similar questions: - -- Simple queries (fetch + format) -- Temporal comparisons (YoY) -- Rankings (sort + share) -- Trends (time series + CAGR) -- Projections (forecasting) -- Aggregations (regional/categorical) - -**2.3 DEFINE priority analyses** - -Choose 4-6 analyses that cover 80% of use cases. - -For each analysis: - -- Name -- Objective -- Required inputs -- Expected outputs -- Methodology (formulas, transformations) -- Interpretation - -**2.4 ADD Comprehensive Report Function** (🆕 Enhancement #8 - MANDATORY!) - -**⚠️ COMMON PROBLEM:** v1.0 skills had isolated functions. When user asks for "complete report", Claude didn't know how to combine all analyses. - -**Solution:** ALWAYS include as last analysis function: - -```python -def comprehensive_{domain}_report( - entity: str, - year: Optional[int] = None, - include_metrics: Optional[List[str]] = None, - client: Optional[Any] = None -) -> Dict: - """ - Generate comprehensive report combining ALL available metrics. - - This is a "one-stop" function that users can call to get - complete picture without knowing individual functions. - - Args: - entity: Entity to analyze (e.g., commodity, stock, location) - year: Year (None for current year with auto-detection) - include_metrics: Which metrics to include (None = all available) - client: API client instance (optional, created if None) - - Returns: - Dict with ALL metrics consolidated: - { - 'entity': str, - 'year': int, - 'year_info': str, - 'generated_at': str (ISO timestamp), - 'metrics': { - 'metric1_name': {metric1_data}, - 'metric2_name': {metric2_data}, - ... - }, - 'summary': str (overall insights), - 'alerts': List[str] (important findings) - } - - Example: - >>> report = comprehensive_{domain}_report("CORN") - >>> print(report['summary']) - "CORN 2025: Production up 5% YoY, yield at record high..." - """ - from datetime import datetime - from utils.helpers import get_{domain}_year_with_fallback, format_year_message - - # Auto-detect year - year_requested = year - if year is None: - year, _ = get_{domain}_year_with_fallback() - - # Initialize report - report = { - 'entity': entity, - 'year': year, - 'year_requested': year_requested, - 'year_info': format_year_message(year, year_requested), - 'generated_at': datetime.now().isoformat(), - 'metrics': {}, - 'alerts': [] - } - - # Determine which metrics to include - if include_metrics is None: - # Include ALL available metrics - metrics_to_fetch = ['{metric1}', '{metric2}', '{metric3}', ...] - else: - metrics_to_fetch = include_metrics - - # Call ALL individual analysis functions - # Graceful degradation: if one fails, others still run - - if '{metric1}' in metrics_to_fetch: - try: - report['metrics']['{metric1}'] = {metric1}_analysis(entity, year, client) - except Exception as e: - report['metrics']['{metric1}'] = { - 'error': str(e), - 'status': 'unavailable' - } - report['alerts'].append(f"{metric1} data unavailable: {e}") - - if '{metric2}' in metrics_to_fetch: - try: - report['metrics']['{metric2}'] = {metric2}_analysis(entity, year, client) - except Exception as e: - report['metrics']['{metric2}'] = { - 'error': str(e), - 'status': 'unavailable' - } - - # Repeat for ALL metrics... - - # Generate summary based on all available data - report['summary'] = _generate_summary(report['metrics'], entity, year) - - # Detect important findings - report['alerts'].extend(_detect_alerts(report['metrics'])) - - return report - - -def _generate_summary(metrics: Dict, entity: str, year: int) -> str: - """Generate human-readable summary from all metrics.""" - insights = [] - - # Extract key insights from each metric - for metric_name, metric_data in metrics.items(): - if 'error' not in metric_data: - # Extract most important insight from this metric - key_insight = _extract_key_insight(metric_name, metric_data) - if key_insight: - insights.append(key_insight) - - # Combine into coherent summary - if insights: - summary = f"{entity} {year}: " + ". ".join(insights[:3]) # Top 3 insights - else: - summary = f"{entity} {year}: No data available" - - return summary - - -def _detect_alerts(metrics: Dict) -> List[str]: - """Detect significant findings that need attention.""" - alerts = [] - - # Check each metric for alert conditions - for metric_name, metric_data in metrics.items(): - if 'error' in metric_data: - continue - - # Domain-specific alert logic - # Example: Large changes, extreme values, anomalies - if metric_name == '{metric1}' and 'change_percent' in metric_data: - if abs(metric_data['change_percent']) > 15: - alerts.append( - f"⚠ Large {metric1} change: {metric_data['change_percent']:.1f}%" - ) - - return alerts -``` - -**Why it's mandatory:** -- ✅ Users want "complete report" → 1 function does everything -- ✅ Ideal for executive dashboards -- ✅ Facilitates sales ("everything in one report") -- ✅ Much better UX (no need to know individual functions) - -**When to mention in SKILL.md:** - -```markdown -## Comprehensive Analysis (All-in-One) - -To get a complete report combining ALL metrics: - -Use the `comprehensive_{domain}_report()` function. - -This function: -- Fetches ALL available metrics -- Combines into single report -- Generates automatic summary -- Detects important alerts -- Degrades gracefully (if 1 metric fails, others work) - -Usage example: -"Generate complete report for {entity}" -"Complete dashboard for {entity}" -"All metrics for {entity}" -``` - -**Impact:** -- ✅ 10x better UX (1 query = everything) -- ✅ More useful skills for end users -- ✅ Facilitates commercial adoption - -**2.5 Specify methodologies** - -For quantitative analyses, define: - -- Mathematical formulas -- Statistical validations -- Interpretations -- Edge cases - -**See** `references/phase2-design.md` for detailed methodologies. - -## PHASE 3: Architecture - -**Objective**: STRUCTURE the agent optimally - -### Process - -**3.1 Define folder structure** - -Based on analyses and API: - -``` -agent-name/ -├── SKILL.md -├── scripts/ -│ ├── [fetch/parse/analyze separate or together?] -│ └── utils/ -│ └── [cache? rate limiter? validators?] -├── references/ -│ └── [API docs? methodologies? troubleshooting?] -└── assets/ - └── [configs? metadata?] -``` - -**Decisions**: - -- Separate scripts (modular) vs monolithic? -- Which utilities needed? -- Which references useful? -- Which configs/assets? - -**3.2 Define responsibilities** - -For each script, specify: - -- File name -- Function/purpose -- Input and output -- Specific responsibilities -- ~Expected number of lines - -**3.3 Plan references** - -Which reference files to create? - -- API guide (how to use API) -- Analysis methods (methodologies) -- Troubleshooting (common errors) -- Domain knowledge (domain context) - -**3.4 Performance strategy** - -- Cache: What to cache? TTL? -- Rate limiting: How to control? -- Optimizations: Parallelization? Lazy loading? - -**See** `references/phase3-architecture.md` for structuring patterns. - -## PHASE 4: Automatic Detection - -**Objective**: DETERMINE keywords for automatic activation - -### Process - -**4.1 List domain entities** - -- Organizations/data sources -- Main metrics -- Geography (countries, regions, states) -- Temporality (years, periods) - -**4.2 List typical actions** - -- Query: "what", "how much", "show" -- Compare: "compare", "vs", "versus" -- Rank: "top", "best", "ranking" -- Analyze: "trend", "growth", "analyze" -- Forecast: "predict", "project", "forecast" - -**4.3 List question variations** - -For each analysis type, how might the user ask? - -**4.4 Define negative scope** - -Important! What should NOT activate the skill? - -**4.5 Create precise description** - -With all keywords identified, create ~200 word description that: - -- Mentions domain -- Lists main keywords -- Gives examples -- Defines negative scope - -**See** `references/phase4-detection.md` for complete guide. - -### 🎯 3-Layer Activation System (v3.0) - -**Important**: As of Agent-Skill-Creator v3.0, we now use a **3-Layer Activation System** to achieve 95%+ activation reliability. - -#### Why 3 Layers? - -Previous skills that relied only on description achieved ~70% activation reliability. The 3-layer system dramatically improves this to 95%+ by combining: - -1. **Layer 1: Keywords** - Exact phrase matching (high precision) -2. **Layer 2: Patterns** - Regex flexible matching (coverage for variations) -3. **Layer 3: Description + NLU** - Claude's understanding (fallback for edge cases) - -#### Quick Implementation Guide - -**Layer 1: Keywords (10-15 phrases)** -```json -"activation": { - "keywords": [ - "create an agent for", - "automate workflow", - "technical analysis for", - "RSI indicator", - // 10-15 total complete phrases - ] -} -``` - -**Requirements:** -- ✅ Complete phrases (2+ words) -- ✅ Action verb + entity -- ✅ Domain-specific terms -- ❌ No single words -- ❌ No overly generic phrases - -**Layer 2: Patterns (5-7 regex)** -```json -"patterns": [ - "(?i)(create|build)\\s+(an?\\s+)?agent\\s+for", - "(?i)(automate|automation)\\s+(workflow|process)", - "(?i)(analyze|analysis)\\s+.*\\s+(stock|data)", - // 5-7 total patterns -] -``` - -**Requirements:** -- ✅ Start with `(?i)` for case-insensitivity -- ✅ Include action verbs + entities -- ✅ Allow flexible word order -- ✅ Specific enough to avoid false positives -- ✅ Flexible enough to capture variations - -**Layer 3: Enhanced Description (300-500 chars, 60+ keywords)** -``` -Comprehensive [domain] tool. [Primary capability] including [specific-feature-1], -[specific-feature-2], and [specific-feature-3]. Generates [output-type] based on -[method]. Compares [entity-type] for [analysis-type]. Monitors [target] and tracks -[metric]. Perfect for [user-persona] needing [use-case-1], [use-case-2], and -[use-case-3] using [methodology]. -``` - -**Requirements:** -- ✅ 60+ unique keywords -- ✅ All Layer 1 keywords included naturally -- ✅ Domain-specific terminology -- ✅ Use cases clearly stated -- ✅ Natural language flow - -#### Usage Sections - -Add to marketplace.json: - -```json -"usage": { - "when_to_use": [ - "User explicitly asks to [capability-1]", - "User mentions [indicator-name] or [domain-term]", - "User describes [use-case-scenario]", - // 5+ use cases - ], - "when_not_to_use": [ - "User asks for [out-of-scope-1]", - "User wants [different-skill-capability]", - // 3+ counter-cases - ] -} -``` - -#### Test Queries - -Add to marketplace.json: - -```json -"test_queries": [ - "Query testing keyword-1", - "Query testing pattern-2", - "Query testing description understanding", - "Natural language variation", - // 10+ total queries covering all layers -] -``` - -#### Complete Example - -See `references/examples/stock-analyzer-cskill/` for a complete working example demonstrating: -- All 3 layers properly configured -- 98% activation reliability -- Complete test suite -- Documentation with activation examples - -#### Quality Checklist - -Before completing Phase 4, verify: - -- [ ] 10-15 complete keyword phrases defined -- [ ] 5-7 regex patterns with verbs + entities -- [ ] 300-500 char description with 60+ keywords -- [ ] 5+ when_to_use cases documented -- [ ] 3+ when_not_to_use cases documented -- [ ] 10+ test_queries covering all layers -- [ ] Tested activation with sample queries -- [ ] Expected success rate: 95%+ - -#### Additional Resources - -- **Complete Guide**: `references/phase4-detection.md` -- **Pattern Library**: `references/activation-patterns-guide.md` (30+ reusable patterns) -- **Testing Guide**: `references/activation-testing-guide.md` (5-phase testing) -- **Quality Checklist**: `references/activation-quality-checklist.md` -- **Templates**: `references/templates/marketplace-robust-template.json` -- **Example**: `references/examples/stock-analyzer-cskill/` - ---- - -## PHASE 5: Complete Implementation - -**Objective**: IMPLEMENT everything with REAL code - -### ⚠️ MANDATORY QUALITY STANDARDS - -Before starting implementation, read `references/quality-standards.md`. - -**NEVER DO**: - -- ❌ `# TODO: implement` -- ❌ `pass` in functions -- ❌ "See external documentation" -- ❌ Configs with "YOUR_KEY_HERE" without instructions -- ❌ Empty references or just links - -**ALWAYS DO**: - -- ✅ Complete and functional code -- ✅ Detailed docstrings -- ✅ Robust error handling -- ✅ Type hints -- ✅ Validations -- ✅ Real content in references -- ✅ Configs with real values - -### 🚨 STEP 0: BEFORE EVERYTHING - Marketplace.json (MANDATORY) - -**STOP! READ THIS BEFORE CONTINUING!** - -🛑 **CRITICAL BLOCKER**: You CANNOT create ANY other file until completing this step. - -**Why marketplace.json is step 0:** - -- ❌ Without this file, the skill CANNOT be installed via `/plugin marketplace add` -- ❌ All the work creating the agent will be USELESS without it -- ❌ This is the most common error when creating agents - DO NOT make this mistake! - -#### Step 0.1: Create basic structure - -```bash -mkdir -p agent-name/.claude-plugin -``` - -#### Step 0.2: Create marketplace.json IMMEDIATELY - -Create `.claude-plugin/marketplace.json` with this content: - -```json -{ - "name": "agent-name", - "owner": { - "name": "Agent Creator", - "email": "noreply@example.com" - }, - "metadata": { - "description": "Brief agent description", - "version": "1.0.0", - "created": "2025-10-17" - }, - "plugins": [ - { - "name": "agent-plugin", - "description": "THIS DESCRIPTION MUST BE IDENTICAL to the description in SKILL.md frontmatter that you'll create in the next step", - "source": "./", - "strict": false, - "skills": ["./"] - } - ] -} -``` - -**⚠️ CRITICAL FIELDS:** - -- `name`: Agent name (same as directory name) -- `plugins[0].description`: **MUST BE EXACTLY EQUAL** to SKILL.md frontmatter description -- `plugins[0].skills`: `["./"]` points to SKILL.md in root -- `plugins[0].source`: `"./"` points to agent root - -#### Step 0.3: VALIDATE IMMEDIATELY (before continuing!) - -**Execute NOW these validation commands:** - -```bash -# 1. Validate JSON syntax -python3 -c "import json; print('✅ Valid JSON'); json.load(open('agent-name/.claude-plugin/marketplace.json'))" - -# 2. Verify file exists -ls -la agent-name/.claude-plugin/marketplace.json - -# If any command fails: STOP and fix before continuing! -``` - -**✅ CHECKLIST - You MUST complete ALL before proceeding:** - -- [ ] ✅ File `.claude-plugin/marketplace.json` created -- [ ] ✅ JSON is syntactically valid (validated with python) -- [ ] ✅ Field `name` is correct -- [ ] ✅ Field `plugins[0].description` ready to receive SKILL.md description -- [ ] ✅ Field `plugins[0].skills` = `["./"]` -- [ ] ✅ Field `plugins[0].source` = `"./"` - -**🛑 ONLY PROCEED AFTER VALIDATING ALL ITEMS ABOVE!** - ---- - -### Implementation Order (AFTER marketplace.json validated) - -Now that marketplace.json is created and validated, proceed: - -**1. Create rest of directory structure** - -```bash -mkdir -p agent-name/{scripts/utils,references,assets,data/{raw,processed,cache,analysis}} -``` - -**2. Create SKILL.md** - -Mandatory structure: - -- Frontmatter (name, description) -- When to use -- How it works (overview) -- Data source (detailed API) -- Workflows (step-by-step by question type) -- Available scripts (each explained) -- Available analyses (each explained) -- Error handling (all expected errors) -- Mandatory validations -- Performance and cache -- Keywords for detection -- Usage examples (5+ complete) - -**Size**: 5000-7000 words - -**⚠️ AFTER creating SKILL.md: SYNCHRONIZE description with marketplace.json!** - -**CRITICAL**: Now that SKILL.md is created with its frontmatter, you MUST: - -```bash -# Edit marketplace.json to update description -# Copy EXACTLY the description from SKILL.md frontmatter -# Paste in .claude-plugin/marketplace.json → plugins[0].description -``` - -**Verify synchronization:** - -- SKILL.md frontmatter description = marketplace.json plugins[0].description -- Must be IDENTICAL (word for word!) -- Without this, skill won't activate automatically - -**3. Implement Python scripts** - -**Order** (MANDATORY): - -1. **Utils first** (including helpers.py + validators/ - CRITICAL!) - - `utils/helpers.py` (🔴 MANDATORY - already specified previously) - - `utils/cache_manager.py` - - `utils/rate_limiter.py` - - `utils/validators/` (🔴 MANDATORY - see Step 3.5 below) -2. **Fetch** (API client - 1 method per API metric) -3. **Parse** (🔴 MODULAR: 1 parser per data type! - see Step 3.2 below) -4. **Analyze** (analyses - include comprehensive_report already specified!) - -**Each script (in general)**: - -- Shebang: `#!/usr/bin/env python3` -- Complete module docstring -- Organized imports -- Classes/functions with docstrings -- Type hints -- Error handling -- Logging -- Main function with argparse -- if __name__ == "__main__" - ---- - -### Step 3.2: Modular Parser Architecture (🆕 Enhancement #5 - MANDATORY!) - -**⚠️ COMMON PROBLEM:** v1.0 had 1 generic parser. When adding new data types, architecture broke. - -**Solution:** **1 specific parser per API data type!** - -**Rule:** If API returns N data types (identified in Phase 1.6) → create N specific parsers - -**Mandatory structure:** - -``` -scripts/ -├── parse_{type1}.py # Ex: parse_conditions.py -├── parse_{type2}.py # Ex: parse_progress.py -├── parse_{type3}.py # Ex: parse_yield.py -├── parse_{type4}.py # Ex: parse_production.py -└── parse_{type5}.py # Ex: parse_area.py -``` - -**Template for each parser:** - -```python -#!/usr/bin/env python3 -""" -Parser for {type} data from {API_name}. -Handles {type}-specific transformations and validations. -""" - -import pandas as pd -from typing import List, Dict, Any, Optional -import logging - -logger = logging.getLogger(__name__) - - -def parse_{type}_response(data: List[Dict]) -> pd.DataFrame: - """ - Parse API response for {type} data. - - Args: - data: Raw API response (list of dicts) - - Returns: - DataFrame with standardized schema: - - entity: str - - year: int - - {type}_value: float - - unit: str - - {type}_specific_fields: various - - Raises: - ValueError: If data is invalid - ParseError: If parsing fails - - Example: - >>> data = [{'entity': 'CORN', 'year': 2025, 'value': '15,300,000'}] - >>> df = parse_{type}_response(data) - >>> df.shape - (1, 5) - """ - if not data: - raise ValueError("Data cannot be empty") - - # Convert to DataFrame - df = pd.DataFrame(data) - - # {Type}-specific transformations - df = _clean_{type}_values(df) - df = _extract_{type}_metadata(df) - df = _standardize_{type}_schema(df) - - # Validate - _validate_{type}_schema(df) - - return df - - -def _clean_{type}_values(df: pd.DataFrame) -> pd.DataFrame: - """Clean {type}-specific values (remove formatting, convert types).""" - # Example: Remove commas from numbers - if 'value' in df.columns: - df['value'] = df['value'].astype(str).str.replace(',', '') - df['value'] = pd.to_numeric(df['value'], errors='coerce') - - # {Type}-specific cleaning - # ... - - return df - - -def _extract_{type}_metadata(df: pd.DataFrame) -> pd.DataFrame: - """Extract {type}-specific metadata fields.""" - # Example for progress data: extract % from "75% PLANTED" - # Example for condition data: extract rating from "GOOD (60%)" - # Customize per data type! - - return df - - -def _standardize_{type}_schema(df: pd.DataFrame) -> pd.DataFrame: - """ - Standardize column names and schema for {type} data. - - Output schema: - - entity: str - - year: int - - {type}_value: float (main metric) - - unit: str - - additional_{type}_fields: various - """ - # Rename columns to standard names - column_mapping = { - 'api_entity_field': 'entity', - 'api_year_field': 'year', - 'api_value_field': '{type}_value', - # Add more as needed - } - df = df.rename(columns=column_mapping) - - # Ensure types - df['year'] = df['year'].astype(int) - df['{type}_value'] = pd.to_numeric(df['{type}_value'], errors='coerce') - - return df - - -def _validate_{type}_schema(df: pd.DataFrame) -> None: - """Validate {type} DataFrame schema.""" - required_columns = ['entity', 'year', '{type}_value'] - - missing = set(required_columns) - set(df.columns) - if missing: - raise ValueError(f"Missing required columns: {missing}") - - # Type validations - if not pd.api.types.is_integer_dtype(df['year']): - raise TypeError("'year' must be integer type") - - if not pd.api.types.is_numeric_dtype(df['{type}_value']): - raise TypeError("'{type}_value' must be numeric type") - - -def aggregate_{type}(df: pd.DataFrame, by: str) -> pd.DataFrame: - """ - Aggregate {type} data by specified level. - - Args: - df: Parsed {type} DataFrame - by: Aggregation level ('national', 'state', 'region') - - Returns: - Aggregated DataFrame - - Example: - >>> agg = aggregate_{type}(df, by='state') - """ - # Aggregation logic specific to {type} - if by == 'national': - return df.groupby(['year']).agg({ - '{type}_value': 'sum', - # Add more as needed - }).reset_index() - - elif by == 'state': - return df.groupby(['year', 'state']).agg({ - '{type}_value': 'sum', - }).reset_index() - - # Add more levels... - - -def format_{type}_report(df: pd.DataFrame) -> str: - """ - Format {type} data as human-readable report. - - Args: - df: Parsed {type} DataFrame - - Returns: - Formatted string report - - Example: - >>> report = format_{type}_report(df) - >>> print(report) - "{Type} Report: ..." - """ - lines = [f"## {Type} Report\n"] - - # Format based on {type} data - # Customize per type! - - return "\n".join(lines) - - -def main(): - """Test parser with sample data.""" - # Sample data for testing - sample_data = [ - { - 'entity': 'CORN', - 'year': 2025, - 'value': '15,300,000', - # Add {type}-specific fields - } - ] - - print("Testing parse_{type}_response()...") - df = parse_{type}_response(sample_data) - print(f"✓ Parsed {len(df)} records") - print(f"✓ Columns: {list(df.columns)}") - print(f"\n{df.head()}") - - print("\nTesting aggregate_{type}()...") - agg = aggregate_{type}(df, by='national') - print(f"✓ Aggregated: {agg}") - - print("\nTesting format_{type}_report()...") - report = format_{type}_report(df) - print(report) - - -if __name__ == "__main__": - main() -``` - -**Why create modular parsers:** -- ✅ Each data type has peculiarities (progress has %, yield has bu/acre, etc) -- ✅ Scalable architecture (easy to add new types) -- ✅ Isolated tests (each parser tested independently) -- ✅ Simple maintenance (bug in 1 type doesn't affect others) -- ✅ Organized code (clear responsibilities) - -**Impact:** Professional and scalable architecture from v1.0! - ---- - -### Step 3.5: Validation System (🆕 Enhancement #10 - MANDATORY!) - -**⚠️ COMMON PROBLEM:** v1.0 without data validation. User doesn't know if data is reliable. - -**Solution:** Complete validation system in `utils/validators/` - -**Mandatory structure:** - -``` -scripts/utils/validators/ -├── __init__.py -├── parameter_validator.py # Validate function parameters -├── data_validator.py # Validate API responses -├── temporal_validator.py # Validate temporal consistency -└── completeness_validator.py # Validate data completeness -``` - -**Template 1: parameter_validator.py** - -```python -#!/usr/bin/env python3 -""" -Parameter validators for {skill-name}. -Validates user inputs before making API calls. -""" - -from typing import Any, List, Optional -from datetime import datetime - - -class ValidationError(Exception): - """Raised when validation fails.""" - pass - - -def validate_entity(entity: str, valid_entities: Optional[List[str]] = None) -> str: - """ - Validate entity parameter. - - Args: - entity: Entity name (e.g., "CORN", "SOYBEANS") - valid_entities: List of valid entities (None to skip check) - - Returns: - str: Validated and normalized entity name - - Raises: - ValidationError: If entity is invalid - - Example: - >>> validate_entity("corn") - "CORN" # Normalized to uppercase - """ - if not entity: - raise ValidationError("Entity cannot be empty") - - if not isinstance(entity, str): - raise ValidationError(f"Entity must be string, got {type(entity)}") - - # Normalize - entity = entity.strip().upper() - - # Check if valid (if list provided) - if valid_entities and entity not in valid_entities: - suggestions = [e for e in valid_entities if entity[:3] in e] - raise ValidationError( - f"Invalid entity: {entity}\n" - f"Valid options: {', '.join(valid_entities[:10])}\n" - f"Did you mean: {', '.join(suggestions[:3])}?" - ) - - return entity - - -def validate_year( - year: Optional[int], - min_year: int = 1900, - allow_future: bool = False -) -> int: - """ - Validate year parameter. - - Args: - year: Year to validate (None returns current year) - min_year: Minimum valid year - allow_future: Whether future years are allowed - - Returns: - int: Validated year - - Raises: - ValidationError: If year is invalid - - Example: - >>> validate_year(2025) - 2025 - >>> validate_year(None) - 2025 # Current year - """ - current_year = datetime.now().year - - if year is None: - return current_year - - if not isinstance(year, int): - raise ValidationError(f"Year must be integer, got {type(year)}") - - if year < min_year: - raise ValidationError( - f"Year {year} is too old (minimum: {min_year})" - ) - - if not allow_future and year > current_year: - raise ValidationError( - f"Year {year} is in the future (current: {current_year})" - ) - - return year - - -def validate_state(state: str, country: str = "US") -> str: - """Validate state/region parameter.""" - # Country-specific validation - # ... - return state.upper() - - -# Add more validators for domain-specific parameters... -``` - -**Template 2: data_validator.py** - -```python -#!/usr/bin/env python3 -""" -Data validators for {skill-name}. -Validates API responses and analysis outputs. -""" - -import pandas as pd -from typing import Dict, List, Any -from dataclasses import dataclass -from enum import Enum - - -class ValidationLevel(Enum): - """Severity levels for validation results.""" - CRITICAL = "critical" # Must fix - WARNING = "warning" # Should review - INFO = "info" # FYI - - -@dataclass -class ValidationResult: - """Single validation check result.""" - check_name: str - level: ValidationLevel - passed: bool - message: str - details: Optional[Dict] = None - - -class ValidationReport: - """Collection of validation results.""" - - def __init__(self): - self.results: List[ValidationResult] = [] - - def add(self, result: ValidationResult): - """Add validation result.""" - self.results.append(result) - - def has_critical_issues(self) -> bool: - """Check if any critical issues found.""" - return any( - r.level == ValidationLevel.CRITICAL and not r.passed - for r in self.results - ) - - def all_passed(self) -> bool: - """Check if all validations passed.""" - return all(r.passed for r in self.results) - - def get_warnings(self) -> List[str]: - """Get all warning messages.""" - return [ - r.message for r in self.results - if r.level == ValidationLevel.WARNING and not r.passed - ] - - def get_summary(self) -> str: - """Get summary of validation results.""" - total = len(self.results) - passed = sum(1 for r in self.results if r.passed) - critical = sum( - 1 for r in self.results - if r.level == ValidationLevel.CRITICAL and not r.passed - ) - - return ( - f"Validation: {passed}/{total} passed " - f"({critical} critical issues)" - ) - - -class DataValidator: - """Validates API responses and DataFrames.""" - - def validate_response(self, data: Any) -> ValidationReport: - """ - Validate raw API response. - - Args: - data: Raw API response - - Returns: - ValidationReport with results - """ - report = ValidationReport() - - # Check 1: Not empty - report.add(ValidationResult( - check_name="not_empty", - level=ValidationLevel.CRITICAL, - passed=bool(data), - message="Data is empty" if not data else "Data present" - )) - - # Check 2: Correct type - expected_type = (list, dict) - is_correct_type = isinstance(data, expected_type) - report.add(ValidationResult( - check_name="correct_type", - level=ValidationLevel.CRITICAL, - passed=is_correct_type, - message=f"Expected {expected_type}, got {type(data)}" - )) - - # Check 3: Has expected structure - if isinstance(data, dict): - has_data_key = 'data' in data - report.add(ValidationResult( - check_name="has_data_key", - level=ValidationLevel.WARNING, - passed=has_data_key, - message="Response has 'data' key" if has_data_key else "No 'data' key" - )) - - return report - - def validate_dataframe(self, df: pd.DataFrame, data_type: str) -> ValidationReport: - """ - Validate parsed DataFrame. - - Args: - df: Parsed DataFrame - data_type: Type of data (for type-specific checks) - - Returns: - ValidationReport - """ - report = ValidationReport() - - # Check 1: Not empty - report.add(ValidationResult( - check_name="not_empty", - level=ValidationLevel.CRITICAL, - passed=len(df) > 0, - message=f"DataFrame has {len(df)} rows" - )) - - # Check 2: Required columns - required = ['entity', 'year'] # Customize per type - missing = set(required) - set(df.columns) - report.add(ValidationResult( - check_name="required_columns", - level=ValidationLevel.CRITICAL, - passed=len(missing) == 0, - message=f"Missing columns: {missing}" if missing else "All required columns present" - )) - - # Check 3: No excessive NaN values - if len(df) > 0: - nan_pct = (df.isna().sum() / len(df) * 100).max() - report.add(ValidationResult( - check_name="nan_threshold", - level=ValidationLevel.WARNING, - passed=nan_pct < 30, - message=f"Max NaN: {nan_pct:.1f}% ({'OK' if nan_pct < 30 else 'HIGH'})" - )) - - # Check 4: Data types correct - if 'year' in df.columns: - is_int = pd.api.types.is_integer_dtype(df['year']) - report.add(ValidationResult( - check_name="year_type", - level=ValidationLevel.CRITICAL, - passed=is_int, - message="'year' is integer" if is_int else "'year' is not integer" - )) - - return report - - -def validate_{type}_output(result: Dict) -> ValidationReport: - """ - Validate analysis output for {type}. - - Args: - result: Analysis result dict - - Returns: - ValidationReport - """ - report = ValidationReport() - - # Check required keys - required_keys = ['year', 'year_info', 'data'] - for key in required_keys: - report.add(ValidationResult( - check_name=f"has_{key}", - level=ValidationLevel.CRITICAL, - passed=key in result, - message=f"'{key}' present" if key in result else f"Missing '{key}'" - )) - - # Check data quality - if 'data' in result and result['data']: - report.add(ValidationResult( - check_name="data_not_empty", - level=ValidationLevel.CRITICAL, - passed=True, - message="Data is present" - )) - - return report - - -# Main for testing -if __name__ == "__main__": - print("Testing validators...") - - # Test entity validator - print("\n1. Testing validate_entity():") - try: - entity = validate_entity("corn", ["CORN", "SOYBEANS"]) - print(f" ✓ Valid: {entity}") - except ValidationError as e: - print(f" ✗ Error: {e}") - - # Test year validator - print("\n2. Testing validate_year():") - year = validate_year(2025) - print(f" ✓ Valid: {year}") - - # Test DataValidator - print("\n3. Testing DataValidator:") - validator = DataValidator() - sample_data = [{'entity': 'CORN', 'year': 2025}] - report = validator.validate_response(sample_data) - print(f" {report.get_summary()}") -``` - -**Template 3: temporal_validator.py** - -```python -#!/usr/bin/env python3 -""" -Temporal validators for {skill-name}. -Checks temporal consistency and data age. -""" - -import pandas as pd -from datetime import datetime, timedelta -from typing import List -from .data_validator import ValidationResult, ValidationReport, ValidationLevel - - -def validate_temporal_consistency(df: pd.DataFrame) -> ValidationReport: - """ - Check temporal consistency in data. - - Validations: - - No future dates - - Years in valid range - - No suspicious gaps in time series - - Data age is acceptable - - Args: - df: DataFrame with 'year' column - - Returns: - ValidationReport - """ - report = ValidationReport() - current_year = datetime.now().year - - if 'year' not in df.columns: - report.add(ValidationResult( - check_name="has_year_column", - level=ValidationLevel.CRITICAL, - passed=False, - message="Missing 'year' column" - )) - return report - - # Check 1: No future years - max_year = df['year'].max() - report.add(ValidationResult( - check_name="no_future_years", - level=ValidationLevel.CRITICAL, - passed=max_year <= current_year, - message=f"Max year: {max_year} ({'valid' if max_year <= current_year else 'FUTURE!'})" - )) - - # Check 2: Years in reasonable range - min_year = df['year'].min() - is_reasonable = min_year >= 1900 - report.add(ValidationResult( - check_name="reasonable_year_range", - level=ValidationLevel.WARNING, - passed=is_reasonable, - message=f"Year range: {min_year}-{max_year}" - )) - - # Check 3: Data age (is data recent enough?) - data_age_years = current_year - max_year - is_recent = data_age_years <= 2 - report.add(ValidationResult( - check_name="data_freshness", - level=ValidationLevel.WARNING, - passed=is_recent, - message=f"Data age: {data_age_years} years ({'recent' if is_recent else 'STALE'})" - )) - - # Check 4: No suspicious gaps in time series - if len(df['year'].unique()) > 2: - years_sorted = sorted(df['year'].unique()) - gaps = [ - years_sorted[i+1] - years_sorted[i] - for i in range(len(years_sorted)-1) - ] - max_gap = max(gaps) if gaps else 0 - has_large_gap = max_gap > 2 - - report.add(ValidationResult( - check_name="no_large_gaps", - level=ValidationLevel.WARNING, - passed=not has_large_gap, - message=f"Max gap: {max_gap} years" + (" (suspicious)" if has_large_gap else "") - )) - - return report - - -def validate_week_number(week: int, year: int) -> ValidationResult: - """Validate week number is in valid range for year.""" - # Most data types use weeks 1-53 - is_valid = 1 <= week <= 53 - - return ValidationResult( - check_name="valid_week", - level=ValidationLevel.CRITICAL, - passed=is_valid, - message=f"Week {week} ({'valid' if is_valid else 'INVALID: must be 1-53'})" - ) - - -# Add more temporal validators as needed... -``` - -**Template 4: completeness_validator.py** - -```python -#!/usr/bin/env python3 -""" -Completeness validators for {skill-name}. -Checks data completeness and coverage. -""" - -import pandas as pd -from typing import List, Set -from .data_validator import ValidationResult, ValidationReport, ValidationLevel - - -def validate_completeness( - df: pd.DataFrame, - expected_entities: Optional[List[str]] = None, - expected_years: Optional[List[int]] = None -) -> ValidationReport: - """ - Validate data completeness. - - Args: - df: DataFrame to validate - expected_entities: Expected entities (None to skip) - expected_years: Expected years (None to skip) - - Returns: - ValidationReport - """ - report = ValidationReport() - - # Check 1: All expected entities present - if expected_entities: - actual_entities = set(df['entity'].unique()) - expected_set = set(expected_entities) - missing = expected_set - actual_entities - - report.add(ValidationResult( - check_name="all_entities_present", - level=ValidationLevel.WARNING, - passed=len(missing) == 0, - message=f"Missing entities: {missing}" if missing else "All entities present", - details={'missing': list(missing)} - )) - - # Check 2: All expected years present - if expected_years: - actual_years = set(df['year'].unique()) - expected_set = set(expected_years) - missing = expected_set - actual_years - - report.add(ValidationResult( - check_name="all_years_present", - level=ValidationLevel.WARNING, - passed=len(missing) == 0, - message=f"Missing years: {missing}" if missing else "All years present" - )) - - # Check 3: No excessive nulls in critical columns - critical_columns = ['entity', 'year'] # Customize - for col in critical_columns: - if col in df.columns: - null_count = df[col].isna().sum() - report.add(ValidationResult( - check_name=f"{col}_no_nulls", - level=ValidationLevel.CRITICAL, - passed=null_count == 0, - message=f"'{col}' has {null_count} nulls" - )) - - # Check 4: Coverage percentage - if expected_entities and expected_years: - expected_total = len(expected_entities) * len(expected_years) - actual_total = len(df) - coverage_pct = (actual_total / expected_total) * 100 if expected_total > 0 else 0 - - report.add(ValidationResult( - check_name="coverage_percentage", - level=ValidationLevel.INFO, - passed=coverage_pct >= 80, - message=f"Coverage: {coverage_pct:.1f}% ({actual_total}/{expected_total})" - )) - - return report -``` - -**Integration in analysis functions:** - -```python -def {analysis_function}(entity: str, year: Optional[int] = None, ...) -> Dict: - """Analysis function with validation.""" - from utils.validators.parameter_validator import validate_entity, validate_year - from utils.validators.data_validator import DataValidator - from utils.validators.temporal_validator import validate_temporal_consistency - - # VALIDATE INPUTS (before doing anything!) - entity = validate_entity(entity, valid_entities=[...]) - year = validate_year(year) - - # Fetch data - data = fetch_{metric}(entity, year) - - # VALIDATE API RESPONSE - validator = DataValidator() - response_validation = validator.validate_response(data) - - if response_validation.has_critical_issues(): - raise DataQualityError( - f"API response validation failed: {response_validation.get_summary()}" - ) - - # Parse - df = parse_{type}(data) - - # VALIDATE PARSED DATA - df_validation = validator.validate_dataframe(df, '{type}') - temporal_validation = validate_temporal_consistency(df) - - if df_validation.has_critical_issues(): - raise DataQualityError( - f"Data validation failed: {df_validation.get_summary()}" - ) - - # Analyze - results = analyze(df) - - # Return with validation info - return { - 'data': results, - 'year': year, - 'year_info': format_year_message(year, year_requested), - 'validation': { - 'passed': df_validation.all_passed(), - 'warnings': df_validation.get_warnings(), - 'report': df_validation.get_summary() - } - } -``` - -**Impact:** -- ✅ Reliable data (validated at multiple layers) -- ✅ Transparency (user sees validation report) -- ✅ Clear error messages (not just "generic error") -- ✅ Problem detection (gaps, nulls, inconsistencies) - ---- - -**4. Write references** - -For each reference file: - -- 1000-2000 words -- Useful content (examples, methodologies, guides) -- Well structured (headings, lists, code blocks) -- Well-formatted markdown - -**5. Create assets** - -- Syntactically valid JSONs -- Real values with comments -- Logical structure - -**6. Write README.md** - -- Step-by-step installation -- Required configuration -- Usage examples -- Troubleshooting - -**7. Create DECISIONS.md** - -Document all decisions made: - -- Which API chosen and why -- Which analyses defined and justification -- Structure chosen and rationale -- Trade-offs considered - -**8. Create VERSION and CHANGELOG.md** (🆕 Enhancement #7 - Versioning) - -**8.1 Create VERSION file:** - -``` -1.0.0 -``` - -**8.2 Create CHANGELOG.md:** - -```markdown -# Changelog - -All notable changes to {skill-name} will be documented here. - -Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). -Versioning follows [Semantic Versioning](https://semver.org/). - -## [1.0.0] - {current_date} - -### Added - -**Core Functionality:** -- {function1}: {Description of what it does} -- {function2}: {Description of what it does} -- {function3}: {Description of what it does} -... - -**Data Sources:** -- {API_name}: {Coverage description} -- Authentication: {auth_method} -- Rate limit: {limit} - -**Analysis Capabilities:** -- {analysis1}: {Description and methodology} -- {analysis2}: {Description and methodology} -... - -**Utilities:** -- Cache system with {TTL} TTL -- Rate limiting: {limit} per {period} -- Error handling with automatic retries -- Data validation and quality checks - -### Data Coverage - -**Metrics implemented:** -- {metric1}: {Coverage details} -- {metric2}: {Coverage details} -... - -**Geographic coverage:** {geo_coverage} -**Temporal coverage:** {temporal_coverage} - -### Known Limitations - -- {limitation1} -- {limitation2} -... - -### Planned for v2.0 - -- {planned_feature1} -- {planned_feature2} -... - -## [Unreleased] - -### Planned - -- Add support for {feature} -- Improve performance for {scenario} -- Expand coverage to {new_area} -``` - -**8.3 Update marketplace.json with version:** - -Edit `.claude-plugin/marketplace.json` to include: - -```json -{ - "metadata": { - "description": "...", - "version": "1.0.0", - "created": "{current_date}", - "updated": "{current_date}" - } -} -``` - -**8.4 Create .bumpversion.cfg (optional):** - -If you want version automation: - -```ini -[bumpversion] -current_version = 1.0.0 -commit = False -tag = False - -[bumpversion:file:VERSION] - -[bumpversion:file:.claude-plugin/marketplace.json] -search = "version": "{current_version}" -replace = "version": "{new_version}" - -[bumpversion:file:CHANGELOG.md] -search = ## [Unreleased] -replace = ## [Unreleased] - -## [{new_version}] - {now:%Y-%m-%d} -``` - -**Impact:** -- ✅ Change traceability -- ✅ Professionalism -- ✅ Facilitates future updates -- ✅ Users know what changed between versions - -**9. Create INSTALLATION.md** (Didactic Tutorial) - -[Content of INSTALLATION.md as previously specified] - -### Practical Implementation - -**Create agent in subdirectory**: - -```bash -# Agent name based on domain/objective -agent_name="nass-usda-agriculture" # example - -# Create structure -mkdir -p $agent_name/{scripts/utils,references,assets,data} - -# Implement each file -# [Claude creates each file with Write tool] -``` - -**At the end, inform user**: - -``` -✅ Agent created in ./{agent_name}/ - -📁 Structure: -- .claude-plugin/marketplace.json ✅ (installation + version) -- SKILL.md (6,200 words) -- scripts/ (2,500+ lines of code) - ├─ utils/helpers.py ✅ (temporal context) - ├─ utils/validators/ ✅ (4 validators, ~800 lines) - ├─ parse_{type}*.py ✅ (1 per data type, modular) - └─ comprehensive_{domain}_report() ✅ -- tests/ (25+ tests, ~800 lines) ✅ - ├─ test_integration.py (end-to-end) - ├─ test_parse.py (all parsers) - ├─ test_helpers.py (temporal) - └─ test_validation.py (validators) -- references/ (5,000 words) -- assets/ (2 configs) -- README.md (1,000+ words with Testing section) -- INSTALLATION.md (1,500 words) ✅ -- DECISIONS.md (justifications) -- VERSION (1.0.0) ✅ -- CHANGELOG.md (release notes) ✅ - -🚀 To install: -/plugin marketplace add ./{agent_name} - -💡 Usage examples: -"[example 1]" -"[example 2]" -``` - -**See** `references/phase5-implementation.md` for complete implementation guide. - -## Complete Flow: Step-by-Step - -### User Input - -User describes workflow/objective: - -``` -"Every day I download US crop data from USDA, -compare current year vs previous, create state ranking -by production, and generate report. Takes 2 hours. -Automate this." -``` - -### Autonomous Execution - -**Claude executes internally** (doesn't need to show everything): - -**PHASE 1**: Discovery (~5-10 min) - -``` -[WebSearch: "USDA API free agriculture data"] -[WebFetch: NASS API docs] -[Compare: NASS vs ERS vs FAO] -→ DECISION: NASS QuickStats API - Justification: Free, data since 1866, all crops, state-level -``` - -**PHASE 2**: Design (~5 min) - -``` -[Analyze: "compare years", "state ranking", "generate report"] -→ DEFINE analyses: - 1. YoY comparison (compare years) - 2. State ranking (state ranking) - 3. Trend analysis (if user asks for trends) - 4. Report generator (generate report) -``` - -**PHASE 3**: Architecture (~5 min) - -``` -→ STRUCTURE: - scripts/ - - fetch_nass.py (API requests) - - parse_nass.py (parsing) - - analyze_nass.py (YoY, ranking, trends) - - generate_report.py (report) - utils/ - - cache_manager.py - - rate_limiter.py - references/ - - nass-api-guide.md - - analysis-methods.md - - report-templates.md - assets/ - - config.json - - metadata.json -``` - -**PHASE 4**: Detection (~2 min) - -``` -→ KEYWORDS: - Entities: USDA, NASS, agriculture, crops - Commodities: corn, soybeans, wheat - Metrics: production, area, yield - Actions: compare, ranking, trend - Geography: US, states, Iowa, Illinois - -→ DESCRIPTION: "This skill should be used when user - asks about US agriculture, production, area, - crop yield..." -``` - -**PHASE 5**: Implementation (~45 min) - -``` -[Write: SKILL.md] ✅ 6,000 words -[Write: fetch_nass.py] ✅ 280 lines -[Write: parse_nass.py] ✅ 180 lines -[Write: analyze_nass.py] ✅ 520 lines -[Write: generate_report.py] ✅ 200 lines -[Write: utils/cache_manager.py] ✅ 120 lines -[Write: utils/rate_limiter.py] ✅ 110 lines -[Write: references/nass-api-guide.md] ✅ 1,500 words -[Write: references/analysis-methods.md] ✅ 2,000 words -[Write: references/report-templates.md] ✅ 1,000 words -[Write: assets/config.json] ✅ -[Write: assets/metadata.json] ✅ -[Write: README.md] ✅ 800 words -[Write: DECISIONS.md] ✅ 600 words -``` - -### User Output - -``` -✅ Agent created: ./usda-agriculture-agent/ - -📊 Technical Decisions: -- API: USDA NASS QuickStats (free, data since 1866) -- Analyses: YoY, Ranking, Trends, Report Generation -- Structure: 4 main scripts + 2 utils -- Cache: Historical permanent, current 7 days - -📁 Files Created: -- SKILL.md: 6,000 words -- Python code: 2,500+ lines - ├─ Modular parsers (1 per type) - ├─ Validation system (800 lines) - ├─ Temporal helpers - └─ comprehensive_report() -- Tests: 25+ tests (800 lines) -- References: 4,500 words -- Configs: 2 files -- README: Complete (with Testing) -- INSTALLATION.md: Didactic tutorial -- VERSION: 1.0.0 -- CHANGELOG.md: Complete release notes - -🎯 Estimated Savings: -- Before: 2 hours/day -- After: 3 minutes/day -- Savings: 98.5% (117h/month → 1.5h/month) - -🚀 To install and use: - -# 1. Get API key (free): -Visit: https://quickstats.nass.usda.gov/api#registration - -# 2. Configure: -export NASS_API_KEY="your_key_here" - -# 3. Install skill: -/plugin marketplace add ./usda-agriculture-agent - -# 4. Use (examples): -"US corn production in 2023" -"Compare soybeans this year vs last year" -"Ranking of wheat producing states" -"Generate current crop report" -``` - -## Detailed References - -For details of each phase, load references: - -- `references/phase1-discovery.md`: API research and decision -- `references/phase2-design.md`: Analysis definition -- `references/phase3-architecture.md`: Project structuring -- `references/phase4-detection.md`: Keywords and automatic activation -- `references/phase5-implementation.md`: Code implementation -- `references/quality-standards.md`: Mandatory standards -- `references/examples.md`: Complete examples of created agents - -## Meta-Skill Usage Examples - -### Example 1: Simple Workflow - -``` -👤 "Automate: download weather data, calculate averages, - generate chart. I do this every week, takes 1h." - -🤖 [Activates agent-creator] - [Phase 1]: Research → NOAA API - [Phase 2]: Defines → Download, Aggregation, Visualization - [Phase 3]: Structure → 3 scripts + 2 utils - [Phase 4]: Keywords → weather, climate, temperature, NOAA - [Phase 5]: Implements everything - - ✅ Agent created: ./weather-analysis-agent/ - [Installation instructions] -``` - -### Example 2: Complex Workflow - -``` -👤 "I need an agent for stock financial analysis: - fetch prices, calculate technical indicators (RSI, MACD), - compare with benchmarks, generate alerts. Daily, 3h." - -🤖 [Activates agent-creator] - [Phase 1]: Research → Alpha Vantage API (or Yahoo Finance) - [Phase 2]: Defines → Price fetching, Technical indicators, - Benchmark comparison, Alert system - [Phase 3]: Structure → 5 scripts + 4 utils - [Phase 4]: Keywords → stock, RSI, MACD, technical analysis - [Phase 5]: Implements - - ✅ Agent created: ./stock-technical-analysis-agent/ -``` - -### Example 3: Just Vague Description - -``` -👤 "Create an agent for Brazilian agriculture" - -🤖 [Activates agent-creator] - - "Got it! I'll create an agent for Brazilian agriculture. - - A few quick questions: - - Focus on which crops? (soy, corn, coffee, all?) - - Desired analyses? (production, prices, exports?) - - Preferred source? (CONAB, IBGE, both?) - - Or I can decide based on most common use cases - (grain production via CONAB). Prefer I decide?" - -👤 "You decide, focus on grain production." - -🤖 [Phase 1]: CONAB Grain Survey - [Phase 2]: YoY, Ranking, Regional, Trends - [Phase 3-5]: Creates everything - - ✅ Agent created: ./conab-agriculture-agent/ -``` - ---- - -## PHASE 6: Test Suite Generation (🆕 Enhancement #4 - MANDATORY!) - -**Objective**: Generate comprehensive test suite that validates ALL functions - -**⚠️ COMMON PROBLEM:** v1.0 without tests. Difficult to validate code works, impossible to do regression testing. - -**Solution:** Automatically generate 25+ tests covering all layers! - -### Test Structure - -``` -tests/ -├── __init__.py -├── test_fetch.py # Test API fetch functions -├── test_parse.py # Test each parser -├── test_analyze.py # Test analysis functions -├── test_integration.py # End-to-end tests -├── test_validation.py # Test validators -├── test_helpers.py # Test temporal helpers -└── conftest.py # Shared fixtures (pytest) -``` - -### Template 1: test_integration.py (MAIN!) - -```python -#!/usr/bin/env python3 -""" -Integration tests for {skill-name}. -Tests complete workflows from query to result. -""" - -import sys -from pathlib import Path - -# Add scripts to path -sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts')) - -from analyze_{domain} import ( - {function1}, - {function2}, - {function3}, - comprehensive_{domain}_report -) - - -def test_{function1}_basic(): - """Test {function1} with auto-year detection.""" - print(f"\n✓ Testing {function1}()...") - - try: - # Test auto-year detection (year=None) - result = {function1}('{example_entity}') - - # Validations - assert 'year' in result, "Missing 'year' in result" - assert 'year_info' in result, "Missing 'year_info'" - assert 'data' in result, "Missing 'data'" - assert result['year'] >= 2024, f"Year too old: {result['year']}" - - print(f" ✓ Auto-year working: {result['year']}") - print(f" ✓ Year info: {result['year_info']}") - print(f" ✓ Data present: {len(result.get('data', {}))} fields") - - return True - - except Exception as e: - print(f" ✗ FAILED: {e}") - import traceback - traceback.print_exc() - return False - - -def test_{function1}_specific_year(): - """Test {function1} with specific year.""" - print(f"\n✓ Testing {function1}(year=2024)...") - - try: - result = {function1}('{example_entity}', year=2024) - - assert result['year'] == 2024, "Requested year not used" - assert result['year_requested'] == 2024, "year_requested not tracked" - - print(f" ✓ Specific year working: {result['year']}") - - return True - - except Exception as e: - print(f" ✗ FAILED: {e}") - return False - - -def test_{function2}_comparison(): - """Test {function2} (comparison function).""" - print(f"\n✓ Testing {function2}()...") - - try: - result = {function2}('{example_entity}', year1=2024, year2=2023) - - # Validations specific to comparison - assert 'change_percent' in result, "Missing 'change_percent'" - assert isinstance(result['change_percent'], (int, float)), "change_percent not numeric" - - print(f" ✓ Comparison working: {result.get('change_percent')}% change") - - return True - - except Exception as e: - print(f" ✗ FAILED: {e}") - return False - - -def test_comprehensive_report(): - """Test comprehensive report (all-in-one function).""" - print(f"\n✓ Testing comprehensive_{domain}_report()...") - - try: - result = comprehensive_{domain}_report('{example_entity}') - - # Validations - assert 'metrics' in result, "Missing 'metrics'" - assert 'summary' in result, "Missing 'summary'" - assert 'alerts' in result, "Missing 'alerts'" - assert isinstance(result['metrics'], dict), "'metrics' must be dict" - - metrics_count = len(result['metrics']) - print(f" ✓ Comprehensive report working") - print(f" ✓ Metrics combined: {metrics_count}") - print(f" ✓ Summary: {result['summary'][:100]}...") - print(f" ✓ Alerts: {len(result['alerts'])}") - - return True - - except Exception as e: - print(f" ✗ FAILED: {e}") - return False - - -def test_validation_integration(): - """Test that validation is integrated in functions.""" - print(f"\n✓ Testing validation integration...") - - try: - result = {function1}('{example_entity}') - - # Check validation info is present - assert 'validation' in result, "Missing 'validation' info" - assert 'passed' in result['validation'], "Missing validation.passed" - assert 'report' in result['validation'], "Missing validation.report" - - print(f" ✓ Validation present: {result['validation']['report']}") - - return True - - except Exception as e: - print(f" ✗ FAILED: {e}") - return False - - -def main(): - """Run all integration tests.""" - print("=" * 70) - print("INTEGRATION TESTS - {skill-name}") - print("=" * 70) - - tests = [ - ("Auto-year detection", test_{function1}_basic), - ("Specific year", test_{function1}_specific_year), - ("Comparison function", test_{function2}_comparison), - ("Comprehensive report", test_comprehensive_report), - ("Validation integration", test_validation_integration), - ] - - results = [] - for test_name, test_func in tests: - passed = test_func() - results.append((test_name, passed)) - - # Summary - print("\n" + "=" * 70) - print("SUMMARY") - print("=" * 70) - - for test_name, passed in results: - status = "✅ PASS" if passed else "❌ FAIL" - print(f"{status}: {test_name}") - - passed_count = sum(1 for _, p in results if p) - total_count = len(results) - - print(f"\nResults: {passed_count}/{total_count} passed") - - return passed_count == total_count - - -if __name__ == "__main__": - success = main() - sys.exit(0 if success else 1) -``` - -### Template 2: test_parse.py - -```python -#!/usr/bin/env python3 -"""Tests for parsers.""" - -import sys -from pathlib import Path -import pandas as pd - -sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts')) - -from parse_{type1} import parse_{type1}_response -from parse_{type2} import parse_{type2}_response -# Import all parsers... - - -def test_parse_{type1}(): - """Test {type1} parser.""" - print("\n✓ Testing parse_{type1}_response()...") - - sample_data = [ - {'{field1}': 'VALUE1', '{field2}': 2025, '{field3}': '1,234,567'} - ] - - try: - df = parse_{type1}_response(sample_data) - - # Validations - assert isinstance(df, pd.DataFrame), "Must return DataFrame" - assert len(df) == 1, f"Expected 1 row, got {len(df)}" - assert 'entity' in df.columns, "Missing 'entity' column" - assert 'year' in df.columns, "Missing 'year' column" - - print(f" ✓ Parsed: {len(df)} records") - print(f" ✓ Columns: {list(df.columns)}") - - return True - - except Exception as e: - print(f" ✗ FAILED: {e}") - return False - - -# Repeat for all parsers... - -def main(): - """Run parser tests.""" - tests = [ - test_parse_{type1}, - test_parse_{type2}, - # Add all... - ] - - passed = sum(1 for test in tests if test()) - print(f"\nResults: {passed}/{len(tests)} passed") - - return passed == len(tests) - - -if __name__ == "__main__": - sys.exit(0 if main() else 1) -``` - -### Template 3: test_helpers.py - -```python -#!/usr/bin/env python3 -"""Tests for temporal helpers.""" - -import sys -from pathlib import Path -from datetime import datetime - -sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts')) - -from utils.helpers import ( - get_current_{domain}_year, - get_{domain}_year_with_fallback, - should_try_previous_year, - format_year_message -) - - -def test_get_current_year(): - """Test current year detection.""" - year = get_current_{domain}_year() - current = datetime.now().year - - assert year == current, f"Expected {current}, got {year}" - print(f"✓ Current year: {year}") - return True - - -def test_year_with_fallback(): - """Test year fallback logic.""" - primary, fallback = get_{domain}_year_with_fallback(2024) - - assert primary == 2024, "Primary should be 2024" - assert fallback == 2023, "Fallback should be 2023" - - print(f"✓ Fallback: {primary} → {fallback}") - return True - - -def test_format_year_message(): - """Test year message formatting.""" - msg = format_year_message(2024, 2025) - - assert '2024' in msg, "Must mention year used" - assert '2025' in msg, "Must mention year requested" - - print(f"✓ Message: {msg}") - return True - - -def main(): - """Run helper tests.""" - tests = [ - test_get_current_year, - test_year_with_fallback, - test_format_year_message - ] - - passed = sum(1 for test in tests if test()) - print(f"\nResults: {passed}/{len(tests)} passed") - - return passed == len(tests) - - -if __name__ == "__main__": - sys.exit(0 if main() else 1) -``` - -### Minimum Test Coverage - -**For skill to be considered complete, needs:** - -- [ ] test_integration.py with ≥5 end-to-end tests -- [ ] test_parse.py with 1 test per parser -- [ ] test_analyze.py with 1 test per analysis function -- [ ] test_helpers.py with ≥3 tests -- [ ] test_validation.py with ≥5 tests -- [ ] **Total:** ≥25 tests -- [ ] **Coverage:** ≥80% of code -- [ ] **All tests PASS** - -### How to test - -Include in README.md: - -```markdown -## Testing - -### Run All Tests - -```bash -cd {skill-name} -python3 tests/test_integration.py -``` - -### Run Specific Tests - -```bash -python3 tests/test_parse.py -python3 tests/test_helpers.py -python3 tests/test_validation.py -``` - -### Expected Output - -``` -====================================================================== -INTEGRATION TESTS - {skill-name} -====================================================================== - -✓ Testing {function1}()... - ✓ Auto-year working: 2025 - ✓ Data present: 8 fields - -✓ Testing {function2}()... - ✓ Comparison working: +12.3% change - -... - -====================================================================== -SUMMARY -====================================================================== -✅ PASS: Auto-year detection -✅ PASS: Specific year -✅ PASS: Comparison function -✅ PASS: Comprehensive report -✅ PASS: Validation integration - -Results: 5/5 passed -``` -``` - -### Test Suite Benefits - -- ✅ Reliability: Tested and working code -- ✅ Regression testing: Detects breaks when modifying -- ✅ Executable documentation: Tests show how to use -- ✅ CI/CD ready: Can run automatically -- ✅ Professionalism: Production-quality skills - -**Impact:** Generated skills are tested and reliable from v1.0! - ---- - -## Agent Creation Workflow: Checklist - -When creating an agent, follow this checklist RIGOROUSLY in order: - ---- - -### 🚨 STEP 0: MANDATORY - FIRST STEP - -**Execute BEFORE anything else:** - -- [ ] 🚨 Create `.claude-plugin/marketplace.json` -- [ ] 🚨 Validate JSON syntax with python -- [ ] 🚨 Verify mandatory fields filled -- [ ] 🚨 Confirm: "Marketplace.json created and validated - can proceed" - -**🛑 DO NOT PROCEED without completing ALL items above!** - ---- - -### ✅ Phase 1-4: Planning - -- [ ] Domain identified -- [ ] API researched and decided (with justification) -- [ ] **API completeness analysis** (Phase 1.6 - coverage ≥50%) -- [ ] Analyses defined (4-6 main + comprehensive_report) -- [ ] Structure planned (modular parsers, validators/) -- [ ] Keywords determined (≥60 unique) - ---- - -### ✅ Phase 5: Implementation - -- [ ] .claude-plugin/marketplace.json created FIRST -- [ ] marketplace.json validated (syntax + fields) -- [ ] SKILL.md created with correct frontmatter -- [ ] **CRITICAL:** SKILL.md description copied to marketplace.json → plugins[0].description (IDENTICAL!) -- [ ] Validate synchronization: SKILL.md description === marketplace.json -- [ ] **MANDATORY:** utils/helpers.py created (temporal context) -- [ ] **MANDATORY:** utils/validators/ created (4 validators) -- [ ] **MANDATORY:** Modular parsers (1 per data type) -- [ ] **MANDATORY:** comprehensive_{domain}_report() implemented -- [ ] DECISIONS.md documenting choices -- [ ] VERSION file created (e.g., 1.0.0) -- [ ] CHANGELOG.md created with complete v1.0.0 entry -- [ ] marketplace.json with version field -- [ ] Implement functional code (no TODOs) -- [ ] Write complete docstrings -- [ ] Add error handling -- [ ] Write references with useful content -- [ ] Create real configs -- [ ] Write complete README -- [ ] INSTALLATION.md with complete tutorial - ---- - -### ✅ Phase 6: Test Suite - -- [ ] tests/ directory created -- [ ] test_integration.py with ≥5 end-to-end tests -- [ ] test_parse.py with 1 test per parser -- [ ] test_analyze.py with 1 test per analysis function -- [ ] test_helpers.py with ≥3 tests -- [ ] test_validation.py with ≥5 tests -- [ ] **Total:** ≥25 tests implemented -- [ ] **ALL tests PASS** (execute and validate!) -- [ ] "Testing" section added to README.md - ---- - -### ✅ Final Validation - -- [ ] Validate marketplace.json again (syntax + synchronized description) -- [ ] Validate other JSONs (configs, assets) -- [ ] Verify imports work -- [ ] Check no placeholder/TODO -- [ ] Test main logic manually -- [ ] Verify README has all instructions -- [ ] Calculate estimated ROI (time before vs after) - ---- - -### 🚀 MANDATORY TEST - DO NOT SKIP THIS STEP! - -**Execute this command MANDATORY before delivering:** - -```bash -cd /path/to/skills -/plugin marketplace add ./agent-name -``` - -**Verifications:** - -- [ ] ✅ Command executed without errors -- [ ] ✅ Skill appears in installed plugins list -- [ ] ✅ Claude recognizes the skill (do test question) - -**🛑 If test fails:** - -1. Verify marketplace.json exists -2. Verify JSON is valid -3. Verify description is synchronized -4. Fix and test again - -**Only deliver to user AFTER installation test passes!** - ---- - -### ✅ Deliver to User - -- [ ] Show created structure -- [ ] Summarize main decisions -- [ ] List files and sizes -- [ ] Give installation instructions (command tested above) -- [ ] Give 3-5 usage examples -- [ ] Inform estimated ROI -- [ ] **Confirm: "Skill tested and installed successfully"** - -## User Communication - -### During Creation - -**Show high-level progress**: - -``` -🔍 Phase 1: Researching APIs... - ✓ 5 options found - ✓ Decided: NASS API (free, complete data) - -🎨 Phase 2: Defining analyses... - ✓ 15 typical questions identified - ✓ 5 main analyses defined - -🏗️ Phase 3: Structuring project... - ✓ 3 scripts + 2 utils planned - -🎯 Phase 4: Defining detection... - ✓ 50+ keywords identified - -⚙️ Phase 5: Implementing code... - [Progress while creating files] - ✓ SKILL.md (6,200 words) - ✓ fetch_nass.py (280 lines) - ✓ parse_nass.py (180 lines) - [...] -``` - -**Don't show**: Technical details during creation (code blocks, etc). Just progress. - -### After Completion - -**Executive summary**: - -``` -✅ AGENT CREATED SUCCESSFULLY! - -📂 Location: ./usda-agriculture-agent/ - -📊 Main Decisions: -- API: USDA NASS QuickStats -- Analyses: YoY, Ranking, Trends, Reports -- Implementation: 1,410 lines Python + 4,500 words docs - -💰 Estimated ROI: -- Time before: 2h/day -- Time after: 3min/day -- Savings: 117h/month - -🎓 See DECISIONS.md for complete justifications. - -🚀 NEXT STEPS: - -1. Get API key (free): - https://quickstats.nass.usda.gov/api#registration - -2. Configure: - export NASS_API_KEY="your_key" - -3. Install: - /plugin marketplace add ./usda-agriculture-agent - -4. Test: - "US corn production in 2023" - "Compare soybeans this year vs last year" - -See README.md for complete instructions. -``` - -## Keywords for This Meta-Skill Detection - -This meta-skill (agent-creator) is activated when user mentions: - -**Create/Develop**: - -- "Create an agent" -- "Develop agent" -- "Create skill" -- "Develop skill" -- "Build agent" - -**Automate**: - -- "Automate this workflow" -- "Automate this process" -- "Automate this task" -- "Need to automate" -- "Turn into agent" - -**Repetitive Workflow**: - -- "Every day I do" -- "Repeatedly need to" -- "Manual process" -- "Workflow that takes Xh" -- "Task I repeat" - -**Agent for Domain**: - -- "Agent for [domain]" -- "Custom skill for [domain]" -- "Specialize Claude in [domain]" - -## ⚠️ Troubleshooting: Common Marketplace.json Errors - -### Error: "Failed to install plugin" - -**Most common cause:** marketplace.json doesn't exist or is poorly formatted - -**Diagnosis:** - -```bash -# 1. Verify file exists -ls -la agent-name/.claude-plugin/marketplace.json - -# 2. Validate JSON -python3 -c "import json; json.load(open('agent-name/.claude-plugin/marketplace.json'))" - -# 3. View content -cat agent-name/.claude-plugin/marketplace.json -``` - -**Solutions:** - -1. If file doesn't exist: Go back to STEP 0 and create -2. If invalid JSON: Fix syntax errors -3. If missing fields: Compare with STEP 0 template - -### Error: "Skill not activating" - -**Cause:** marketplace.json description ≠ SKILL.md description - -**Diagnosis:** - -```bash -# Compare descriptions -grep "description:" agent-name/SKILL.md -grep "\"description\":" agent-name/.claude-plugin/marketplace.json -``` - -**Solution:** - -1. Copy EXACT description from SKILL.md frontmatter -2. Paste in marketplace.json → plugins[0].description -3. Ensure they are IDENTICAL (word for word) -4. Save and test installation again - -### Error: "Invalid plugin structure" - -**Cause:** Mandatory marketplace.json fields incorrect - -**Verify:** - -- ✅ `plugins[0].skills` = `["./"]` (not `["SKILL.md"]` or other value) -- ✅ `plugins[0].source` = `"./"` (not empty or other value) -- ✅ `name` in JSON root matches directory name - -**Solution:** -Edit marketplace.json and fix fields above according to STEP 0 template. - -## 🧠 Final Step: Store Episode for Learning - -**⚠️ CRITICAL**: After successful agent creation, store the episode in AgentDB for future learning. - -### Automatic Episode Storage - -```python -# Store this successful creation for future learning -from integrations.agentdb_bridge import get_agentdb_bridge -from integrations.agentdb_real_integration import Episode - -try: - bridge = get_real_agentdb_bridge() - - # Create episode from this creation - episode = Episode( - session_id=f"agent-creation-{datetime.now().strftime('%Y%m%d-%H%M%S')}", - task=user_input, # Original user request - input=f"Domain: {domain}, API: {selected_api}, Structure: {architecture}", - output=f"Created: {agent_name}/ with {len(scripts)} scripts", - critique=f"Success: {'✅ High quality' if all_tests_passed else '⚠️ Needs refinement'}", - reward=0.9 if all_tests_passed else 0.7, - success=all_tests_passed, - latency_ms=creation_time_seconds * 1000, - tokens_used=estimated_tokens, - tags=[domain, selected_api, architecture_type], - metadata={ - "agent_name": agent_name, - "domain": domain, - "api": selected_api, - "complexity": complexity, - "files_created": len(all_files), - "validation_passed": all_tests_passed - } - ) - - # Store episode for learning - episode_id = bridge.store_episode(episode) - print(f"🧠 Episode stored for learning: #{episode_id}") - - # If successful, create skill - if all_tests_passed and bridge.is_available: - skill_name = f"{domain}_agent_template" - skill = Skill( - name=skill_name, - description=f"Proven template for {domain} agents", - code=f"API: {selected_api}, Structure: {architecture}", - success_rate=1.0, - uses=1, - avg_reward=0.9, - metadata={"domain": domain, "api": selected_api} - ) - - skill_id = bridge.create_skill(skill) - print(f"🎯 Skill created: #{skill_id}") - -except Exception as e: - # AgentDB failure should not break agent creation - print("🔄 AgentDB learning unavailable - agent creation completed successfully") - pass -``` - -### Learning Progress Indicators - -**Provide subtle feedback to user about learning progress:** - -```python -# Check learning milestones -if episode_id: - from integrations.learning_feedback import analyze_agent_execution - - feedback = analyze_agent_execution( - agent_name=agent_name, - user_input=user_input, - execution_time=creation_time_seconds, - success=all_tests_passed, - result_quality=0.9 if all_tests_passed else 0.7 - ) - - if feedback: - print(feedback) # Subtle milestone feedback -``` - -**Example user feedback:** -- First creation: "🎉 First agent created successfully!" -- After 10 creations: "⚡ Agent creation optimized based on 10 successful patterns" -- After 30 days: "🌟 I've learned your preferences - shall I optimize this agent?" - -### Invisible Learning Complete +See `references/interactive-mode.md` for wizard documentation. -**What happens behind the scenes:** -- ✅ Episode stored with full creation context -- ✅ Success patterns learned for future use -- ✅ Skills consolidated from successful templates -- ✅ Causal relationships established (API → success rate) -- ✅ User sees only: "Agent created successfully!" +## AgentDB Integration -**Next user gets benefits:** -- Faster creation (learned optimal patterns) -- Better API selection (historical success rates) -- Proven architectures (domain-specific success) -- Personalized suggestions (learned preferences) +Optional learning system that gets smarter over time: ---- +- Stores creation episodes for pattern learning +- Progressively improves API selection, architecture, and keywords +- Works identically with or without AgentDB available -## Limitations and Warnings +See `references/agentdb-integration.md` for integration details. -### When NOT to use +## Quality Standards -❌ Don't use this skill for: +**Always**: +- Complete, functional code (no TODOs, no `pass`) +- Detailed docstrings and type hints +- Robust error handling +- Real content in references (not "see docs") +- Configs with real values -- Editing existing skills (use directly) -- Debugging skills (use directly) -- Questions about skills (answer directly) +**Never**: +- Placeholder code or empty functions +- `api_key: YOUR_KEY_HERE` without env var instructions +- SKILL.md over 500 lines +- Platform-specific hacks -### Warnings +See `references/quality-standards.md` for complete standards. -⚠️ **Creation time**: +## Naming Convention -- Simple agents: ~30-60 min -- Complex agents: ~60-120 min -- It's normal to take time (creating everything from scratch) +Skills use standard kebab-case naming per the Agent Skills Open Standard: -⚠️ **Review needed**: +- 1-64 characters, lowercase letters, numbers, and hyphens +- Must match parent directory name +- Must not start or end with hyphen +- Must not contain consecutive hyphens -- Created agent is functional but may need adjustments -- Test examples in README -- Iterate if necessary +Examples: `stock-analyzer`, `csv-data-cleaner`, `weekly-report-generator` -⚠️ **API keys**: +## Reference Files -- User needs to obtain API key -- Instructions in created agent's README +| File | Contents | +|------|----------| +| `references/pipeline-phases.md` | Detailed Phase 1-5 instructions | +| `references/architecture-guide.md` | Simple vs Suite decision logic | +| `references/templates-guide.md` | Template-based creation | +| `references/interactive-mode.md` | Interactive wizard docs | +| `references/multi-agent-guide.md` | Batch/suite creation | +| `references/agentdb-integration.md` | AgentDB learning system | +| `references/cross-platform-guide.md` | Platform compatibility matrix | +| `references/export-guide.md` | Cross-platform export system | +| `references/quality-standards.md` | Quality and code standards | +| `references/phase1-discovery.md` | Phase 1 deep-dive | +| `references/phase2-design.md` | Phase 2 deep-dive | +| `references/phase3-architecture.md` | Phase 3 deep-dive | +| `references/phase4-detection.md` | Phase 4 deep-dive | diff --git a/article-to-prototype-cskill/.claude-plugin/marketplace.json b/article-to-prototype-cskill/.claude-plugin/marketplace.json deleted file mode 100644 index e33fc0b..0000000 --- a/article-to-prototype-cskill/.claude-plugin/marketplace.json +++ /dev/null @@ -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 - } -} diff --git a/article-to-prototype/.claude-plugin/marketplace.json b/article-to-prototype/.claude-plugin/marketplace.json new file mode 100644 index 0000000..40bf171 --- /dev/null +++ b/article-to-prototype/.claude-plugin/marketplace.json @@ -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": ["./"] + } + ] +} diff --git a/article-to-prototype-cskill/DECISIONS.md b/article-to-prototype/DECISIONS.md similarity index 100% rename from article-to-prototype-cskill/DECISIONS.md rename to article-to-prototype/DECISIONS.md diff --git a/article-to-prototype-cskill/README.md b/article-to-prototype/README.md similarity index 99% rename from article-to-prototype-cskill/README.md rename to article-to-prototype/README.md index 07e993a..8e7b430 100644 --- a/article-to-prototype-cskill/README.md +++ b/article-to-prototype/README.md @@ -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 diff --git a/article-to-prototype-cskill/SKILL.md b/article-to-prototype/SKILL.md similarity index 99% rename from article-to-prototype-cskill/SKILL.md rename to article-to-prototype/SKILL.md index 1259105..4000940 100644 --- a/article-to-prototype-cskill/SKILL.md +++ b/article-to-prototype/SKILL.md @@ -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 \ No newline at end of file diff --git a/article-to-prototype-cskill/assets/examples/sample_input.md b/article-to-prototype/assets/examples/sample_input.md similarity index 100% rename from article-to-prototype-cskill/assets/examples/sample_input.md rename to article-to-prototype/assets/examples/sample_input.md diff --git a/article-to-prototype-cskill/assets/prompts/analysis_prompt.txt b/article-to-prototype/assets/prompts/analysis_prompt.txt similarity index 100% rename from article-to-prototype-cskill/assets/prompts/analysis_prompt.txt rename to article-to-prototype/assets/prompts/analysis_prompt.txt diff --git a/article-to-prototype-cskill/references/analysis-methodology.md b/article-to-prototype/references/analysis-methodology.md similarity index 100% rename from article-to-prototype-cskill/references/analysis-methodology.md rename to article-to-prototype/references/analysis-methodology.md diff --git a/article-to-prototype-cskill/references/extraction-patterns.md b/article-to-prototype/references/extraction-patterns.md similarity index 100% rename from article-to-prototype-cskill/references/extraction-patterns.md rename to article-to-prototype/references/extraction-patterns.md diff --git a/article-to-prototype-cskill/references/generation-rules.md b/article-to-prototype/references/generation-rules.md similarity index 100% rename from article-to-prototype-cskill/references/generation-rules.md rename to article-to-prototype/references/generation-rules.md diff --git a/article-to-prototype-cskill/requirements.txt b/article-to-prototype/requirements.txt similarity index 100% rename from article-to-prototype-cskill/requirements.txt rename to article-to-prototype/requirements.txt diff --git a/article-to-prototype-cskill/scripts/__init__.py b/article-to-prototype/scripts/__init__.py similarity index 100% rename from article-to-prototype-cskill/scripts/__init__.py rename to article-to-prototype/scripts/__init__.py diff --git a/article-to-prototype-cskill/scripts/analyzers/__init__.py b/article-to-prototype/scripts/analyzers/__init__.py similarity index 100% rename from article-to-prototype-cskill/scripts/analyzers/__init__.py rename to article-to-prototype/scripts/analyzers/__init__.py diff --git a/article-to-prototype-cskill/scripts/analyzers/code_detector.py b/article-to-prototype/scripts/analyzers/code_detector.py similarity index 100% rename from article-to-prototype-cskill/scripts/analyzers/code_detector.py rename to article-to-prototype/scripts/analyzers/code_detector.py diff --git a/article-to-prototype-cskill/scripts/analyzers/content_analyzer.py b/article-to-prototype/scripts/analyzers/content_analyzer.py similarity index 100% rename from article-to-prototype-cskill/scripts/analyzers/content_analyzer.py rename to article-to-prototype/scripts/analyzers/content_analyzer.py diff --git a/article-to-prototype-cskill/scripts/extractors/__init__.py b/article-to-prototype/scripts/extractors/__init__.py similarity index 100% rename from article-to-prototype-cskill/scripts/extractors/__init__.py rename to article-to-prototype/scripts/extractors/__init__.py diff --git a/article-to-prototype-cskill/scripts/extractors/markdown_extractor.py b/article-to-prototype/scripts/extractors/markdown_extractor.py similarity index 100% rename from article-to-prototype-cskill/scripts/extractors/markdown_extractor.py rename to article-to-prototype/scripts/extractors/markdown_extractor.py diff --git a/article-to-prototype-cskill/scripts/extractors/notebook_extractor.py b/article-to-prototype/scripts/extractors/notebook_extractor.py similarity index 100% rename from article-to-prototype-cskill/scripts/extractors/notebook_extractor.py rename to article-to-prototype/scripts/extractors/notebook_extractor.py diff --git a/article-to-prototype-cskill/scripts/extractors/pdf_extractor.py b/article-to-prototype/scripts/extractors/pdf_extractor.py similarity index 100% rename from article-to-prototype-cskill/scripts/extractors/pdf_extractor.py rename to article-to-prototype/scripts/extractors/pdf_extractor.py diff --git a/article-to-prototype-cskill/scripts/extractors/web_extractor.py b/article-to-prototype/scripts/extractors/web_extractor.py similarity index 100% rename from article-to-prototype-cskill/scripts/extractors/web_extractor.py rename to article-to-prototype/scripts/extractors/web_extractor.py diff --git a/article-to-prototype-cskill/scripts/generators/__init__.py b/article-to-prototype/scripts/generators/__init__.py similarity index 100% rename from article-to-prototype-cskill/scripts/generators/__init__.py rename to article-to-prototype/scripts/generators/__init__.py diff --git a/article-to-prototype-cskill/scripts/generators/language_selector.py b/article-to-prototype/scripts/generators/language_selector.py similarity index 100% rename from article-to-prototype-cskill/scripts/generators/language_selector.py rename to article-to-prototype/scripts/generators/language_selector.py diff --git a/article-to-prototype-cskill/scripts/generators/prototype_generator.py b/article-to-prototype/scripts/generators/prototype_generator.py similarity index 100% rename from article-to-prototype-cskill/scripts/generators/prototype_generator.py rename to article-to-prototype/scripts/generators/prototype_generator.py diff --git a/article-to-prototype-cskill/scripts/main.py b/article-to-prototype/scripts/main.py similarity index 100% rename from article-to-prototype-cskill/scripts/main.py rename to article-to-prototype/scripts/main.py diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 33344b6..2b392af 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -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** diff --git a/docs/CLAUDE_SKILLS_ARCHITECTURE.md b/docs/CLAUDE_SKILLS_ARCHITECTURE.md index 00afb40..94e3d97 100644 --- a/docs/CLAUDE_SKILLS_ARCHITECTURE.md +++ b/docs/CLAUDE_SKILLS_ARCHITECTURE.md @@ -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** diff --git a/docs/DECISION_LOGIC.md b/docs/DECISION_LOGIC.md index c54191b..15de143 100644 --- a/docs/DECISION_LOGIC.md +++ b/docs/DECISION_LOGIC.md @@ -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** diff --git a/docs/INTERNAL_FLOW_ANALYSIS.md b/docs/INTERNAL_FLOW_ANALYSIS.md index fe2e820..02344af 100644 --- a/docs/INTERNAL_FLOW_ANALYSIS.md +++ b/docs/INTERNAL_FLOW_ANALYSIS.md @@ -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** diff --git a/docs/NAMING_CONVENTIONS.md b/docs/NAMING_CONVENTIONS.md index 402ced4..c45b368 100644 --- a/docs/NAMING_CONVENTIONS.md +++ b/docs/NAMING_CONVENTIONS.md @@ -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. diff --git a/docs/PIPELINE_ARCHITECTURE.md b/docs/PIPELINE_ARCHITECTURE.md index 0912c9b..d8420c2 100644 --- a/docs/PIPELINE_ARCHITECTURE.md +++ b/docs/PIPELINE_ARCHITECTURE.md @@ -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.** \ No newline at end of file +**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.** \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 29be2a7..d57a3b9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/exports/README.md b/exports/README.md index cadfa95..03c9cad 100644 --- a/exports/README.md +++ b/exports/README.md @@ -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 diff --git a/references/ACTIVATION_BEST_PRACTICES.md b/references/ACTIVATION_BEST_PRACTICES.md index e80dc7a..918a508 100644 --- a/references/ACTIVATION_BEST_PRACTICES.md +++ b/references/ACTIVATION_BEST_PRACTICES.md @@ -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/` --- diff --git a/references/agentdb-integration.md b/references/agentdb-integration.md new file mode 100644 index 0000000..27569b4 --- /dev/null +++ b/references/agentdb-integration.md @@ -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. diff --git a/references/architecture-guide.md b/references/architecture-guide.md new file mode 100644 index 0000000..148e3c2 --- /dev/null +++ b/references/architecture-guide.md @@ -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) diff --git a/references/cross-platform-guide.md b/references/cross-platform-guide.md index a5c9692..778ea2a 100644 --- a/references/cross-platform-guide.md +++ b/references/cross-platform-guide.md @@ -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) diff --git a/references/examples/exports/stock-analyzer-cskill-api-v1.0.0.zip b/references/examples/exports/stock-analyzer-api-v1.0.0.zip similarity index 100% rename from references/examples/exports/stock-analyzer-cskill-api-v1.0.0.zip rename to references/examples/exports/stock-analyzer-api-v1.0.0.zip diff --git a/references/examples/exports/stock-analyzer-cskill-desktop-v1.0.0.zip b/references/examples/exports/stock-analyzer-desktop-v1.0.0.zip similarity index 100% rename from references/examples/exports/stock-analyzer-cskill-desktop-v1.0.0.zip rename to references/examples/exports/stock-analyzer-desktop-v1.0.0.zip diff --git a/references/examples/exports/stock-analyzer-cskill-v1.0.0_INSTALL.md b/references/examples/exports/stock-analyzer-v1.0.0_INSTALL.md similarity index 97% rename from references/examples/exports/stock-analyzer-cskill-v1.0.0_INSTALL.md rename to references/examples/exports/stock-analyzer-v1.0.0_INSTALL.md index a5a36f9..a878f64 100644 --- a/references/examples/exports/stock-analyzer-cskill-v1.0.0_INSTALL.md +++ b/references/examples/exports/stock-analyzer-v1.0.0_INSTALL.md @@ -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 diff --git a/references/examples/stock-analyzer-cskill/.claude-plugin/marketplace.json b/references/examples/stock-analyzer-cskill/.claude-plugin/marketplace.json deleted file mode 100644 index a0c58bd..0000000 --- a/references/examples/stock-analyzer-cskill/.claude-plugin/marketplace.json +++ /dev/null @@ -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" - ] -} diff --git a/references/examples/stock-analyzer/.claude-plugin/marketplace.json b/references/examples/stock-analyzer/.claude-plugin/marketplace.json new file mode 100644 index 0000000..fd4f372 --- /dev/null +++ b/references/examples/stock-analyzer/.claude-plugin/marketplace.json @@ -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": ["./"] + } + ] +} diff --git a/references/examples/stock-analyzer-cskill/README.md b/references/examples/stock-analyzer/README.md similarity index 99% rename from references/examples/stock-analyzer-cskill/README.md rename to references/examples/stock-analyzer/README.md index e783251..cd69718 100644 --- a/references/examples/stock-analyzer-cskill/README.md +++ b/references/examples/stock-analyzer/README.md @@ -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 ``` diff --git a/references/examples/stock-analyzer-cskill/SKILL.md b/references/examples/stock-analyzer/SKILL.md similarity index 99% rename from references/examples/stock-analyzer-cskill/SKILL.md rename to references/examples/stock-analyzer/SKILL.md index 54f20b0..3e569f2 100644 --- a/references/examples/stock-analyzer-cskill/SKILL.md +++ b/references/examples/stock-analyzer/SKILL.md @@ -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/ diff --git a/references/examples/stock-analyzer-cskill/requirements.txt b/references/examples/stock-analyzer/requirements.txt similarity index 100% rename from references/examples/stock-analyzer-cskill/requirements.txt rename to references/examples/stock-analyzer/requirements.txt diff --git a/references/examples/stock-analyzer-cskill/scripts/main.py b/references/examples/stock-analyzer/scripts/main.py similarity index 100% rename from references/examples/stock-analyzer-cskill/scripts/main.py rename to references/examples/stock-analyzer/scripts/main.py diff --git a/references/export-guide.md b/references/export-guide.md index 269926c..6e72ec3 100644 --- a/references/export-guide.md +++ b/references/export-guide.md @@ -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 diff --git a/references/interactive-mode.md b/references/interactive-mode.md new file mode 100644 index 0000000..b5370f5 --- /dev/null +++ b/references/interactive-mode.md @@ -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. diff --git a/references/multi-agent-guide.md b/references/multi-agent-guide.md new file mode 100644 index 0000000..38b4c5a --- /dev/null +++ b/references/multi-agent-guide.md @@ -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. diff --git a/references/phase3-architecture.md b/references/phase3-architecture.md index 23d107c..721bf44 100644 --- a/references/phase3-architecture.md +++ b/references/phase3-architecture.md @@ -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 diff --git a/references/phase4-detection.md b/references/phase4-detection.md index 09de877..1f68b2b 100644 --- a/references/phase4-detection.md +++ b/references/phase4-detection.md @@ -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": { diff --git a/references/phase5-implementation.md b/references/phase5-implementation.md index e0ec968..70483c4 100644 --- a/references/phase5-implementation.md +++ b/references/phase5-implementation.md @@ -1,1011 +1,30 @@ # Phase 5: Complete Implementation -## Objective - -**IMPLEMENT** everything with FUNCTIONAL code, USEFUL documentation, and REAL configs. - -## ⚠️ FUNDAMENTAL RULES - -### What to NEVER Do - -❌ **FORBIDDEN**: -```python -# TODO: implement this function -def analyze(): - pass -``` - -❌ **FORBIDDEN**: -```markdown -For more details, consult the official documentation at [external link]. -``` - -❌ **FORBIDDEN**: -```json -{ - "api_key": "YOUR_API_KEY_HERE" -} -``` - -### What to ALWAYS Do - -✅ **MANDATORY**: Complete and functional code -✅ **MANDATORY**: Detailed docstrings -✅ **MANDATORY**: Useful content in references -✅ **MANDATORY**: Configs with real values + instructions - -## Implementation Order (Updated v2.0) - -``` -1. Create directory structure -2. Create marketplace.json (MANDATORY!) -3. Implement base utils (cache, rate limiter) -4. Implement utils/helpers.py (NEW! - Temporal context) -5. Create utils/validators/ (NEW! - Validation system) -6. Implement fetch (API client - ALL endpoints!) -7. Implement parsers (1 per data type - NEW!) -8. Implement analyze (analyses + comprehensive report) -9. Create tests/ (NEW! - Test suite) -10. Create examples/ (NEW! - Real-world examples) -11. Write SKILL.md -12. Write references -13. Create assets -14. Write README -15. Create QUICK-START.md (NEW!) -16. Create CHANGELOG.md and VERSION (NEW!) -17. Create DECISIONS.md -``` - -**Why this order** (updated)? -- Marketplace.json FIRST (without it, skill can't install) -- Helpers early (used by analyze functions) -- Validators before analyze (integration) -- ALL fetch methods (not just 1!) -- Modular parsers (1 per type) -- Tests and examples before docs (validate before documenting) -- Distribution docs (QUICK-START) to facilitate usage - -## Implementation: Directory Structure - -```bash -# Create using Bash tool -mkdir -p {agent-name}/{scripts/utils,references,assets,data/{raw,processed,cache,analysis},.claude-plugin} - -# Verify -ls -la {agent-name}/ -``` - -## Implementation: Marketplace.json (MANDATORY!) - -### ⚠️ CRITICAL: Without marketplace.json, skill CANNOT be installed! - -**Create FIRST**, before any other file! - -### Location - -``` -{agent-name}/.claude-plugin/marketplace.json -``` - -### Complete Template - -```json -{ - "name": "{agent-name}", - "owner": { - "name": "Agent Creator", - "email": "noreply@example.com" - }, - "metadata": { - "description": "Brief agent description", - "version": "1.0.0", - "created": "2025-10-17" - }, - "plugins": [ - { - "name": "{agent-name}-plugin", - "description": "COPY EXACTLY the description from SKILL.md frontmatter", - "source": "./", - "strict": false, - "skills": ["./"] - } - ] -} -``` - -### Required Fields - -**`name` (root level)**: -- Agent name (same as directory name) -- Example: `"climate-analysis-sorriso-mt"` - -**`plugins[0].name`**: -- Plugin name (can be agent-name + "-plugin") -- Example: `"climate-analysis-plugin"` - -**`plugins[0].description`** (VERY IMPORTANT!): -- **MUST BE EXACTLY EQUAL** to `description` in SKILL.md frontmatter -- This is the description Claude uses to detect when to activate the skill -- Copy word-for-word, including keywords -- Size: 150-250 words - -**`plugins[0].source`**: -- Always `"./"` (points to agent root) - -**`plugins[0].skills`**: -- Always `["./"]` (points to SKILL.md in root) - -### Complete Example (Climate Agent) - -```json -{ - "name": "climate-analysis-sorriso-mt", - "owner": { - "name": "Agent Creator", - "email": "noreply@example.com" - }, - "metadata": { - "description": "Climate analysis agent for Sorriso, Mato Grosso", - "version": "1.0.0", - "created": "2025-10-17" - }, - "plugins": [ - { - "name": "climate-analysis", - "description": "This skill should be used for climate analysis of Sorriso in Mato Grosso State, Brazil. Activates when user asks about temperature, precipitation, rainfall or climate in Sorriso-MT. Supports historical data analyses since 1940 including time series, year-over-year comparisons (YoY), long-term trends, climate anomaly detection, seasonal patterns and descriptive statistics. Uses Open-Meteo Historical Weather API data based on ERA5 reanalysis.", - "source": "./", - "strict": false, - "skills": ["./"] - } - ] -} -``` - -### Validation - -**After creating, ALWAYS validate**: - -```bash -# Syntax check -python -c "import json; print(json.load(open('.claude-plugin/marketplace.json')))" - -# If no error, it's valid! -``` - -**Verify**: -- ✅ JSON syntactically correct -- ✅ `plugins[0].description` **identical** to SKILL.md frontmatter -- ✅ `skills` points to `["./"]` -- ✅ `source` is `"./"` - -### Creation Order - -```bash -1. ✅ mkdir .claude-plugin -2. ✅ Write: .claude-plugin/marketplace.json ← FIRST! -3. ✅ Write: SKILL.md (with frontmatter) -4. ... (rest of files) -``` - -### Why Marketplace.json is Mandatory - -Without this file: -- ❌ `/plugin marketplace add ./agent-name` FAILS -- ❌ Skill cannot be installed -- ❌ Claude cannot use the skill -- ❌ All work creating agent is useless - -**NEVER forget to create marketplace.json!** - -## Implementation: Python Scripts - -### Quality Standard for EVERY Script - -**Mandatory template**: - -```python -#!/usr/bin/env python3 -""" -[Script title in 1 line] - -[Detailed description in 2-3 paragraphs explaining: -- What the script does -- How it works -- When to use -- Inputs and outputs -- Dependencies] - -Example: - $ python script.py --param1 value1 --param2 value2 -""" - -# Organized imports -# 1. Standard library -import sys -import os -from pathlib import Path -from typing import Dict, List, Optional -from datetime import datetime - -# 2. Third-party -import requests -import pandas as pd - -# 3. Local -from utils.cache_manager import CacheManager - - -# Constants at top -API_BASE_URL = "https://..." -DEFAULT_TIMEOUT = 30 - - -class MainClass: - """ - [Class description] - - Attributes: - attr1: [description] - attr2: [description] - - Example: - >>> obj = MainClass(param) - >>> result = obj.method() - """ - - def __init__(self, param1: str, param2: int = 10): - """ - Initialize [MainClass] - - Args: - param1: [detailed description] - param2: [detailed description]. Defaults to 10. - - Raises: - ValueError: If param1 is invalid - """ - if not param1: - raise ValueError("param1 cannot be empty") - - self.param1 = param1 - self.param2 = param2 - - def main_method(self, input_val: str) -> Dict: - """ - [What the method does] - - Args: - input_val: [description] - - Returns: - Dict with keys: - - key1: [description] - - key2: [description] - - Raises: - APIError: If API request fails - ValueError: If input is invalid - - Example: - >>> obj.main_method("value") - {'key1': 123, 'key2': 'abc'} - """ - # Validate input - if not self._validate_input(input_val): - raise ValueError(f"Invalid input: {input_val}") - - try: - # Complete implementation here - result = self._do_work(input_val) - - return result - - except Exception as e: - # Specific error handling - print(f"Error: {e}") - raise - - def _validate_input(self, value: str) -> bool: - """Helper for validation""" - # Complete implementation - return len(value) > 0 - - def _do_work(self, value: str) -> Dict: - """Internal helper""" - # Complete implementation - return {"result": "value"} - - -def main(): - """Main function with argparse""" - import argparse - - parser = argparse.ArgumentParser( - description="[Script description]" - ) - parser.add_argument( - '--param1', - required=True, - help="[Parameter description with example]" - ) - parser.add_argument( - '--output', - default='output.json', - help="Output file path" - ) - - args = parser.parse_args() - - # Execute - obj = MainClass(args.param1) - result = obj.main_method(args.param1) - - # Save output - output_path = Path(args.output) - output_path.parent.mkdir(parents=True, exist_ok=True) - - with open(output_path, 'w') as f: - json.dump(result, f, indent=2) - - print(f"✓ Saved: {output_path}") - - -if __name__ == "__main__": - main() -``` - -**Verify each script has**: -- ✅ Correct shebang -- ✅ Complete module docstring -- ✅ Organized imports -- ✅ Type hints in functions -- ✅ Docstrings in classes and methods -- ✅ Error handling -- ✅ Input validations -- ✅ Main function with argparse -- ✅ if __name__ == "__main__" - -### Script 1: fetch_*.py - -**Responsibility**: API requests - -**Must implement**: - -```python -class APIClient: - """Client for [API]""" - - def __init__(self, api_key: str): - """ - Initialize API client - - Args: - api_key: API key (get from [where]) - - Raises: - ValueError: If API key is None or empty - """ - if not api_key: - raise ValueError("API key required") - - self.api_key = api_key - self.session = requests.Session() - self.rate_limiter = RateLimiter(...) - - def fetch(self, **params) -> Dict: - """ - Fetch data from API - - Args: - **params: Query parameters - - Returns: - API response as dict - - Raises: - RateLimitError: If rate limit exceeded - APIError: If API returns error - """ - # 1. Check rate limit - if not self.rate_limiter.allow(): - raise RateLimitError("Rate limit exceeded") - - # 2. Build request - url = f"{BASE_URL}/endpoint" - headers = {"Authorization": f"Bearer {self.api_key}"} - - # 3. Make request with retry - response = self._request_with_retry(url, headers, params) - - # 4. Validate response - self._validate_response(response) - - # 5. Record request - self.rate_limiter.record() - - return response.json() - - def _request_with_retry(self, url, headers, params, max_retries=3): - """Request with exponential retry""" - for attempt in range(max_retries): - try: - response = self.session.get( - url, - headers=headers, - params=params, - timeout=30 - ) - response.raise_for_status() - return response - - except requests.Timeout: - if attempt < max_retries - 1: - wait = 2 ** attempt - time.sleep(wait) - else: - raise - - except requests.HTTPError as e: - if e.response.status_code == 429: # Rate limit - raise RateLimitError("Rate limit exceeded") - elif e.response.status_code in [500, 502, 503]: - if attempt < max_retries - 1: - wait = 2 ** attempt - time.sleep(wait) - else: - raise APIError(f"API error: {e}") - else: - raise APIError(f"HTTP {e.response.status_code}: {e}") -``` - -**Size**: 200-300 lines - -### Script 2: parse_*.py - -**Responsibility**: Parsing and validation - -**Must implement**: - -```python -class DataParser: - """Parser for [API] data""" - - def parse(self, raw_data: Dict) -> pd.DataFrame: - """ - Parse raw API response to structured DataFrame - - Args: - raw_data: Raw response from API - - Returns: - Cleaned DataFrame with columns: [list] - - Raises: - ParseError: If data format is unexpected - """ - # 1. Extract data - records = raw_data.get('data', []) - - if not records: - raise ParseError("No data in response") - - # 2. Convert to DataFrame - df = pd.DataFrame(records) - - # 3. Cleaning - df = self._clean_data(df) - - # 4. Transformations - df = self._transform(df) - - # 5. Validation - self._validate(df) - - return df - - def _clean_data(self, df: pd.DataFrame) -> pd.DataFrame: - """Data cleaning""" - # Remove number formatting - for col in ['production', 'area', 'yield']: - if col in df.columns: - df[col] = df[col].str.replace(',', '') - df[col] = pd.to_numeric(df[col], errors='coerce') - - # Handle suppressed values - df = df.replace('(D)', pd.NA) - df = df.replace('(E)', pd.NA) # Or mark as estimate - - return df - - def _transform(self, df: pd.DataFrame) -> pd.DataFrame: - """Transformations""" - # Standardize names - df['state'] = df['state_name'].str.upper() - - # Convert units (if needed) - if 'unit' in df.columns and df['unit'].iloc[0] == 'BU': - # Bushels to metric tons - df['value_mt'] = df['value'] * 0.0254 - - return df - - def _validate(self, df: pd.DataFrame): - """Validations""" - # Required fields - required = ['state', 'year', 'commodity', 'value'] - missing = set(required) - set(df.columns) - if missing: - raise ParseError(f"Missing columns: {missing}") - - # Values in expected ranges - if (df['value'] < 0).any(): - raise ParseError("Negative values found") - - # No duplicates - duplicates = df.duplicated(subset=['state', 'year', 'commodity']) - if duplicates.any(): - raise ParseError(f"Duplicates found: {duplicates.sum()}") -``` - -**Size**: 150-200 lines - -### Script 3: analyze_*.py - -**Responsibility**: All analyses - -**Must implement**: - -```python -class Analyzer: - """Analyses for [domain] data""" - - def __init__(self, df: pd.DataFrame): - """ - Initialize analyzer - - Args: - df: Cleaned DataFrame from parser - """ - self.df = df - self._validate_dataframe() - - def yoy_comparison( - self, - commodity: str, - current_year: int, - previous_year: int, - geography: str = "US" - ) -> Dict: - """ - Year-over-year comparison - - Args: - commodity: Commodity name - current_year: Current year - previous_year: Previous year - geography: Geography level (US, STATE, etc) - - Returns: - Dict with comparison results: - - production_current - - production_previous - - change_absolute - - change_percent - - decomposition (if production) - - interpretation - - Example: - >>> analyzer.yoy_comparison("CORN", 2023, 2022) - {'production_current': 15.3, 'change_percent': 11.7, ...} - """ - # Filter data - df_current = self.df[ - (self.df['commodity'] == commodity) & - (self.df['year'] == current_year) & - (self.df['geography'] == geography) - ] - - df_previous = self.df[ - (self.df['commodity'] == commodity) & - (self.df['year'] == previous_year) & - (self.df['geography'] == geography) - ] - - if len(df_current) == 0 or len(df_previous) == 0: - raise ValueError(f"Data not found for {commodity} in {current_year} or {previous_year}") - - # Extract values - prod_curr = df_current['production'].iloc[0] - prod_prev = df_previous['production'].iloc[0] - - # Calculate changes - change_abs = prod_curr - prod_prev - change_pct = (change_abs / prod_prev) * 100 - - # Decomposition (if has area and yield) - decomp = None - if 'area' in df_current.columns and 'yield' in df_current.columns: - decomp = self._decompose_growth(df_current, df_previous) - - # Interpretation - if abs(change_pct) < 2: - interpretation = "stable" - elif change_pct > 10: - interpretation = "significant_increase" - elif change_pct > 2: - interpretation = "moderate_increase" - elif change_pct < -10: - interpretation = "significant_decrease" - else: - interpretation = "moderate_decrease" - - return { - "commodity": commodity, - "geography": geography, - "year_current": current_year, - "year_previous": previous_year, - "production_current": round(prod_curr, 1), - "production_previous": round(prod_prev, 1), - "change_absolute": round(change_abs, 1), - "change_percent": round(change_pct, 1), - "decomposition": decomp, - "interpretation": interpretation - } - - def _decompose_growth(self, df_current, df_previous) -> Dict: - """Area vs yield decomposition""" - area_curr = df_current['area'].iloc[0] - area_prev = df_previous['area'].iloc[0] - yield_curr = df_current['yield'].iloc[0] - yield_prev = df_previous['yield'].iloc[0] - - area_change_pct = ((area_curr - area_prev) / area_prev) * 100 - yield_change_pct = ((yield_curr - yield_prev) / yield_prev) * 100 - - prod_change_pct = ((df_current['production'].iloc[0] - df_previous['production'].iloc[0]) / - df_previous['production'].iloc[0]) * 100 - - if prod_change_pct != 0: - area_contrib = (area_change_pct / prod_change_pct) * 100 - yield_contrib = (yield_change_pct / prod_change_pct) * 100 - else: - area_contrib = yield_contrib = 0 - - return { - "area_change_pct": round(area_change_pct, 1), - "yield_change_pct": round(yield_change_pct, 1), - "area_contribution": round(area_contrib, 1), - "yield_contribution": round(yield_contrib, 1), - "growth_type": "intensive" if yield_contrib > 60 else - "extensive" if area_contrib > 60 else - "balanced" - } - - # Implement ALL other analyses - # state_ranking(), trend_analysis(), etc. - # [Complete code for each one] -``` - -**Size**: 400-500 lines - -## Implementation: SKILL.md - -### Mandatory Structure - -```markdown ---- -name: [agent-name] -description: [description of 150-250 words with all keywords] ---- - -# [Agent Name] - -[Introduction of 2-3 paragraphs explaining what the agent is] - -## When to Use This Skill - -Claude should automatically activate when user: - -✅ [Trigger 1 with examples] -✅ [Trigger 2 with examples] -✅ [Trigger 3 with examples] - -## Data Source - -**API**: [Name] -**URL**: [URL] -**Documentation**: [link] -**Authentication**: [how to get key] - -[API summary in 1-2 paragraphs] - -See `references/api-guide.md` for complete details. - -## Workflows - -### Workflow 1: [Name] - -**When to execute**: [trigger conditions] - -**Step-by-step**: - -1. **Identify parameters** - - [what to extract from user's question] - -2. **Fetch data** - ```bash - python scripts/fetch_[source].py \ - --param1 value1 \ - --output data/raw/file.json - ``` - -3. **Parse data** - ```bash - python scripts/parse_[source].py \ - --input data/raw/file.json \ - --output data/processed/file.csv - ``` - -4. **Analyze** - ```bash - python scripts/analyze_[source].py \ - --input data/processed/file.csv \ - --analysis yoy \ - --output data/analysis/result.json - ``` - -5. **Interpret results** - [How to interpret the result JSON] - -**Complete example**: - -Question: "[example]" - -[Step-by-step flow with commands and outputs] - -Answer: "[expected response]" - -### Workflow 2: [Name] -[...] - -[Repeat for all main workflows] - -## Available Scripts - -### scripts/fetch_[source].py - -**Function**: Make API requests - -**Inputs**: -- `--param1`: [description] -- `--param2`: [description] - -**Output**: JSON in `data/raw/` - -**Example**: -```bash -python scripts/fetch_[source].py --commodity CORN --year 2023 -``` - -**Error handling**: -- API unavailable: [action] -- Rate limit: [action] -- [other errors] - -### scripts/parse_[source].py - -[Same level of detail...] - -### scripts/analyze_[source].py - -**Available analyses**: -- `--analysis yoy`: Year-over-year comparison -- `--analysis ranking`: State ranking -- [complete list] - -[Detail each one...] - -## Available Analyses - -### 1. YoY Comparison - -**Objective**: [...] -**When to use**: [...] -**Methodology**: [...] -**Output**: [...] -**Interpretation**: [...] - -See `references/analysis-methods.md` for detailed formulas. - -### 2. State Ranking - -[...] - -[For all analyses] - -## Error Handling - -### Error: API Unavailable - -**Symptom**: [...] -**Cause**: [...] -**Automatic action**: [...] -**Fallback**: [...] -**User message**: [...] - -### Error: Rate Limit Exceeded - -[...] - -[All expected errors] - -## Mandatory Validations - -1. **API key validation**: [...] -2. **Data validation**: [...] -3. **Consistency checks**: [...] - -## Performance and Cache - -**Cache strategy**: -- Historical data: [TTL] -- Current data: [TTL] -- Justification: [...] - -**Rate limiting**: -- Limit: [number] -- Implementation: [...] - -## References - -- `references/api-guide.md`: Complete API documentation -- `references/analysis-methods.md`: Detailed methodologies -- `references/troubleshooting.md`: Troubleshooting guide - -## Keywords for Detection - -[Complete keyword list organized by category] - -## Usage Examples - -### Example 1: [Scenario] - -**Question**: "[exact question]" - -**Internal flow**: [commands executed] - -**Answer**: "[complete and formatted answer]" - -### Examples 2-5: [...] - -[Minimum 5 complete examples] -``` - -**Size**: 5000-7000 words - -## File Creation - -**Use Write tool for each file**: - -```bash -# Creation order (UPDATED with marketplace.json): -1. ✅ Write: .claude-plugin/marketplace.json ← MANDATORY FIRST! -2. Write: SKILL.md (frontmatter with description) -3. Write: DECISIONS.md -4. Write: scripts/utils/cache_manager.py -5. Write: scripts/utils/rate_limiter.py -6. Write: scripts/utils/validators.py -7. Write: scripts/fetch_[source].py -8. Write: scripts/parse_[source].py -9. Write: scripts/analyze_[source].py -10. Write: references/api-guide.md -11. Write: references/analysis-methods.md -12. Write: references/troubleshooting.md -13. Write: assets/config.json -14. Write: assets/metadata.json (if needed) -15. Write: README.md -16. Write: requirements.txt -17. Write: .gitignore -18. Bash: chmod +x scripts/*.py - -# ⚠️ CRITICAL: marketplace.json ALWAYS FIRST! -# Reason: Without it, skill cannot be installed -``` - -## Post-Implementation Validation - -### Verify Each File - -**Python scripts**: -```bash -# Syntax check -python -m py_compile scripts/fetch_*.py -python -m py_compile scripts/parse_*.py -python -m py_compile scripts/analyze_*.py - -# Import check (mental - verify imports make sense) -``` - -**JSONs**: -```bash -# Validate syntax -python -c "import json; json.load(open('assets/config.json'))" -``` - -**Markdown**: -- [ ] SKILL.md has valid frontmatter -- [ ] No broken links -- [ ] Code blocks have syntax highlighting - -### Final Checklist - -- [ ] All files created (15+ files) -- [ ] No TODO or pass -- [ ] Code has correct imports -- [ ] JSONs are valid -- [ ] References have useful content -- [ ] README has complete instructions -- [ ] DECISIONS.md documents choices - -## Final Communication to User - -After creating everything: - -``` -✅ AGENT CREATED SUCCESSFULLY! - -📂 Location: ./[agent-name]/ - -📊 Statistics: -- SKILL.md: [N] words -- Python code: [N] lines -- References: [N] words -- Total files: [N] - -🎯 Main Decisions: -- API: [name] ([short justification]) -- Analyses: [list] -- Structure: [type] - -💰 Estimated ROI: -- Before: [X]h/[frequency] -- After: [Y]min/[frequency] -- Savings: [%] - -🚀 NEXT STEPS: - -1. Get API key: - [Instructions or link] - -2. Configure: - export API_KEY_VAR="your_key" - -3. Install: - /plugin marketplace add ./[agent-name] - -4. Test: - "[example 1]" - "[example 2]" - -📖 See README.md for complete instructions. -📋 See DECISIONS.md for decision justifications. -``` - -## Phase 5 Checklist - -- [ ] Directory structure created (including .claude-plugin/) -- [ ] ✅ **marketplace.json created (MANDATORY!)** -- [ ] **marketplace.json validated (syntax + description identical to SKILL.md)** -- [ ] SKILL.md created with correct frontmatter -- [ ] DECISIONS.md created -- [ ] Utils implemented (functional code) -- [ ] Main scripts implemented (functional code) -- [ ] SKILL.md written (5000+ words) -- [ ] References written (useful content) -- [ ] Assets created (valid JSONs) -- [ ] README.md written -- [ ] requirements.txt created -- [ ] Syntax validation passed -- [ ] No TODO or placeholder -- [ ] **Test installation**: `/plugin marketplace add ./agent-name` -- [ ] Final message to user formatted +> **Note**: This file is maintained for backwards compatibility. The complete, updated Phase 5 instructions are now in `references/pipeline-phases.md` (Section: Phase 5). + +See **`references/pipeline-phases.md`** for the authoritative Phase 5 implementation guide, which includes: + +1. Create directory structure (no -cskill suffix) +2. Write **SKILL.md first** (spec-compliant frontmatter with name, description, license, metadata) +3. Implement Python scripts (functional, no placeholders) +4. Write references (detailed documentation) +5. Write assets (templates, configs) +6. Generate `install.sh` (cross-platform installer) +7. Write `README.md` (multi-platform install instructions) +8. Run **spec validation** (`scripts/validate.py`) +9. Run **security scan** (`scripts/security_scan.py`) +10. Report results to user + +## Key Changes from v3.x + +- **SKILL.md is created first** (not marketplace.json) +- **No mandatory marketplace.json** for simple skills +- **install.sh** is generated for cross-platform support +- **Validation and security scan** run automatically after generation +- **No -cskill suffix** in generated skill names +- **Description must be <=1024 characters** +- **Generated SKILL.md must be <500 lines** + +## Quality Standards + +See `references/quality-standards.md` and `references/pipeline-phases.md` for complete quality requirements. diff --git a/references/pipeline-phases.md b/references/pipeline-phases.md new file mode 100644 index 0000000..f6d090d --- /dev/null +++ b/references/pipeline-phases.md @@ -0,0 +1,1360 @@ +# Pipeline Phases: Complete 5-Phase Skill Creation Reference + +**Version:** 4.0 +**Purpose:** Consolidated reference for the autonomous 5-phase skill creation pipeline used by agent-skill-creator v4.0. + +This document contains the detailed instructions for each phase of skill creation, updated for the Agent Skills Open Standard (SKILL.md-first, no `-cskill` suffix, spec-compliant frontmatter, cross-platform support). + +--- + +## Pipeline Overview + +``` +Phase 1: DISCOVERY -> Research APIs, data sources, domain mapping +Phase 2: DESIGN -> Define use cases, analyses, methodologies +Phase 3: ARCHITECTURE -> Structure skill directory (standard-compliant) +Phase 4: DETECTION -> Generate description + keywords for activation +Phase 5: IMPLEMENTATION -> Create all files, validate, security scan +``` + +**Key v4.0 principles:** + +- SKILL.md is the **primary file**, created first in Phase 5 +- Generated names use **kebab-case** (no `-cskill` suffix) +- Name: 1-64 chars, lowercase letters, numbers, hyphens; must match directory +- Description: 1-1024 chars; this IS the activation mechanism +- Generated SKILL.md must be **<500 lines** (move detail to `references/`) +- Frontmatter must include: `name`, `description`, `license`, `metadata` (author, version) +- `install.sh` is generated for cross-platform support +- `marketplace.json` is **NOT** needed for simple skills +- Validation and security scan run at the end of Phase 5 + +--- + +# Phase 1: Discovery + +## Objective + +Research and **DECIDE** autonomously which API or data source to use for the skill being created. + +## Detailed Process + +### Step 1: Identify Domain + +From user input, extract the main domain: + +| User Input | Identified Domain | +|---|---| +| "US crop data" | Agriculture (US) | +| "stock market analysis" | Finance / Stock Market | +| "global climate data" | Climate / Meteorology | +| "economic indicators" | Economy / Macro | +| "commodity data" | Trading / Commodities | + +### Step 2: Search Available APIs + +For the identified domain, use WebSearch to find public APIs: + +**Search queries:** +``` +"[domain] API free public data" +"[domain] government API documentation" +"best API for [domain] historical data" +"[domain] open data sources" +``` + +**Example (US agriculture):** +```bash +WebSearch: "US agriculture API free historical data" +WebSearch: "USDA API documentation" +WebSearch: "agricultural statistics API United States" +``` + +**Typical result:** 5-10 candidate APIs. + +### Step 3: Research Documentation + +For each candidate API, use WebFetch to load: +- Homepage/overview +- Getting started guide +- API reference +- Rate limits and pricing + +**Extract information per API:** + +```markdown +## API: [Name] + +**URL**: [base URL] +**Docs**: [docs URL] + +**Authentication**: +- Type: API key / OAuth / None +- Cost: Free / Paid +- How to obtain: [steps] + +**Available Data**: +- Temporal coverage: [from when to when] +- Geographic coverage: [countries, regions] +- Metrics: [list] +- Granularity: [daily, monthly, annual] + +**Limitations**: +- Rate limit: [requests per day/hour] +- Max records: [per request] + +**Quality**: +- Source: [official government / private] +- Reliability: [high/medium/low] +- Update frequency: [frequency] +- Documentation quality: [excellent/good/poor] + +**Ease of Use**: +- Format: JSON / CSV / XML +- SDKs: [Python/R/None] +- Quirks: [any non-obvious behavior] +``` + +### Step 4: API Capability Inventory + +Ensure the skill uses the maximum useful surface of the chosen API. + +**Step 4.1: Complete Inventory** + +For the chosen API, catalog ALL data types: + +```markdown +## Complete Inventory - {API Name} + +| Endpoint/Metric | Returns | Granularity | Coverage | Value | +|---|---|---|---|---| +| {metric1} | {description} | {daily/weekly} | {geo} | High | +| {metric2} | {description} | {monthly} | {geo} | High | +| {metric3} | {description} | {annual} | {geo} | Medium | +``` + +**Step 4.2: Coverage Decision** + +- If metric has high value: implement in v1.0 +- If API has 5 high-value metrics: implement all 5 +- Never leave >50% of API unused without strong justification + +**Step 4.3: Document Decision** + +In `DECISIONS.md`: + +```markdown +## API Coverage Decision + +API {name} offers {N} types of metrics. + +**Implemented in v1.0 ({X} of {N}):** +- {metric1} - {justification} +- {metric2} - {justification} + +**Not implemented ({Y} of {N}):** +- {metricZ} - {why not} (planned for v2.0) + +**Coverage:** {X/N * 100}% +``` + +**Output of this step:** Exact list of all `get_*()` methods to implement. + +### Step 5: Compare Options + +Create comparison table: + +| API | Coverage | Cost | Rate Limit | Quality | Docs | Ease | Score | +|---|---|---|---|---|---|---|---| +| API 1 | 5/5 | Free | 1000/day | Official | 4/5 | 5/5 | 9.2/10 | +| API 2 | 4/5 | $49/mo | Unlimited | Private | 5/5 | 4/5 | 7.8/10 | + +**Scoring criteria:** +- Coverage (fit with need): 30% weight +- Cost (prefer free): 20% weight +- Rate limit (sufficient?): 15% weight +- Quality (official > private): 15% weight +- Documentation (facilitates implementation): 10% weight +- Ease of use (format, structure): 10% weight + +### Step 6: DECIDE + +**Consider user constraints:** +- Mentioned "free"? Eliminate paid options +- Mentioned "10+ years historical data"? Check coverage +- Mentioned "real-time"? Prioritize streaming APIs + +**Apply logic:** +1. Eliminate APIs that violate constraints +2. Of remaining, choose highest score +3. If tie, prefer: official > private, better docs, easier to use + +**Document the final decision:** + +```markdown +## Selected API: [API Name] + +**Score**: X.X/10 + +**Justification**: +- Coverage: [specific details] +- Cost: [free/paid + details] +- Rate limit: [number] requests/day +- Quality: [official/private + reliability] +- Documentation: [quality + examples] + +**Alternatives Considered**: +- API X: Score 7.5/10 - Rejected because [reason] +- API Y: Score 6.2/10 - Rejected because [reason] +``` + +### Step 7: Research Technical Details + +After deciding, dive deep into documentation via WebFetch: +- Getting started guide +- Complete API reference +- Authentication guide +- Rate limiting details +- Best practices + +**Extract for implementation:** + +```markdown +## Technical Details - [API] + +### Authentication +- Method: API key in header +- Header: `X-Api-Key: YOUR_KEY` +- Obtaining key: [step-by-step] + +### Main Endpoints +- URL, parameters, response format, errors + +### Rate Limiting +- Limit, response headers, behavior when exceeded + +### Quirks and Gotchas +- Data formatting issues (e.g., values as strings with commas) +- Suppressed data markers +- Any non-obvious behavior + +### Performance Tips +- What to cache and for how long +- Pagination +- Parallel requests +``` + +### Step 8: Document for Later Use + +Save everything in `references/api-guide.md` of the skill to be created. + +## Phase 1 Checklist + +- [ ] Research completed (WebSearch + WebFetch) +- [ ] Minimum 3 APIs compared +- [ ] Decision made with clear justification +- [ ] User constraints respected +- [ ] API capability inventory completed +- [ ] Technical details extracted +- [ ] DECISIONS.md content prepared +- [ ] Ready for analysis design + +--- + +# Phase 2: Design + +## Objective + +**DEFINE** autonomously which analyses the skill will perform and how. + +## Detailed Process + +### Step 1: Brainstorm Use Cases + +From the workflow described by the user, think of typical questions they will ask. + +**Technique:** "If I were this user, what would I ask?" + +**Example (US agriculture):** + +User said: "download crop data, compare year vs year, make rankings" + +Typical questions: +1. "What's the corn production in 2023?" +2. "How's soybean compared to last year?" +3. "Did production grow or fall?" +4. "Does growth come from area or productivity?" +5. "Which states produce most wheat?" +6. "Top 5 soybean producers" +7. "Production trend last 5 years?" +8. "Average US yield" +9. "Compare Midwest vs South" +10. "Production by region" + +**Goal:** List 15-20 typical questions. + +### Step 2: Group by Analysis Type + +Group similar questions: + +**Group 1: Simple Queries** (fetching + formatting) +- Required analysis: **Data Retrieval** +- Complexity: Low + +**Group 2: Temporal Comparisons** (YoY) +- Required analysis: **YoY Comparison + Decomposition** +- Complexity: Medium + +**Group 3: Rankings** (sorting + share) +- Required analysis: **State/Entity Ranking** +- Complexity: Medium + +**Group 4: Trends** (time series) +- Required analysis: **Trend Analysis** +- Complexity: Medium-High + +**Group 5: Projections** (forecasting) +- Required analysis: **Forecasting** +- Complexity: High + +**Group 6: Geographic Aggregations** +- Required analysis: **Regional Aggregation** +- Complexity: Medium + +### Step 3: Prioritize Analyses + +**Prioritization criteria:** +1. **Frequency of use** (based on described workflow) +2. **Analytical value** (insight vs effort) +3. **Implementation complexity** (easier first) +4. **Dependencies** (does one analysis depend on another?) + +Score each analysis on these criteria and implement the top 4-6 that cover 80% of use cases. Always include a **comprehensive report function** that combines multiple analyses into a single summary. + +### Step 4: Specify Each Analysis + +For each selected analysis, document: + +```markdown +## Analysis: [Name] + +**Objective**: [What it does in 1 sentence] +**When to use**: [Types of questions that trigger it] + +**Required inputs**: +- Input 1: [type, description] +- Input 2: [type, description] + +**Expected outputs**: +- Output 1: [type, description] + +**Methodology**: [Explanation in natural language] + +**Formulas**: +- Formula 1 = ... + +**Validations**: +- Validation 1: [criteria] + +**Interpretation**: +- If result > X: [interpretation] +- If result < Y: [interpretation] + +**Concrete example**: +- Input: [specific values] +- Processing: [step by step calculation] +- Output: [JSON with result] +- Response to user: [formatted answer] +``` + +### Step 5: Specify Methodologies + +For quantitative analyses, detail methodology with formulas. + +**Example: YoY Decomposition** + +``` +Production = Area x Yield + +Change_Production ~ Change_Area x Yield(t-1) + Area(t-1) x Change_Yield + +Contrib_Area = (Change_Area% / Change_Production%) x 100 +Contrib_Yield = (Change_Yield% / Change_Production%) x 100 +``` + +**Interpretation:** +- Contrib_Area > 60%: Extensive growth (area expansion is main driver) +- Contrib_Yield > 60%: Intensive growth (technology improvement is main driver) +- Both ~50%: Balanced growth + +**Validation:** +- Production(t) approximately equals Area(t) x Yield(t) (margin 1%) +- Contrib_Area + Contrib_Yield approximately equals 100% (margin 5%) + +### Step 6: Comprehensive Report Function + +Always design a comprehensive report function that: +- Combines data from multiple analyses +- Provides an executive summary +- Includes key metrics, comparisons, and trends +- Is the single most useful output of the skill + +### Step 7: Document Analyses + +Save all specifications in `references/analysis-methods.md` of the skill. + +## Phase 2 Checklist + +- [ ] 15+ typical questions listed +- [ ] Questions grouped by analysis type +- [ ] 4-6 analyses prioritized (with scoring) +- [ ] Each analysis specified (objective, inputs, outputs, methodology) +- [ ] Methodologies detailed with formulas +- [ ] Validations defined +- [ ] Interpretations specified +- [ ] Concrete examples included +- [ ] Comprehensive report function designed + +--- + +# Phase 3: Architecture + +## Objective + +**STRUCTURE** the skill using the Agent Skills Open Standard: directory layout, files, responsibilities, cache, performance. + +## Detailed Process + +### Step 1: Define Skill Name + +**Format:** Standard kebab-case per the Agent Skills Open Standard. + +**Rules:** +- 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 +- **NO `-cskill` suffix** + +**Examples:** +- `stock-analyzer` +- `csv-data-cleaner` +- `weekly-report-generator` +- `nass-agriculture-monitor` +- `noaa-climate-analysis` + +### Step 2: Directory Structure + +All skills follow the Agent Skills Open Standard structure: + +**Simple Skill (1-2 workflows, <1000 lines):** + +``` +skill-name/ +├── SKILL.md # Primary file, <500 lines +├── scripts/ +│ └── main.py +├── references/ +│ └── guide.md +├── assets/ +│ └── config.json +├── install.sh # Cross-platform installer +└── README.md # Multi-platform install instructions +``` + +**Organized Skill (3-5 scripts, medium complexity):** + +``` +skill-name/ +├── SKILL.md +├── scripts/ +│ ├── fetch.py +│ ├── parse.py +│ ├── analyze.py +│ └── utils/ +│ ├── cache.py +│ └── validators.py +├── references/ +│ ├── api-guide.md +│ └── analysis-methods.md +├── assets/ +│ └── config.json +├── install.sh +└── README.md +``` + +**Complex Skill (6+ scripts, large scope):** + +``` +skill-name/ +├── SKILL.md +├── scripts/ +│ ├── core/ +│ │ ├── fetch_source.py +│ │ ├── parse_source.py +│ │ └── analyze_source.py +│ ├── models/ +│ │ └── forecasting.py +│ └── utils/ +│ ├── cache_manager.py +│ ├── rate_limiter.py +│ └── validators.py +├── references/ +│ ├── api-guide.md +│ ├── analysis-methods.md +│ └── troubleshooting.md +├── assets/ +│ ├── config.json +│ └── metadata.json +├── install.sh +└── README.md +``` + +**Important:** There is NO `.claude-plugin/marketplace.json` required for simple skills. The SKILL.md file with its frontmatter is sufficient for discovery and activation on all platforms. + +### Step 3: Simple vs Complex Suite Decision + +| Factor | Simple Skill | Complex Suite | +|---|---|---| +| Workflows | 1-2 | 3+ distinct | +| Code size | <1000 lines | >2000 lines | +| Maintenance | Single developer | Team | +| Structure | Single SKILL.md | Multiple component SKILL.md files | +| marketplace.json | Not needed | Optional (official fields only) | + +**Default:** Start with simple skill. Upgrade to complex suite only when warranted. + +### Step 4: Define Script Responsibilities + +**Principle:** Separation of Concerns. + +**Typical scripts:** + +| Script | Responsibility | Does NOT | Size | +|---|---|---|---| +| `fetch_source.py` | API requests, auth, rate limiting | Parse, transform, analyze | 200-300 lines | +| `parse_source.py` | Parsing, cleaning, validation | Fetch, analyze | 150-200 lines | +| `analyze_source.py` | All analyses (YoY, ranking, etc.) | Fetch, parse | 300-500 lines | + +**Typical utils:** + +| Util | Responsibility | Size | +|---|---|---| +| `cache_manager.py` | Response cache, differentiated TTL | 100-150 lines | +| `rate_limiter.py` | Rate limit control, persistent counter | 100-150 lines | +| `validators.py` | Data validations, consistency checks | 100-150 lines | + +### Step 5: Plan References + +Detailed documentation files loaded on demand: + +| File | Content | Size | +|---|---|---| +| `api-guide.md` | How to get API key, endpoints, parameters, response format, quirks | ~1500 words | +| `analysis-methods.md` | Each analysis explained, formulas, interpretations, examples | ~2000 words | +| `troubleshooting.md` | Common problems, step-by-step solutions, FAQs | ~1000 words | + +### Step 6: Plan Assets + +**config.json** structure: + +```json +{ + "api": { + "base_url": "https://api.example.com/v1", + "api_key_env": "API_KEY_VAR", + "_instructions": "Get free key from: https://example.com/register", + "rate_limit_per_day": 1000, + "timeout_seconds": 30 + }, + "cache": { + "enabled": true, + "ttl_historical_days": 365, + "ttl_current_days": 7 + }, + "defaults": { + "param1": "value1" + } +} +``` + +### Step 7: Cache and Rate Limiting Strategy + +**Cache rules:** +- Historical data (year < current): Permanent cache (365+ days) +- Current year data: Short cache (7 days, may be revised) +- Metadata (lists, mappings): Permanent cache + +**Rate limiting:** +- Persistent counter (file-based) +- Pre-request verification +- Alerts when near limit (>90%) +- Blocking when limit reached + +### Step 8: Document Architecture + +Prepare content for `DECISIONS.md`: +- Chosen directory structure and justification +- Script responsibilities +- Cache strategy and TTLs +- Rate limiting approach + +## Phase 3 Checklist + +- [ ] Skill name defined (kebab-case, no `-cskill`, 1-64 chars) +- [ ] Directory structure chosen +- [ ] Responsibilities of each script defined +- [ ] References planned (which files, content) +- [ ] Assets planned (which configs, structure) +- [ ] Cache strategy defined (what, TTL) +- [ ] Rate limiting strategy defined +- [ ] Architecture documented + +--- + +# Phase 4: Detection + +## Objective + +Generate a **description** (<=1024 characters) with domain keywords for agent discovery. The description in the SKILL.md frontmatter IS the primary activation mechanism across all platforms. + +**Key v4.0 change:** There are NO `activation.keywords` or `activation.patterns` fields in marketplace.json. The `description` field in SKILL.md frontmatter is the single activation mechanism. All keywords must be embedded in the description itself. + +## Detailed Process + +### Step 1: List Domain Entities + +Identify all relevant entities users may mention: + +**Entity categories:** + +1. **Organizations/Sources**: Names, acronyms, full names (USDA, NASS, NOAA) +2. **Main Objects**: Domain-specific items (commodities, instruments, metrics) +3. **Geography**: Countries, regions, states +4. **Metrics**: production, area, yield, price, revenue, temperature +5. **Temporality**: years, seasons, current, historical, YoY + +### Step 2: List Actions/Verbs + +Which verbs does the user use to request analyses? + +**Categories:** +- **Query**: what is, how much, show me, get, tell me, find +- **Compare**: compare, versus, vs, difference, change, growth +- **Rank**: top, best, leading, biggest, rank, ranking, list +- **Analyze**: analyze, trend, pattern, evolution, breakdown +- **Forecast**: predict, project, forecast, outlook, estimate +- **Report**: report, dashboard, summary, overview + +### Step 3: Generate Comprehensive Keywords + +For EACH metric/capability the skill implements, generate keywords: + +```markdown +Metric 1: [metric name] +Primary keywords: [3-5 keywords] +Secondary keywords: [3-5 synonyms] +Action keywords: [2-3 verbs specific to this metric] +Total: ~10-15 keywords per metric +``` + +**Goal:** 50-80 unique keywords total across all metrics. + +### Step 4: List Question Variations + +For each analysis type, enumerate how users might ask: + +**YoY Comparison:** +- "Compare X this year vs last year" +- "How does X compare to last year" +- "X growth rate" +- "X change YoY" +- "Did X increase or decrease" + +**Ranking:** +- "Top states for X" +- "Which states produce most X" +- "Leading X producers" +- "Ranking of X" + +**Trend:** +- "X trend last N years" +- "How has X changed over time" +- "Historical X data" + +### Step 5: Define Negative Scope + +What should NOT activate the skill? Avoid false positives. + +```markdown +## Skill Scope + +### WITHIN scope: +- [specific capability 1] +- [specific capability 2] + +### OUT of scope: +- [related but unsupported topic 1] +- [related but unsupported topic 2] +``` + +### Step 6: Create the Description + +The description must be <=1024 characters and serve as the sole activation mechanism. Pack it with the most important keywords. + +**Template:** + +```yaml +description: >- + [What the skill does]. Activates when users ask to [primary use case], + [secondary use case], or [tertiary use case]. Triggers on phrases like + [keyword phrase 1], [keyword phrase 2], [keyword phrase 3], [keyword + phrase 4]. Supports [capability 1], [capability 2], [capability 3]. + Uses [technology/API] to [what it does with real data]. +``` + +**Mandatory components:** +1. Domain with specific entities (not just "crops" but "corn, soybeans, wheat") +2. Each major API metric explicitly mentioned +3. Action verbs covered (compare, rank, analyze, report) +4. Temporal context (current, historical, year-over-year) +5. Geographic context if relevant (states, regions, national) +6. Data source name (USDA NASS, Alpha Vantage, etc.) + +**Constraints:** +- Must be 1-1024 characters +- Must be a single string (use `>-` for YAML folding) +- No line breaks in the final output + +**Real example:** + +```yaml +description: >- + Analyze US agricultural production using official USDA NASS data. + Activates when users ask about crop production, area planted, yield, + harvest progress, or crop conditions for corn, soybeans, wheat, and + other commodities. Triggers on phrases like compare corn production, + top soybean states, wheat yield trend, crop condition report, harvest + progress update. Supports year-over-year comparisons, state rankings, + trend analyses, growth decomposition, regional aggregations, and + comprehensive crop reports. Uses Python with NASS QuickStats API to + fetch real data on production, area, yield, conditions, and progress. +``` + +### Step 7: Mental Testing + +For each example question from Phase 2, verify: +- Does the description contain relevant keywords? +- Would an LLM reading the description match this query? + +If any use case would NOT be detected, add missing keywords to the description. + +### Step 8: Document Keywords in SKILL.md Body + +In the SKILL.md body (not frontmatter), include a keywords section for transparency: + +```markdown +## Keywords for Automatic Detection + +This skill is activated when user mentions: + +**Entities**: [list] +**Geography**: [list] +**Metrics**: [list] +**Actions**: [list] + +**Activation examples:** +- "[example 1]" +- "[example 2]" +- "[example 3]" + +**Does NOT activate for:** +- "[out of scope 1]" +- "[out of scope 2]" +``` + +## Phase 4 Checklist + +- [ ] Domain entities listed (organizations, objects, geography) +- [ ] Actions/verbs listed +- [ ] 50+ keywords generated across all metrics +- [ ] Question variations mapped +- [ ] Negative scope defined +- [ ] Description created (<=1024 chars, packed with keywords) +- [ ] Keywords documented in SKILL.md body +- [ ] Activation examples (positive and negative) +- [ ] Mental detection simulation (all use cases covered) + +--- + +# Phase 5: Implementation + +## Objective + +**IMPLEMENT** everything with functional code, useful documentation, and real configs. Then **validate** against the spec and run a **security scan**. + +## Quality Rules (Non-Negotiable) + +### NEVER: + +```python +# FORBIDDEN: placeholder code +def analyze(): + # TODO: implement this function + pass +``` + +```markdown + +For more details, consult the official documentation at [external link]. +``` + +```json +// FORBIDDEN: placeholder config +{ "api_key": "YOUR_API_KEY_HERE" } +``` + +### ALWAYS: + +- Complete, functional code in every function +- Detailed docstrings with Args, Returns, Raises, Example +- Type hints on all public functions +- Robust error handling with specific exceptions +- Input and output validations +- Real values in configs with instructions for user-provided values +- Self-contained content in references (not just links) + +## Implementation Order + +Execute these 10 steps in order: + +### Step 1: Create Directory Structure + +```bash +mkdir -p skill-name/{scripts,references,assets} +``` + +No `.claude-plugin/` directory needed for simple skills. + +### Step 2: Write SKILL.md (PRIMARY FILE - CREATE FIRST) + +The SKILL.md is the most important file. It must have spec-compliant frontmatter and be <500 lines. + +**Required frontmatter:** + +```yaml +--- +name: skill-name +description: >- + Description here, <=1024 chars, packed with activation keywords. +license: MIT +metadata: + author: Author Name + version: 1.0.0 +--- +``` + +**Frontmatter field rules:** +- `name`: 1-64 chars, lowercase + hyphens, must match directory name +- `description`: 1-1024 chars, the activation mechanism +- `license`: Required (MIT, Apache-2.0, etc.) +- `metadata.author`: Required +- `metadata.version`: Required, semver format + +**Body structure (must be <500 lines total including frontmatter):** + +```markdown +# Skill Name + +[Introduction: 2-3 paragraphs] + +## When to Use This Skill + +[Activation triggers with examples] + +## Data Source + +[API summary, link to references/api-guide.md for details] + +## Workflows + +### Workflow 1: [Name] +[Step-by-step with commands and examples] + +### Workflow 2: [Name] +[Step-by-step with commands and examples] + +## Available Scripts + +[Brief description of each script, inputs, outputs] + +## Available Analyses + +[Brief description of each analysis, link to references/ for details] + +## Error Handling + +[Common errors and how the skill handles them] + +## Keywords for Detection + +[Organized keyword list] + +## Usage Examples + +[3-5 complete examples with question, flow, and answer] + +## References + +[Table of reference files and what they contain] +``` + +**Keeping under 500 lines:** Move detailed content to `references/`: +- Detailed API docs go to `references/api-guide.md` +- Detailed methodologies go to `references/analysis-methods.md` +- Troubleshooting goes to `references/troubleshooting.md` + +### Step 3: Implement Python Scripts + +Every script must follow this quality standard: + +```python +#!/usr/bin/env python3 +""" +Script title in 1 line. + +Detailed description: what it does, how it works, +when to use, inputs and outputs. + +Example: + $ python script.py --param1 value1 +""" + +# 1. Standard library imports +import sys +import os +from pathlib import Path +from typing import Dict, List, Optional +from datetime import datetime + +# 2. Third-party imports +import requests + +# 3. Local imports +from utils.cache_manager import CacheManager + + +# Constants +API_BASE_URL = "https://..." +DEFAULT_TIMEOUT = 30 + + +class MainClass: + """ + Class description. + + Attributes: + attr1: description + attr2: description + + Example: + >>> obj = MainClass(param) + >>> result = obj.method() + """ + + def __init__(self, param1: str, param2: int = 10): + """ + Initialize MainClass. + + Args: + param1: detailed description + param2: detailed description. Defaults to 10. + + Raises: + ValueError: If param1 is invalid + """ + if not param1: + raise ValueError("param1 cannot be empty") + self.param1 = param1 + self.param2 = param2 + + def main_method(self, input_val: str) -> Dict: + """ + What the method does. + + Args: + input_val: description + + Returns: + Dict with keys: + - key1: description + - key2: description + + Raises: + APIError: If API request fails + + Example: + >>> obj.main_method("value") + {'key1': 123, 'key2': 'abc'} + """ + if not self._validate_input(input_val): + raise ValueError(f"Invalid input: {input_val}") + + try: + result = self._do_work(input_val) + return result + except Exception as e: + print(f"Error: {e}") + raise + + +def main(): + """Main function with argparse.""" + import argparse + + parser = argparse.ArgumentParser(description="Script description") + parser.add_argument('--param1', required=True, help="Parameter description") + parser.add_argument('--output', default='output.json', help="Output file path") + + args = parser.parse_args() + obj = MainClass(args.param1) + result = obj.main_method(args.param1) + + import json + output_path = Path(args.output) + output_path.parent.mkdir(parents=True, exist_ok=True) + with open(output_path, 'w') as f: + json.dump(result, f, indent=2) + print(f"Saved: {output_path}") + + +if __name__ == "__main__": + main() +``` + +**Checklist per script:** +- Correct shebang (`#!/usr/bin/env python3`) +- Complete module docstring +- Organized imports (stdlib, third-party, local) +- Type hints on all public functions +- Docstrings with Args, Returns, Raises, Example +- Error handling for risky operations +- Input and output validations +- Main function with argparse +- `if __name__ == "__main__"` guard +- No TODO, no `pass`, no `NotImplementedError` + +**Script patterns by type:** + +**fetch_source.py** (200-300 lines): +- API client class with authentication +- Rate limiting integration +- Request retry with exponential backoff +- Response validation +- Cache integration (check cache before API call) + +**parse_source.py** (150-200 lines): +- Parse raw API JSON to structured data +- Clean data (remove formatting, handle nulls) +- Transform data (standardize names, convert units) +- Validate data (required fields, ranges, no duplicates) + +**analyze_source.py** (300-500 lines): +- All analysis functions (YoY, ranking, trend, etc.) +- Comprehensive report function +- Each function: validate inputs, compute, interpret, return structured result + +### Step 4: Write References + +Detailed documentation files. Each must be self-contained with real content. + +**api-guide.md** (~1500 words): +- How to get API key (step-by-step) +- Main endpoints with example requests and responses +- Parameter details with types and valid values +- Response format with field descriptions +- Rate limits and how to handle them +- Known quirks and workarounds + +**analysis-methods.md** (~2000 words): +- Each analysis explained with objective and methodology +- Mathematical formulas +- Interpretation guidelines +- Validation criteria +- Complete numerical examples with real values + +**troubleshooting.md** (~1000 words): +- Common problems with symptoms, causes, and solutions +- Error messages and what they mean +- Step-by-step debugging procedures + +### Step 5: Write Assets + +**config.json**: Real API URLs, env var names for keys, rate limits, cache TTLs, default parameters. Always include `_instructions` or `_note` fields explaining user-provided values. + +**metadata.json** (if needed): Domain-specific mappings, aliases, conversions, groupings. + +### Step 6: Generate install.sh + +Create a cross-platform installer script: + +```bash +#!/usr/bin/env bash +set -euo pipefail + +SKILL_NAME="skill-name" +SKILL_DIR="$(cd "$(dirname "$0")" && pwd)" + +# Platform detection +detect_platform() { + case "${1:-auto}" in + claude|claude-code) echo "$HOME/.claude/skills" ;; + copilot|github) echo ".github/skills" ;; + cursor) echo ".cursor/rules" ;; + windsurf) echo ".windsurf/skills" ;; + cline) echo ".clinerules" ;; + codex) echo ".codex/skills" ;; + gemini) echo ".gemini/skills" ;; + auto) + # Auto-detect based on environment + if command -v claude >/dev/null 2>&1; then + echo "$HOME/.claude/skills" + elif [ -d ".github" ]; then + echo ".github/skills" + elif [ -d ".cursor" ]; then + echo ".cursor/rules" + else + echo "$HOME/.claude/skills" # default + fi + ;; + *) + echo "Unknown platform: $1" >&2 + echo "Supported: claude, copilot, cursor, windsurf, cline, codex, gemini" >&2 + exit 1 + ;; + esac +} + +PLATFORM="${1:-auto}" +TARGET_BASE=$(detect_platform "$PLATFORM") +TARGET_DIR="$TARGET_BASE/$SKILL_NAME" + +echo "Installing $SKILL_NAME..." +echo "Target: $TARGET_DIR" + +mkdir -p "$TARGET_DIR" +cp -r "$SKILL_DIR"/* "$TARGET_DIR/" 2>/dev/null || true +cp -r "$SKILL_DIR"/.[!.]* "$TARGET_DIR/" 2>/dev/null || true + +echo "Installed successfully to $TARGET_DIR" +``` + +### Step 7: Write README.md + +Multi-platform installation instructions: + +```markdown +# Skill Name + +Brief description. + +## Installation + +### Using install.sh (Recommended) + +```bash +chmod +x install.sh +./install.sh # Auto-detect platform +./install.sh claude # Claude Code +./install.sh copilot # GitHub Copilot +./install.sh cursor # Cursor +``` + +### Manual Installation + +| Platform | Copy to | +|---|---| +| Claude Code | `~/.claude/skills/skill-name/` or `.claude/skills/skill-name/` | +| GitHub Copilot | `.github/skills/skill-name/` | +| Cursor | `.cursor/rules/skill-name/` | +| Windsurf | `.windsurf/skills/skill-name/` | +| Cline | `.clinerules/skill-name/` | +| Codex CLI | `.codex/skills/skill-name/` | +| Gemini CLI | `.gemini/skills/skill-name/` | + +## Prerequisites + +[API key instructions, dependencies] + +## Usage Examples + +[3-5 examples] + +## Troubleshooting + +[Common issues and solutions] +``` + +### Step 8: Run Spec Validation + +After creating all files, run the validation script: + +```bash +python3 scripts/validate.py path/to/skill/ +``` + +**What it checks:** +- Frontmatter fields present and valid (name, description, license, metadata) +- Name matches directory name +- Name format: 1-64 chars, lowercase + hyphens, no leading/trailing hyphens, no consecutive hyphens +- Description: 1-1024 chars +- SKILL.md under 500 lines +- Required files present + +**If validation fails:** Fix the issues and re-run. Do not proceed until validation passes. + +### Step 9: Run Security Scan + +```bash +python3 scripts/security_scan.py path/to/skill/ +``` + +**What it checks:** +- Hardcoded API keys or secrets +- `.env` files with credentials +- Shell injection patterns +- Sensitive data in committed files + +**If security scan finds issues:** Fix them (replace hardcoded keys with env var references, remove `.env` files, sanitize shell inputs) and re-run. + +### Step 10: Report Results + +After successful validation and security scan, report to the user: + +``` +SKILL CREATED SUCCESSFULLY + +Location: ./skill-name/ + +Statistics: +- SKILL.md: [N] lines (<500) +- Python code: [N] lines across [N] scripts +- References: [N] files +- Total files: [N] + +Validation: PASSED +Security Scan: PASSED + +Main Decisions: +- API: [name] ([short justification]) +- Analyses: [list] +- Structure: [simple/organized/complex] + +Next Steps: +1. Get API key: [instructions or link] +2. Configure: export API_KEY_VAR="your_key" +3. Install: ./install.sh +4. Test: "[example query 1]" + +See README.md for complete multi-platform installation instructions. +``` + +## File Creation Order Summary + +| Order | File | Notes | +|---|---|---| +| 1 | Directory structure | `mkdir -p skill-name/{scripts,references,assets}` | +| 2 | `SKILL.md` | PRIMARY file, <500 lines, spec-compliant frontmatter | +| 3 | `scripts/*.py` | Functional Python code, no placeholders | +| 4 | `references/*.md` | Detailed documentation, self-contained | +| 5 | `assets/*.json` | Real values, validated JSON | +| 6 | `install.sh` | Cross-platform installer, `chmod +x` | +| 7 | `README.md` | Multi-platform install instructions | +| 8 | Run `validate.py` | Must pass before delivery | +| 9 | Run `security_scan.py` | Must pass before delivery | +| 10 | Report results | Summary to user | + +## Phase 5 Checklist + +- [ ] Directory structure created (NO `.claude-plugin/` for simple skills) +- [ ] SKILL.md created FIRST with spec-compliant frontmatter +- [ ] SKILL.md is <500 lines +- [ ] Frontmatter has: name, description (<=1024 chars), license, metadata (author, version) +- [ ] Name is kebab-case, no `-cskill`, matches directory +- [ ] All Python scripts implemented with functional code +- [ ] No TODO, no `pass`, no `NotImplementedError`, no placeholders +- [ ] All scripts have: shebang, docstrings, type hints, error handling +- [ ] References written with real, self-contained content +- [ ] Assets created with valid JSON and real values +- [ ] `install.sh` generated with cross-platform support +- [ ] `README.md` written with multi-platform install instructions +- [ ] `requirements.txt` created (if third-party dependencies used) +- [ ] Spec validation passed (`scripts/validate.py`) +- [ ] Security scan passed (`scripts/security_scan.py`) +- [ ] Results reported to user + +--- + +# Quality Standards Reminders + +These standards apply across ALL phases and ALL generated files. + +## Code Quality + +**Every function must be:** +- Complete and functional (no stubs) +- Documented with docstrings (Args, Returns, Raises, Example) +- Type-hinted on all public interfaces +- Protected by error handling +- Validated on inputs and outputs + +**Every script must have:** +- `#!/usr/bin/env python3` shebang +- Module-level docstring +- Organized imports (stdlib, third-party, local) +- Constants at top level +- `main()` function with argparse +- `if __name__ == "__main__"` guard + +## Documentation Quality + +**References must be:** +- Self-contained (not just links to external docs) +- Concrete (real values, executable examples) +- Substantial (1000+ words for main reference files) +- Well-structured (headings, lists, code blocks) + +**SKILL.md must be:** +- Under 500 lines (move detail to references) +- Frontmatter-compliant (name, description, license, metadata) +- Actionable (workflows with specific commands) + +## Configuration Quality + +**JSON configs must be:** +- Syntactically valid (always validate with `python -c "import json; ..."`) +- Populated with real values (real API URLs, real rate limits) +- Annotated with `_instructions` or `_note` fields for user-provided values +- Never contain hardcoded secrets + +## Naming Quality + +- Skill names: kebab-case, 1-64 chars, no `-cskill` suffix +- Python files: snake_case +- Classes: PascalCase +- Functions/methods: snake_case +- Constants: UPPER_SNAKE_CASE + +## Anti-Patterns to Avoid + +| Anti-Pattern | Correct Approach | +|---|---| +| `def analyze(): pass` | Complete implementation with real logic | +| `# TODO: implement` | Implement it now | +| `api_key: YOUR_KEY_HERE` | `api_key_env: "ENV_VAR_NAME"` with instructions | +| `See official docs at [link]` | Include the relevant information directly | +| SKILL.md over 500 lines | Move detail to `references/` | +| marketplace.json as step 0 | SKILL.md is the primary file, created first | +| `-cskill` suffix in names | Standard kebab-case: `stock-analyzer` | +| Description over 1024 chars | Trim to essential keywords within limit | diff --git a/references/templates-guide.md b/references/templates-guide.md new file mode 100644 index 0000000..dd7d1a7 --- /dev/null +++ b/references/templates-guide.md @@ -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. diff --git a/references/templates/marketplace-robust-template.json b/references/templates/marketplace-robust-template.json index 800421c..56a61c9 100644 --- a/references/templates/marketplace-robust-template.json +++ b/references/templates/marketplace-robust-template.json @@ -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" diff --git a/references/tools/activation-tester.md b/references/tools/activation-tester.md index 217d8de..8875ed6 100644 --- a/references/tools/activation-tester.md +++ b/references/tools/activation-tester.md @@ -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 diff --git a/references/tools/test-automation-scripts.sh b/references/tools/test-automation-scripts.sh index 1880fdc..8924db6 100755 --- a/references/tools/test-automation-scripts.sh +++ b/references/tools/test-automation-scripts.sh @@ -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) diff --git a/scenarios/SC-001-valid-frontmatter-happy.scenario.md b/scenarios/SC-001-valid-frontmatter-happy.scenario.md new file mode 100644 index 0000000..2817150 --- /dev/null +++ b/scenarios/SC-001-valid-frontmatter-happy.scenario.md @@ -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. diff --git a/scenarios/SC-002-invalid-frontmatter-missing-name.scenario.md b/scenarios/SC-002-invalid-frontmatter-missing-name.scenario.md new file mode 100644 index 0000000..1255250 --- /dev/null +++ b/scenarios/SC-002-invalid-frontmatter-missing-name.scenario.md @@ -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"`. diff --git a/scenarios/SC-003-invalid-frontmatter-missing-description.scenario.md b/scenarios/SC-003-invalid-frontmatter-missing-description.scenario.md new file mode 100644 index 0000000..2dee8e7 --- /dev/null +++ b/scenarios/SC-003-invalid-frontmatter-missing-description.scenario.md @@ -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"`. diff --git a/scenarios/SC-004-name-matches-directory.scenario.md b/scenarios/SC-004-name-matches-directory.scenario.md new file mode 100644 index 0000000..9204bf7 --- /dev/null +++ b/scenarios/SC-004-name-matches-directory.scenario.md @@ -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. diff --git a/scenarios/SC-005-name-directory-mismatch-fails-validation.scenario.md b/scenarios/SC-005-name-directory-mismatch-fails-validation.scenario.md new file mode 100644 index 0000000..ba7e2f2 --- /dev/null +++ b/scenarios/SC-005-name-directory-mismatch-fails-validation.scenario.md @@ -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'"`. diff --git a/scenarios/SC-006-skillmd-under-500-lines.scenario.md b/scenarios/SC-006-skillmd-under-500-lines.scenario.md new file mode 100644 index 0000000..b83cac8 --- /dev/null +++ b/scenarios/SC-006-skillmd-under-500-lines.scenario.md @@ -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/`. diff --git a/scenarios/SC-007-skillmd-over-500-lines-fails.scenario.md b/scenarios/SC-007-skillmd-over-500-lines-fails.scenario.md new file mode 100644 index 0000000..23f1f35 --- /dev/null +++ b/scenarios/SC-007-skillmd-over-500-lines-fails.scenario.md @@ -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)"`. diff --git a/scenarios/SC-008-metaskill-own-skillmd-under-500.scenario.md b/scenarios/SC-008-metaskill-own-skillmd-under-500.scenario.md new file mode 100644 index 0000000..ba40f11 --- /dev/null +++ b/scenarios/SC-008-metaskill-own-skillmd-under-500.scenario.md @@ -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. diff --git a/scenarios/SC-009-no-marketplace-json-simple-skill.scenario.md b/scenarios/SC-009-no-marketplace-json-simple-skill.scenario.md new file mode 100644 index 0000000..4b63aec --- /dev/null +++ b/scenarios/SC-009-no-marketplace-json-simple-skill.scenario.md @@ -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. diff --git a/scenarios/SC-010-marketplace-json-complex-suite.scenario.md b/scenarios/SC-010-marketplace-json-complex-suite.scenario.md new file mode 100644 index 0000000..3316df3 --- /dev/null +++ b/scenarios/SC-010-marketplace-json-complex-suite.scenario.md @@ -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`. diff --git a/scenarios/SC-011-no-cskill-suffix.scenario.md b/scenarios/SC-011-no-cskill-suffix.scenario.md new file mode 100644 index 0000000..29dd238 --- /dev/null +++ b/scenarios/SC-011-no-cskill-suffix.scenario.md @@ -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. diff --git a/scenarios/SC-012-cskill-suffix-rejected.scenario.md b/scenarios/SC-012-cskill-suffix-rejected.scenario.md new file mode 100644 index 0000000..247582d --- /dev/null +++ b/scenarios/SC-012-cskill-suffix-rejected.scenario.md @@ -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/`. diff --git a/scenarios/SC-013-license-field-present.scenario.md b/scenarios/SC-013-license-field-present.scenario.md new file mode 100644 index 0000000..9173bbd --- /dev/null +++ b/scenarios/SC-013-license-field-present.scenario.md @@ -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). diff --git a/scenarios/SC-014-metadata-author-version.scenario.md b/scenarios/SC-014-metadata-author-version.scenario.md new file mode 100644 index 0000000..f731a51 --- /dev/null +++ b/scenarios/SC-014-metadata-author-version.scenario.md @@ -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" +``` diff --git a/scenarios/SC-015-compatibility-field-platform-specific.scenario.md b/scenarios/SC-015-compatibility-field-platform-specific.scenario.md new file mode 100644 index 0000000..9db5a99 --- /dev/null +++ b/scenarios/SC-015-compatibility-field-platform-specific.scenario.md @@ -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. diff --git a/scenarios/SC-016-validation-all-spec-rules.scenario.md b/scenarios/SC-016-validation-all-spec-rules.scenario.md new file mode 100644 index 0000000..e44b040 --- /dev/null +++ b/scenarios/SC-016-validation-all-spec-rules.scenario.md @@ -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. diff --git a/scenarios/SC-017-validation-invalid-name-format.scenario.md b/scenarios/SC-017-validation-invalid-name-format.scenario.md new file mode 100644 index 0000000..d90dc0e --- /dev/null +++ b/scenarios/SC-017-validation-invalid-name-format.scenario.md @@ -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."`. diff --git a/scenarios/SC-018-security-scan-hardcoded-key.scenario.md b/scenarios/SC-018-security-scan-hardcoded-key.scenario.md new file mode 100644 index 0000000..eb2ec16 --- /dev/null +++ b/scenarios/SC-018-security-scan-hardcoded-key.scenario.md @@ -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"`. diff --git a/scenarios/SC-019-security-scan-env-file.scenario.md b/scenarios/SC-019-security-scan-env-file.scenario.md new file mode 100644 index 0000000..d4a99ec --- /dev/null +++ b/scenarios/SC-019-security-scan-env-file.scenario.md @@ -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"`. diff --git a/scenarios/SC-020-security-scan-clean-skill.scenario.md b/scenarios/SC-020-security-scan-clean-skill.scenario.md new file mode 100644 index 0000000..d0e77fb --- /dev/null +++ b/scenarios/SC-020-security-scan-clean-skill.scenario.md @@ -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. diff --git a/scenarios/SC-021-security-scan-shell-injection.scenario.md b/scenarios/SC-021-security-scan-shell-injection.scenario.md new file mode 100644 index 0000000..6ea0181 --- /dev/null +++ b/scenarios/SC-021-security-scan-shell-injection.scenario.md @@ -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"`. diff --git a/scenarios/SC-022-install-sh-generated.scenario.md b/scenarios/SC-022-install-sh-generated.scenario.md new file mode 100644 index 0000000..2d3ff21 --- /dev/null +++ b/scenarios/SC-022-install-sh-generated.scenario.md @@ -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. diff --git a/scenarios/SC-023-install-sh-primary-platforms.scenario.md b/scenarios/SC-023-install-sh-primary-platforms.scenario.md new file mode 100644 index 0000000..ea9b74e --- /dev/null +++ b/scenarios/SC-023-install-sh-primary-platforms.scenario.md @@ -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. diff --git a/scenarios/SC-024-install-sh-project-level.scenario.md b/scenarios/SC-024-install-sh-project-level.scenario.md new file mode 100644 index 0000000..f6c2e5e --- /dev/null +++ b/scenarios/SC-024-install-sh-project-level.scenario.md @@ -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. diff --git a/scenarios/SC-025-install-sh-extended-platforms.scenario.md b/scenarios/SC-025-install-sh-extended-platforms.scenario.md new file mode 100644 index 0000000..0762cd7 --- /dev/null +++ b/scenarios/SC-025-install-sh-extended-platforms.scenario.md @@ -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. diff --git a/scenarios/SC-026-install-sh-platform-not-detected.scenario.md b/scenarios/SC-026-install-sh-platform-not-detected.scenario.md new file mode 100644 index 0000000..5e75278 --- /dev/null +++ b/scenarios/SC-026-install-sh-platform-not-detected.scenario.md @@ -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. diff --git a/scenarios/SC-027-install-sh-validation-fails.scenario.md b/scenarios/SC-027-install-sh-validation-fails.scenario.md new file mode 100644 index 0000000..00b78f0 --- /dev/null +++ b/scenarios/SC-027-install-sh-validation-fails.scenario.md @@ -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/`. diff --git a/scenarios/SC-028-install-sh-permission-denied.scenario.md b/scenarios/SC-028-install-sh-permission-denied.scenario.md new file mode 100644 index 0000000..cb63c62 --- /dev/null +++ b/scenarios/SC-028-install-sh-permission-denied.scenario.md @@ -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". diff --git a/scenarios/SC-029-install-sh-dry-run.scenario.md b/scenarios/SC-029-install-sh-dry-run.scenario.md new file mode 100644 index 0000000..31b796b --- /dev/null +++ b/scenarios/SC-029-install-sh-dry-run.scenario.md @@ -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. diff --git a/scenarios/SC-030-readme-multiplatform-instructions.scenario.md b/scenarios/SC-030-readme-multiplatform-instructions.scenario.md new file mode 100644 index 0000000..629bdf7 --- /dev/null +++ b/scenarios/SC-030-readme-multiplatform-instructions.scenario.md @@ -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`. diff --git a/scenarios/SC-031-export-desktop-zip.scenario.md b/scenarios/SC-031-export-desktop-zip.scenario.md new file mode 100644 index 0000000..c06fc78 --- /dev/null +++ b/scenarios/SC-031-export-desktop-zip.scenario.md @@ -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 ` 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`. diff --git a/scenarios/SC-032-export-api-zip.scenario.md b/scenarios/SC-032-export-api-zip.scenario.md new file mode 100644 index 0000000..0bd1a6a --- /dev/null +++ b/scenarios/SC-032-export-api-zip.scenario.md @@ -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 ` 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. diff --git a/scenarios/SC-033-export-platform-flag.scenario.md b/scenarios/SC-033-export-platform-flag.scenario.md new file mode 100644 index 0000000..3062d76 --- /dev/null +++ b/scenarios/SC-033-export-platform-flag.scenario.md @@ -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. diff --git a/scenarios/SC-034-phase3-standard-directory-structure.scenario.md b/scenarios/SC-034-phase3-standard-directory-structure.scenario.md new file mode 100644 index 0000000..75eb91d --- /dev/null +++ b/scenarios/SC-034-phase3-standard-directory-structure.scenario.md @@ -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`. diff --git a/scenarios/SC-035-phase5-skillmd-first.scenario.md b/scenarios/SC-035-phase5-skillmd-first.scenario.md new file mode 100644 index 0000000..5a61ee7 --- /dev/null +++ b/scenarios/SC-035-phase5-skillmd-first.scenario.md @@ -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. diff --git a/scenarios/SC-036-phase5-runs-validation.scenario.md b/scenarios/SC-036-phase5-runs-validation.scenario.md new file mode 100644 index 0000000..4c1e456 --- /dev/null +++ b/scenarios/SC-036-phase5-runs-validation.scenario.md @@ -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 +``` diff --git a/scenarios/SC-037-phase5-runs-security-scan.scenario.md b/scenarios/SC-037-phase5-runs-security-scan.scenario.md new file mode 100644 index 0000000..3e9b517 --- /dev/null +++ b/scenarios/SC-037-phase5-runs-security-scan.scenario.md @@ -0,0 +1,33 @@ +# SC-037: Phase 5 Runs Security Scan After Generating All Files + +> Covers: FR-025 — Phase 5 SHOULD run security scan after generating all files +> Type: Happy Path + +## Given +- The meta-skill has completed Phases 1-4 +- Phase 5 has generated all files and passed validation + +## When +- Phase 5 reaches the security scan step (step i in the pipeline) + +## Then +- The security scan function is invoked automatically on the generated skill directory +- The security scan result is reported to the user +- Any security findings are listed with file locations and descriptions + +## Verification Method + +**Method**: Manual test + +**Steps**: +1. Run the meta-skill to completion +2. Observe Phase 5 output for security scan step +3. Verify a security report is shown + +**Expected evidence**: Phase 5 output includes a security scan report section, such as: +``` +Security Scan: PASSED + - No hardcoded secrets found + - No .env files detected + - No shell injection patterns found +``` diff --git a/scenarios/SC-038-five-phase-pipeline-preserved.scenario.md b/scenarios/SC-038-five-phase-pipeline-preserved.scenario.md new file mode 100644 index 0000000..94f965b --- /dev/null +++ b/scenarios/SC-038-five-phase-pipeline-preserved.scenario.md @@ -0,0 +1,31 @@ +# SC-038: Five-Phase Pipeline Is Preserved + +> Covers: FR-027 — The meta-skill MUST preserve the 5-phase pipeline as the core creation methodology +> Type: Happy Path + +## Given +- The meta-skill is invoked with: "Create a skill for automated email triage" + +## When +- The meta-skill processes the request from start to finish + +## Then +- All 5 phases execute in order: + 1. Phase 1: Discovery (research APIs, tools, data sources) + 2. Phase 2: Design (define use cases, methodologies) + 3. Phase 3: Architecture (structure the skill directory) + 4. Phase 4: Detection (generate description with domain keywords) + 5. Phase 5: Implementation (create all files, validate, scan) +- No phase is skipped +- The output explicitly references each phase + +## Verification Method + +**Method**: Manual test + +**Steps**: +1. Run the meta-skill with the email triage input +2. Observe the output for phase markers (Phase 1, Phase 2, Phase 3, Phase 4, Phase 5) +3. Verify all 5 phases are executed sequentially + +**Expected evidence**: Output contains clear markers for all 5 phases: "Phase 1: Discovery", "Phase 2: Design", "Phase 3: Architecture", "Phase 4: Detection", "Phase 5: Implementation". Each phase produces visible output. diff --git a/scenarios/SC-039-cross-platform-portability.scenario.md b/scenarios/SC-039-cross-platform-portability.scenario.md new file mode 100644 index 0000000..29d83e4 --- /dev/null +++ b/scenarios/SC-039-cross-platform-portability.scenario.md @@ -0,0 +1,32 @@ +# SC-039: Generated Skills Work Across Platforms Without Modification + +> Covers: FR-028, NFR-001 — Generated skills MUST work on any SKILL.md-standard platform without modification +> Type: Happy Path + +## Given +- A skill has been generated by the meta-skill for "code review automation" +- The skill uses only standard SKILL.md features (no platform-specific extensions) + +## When +- The generated skill directory is copied to: + - `~/.claude/skills/code-review-automation/` + - `.github/skills/code-review-automation/` + - `.cursor/rules/code-review-automation/` + +## Then +- The SKILL.md is valid standard SKILL.md format readable by all platforms +- No platform-specific hacks or workarounds are present in the files +- The frontmatter uses only standard fields (name, description, license, compatibility, metadata, allowed-tools) +- No files reference platform-specific paths or configurations + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Generate a skill using the meta-skill +2. Parse SKILL.md frontmatter and verify all fields are standard spec fields +3. Grep for platform-specific strings: `grep -r "claude-code\|copilot\|cursor" code-review-automation/SKILL.md` +4. Verify no platform-specific conditional logic in SKILL.md body + +**Expected evidence**: SKILL.md frontmatter contains only standard fields. No platform-specific strings in SKILL.md body. The skill is a pure standard SKILL.md that any compliant platform can read. diff --git a/scenarios/SC-040-name-exceeds-64-chars.scenario.md b/scenarios/SC-040-name-exceeds-64-chars.scenario.md new file mode 100644 index 0000000..331132e --- /dev/null +++ b/scenarios/SC-040-name-exceeds-64-chars.scenario.md @@ -0,0 +1,30 @@ +# SC-040: Skill Name Exceeds 64 Characters Is Truncated + +> Covers: FR-001, Edge case 2.3 — Skill name exceeds 64 chars: truncate intelligently, warn user, suggest alternative +> Type: Edge Case + +## Given +- The meta-skill is invoked with a very long workflow name +- Input: "Create a skill for automatically processing and analyzing extremely long complex multi-step data transformation pipelines with validation" + +## When +- Phase 3 derives the skill name from the description + +## Then +- The generated `name` field is <=64 characters +- The name is truncated at a word boundary (not mid-word) +- The user receives a warning that the name was truncated +- An alternative shorter name is suggested + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Run the meta-skill with the long workflow description +2. Parse the generated SKILL.md frontmatter +3. Assert `len(name) <= 64` +4. Assert the name does not end with a partial word fragment +5. Verify meta-skill output contains a truncation warning + +**Expected evidence**: `name` is <=64 chars. Output includes a message like "Name truncated from 78 to 64 characters" and suggests an alternative. Name ends at a clean word boundary. diff --git a/scenarios/SC-041-description-exceeds-1024-chars.scenario.md b/scenarios/SC-041-description-exceeds-1024-chars.scenario.md new file mode 100644 index 0000000..43651bd --- /dev/null +++ b/scenarios/SC-041-description-exceeds-1024-chars.scenario.md @@ -0,0 +1,29 @@ +# SC-041: Description Exceeds 1024 Characters Is Summarized + +> Covers: FR-001, Edge case 2.3 — Description exceeds 1024 chars: summarize, move detail to body, warn user +> Type: Edge Case + +## Given +- The meta-skill is invoked with an extremely detailed workflow description that would produce a description >1024 chars +- The Phase 4 (Detection) output initially generates a description of 1500 characters + +## When +- Phase 5 generates the SKILL.md frontmatter + +## Then +- The `description` field in frontmatter is <=1024 characters +- The excess detail is moved into the SKILL.md body (not lost) +- The user receives a warning that the description was summarized + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Run the meta-skill with a very detailed workflow +2. Parse the generated SKILL.md frontmatter +3. Assert `len(description) <= 1024` +4. Verify SKILL.md body contains additional context that supplements the shortened description +5. Verify meta-skill output mentions description truncation + +**Expected evidence**: `description` is <=1024 chars. SKILL.md body starts with expanded context. Warning message present. diff --git a/scenarios/SC-042-name-uppercase-auto-converts.scenario.md b/scenarios/SC-042-name-uppercase-auto-converts.scenario.md new file mode 100644 index 0000000..4f222f5 --- /dev/null +++ b/scenarios/SC-042-name-uppercase-auto-converts.scenario.md @@ -0,0 +1,28 @@ +# SC-042: Uppercase Name Auto-Converts to Lowercase Kebab-Case + +> Covers: FR-001, Edge case 2.3 — Name contains uppercase or special chars: auto-convert to lowercase kebab-case +> Type: Edge Case + +## Given +- The meta-skill is processing a skill where the derived name would be "MyAwesome_DataProcessor" + +## When +- The name normalization step runs + +## Then +- The name is auto-converted to `my-awesome-data-processor` (lowercase kebab-case) +- Underscores are replaced with hyphens +- Uppercase letters are lowered +- The user is informed of the conversion + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Generate a skill where the initial name would contain uppercase/special chars +2. Parse the final SKILL.md frontmatter `name` field +3. Assert `name` matches regex `^[a-z][a-z0-9-]*[a-z0-9]$` +4. Assert no uppercase letters, underscores, or special chars remain + +**Expected evidence**: `name: my-awesome-data-processor`. All lowercase. Hyphens as separators. No underscores or special characters. diff --git a/scenarios/SC-043-name-leading-trailing-hyphen-stripped.scenario.md b/scenarios/SC-043-name-leading-trailing-hyphen-stripped.scenario.md new file mode 100644 index 0000000..159f8e5 --- /dev/null +++ b/scenarios/SC-043-name-leading-trailing-hyphen-stripped.scenario.md @@ -0,0 +1,26 @@ +# SC-043: Name Starting/Ending with Hyphen Is Auto-Stripped + +> Covers: FR-001, Edge case 2.3 — Name starts/ends with hyphen: auto-strip, warn user +> Type: Edge Case + +## Given +- The name normalization process produces `-my-skill-` (leading and trailing hyphens) + +## When +- The validation/normalization step processes the name + +## Then +- Leading and trailing hyphens are stripped, resulting in `my-skill` +- The user is warned about the automatic stripping +- The final `name` field is `my-skill` + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Construct a scenario where name normalization would produce `-my-skill-` +2. Verify the final `name` in frontmatter is `my-skill` +3. Verify the name does not start or end with a hyphen + +**Expected evidence**: `name: my-skill`. No leading or trailing hyphens. Warning message like "Stripped leading/trailing hyphens from name". diff --git a/scenarios/SC-044-name-consecutive-hyphens-collapsed.scenario.md b/scenarios/SC-044-name-consecutive-hyphens-collapsed.scenario.md new file mode 100644 index 0000000..b215d23 --- /dev/null +++ b/scenarios/SC-044-name-consecutive-hyphens-collapsed.scenario.md @@ -0,0 +1,26 @@ +# SC-044: Consecutive Hyphens in Name Are Collapsed + +> Covers: FR-001, Edge case 2.3 — Name has consecutive hyphens: collapse to single hyphen, warn user +> Type: Edge Case + +## Given +- The name normalization process produces `my---awesome--skill` (consecutive hyphens) + +## When +- The validation/normalization step processes the name + +## Then +- Consecutive hyphens are collapsed to a single hyphen: `my-awesome-skill` +- The user is warned about the automatic collapse +- The final `name` field is `my-awesome-skill` + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Construct a scenario where name normalization produces `my---awesome--skill` +2. Verify the final `name` in frontmatter is `my-awesome-skill` +3. Assert `--` does not appear in the name + +**Expected evidence**: `name: my-awesome-skill`. No consecutive hyphens. Warning message like "Collapsed consecutive hyphens in name". diff --git a/scenarios/SC-045-directory-name-mismatch-auto-rename.scenario.md b/scenarios/SC-045-directory-name-mismatch-auto-rename.scenario.md new file mode 100644 index 0000000..ba84ddf --- /dev/null +++ b/scenarios/SC-045-directory-name-mismatch-auto-rename.scenario.md @@ -0,0 +1,30 @@ +# SC-045: Directory Renamed When It Doesn't Match Name Field + +> Covers: FR-002, Edge case 2.3 — Directory name doesn't match name field: rename directory to match, warn user +> Type: Edge Case + +## Given +- During migration or manual editing, a skill directory is named `old-name/` +- The SKILL.md inside has `name: new-name` in frontmatter + +## When +- The "Migrate Legacy Skill" flow is invoked on `old-name/` + +## Then +- The directory is renamed from `old-name/` to `new-name/` +- The user is warned about the rename +- All files inside are preserved after the rename +- Validation passes after the rename + +## Verification Method + +**Method**: CLI command + +**Steps**: +1. Create `old-name/` with SKILL.md containing `name: new-name` +2. Run the migration flow on `old-name/` +3. Assert `old-name/` no longer exists +4. Assert `new-name/` exists with all original files +5. Run validation on `new-name/` and assert it passes + +**Expected evidence**: `old-name/` is gone. `new-name/` exists with intact files. Validation passes. Output includes "Renamed directory from 'old-name' to 'new-name'". diff --git a/scenarios/SC-046-hardcoded-key-replaced-with-envvar.scenario.md b/scenarios/SC-046-hardcoded-key-replaced-with-envvar.scenario.md new file mode 100644 index 0000000..71bad98 --- /dev/null +++ b/scenarios/SC-046-hardcoded-key-replaced-with-envvar.scenario.md @@ -0,0 +1,36 @@ +# SC-046: Hardcoded API Key Replaced with Environment Variable Reference + +> Covers: FR-013, Edge case 2.3 — Generated script contains hardcoded API key: fail scan, replace with env var, warn user +> Type: Edge Case + +## Given +- During Phase 5, the generated `scripts/main.py` contains: + ```python + API_KEY = "sk-abc123def456" + headers = {"Authorization": f"Bearer {API_KEY}"} + ``` + +## When +- The security scan runs on the generated skill + +## Then +- The security scan fails and identifies the hardcoded key +- The script is updated to use an environment variable: + ```python + API_KEY = os.environ.get("API_KEY") + headers = {"Authorization": f"Bearer {API_KEY}"} + ``` +- The user is warned about the replacement + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Generate a skill where a script would contain a hardcoded API key +2. After Phase 5 completes, read `scripts/main.py` +3. Assert the hardcoded key string `sk-abc123def456` is NOT present +4. Assert `os.environ.get` or `os.getenv` is present +5. Verify security scan output mentions the replacement + +**Expected evidence**: No hardcoded key in final script. `os.environ.get("API_KEY")` is used instead. Security warning present in output. diff --git a/scenarios/SC-047-skillmd-excess-moved-to-references.scenario.md b/scenarios/SC-047-skillmd-excess-moved-to-references.scenario.md new file mode 100644 index 0000000..4bf6a5a --- /dev/null +++ b/scenarios/SC-047-skillmd-excess-moved-to-references.scenario.md @@ -0,0 +1,30 @@ +# SC-047: Excess SKILL.md Content Moved to References + +> Covers: FR-003, Edge case 2.3 — SKILL.md body exceeds 500 lines: move excess to references, add cross-references +> Type: Edge Case + +## Given +- During Phase 5, the initial SKILL.md draft has 750 lines of body content + +## When +- The line-count check runs and detects the excess + +## Then +- The SKILL.md is trimmed to <500 lines +- The excess content is extracted and saved to one or more files in `references/` +- The SKILL.md body contains cross-reference links like `See references/detailed-guide.md for full documentation` +- No content is lost -- it is all preserved in `references/` + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Generate a skill with a very complex workflow that produces extensive documentation +2. Count lines in SKILL.md: `wc -l SKILL.md` +3. Assert line count <500 +4. List files in `references/`: `ls references/` +5. Assert at least one reference file contains content from the original SKILL.md draft +6. Grep SKILL.md for cross-references: `grep 'references/' SKILL.md` + +**Expected evidence**: SKILL.md is <500 lines. `references/` contains extracted detail files. SKILL.md body contains at least one `references/` cross-reference. diff --git a/scenarios/SC-048-platform-directory-created.scenario.md b/scenarios/SC-048-platform-directory-created.scenario.md new file mode 100644 index 0000000..c6e9325 --- /dev/null +++ b/scenarios/SC-048-platform-directory-created.scenario.md @@ -0,0 +1,29 @@ +# SC-048: Platform Directory Created When Missing + +> Covers: Edge case 2.3 — Platform directory doesn't exist (e.g., no .claude/): create it or inform user +> Type: Edge Case + +## Given +- A valid skill `log-analysis/` with `install.sh` +- The target directory `~/.claude/skills/` does NOT exist + +## When +- `./install.sh --platform claude-code` is run + +## Then +- The `~/.claude/skills/` directory is created automatically +- The skill is installed to `~/.claude/skills/log-analysis/` +- Exit code is 0 +- The user is informed that the directory was created + +## Verification Method + +**Method**: CLI command + +**Steps**: +1. Ensure `~/.claude/skills/` does not exist: `rm -rf ~/.claude/skills/` +2. Run: `./log-analysis/install.sh --platform claude-code` +3. Assert `~/.claude/skills/log-analysis/SKILL.md` exists +4. Check exit code is 0 + +**Expected evidence**: Exit code 0. `~/.claude/skills/log-analysis/SKILL.md` exists. Output includes "Created directory ~/.claude/skills/". diff --git a/scenarios/SC-049-complex-suite-marketplace-json-official-fields.scenario.md b/scenarios/SC-049-complex-suite-marketplace-json-official-fields.scenario.md new file mode 100644 index 0000000..eb3787d --- /dev/null +++ b/scenarios/SC-049-complex-suite-marketplace-json-official-fields.scenario.md @@ -0,0 +1,31 @@ +# SC-049: Complex Suite marketplace.json Contains Only Official Fields + +> Covers: FR-006, Edge case 2.3 — Complex skill suite marketplace.json has ONLY official fields +> Type: Edge Case + +## Given +- The meta-skill generates a complex multi-skill suite +- A `.claude-plugin/marketplace.json` is created + +## When +- The validation runs on the suite + +## Then +- The marketplace.json contains ONLY the following fields: + - Top level: `name`, `plugins` + - Per plugin: `name`, `description`, `source`, `skills` +- No non-standard fields exist (no `version`, `author`, `repository`, `tags`, `icon`, etc.) +- The JSON is valid + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Generate a complex skill suite +2. Parse `.claude-plugin/marketplace.json` with `json.load()` +3. Assert top-level keys are exactly `{"name", "plugins"}` +4. For each plugin in `plugins`, assert keys are a subset of `{"name", "description", "source", "skills"}` +5. Fail if any extra keys are found at any level + +**Expected evidence**: JSON contains only `name` and `plugins` at top level. Each plugin entry has only `name`, `description`, `source`, `skills`. No extra fields like `version` or `author`. diff --git a/scenarios/SC-050-nfr-context-consumption.scenario.md b/scenarios/SC-050-nfr-context-consumption.scenario.md new file mode 100644 index 0000000..a216465 --- /dev/null +++ b/scenarios/SC-050-nfr-context-consumption.scenario.md @@ -0,0 +1,28 @@ +# SC-050: Meta-Skill SKILL.md Context Consumption Under 5000 Tokens + +> Covers: NFR-002 — Meta-skill SKILL.md context consumption <5,000 tokens for body +> Type: Performance + +## Given +- The meta-skill's own SKILL.md has been restructured for v4.0 +- The file is at `/Users/francylisboacharuto/agent-skill-creator/SKILL.md` + +## When +- The token count of the SKILL.md body (excluding frontmatter) is estimated + +## Then +- The body content consumes fewer than 5,000 tokens +- Using the heuristic of ~4 chars per token, the body is <20,000 characters +- Detailed content is in `references/` and loaded on demand + +## Verification Method + +**Method**: CLI command + +**Steps**: +1. Extract the body (everything after the second `---`): `sed -n '/^---$/,/^---$/!p' SKILL.md | tail -n +1` +2. Count characters: `wc -c` on the body +3. Assert character count <20,000 (conservative ~4 chars/token estimate for 5,000 token limit) +4. Alternatively, use `tiktoken` if available: `python3 -c "import tiktoken; enc=tiktoken.get_encoding('cl100k_base'); print(len(enc.encode(open('SKILL.md').read())))"` + +**Expected evidence**: Body character count is <20,000 characters. Estimated token count is <5,000 tokens. diff --git a/scenarios/SC-051-nfr-install-sh-macos-linux-wsl.scenario.md b/scenarios/SC-051-nfr-install-sh-macos-linux-wsl.scenario.md new file mode 100644 index 0000000..defaef1 --- /dev/null +++ b/scenarios/SC-051-nfr-install-sh-macos-linux-wsl.scenario.md @@ -0,0 +1,29 @@ +# SC-051: install.sh Works on macOS, Linux, and WSL + +> Covers: NFR-005 — install.sh must work on macOS, Linux, and WSL (3 OS families) +> Type: Performance + +## Given +- A generated skill with an `install.sh` script +- The script uses only POSIX-compatible bash constructs + +## When +- The script is analyzed for POSIX compatibility + +## Then +- The shebang is `#!/usr/bin/env bash` or `#!/bin/bash` +- No macOS-only (`gstat`, `pbcopy`) or Linux-only (`apt`, `systemctl`) commands are used +- Path handling uses `$HOME` instead of hardcoded paths +- The script uses portable constructs (`[` not `[[` where possible, `printf` not `echo -e`) + +## Verification Method + +**Method**: CLI command + +**Steps**: +1. Run: `head -1 install.sh` to check shebang +2. Run: `shellcheck install.sh` (if available) to check for portability issues +3. Grep for non-portable constructs: `grep -n "gstat\|pbcopy\|apt-get\|systemctl\|echo -e" install.sh` +4. Verify `$HOME` is used instead of `/Users/` or `/home/` + +**Expected evidence**: Shebang is `#!/usr/bin/env bash`. `shellcheck` reports no portability errors. No platform-specific commands found. `$HOME` used for home directory references. diff --git a/scenarios/SC-052-nfr-zero-config-activation.scenario.md b/scenarios/SC-052-nfr-zero-config-activation.scenario.md new file mode 100644 index 0000000..e9ec759 --- /dev/null +++ b/scenarios/SC-052-nfr-zero-config-activation.scenario.md @@ -0,0 +1,28 @@ +# SC-052: Generated Skills Activate Without Platform-Specific Configuration + +> Covers: NFR-006 — Generated skills must not require any tool-specific configuration to activate; zero-config activation +> Type: Happy Path + +## Given +- A skill has been generated and installed to `~/.claude/skills/log-analysis/` +- No additional configuration steps have been taken (no `.claude-plugin/`, no marketplace registration) + +## When +- A user starts a new Claude Code session and uses a trigger phrase related to the skill + +## Then +- The skill is discovered and activated based on its SKILL.md `description` field alone +- No manual configuration, plugin registration, or marketplace.json was required +- The skill description contains sufficient domain keywords for agent discovery + +## Verification Method + +**Method**: Manual test + +**Steps**: +1. Install a generated skill to `~/.claude/skills/log-analysis/` +2. Start a new Claude Code session +3. Ask: "Help me analyze these server logs for error patterns" +4. Verify the skill is activated (agent references skill instructions) + +**Expected evidence**: The skill activates based on the description matching the user's request. No additional setup steps were required. The agent follows the skill's SKILL.md instructions. diff --git a/scenarios/SC-053-nfr-backwards-compatibility.scenario.md b/scenarios/SC-053-nfr-backwards-compatibility.scenario.md new file mode 100644 index 0000000..cbfee6c --- /dev/null +++ b/scenarios/SC-053-nfr-backwards-compatibility.scenario.md @@ -0,0 +1,29 @@ +# SC-053: Backwards Compatibility with v3.x Workflows + +> Covers: NFR-007 — Users can git pull and use immediately; no breaking changes to user-facing invocation +> Type: Happy Path + +## Given +- A user has the v3.x version of agent-skill-creator installed via `/plugin marketplace add ./` +- The user runs `git pull` to update to v4.0 + +## When +- The user invokes the meta-skill with: "Create a skill for data validation" + +## Then +- The meta-skill works without errors +- The 5-phase pipeline executes as before +- The trigger phrases that worked in v3.x still work +- The output is now v4.0 compliant (standard naming, no -cskill suffix) but the invocation did not break + +## Verification Method + +**Method**: Manual test + +**Steps**: +1. From an existing v3.x installation, run: `git pull` +2. Invoke the meta-skill with a standard trigger: "Create a skill for data validation" +3. Verify the pipeline completes without errors +4. Verify the generated output is v4.0 compliant + +**Expected evidence**: No errors during or after `git pull`. The meta-skill activates with the same trigger phrases. The 5 phases complete. Generated skill is v4.0 compliant (no -cskill, <500 line SKILL.md, includes install.sh). diff --git a/scenarios/SC-054-validate-existing-skill-flow.scenario.md b/scenarios/SC-054-validate-existing-skill-flow.scenario.md new file mode 100644 index 0000000..ba654a6 --- /dev/null +++ b/scenarios/SC-054-validate-existing-skill-flow.scenario.md @@ -0,0 +1,35 @@ +# SC-054: Validate Existing Skill Flow + +> Covers: FR-011, Section 2.2 — Secondary flow: Validate existing skill +> Type: Happy Path + +## Given +- An existing skill directory `my-tool/` with: + - Valid SKILL.md with proper frontmatter + - `scripts/main.py` (clean, no secrets) + - `references/guide.md` + - No `.env` files + +## When +- The user invokes: "Validate this skill: my-tool/" + +## Then +- The meta-skill runs spec validation (frontmatter, naming, structure) +- The meta-skill runs security scan +- The meta-skill reports pass/fail with specific issues +- For this valid skill, both validation and security pass + +## Verification Method + +**Method**: Manual test + +**Steps**: +1. Create a valid skill directory `my-tool/` with all proper files +2. Invoke the meta-skill with: "Validate this skill: my-tool/" +3. Observe the validation and security scan output + +**Expected evidence**: Output shows: +``` +Spec Validation: PASSED (0 errors, 0 warnings) +Security Scan: PASSED (0 findings) +``` diff --git a/scenarios/SC-055-validate-existing-skill-with-issues.scenario.md b/scenarios/SC-055-validate-existing-skill-with-issues.scenario.md new file mode 100644 index 0000000..eaf4ea4 --- /dev/null +++ b/scenarios/SC-055-validate-existing-skill-with-issues.scenario.md @@ -0,0 +1,37 @@ +# SC-055: Validate Existing Skill Reports Specific Issues + +> Covers: FR-011, FR-012, Section 2.2 — Secondary flow: Validate existing skill with issues +> Type: Failure + +## Given +- An existing skill directory `broken-tool/` with: + - SKILL.md with `name: Broken_Tool` (invalid format) + - Description of 1500 characters (exceeds 1024 limit) + - `scripts/main.py` containing `API_KEY = "sk-secret123"` + - A `.env` file with database credentials + +## When +- The user invokes: "Validate this skill: broken-tool/" + +## Then +- Spec validation fails with specific errors: + - Invalid name format (uppercase, underscore) + - Description exceeds 1024 characters + - Name does not match directory name +- Security scan reports findings: + - Hardcoded API key in scripts/main.py + - .env file with credentials +- Fix suggestions are provided for each issue + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Create `broken-tool/` with the described invalid files +2. Call `validate_skill("broken-tool/")` +3. Assert `result.valid is False` +4. Assert `result.errors` has >=3 entries (name format, description length, directory mismatch) +5. Assert `result.security` has >=2 entries (hardcoded key, .env file) + +**Expected evidence**: `valid: False`. Errors list includes name format, description length, and directory mismatch issues. Security list includes hardcoded key and .env file findings. Each finding includes a fix suggestion. diff --git a/scenarios/SC-056-migrate-legacy-skill-flow.scenario.md b/scenarios/SC-056-migrate-legacy-skill-flow.scenario.md new file mode 100644 index 0000000..5864039 --- /dev/null +++ b/scenarios/SC-056-migrate-legacy-skill-flow.scenario.md @@ -0,0 +1,37 @@ +# SC-056: Migrate Legacy Skill with -cskill Suffix and marketplace.json + +> Covers: FR-007, FR-005, Section 2.2 — Secondary flow: Migrate legacy skill +> Type: Happy Path + +## Given +- A legacy skill directory `my-tool-cskill/` exists with: + - SKILL.md with `name: my-tool-cskill` + - `.claude-plugin/marketplace.json` with non-standard fields (`version`, `author`, `tags`) + - Scripts and references from v3.x + +## When +- The user invokes: "Migrate this skill to the new standard" + +## Then +- The directory is renamed from `my-tool-cskill/` to `my-tool/` +- The `name` field in SKILL.md is updated to `my-tool` +- The `.claude-plugin/marketplace.json` is removed (simple skill) or stripped to official fields only +- An `install.sh` is generated +- A README.md with cross-platform instructions is generated +- Validation passes on the migrated skill + +## Verification Method + +**Method**: Manual test + +**Steps**: +1. Create `my-tool-cskill/` with legacy structure +2. Invoke: "Migrate this skill to the new standard" +3. Verify `my-tool-cskill/` no longer exists +4. Verify `my-tool/` exists with updated files +5. Verify `name: my-tool` in SKILL.md +6. Verify `.claude-plugin/` is removed +7. Verify `install.sh` and `README.md` exist +8. Run validation on `my-tool/` + +**Expected evidence**: Directory renamed. Frontmatter updated. marketplace.json removed. install.sh and README.md present. Validation passes. diff --git a/scenarios/SC-057-cross-platform-export-claude-code.scenario.md b/scenarios/SC-057-cross-platform-export-claude-code.scenario.md new file mode 100644 index 0000000..ee80c38 --- /dev/null +++ b/scenarios/SC-057-cross-platform-export-claude-code.scenario.md @@ -0,0 +1,28 @@ +# SC-057: Cross-Platform Export for Claude Code + +> Covers: FR-019, Section 2.2 — Export flow: Claude Code standard directory +> Type: Happy Path + +## Given +- A valid skill directory `data-processor/` exists +- The user wants to export for Claude Code + +## When +- The user invokes: "Export this skill for Claude Code" + +## Then +- The export generates a standard directory output (ready to copy to `~/.claude/skills/` or `.claude/skills/`) +- The output includes all necessary files (SKILL.md, scripts, references, install.sh, README.md) +- A platform-specific installation guide is provided + +## Verification Method + +**Method**: Manual test + +**Steps**: +1. Create a valid skill `data-processor/` +2. Invoke: "Export this skill for Claude Code" +3. Verify the output is a directory (not .zip) with all standard files +4. Verify installation instructions reference `~/.claude/skills/` and `.claude/skills/` + +**Expected evidence**: Output is a standard skill directory. Contains SKILL.md, install.sh, README.md. Installation guide references Claude Code paths. diff --git a/scenarios/SC-058-cross-platform-export-desktop-web.scenario.md b/scenarios/SC-058-cross-platform-export-desktop-web.scenario.md new file mode 100644 index 0000000..3e3a914 --- /dev/null +++ b/scenarios/SC-058-cross-platform-export-desktop-web.scenario.md @@ -0,0 +1,28 @@ +# SC-058: Cross-Platform Export for Desktop/Web as .zip + +> Covers: FR-019 — Export system MUST continue to support Desktop/Web .zip +> Type: Happy Path + +## Given +- A valid skill directory `data-processor/` exists +- The user wants a Desktop/Web export + +## When +- `export_skill("data-processor/", variants=["desktop"])` is called + +## Then +- A `.zip` file is produced +- The zip contains the skill directory with all files +- The zip is suitable for Desktop/Web import + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Call `export_skill("data-processor/", variants=["desktop"])` +2. Verify a `.zip` file was created +3. Run `unzip -l ` to list contents +4. Verify SKILL.md is present in the archive + +**Expected evidence**: `.zip` file produced. Contains `SKILL.md`, `scripts/`, `references/`, `install.sh`, `README.md`. Archive is valid. diff --git a/scenarios/SC-059-install-sh-copilot-platform.scenario.md b/scenarios/SC-059-install-sh-copilot-platform.scenario.md new file mode 100644 index 0000000..80697f9 --- /dev/null +++ b/scenarios/SC-059-install-sh-copilot-platform.scenario.md @@ -0,0 +1,27 @@ +# SC-059: install.sh Installs to GitHub Copilot Path + +> Covers: FR-016 — install.sh MUST support ~/.github/skills/ and .github/skills/ +> Type: Happy Path + +## Given +- A generated skill `code-review/` with a valid `install.sh` +- The user wants to install for GitHub Copilot + +## When +- `./install.sh --platform copilot` is run + +## Then +- The skill is copied to `.github/skills/code-review/` (project level) or `~/.github/skills/code-review/` (user level) +- All skill files are present in the destination +- Exit code is 0 + +## Verification Method + +**Method**: CLI command + +**Steps**: +1. Run: `./code-review/install.sh --platform copilot` +2. Verify the skill files exist at the Copilot path +3. Check exit code is 0 + +**Expected evidence**: Exit code 0. Skill files exist at `.github/skills/code-review/` or `~/.github/skills/code-review/`. SKILL.md is present. diff --git a/scenarios/SC-060-validation-frontmatter-structure.scenario.md b/scenarios/SC-060-validation-frontmatter-structure.scenario.md new file mode 100644 index 0000000..500d5c6 --- /dev/null +++ b/scenarios/SC-060-validation-frontmatter-structure.scenario.md @@ -0,0 +1,33 @@ +# SC-060: Validation Checks Frontmatter Structure Completeness + +> Covers: FR-012 — Validation MUST check frontmatter structure +> Type: Failure + +## Given +- A skill directory `bad-frontmatter/` with SKILL.md that has malformed YAML: + ``` + --- + name: bad-frontmatter + description "missing colon after description" + --- + ``` + +## When +- The validation function `validate_skill("bad-frontmatter/")` is invoked + +## Then +- The validation result `valid` is `False` +- The `errors` list contains a message about invalid YAML frontmatter structure +- The error is specific enough to help the user fix it + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Create `bad-frontmatter/` with malformed YAML in SKILL.md +2. Call `validate_skill("bad-frontmatter/")` +3. Assert `result.valid is False` +4. Assert `result.errors` contains a message about YAML parsing failure + +**Expected evidence**: `valid: False`. Error message like `"Invalid YAML frontmatter: could not parse frontmatter block"`. diff --git a/scenarios/SC-061-metaskill-restructured-references.scenario.md b/scenarios/SC-061-metaskill-restructured-references.scenario.md new file mode 100644 index 0000000..022880d --- /dev/null +++ b/scenarios/SC-061-metaskill-restructured-references.scenario.md @@ -0,0 +1,29 @@ +# SC-061: Meta-Skill Content Restructured Into References + +> Covers: FR-021 — Meta-skill MUST restructure its own content: <500 line SKILL.md with references in references/ +> Type: Happy Path + +## Given +- The agent-skill-creator repository has been updated to v4.0 +- The original SKILL.md was 4,116 lines + +## When +- The restructured repository is inspected + +## Then +- `SKILL.md` is <500 lines +- The `references/` directory contains files that hold the detailed content previously in SKILL.md +- The SKILL.md body includes cross-references to specific files in `references/` +- All original content is preserved across SKILL.md + references/ (nothing lost) + +## Verification Method + +**Method**: CLI command + +**Steps**: +1. Run: `wc -l /Users/francylisboacharuto/agent-skill-creator/SKILL.md` +2. Run: `ls -la /Users/francylisboacharuto/agent-skill-creator/references/` +3. Run: `grep -c 'references/' /Users/francylisboacharuto/agent-skill-creator/SKILL.md` +4. Assert line count <500, references/ has files, and cross-references exist + +**Expected evidence**: SKILL.md line count <500. Multiple files in `references/`. At least 3 cross-references in SKILL.md body. diff --git a/scenarios/SC-062-example-skill-renamed.scenario.md b/scenarios/SC-062-example-skill-renamed.scenario.md new file mode 100644 index 0000000..461c2b7 --- /dev/null +++ b/scenarios/SC-062-example-skill-renamed.scenario.md @@ -0,0 +1,28 @@ +# SC-062: Example Skill Renamed from -cskill to Standard + +> Covers: FR-007, Migration Requirements — article-to-prototype-cskill must be renamed and updated +> Type: Happy Path + +## Given +- The v3.x repository had `article-to-prototype-cskill/` as an example skill +- The repository has been updated to v4.0 + +## When +- The repository file structure is inspected + +## Then +- `article-to-prototype-cskill/` no longer exists +- `article-to-prototype/` exists as the renamed example +- The SKILL.md inside has `name: article-to-prototype` (no -cskill) +- The example follows v4.0 conventions (install.sh, README.md with cross-platform instructions) + +## Verification Method + +**Method**: CLI command + +**Steps**: +1. Run: `test -d /Users/francylisboacharuto/agent-skill-creator/article-to-prototype-cskill && echo "OLD EXISTS" || echo "OLD REMOVED"` +2. Run: `test -d /Users/francylisboacharuto/agent-skill-creator/article-to-prototype && echo "NEW EXISTS" || echo "NEW MISSING"` +3. If new exists, grep for name field: `grep "^name:" article-to-prototype/SKILL.md` + +**Expected evidence**: `article-to-prototype-cskill/` does not exist. `article-to-prototype/` exists. SKILL.md contains `name: article-to-prototype`. diff --git a/scenarios/SC-063-migration-guide-exists.scenario.md b/scenarios/SC-063-migration-guide-exists.scenario.md new file mode 100644 index 0000000..58b7e21 --- /dev/null +++ b/scenarios/SC-063-migration-guide-exists.scenario.md @@ -0,0 +1,25 @@ +# SC-063: MIGRATION.md Guide Exists for v3.x Users + +> Covers: Migration Requirements — A MIGRATION.md guide for users of v3.x +> Type: Happy Path + +## Given +- The repository has been updated to v4.0 + +## When +- The repository root is inspected for migration documentation + +## Then +- A `MIGRATION.md` file exists at the repository root +- It documents how to update from v3.x to v4.0 +- It covers: -cskill suffix removal, marketplace.json changes, SKILL.md restructuring, install.sh addition + +## Verification Method + +**Method**: CLI command + +**Steps**: +1. Run: `test -f /Users/francylisboacharuto/agent-skill-creator/MIGRATION.md && echo "EXISTS" || echo "MISSING"` +2. Run: `grep -c "cskill\|marketplace.json\|install.sh\|v3\|v4\|migration" /Users/francylisboacharuto/agent-skill-creator/MIGRATION.md` + +**Expected evidence**: `MIGRATION.md` exists. Contains references to -cskill removal, marketplace.json changes, and upgrade steps from v3.x to v4.0. diff --git a/scenarios/SC-064-security-scan-eval-call.scenario.md b/scenarios/SC-064-security-scan-eval-call.scenario.md new file mode 100644 index 0000000..4a7108e --- /dev/null +++ b/scenarios/SC-064-security-scan-eval-call.scenario.md @@ -0,0 +1,29 @@ +# SC-064: Security Scan Detects eval() Calls + +> Covers: FR-013, NFR-004 — Security scan catches OWASP top patterns including eval() +> Type: Happy Path + +## Given +- A generated skill directory `risky-skill/` contains `scripts/processor.py` with: + ```python + user_code = input("Enter expression: ") + result = eval(user_code) + ``` + +## When +- The security scan is run on `risky-skill/` + +## Then +- The security scan identifies the `eval()` call as a risk +- The `security` list contains a finding about dangerous `eval()` usage + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Create `risky-skill/scripts/processor.py` with `eval()` call on user input +2. Run the security scan +3. Assert security findings reference `eval()` or "code injection" + +**Expected evidence**: Security finding like `"Dangerous eval() call in scripts/processor.py: potential code injection risk"`. diff --git a/scenarios/SC-065-install-sh-codex-platform.scenario.md b/scenarios/SC-065-install-sh-codex-platform.scenario.md new file mode 100644 index 0000000..0886874 --- /dev/null +++ b/scenarios/SC-065-install-sh-codex-platform.scenario.md @@ -0,0 +1,26 @@ +# SC-065: install.sh Supports Codex CLI Platform + +> Covers: FR-017 — install.sh SHOULD support .codex/skills/ +> Type: Happy Path + +## Given +- A generated skill `log-analysis/` with a valid `install.sh` + +## When +- `./install.sh --platform codex` is run + +## Then +- The skill is copied to `.codex/skills/log-analysis/` +- All skill files are present in the destination +- Exit code is 0 + +## Verification Method + +**Method**: CLI command + +**Steps**: +1. Run: `./log-analysis/install.sh --platform codex` +2. Verify `.codex/skills/log-analysis/SKILL.md` exists +3. Check exit code is 0 + +**Expected evidence**: Exit code 0. Skill files exist at `.codex/skills/log-analysis/`. diff --git a/scenarios/SC-066-activation-trigger-phrases.scenario.md b/scenarios/SC-066-activation-trigger-phrases.scenario.md new file mode 100644 index 0000000..c8c8329 --- /dev/null +++ b/scenarios/SC-066-activation-trigger-phrases.scenario.md @@ -0,0 +1,32 @@ +# SC-066: Meta-Skill Activates on Standard Trigger Phrases + +> Covers: Section 5.1 — Activation interface trigger phrases +> Type: Happy Path + +## Given +- The meta-skill is installed and active in a Claude Code session + +## When +- The user types one of the documented trigger phrases: + - "Create a skill for file organization" + - "Automate this workflow: daily report generation" + - "Every day I copy CSV files manually, automate this" + - "Create an agent for code formatting" + - "Create a cross-platform skill for linting" + - "Validate this skill: my-tool/" + - "Export this skill for Cursor" + +## Then +- Each trigger phrase activates the meta-skill +- The meta-skill begins the appropriate flow (creation, validation, export, or migration) + +## Verification Method + +**Method**: Manual test + +**Steps**: +1. Start a Claude Code session with the meta-skill installed +2. Test each trigger phrase individually +3. Verify the meta-skill activates and begins the correct flow + +**Expected evidence**: Each trigger phrase results in the meta-skill activating. "Create a skill" triggers the 5-phase pipeline. "Validate this skill" triggers the validation flow. "Export this skill" triggers the export flow. diff --git a/scenarios/SC-067-validation-result-structure.scenario.md b/scenarios/SC-067-validation-result-structure.scenario.md new file mode 100644 index 0000000..8382d2c --- /dev/null +++ b/scenarios/SC-067-validation-result-structure.scenario.md @@ -0,0 +1,32 @@ +# SC-067: Validation Returns Correct ValidationResult Structure + +> Covers: FR-011, Section 5.3 — Validation interface returns ValidationResult with valid, errors, warnings, security +> Type: Happy Path + +## Given +- The `validate_skill` function is available in `scripts/validate.py` +- A valid skill directory `test-skill/` exists + +## When +- `result = validate_skill("test-skill/")` is called + +## Then +- The result is a `ValidationResult` object (or dict) with the following fields: + - `valid`: bool + - `errors`: list of strings (spec violations) + - `warnings`: list of strings (recommendations) + - `security`: list of strings (security issues) +- All four fields are present regardless of pass/fail status + +## Verification Method + +**Method**: Automated test + +**Steps**: +1. Call `validate_skill("test-skill/")` +2. Assert `hasattr(result, 'valid')` and `isinstance(result.valid, bool)` +3. Assert `hasattr(result, 'errors')` and `isinstance(result.errors, list)` +4. Assert `hasattr(result, 'warnings')` and `isinstance(result.warnings, list)` +5. Assert `hasattr(result, 'security')` and `isinstance(result.security, list)` + +**Expected evidence**: Result object has all four fields: `valid` (bool), `errors` (list), `warnings` (list), `security` (list). diff --git a/scripts/export_utils.py b/scripts/export_utils.py index 4506d41..e6a463a 100755 --- a/scripts/export_utils.py +++ b/scripts/export_utils.py @@ -8,11 +8,9 @@ Packages Claude Code skills for Desktop/Web/API use with versioning and validati import os import sys import zipfile -import json import subprocess from datetime import datetime -from pathlib import Path -from typing import Dict, List, Tuple, Optional +from typing import Dict, List, Tuple # Directories and files to exclude from exports EXCLUDE_DIRS = { @@ -365,140 +363,117 @@ def generate_installation_guide( """ - content += """--- + content += f"""--- -## 🚀 Installation Instructions +## Cross-Platform Installation -### For Claude Desktop +This skill works on all platforms supporting the Agent Skills Open Standard. -1. **Locate the Desktop package** - - File: `{skill}-desktop-{version}.zip` +### Using install.sh (Recommended) -2. **Open Claude Desktop** - - Launch the Claude Desktop application +If the skill includes an `install.sh` script: -3. **Navigate to Skills settings** - - Go to: **Settings → Capabilities → Skills** +```bash +# Auto-detect platform and install +./install.sh -4. **Upload the skill** - - Click: **Upload skill** - - Select the desktop package .zip file - - Wait for upload confirmation +# Install to specific platform +./install.sh --platform claude-code +./install.sh --platform copilot +./install.sh --platform cursor -5. **Verify installation** - - The skill should now appear in your Skills list - - Try using it with a relevant query +# Project-level install +./install.sh --project -✅ **Your skill is now available in Claude Desktop!** +# Preview without installing +./install.sh --dry-run +``` + +### Manual Installation by Platform + +#### Claude Code +```bash +# User-level +cp -r {skill_name}/ ~/.claude/skills/{skill_name}/ + +# Project-level +cp -r {skill_name}/ .claude/skills/{skill_name}/ +``` + +#### GitHub Copilot +```bash +cp -r {skill_name}/ .github/skills/{skill_name}/ +``` + +#### Cursor +```bash +cp -r {skill_name}/ .cursor/rules/{skill_name}/ +``` + +#### Windsurf +```bash +cp -r {skill_name}/ .windsurf/skills/{skill_name}/ +``` + +#### Cline +```bash +cp -r {skill_name}/ .clinerules/{skill_name}/ +``` + +#### OpenAI Codex CLI +```bash +cp -r {skill_name}/ .codex/skills/{skill_name}/ +``` + +#### Gemini CLI +```bash +cp -r {skill_name}/ .gemini/skills/{skill_name}/ +``` + +### Claude Desktop / claude.ai (Web) + +1. Locate the Desktop package: `{skill_name}-desktop-{{version}}.zip` +2. Open Claude Desktop or claude.ai +3. Go to **Settings > Skills > Upload skill** +4. Select the .zip file and confirm + +### Claude API + +1. Locate the API package: `{skill_name}-api-{{version}}.zip` +2. Upload programmatically: +```python +import anthropic +client = anthropic.Anthropic() +with open('{skill_name}-api-{{version}}.zip', 'rb') as f: + skill = client.skills.create(file=f, name="{skill_name}") +``` --- -### For claude.ai (Web Interface) +## Platform Comparison -1. **Locate the Desktop package** - - File: `{skill}-desktop-{version}.zip` - - (Same package as Desktop - optimized for both) - -2. **Visit claude.ai** - - Open https://claude.ai in your browser - - Log in to your account - -3. **Open Settings** - - Click your profile icon - - Select **Settings** - -4. **Navigate to Skills** - - Click on the **Skills** section - -5. **Upload the skill** - - Click: **Upload skill** - - Select the desktop package .zip file - - Confirm the upload - -6. **Start using** - - Create a new conversation - - The skill will activate automatically when relevant - -✅ **Your skill is now available at claude.ai!** +| Platform | Install Method | Updates | marketplace.json | +|----------|---------------|---------|-----------------| +| **Claude Code** | install.sh / copy | git pull | Optional | +| **GitHub Copilot** | install.sh / copy | git pull | Not used | +| **Cursor** | install.sh / copy | git pull | Not used | +| **Windsurf** | install.sh / copy | git pull | Not used | +| **Cline** | install.sh / copy | git pull | Not used | +| **Codex CLI** | install.sh / copy | git pull | Not used | +| **Gemini CLI** | install.sh / copy | git pull | Not used | +| **Desktop/Web** | .zip upload | Re-upload | Not used | +| **Claude API** | API upload | New upload | Not used | --- -### For Claude API (Programmatic Integration) - -1. **Locate the API package** - - File: `{skill}-api-{version}.zip` - - Optimized for API use (smaller, execution-focused) - -2. **Install required packages** - ```bash - pip install anthropic - ``` - -3. **Upload skill programmatically** - ```python - import anthropic - - client = anthropic.Anthropic(api_key="your-api-key") - - # Upload the skill - with open('{skill}-api-{version}.zip', 'rb') as f: - skill = client.skills.create( - file=f, - name="{skill}" - ) - - print(f"Skill uploaded! ID: {{skill.id}}") - ``` - -4. **Use in API requests** - ```python - response = client.messages.create( - model="claude-sonnet-4", - 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" - ] - ) - - print(response.content) - ``` - -5. **Important API requirements** - - Must include beta headers: `code-execution-2025-08-25` and `skills-2025-10-02` - - Maximum 8 skills per request - - Skills run in isolated containers (no network access, no pip install) - -✅ **Your skill is now integrated with the Claude API!** - ---- - -## 📋 Platform Comparison - -| Feature | Claude Code | Desktop/Web | Claude API | -|---------|-------------|-------------|------------| -| **Installation** | Plugin command | Manual upload | Programmatic | -| **Updates** | Git pull | Re-upload .zip | New upload | -| **Version Control** | ✅ Native | ⚠️ Manual | ✅ Versioned | -| **Team Sharing** | ✅ Via plugins | ❌ Individual | ✅ Via API | -| **marketplace.json** | ✅ Used | ❌ Ignored | ❌ Not used | - ---- - -## ⚙️ Technical Details +## Technical Details ### What's Included """ if desktop_package and desktop_package['success']: - content += f"""**Desktop Package:** + content += """**Desktop Package:** - SKILL.md (core functionality) - Complete scripts/ directory - Full references/ documentation @@ -508,7 +483,7 @@ def generate_installation_guide( """ if api_package and api_package['success']: - content += f"""**API Package:** + content += """**API Package:** - SKILL.md (required) - Essential scripts only - Minimal documentation (execution-focused) @@ -585,7 +560,7 @@ After installation, verify: **Need help?** Refer to the platform-specific documentation or the main repository guides. -**Generated by:** agent-skill-creator v3.2 cross-platform export system +**Generated by:** agent-skill-creator v4.0 cross-platform export system """ # Write guide to file @@ -598,6 +573,7 @@ After installation, verify: def export_skill( skill_path: str, variants: List[str] = ['desktop', 'api'], + platform: str = None, version_override: str = None, output_dir: str = None ) -> Dict: @@ -607,6 +583,7 @@ def export_skill( Args: skill_path: Path to skill directory variants: List of variants to create ('desktop', 'api', or both) + platform: Target platform for platform-specific output (optional) version_override: User-specified version (optional) output_dir: Where to save exports (default: exports/ in parent dir) @@ -637,6 +614,54 @@ def export_skill( } print("✅ Skill structure valid") + # Run spec validation if validate.py is available + validate_script = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'validate.py') + if os.path.exists(validate_script): + print("🔍 Running spec validation...") + try: + result = subprocess.run( + [sys.executable, validate_script, skill_path, '--json'], + capture_output=True, text=True, timeout=30 + ) + if result.returncode != 0: + import json as _json + try: + val_result = _json.loads(result.stdout) + if val_result.get('errors'): + print(f"⚠️ Spec validation warnings: {len(val_result['errors'])} errors") + for err in val_result['errors']: + print(f" - {err}") + except (ValueError, KeyError): + pass + else: + print("✅ Spec validation passed") + except (subprocess.TimeoutExpired, Exception): + print("⚠️ Spec validation skipped (script error)") + + # Run security scan if security_scan.py is available + security_script = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'security_scan.py') + if os.path.exists(security_script): + print("🔍 Running security scan...") + try: + result = subprocess.run( + [sys.executable, security_script, skill_path, '--json'], + capture_output=True, text=True, timeout=30 + ) + if result.returncode != 0: + import json as _json + try: + sec_result = _json.loads(result.stdout) + if sec_result.get('issues'): + print(f"⚠️ Security issues found: {len(sec_result['issues'])}") + for issue in sec_result['issues'][:5]: + print(f" - [{issue.get('severity', 'unknown')}] {issue.get('description', '')}") + except (ValueError, KeyError): + pass + else: + print("✅ Security scan passed") + except (subprocess.TimeoutExpired, Exception): + print("⚠️ Security scan skipped (script error)") + # Determine version version = get_skill_version(skill_path, version_override) print(f"📌 Version: {version}") @@ -649,7 +674,7 @@ def export_skill( } if 'desktop' in variants: - print(f"\n🔨 Creating Desktop/Web package...") + print("\n🔨 Creating Desktop/Web package...") desktop_result = create_export_package( skill_path, output_dir, 'desktop', version, skill_name ) @@ -661,7 +686,7 @@ def export_skill( results['success'] = False if 'api' in variants: - print(f"\n🔨 Creating API package...") + print("\n🔨 Creating API package...") api_result = create_export_package( skill_path, output_dir, 'api', version, skill_name ) @@ -674,7 +699,7 @@ def export_skill( # Generate installation guide if results['success']: - print(f"\n📄 Generating installation guide...") + print("\n📄 Generating installation guide...") guide_path = generate_installation_guide( skill_name, version, @@ -703,10 +728,10 @@ Options: --output-dir DIR Output directory (default: exports/) Examples: - python export_utils.py ./my-skill-cskill - python export_utils.py ./my-skill-cskill --variant desktop - python export_utils.py ./my-skill-cskill --version 2.0.1 - python export_utils.py ./my-skill-cskill --variant api --output-dir ./dist + python export_utils.py ./my-skill + python export_utils.py ./my-skill --variant desktop + python export_utils.py ./my-skill --version 2.0.1 + python export_utils.py ./my-skill --variant api --output-dir ./dist """) sys.exit(1) @@ -744,7 +769,7 @@ Examples: print(f"\n{'='*60}") if results['success']: print("✅ Export completed successfully!") - print(f"\n📦 Packages created:") + print("\n📦 Packages created:") for variant, package in results['packages'].items(): if package['success']: print(f" - {variant.capitalize()}: {os.path.basename(package['zip_path'])}") diff --git a/scripts/install-template.sh b/scripts/install-template.sh new file mode 100755 index 0000000..c8ec541 --- /dev/null +++ b/scripts/install-template.sh @@ -0,0 +1,434 @@ +#!/bin/sh +# install-template.sh — Cross-platform skill installation script +# This file is a template. During skill generation, {{SKILL_NAME}} is replaced +# with the actual skill name and the result is shipped as install.sh inside +# every generated skill package. +# +# POSIX-compatible (works in bash, dash, zsh, ash, etc.) +# Exit codes: +# 0 — Success +# 1 — Validation failed (missing or malformed SKILL.md) +# 2 — Platform not detected +# 3 — Permission denied + +set -euo pipefail + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- +SKILL_NAME="{{SKILL_NAME}}" +VERSION="1.0.0" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" + +# --------------------------------------------------------------------------- +# Colors (disabled when stdout is not a terminal) +# --------------------------------------------------------------------------- +if [ -t 1 ]; then + RED='\033[0;31m' + GREEN='\033[0;32m' + YELLOW='\033[1;33m' + BLUE='\033[0;34m' + BOLD='\033[1m' + NC='\033[0m' +else + RED='' + GREEN='' + YELLOW='' + BLUE='' + BOLD='' + NC='' +fi + +# --------------------------------------------------------------------------- +# Logging helpers +# --------------------------------------------------------------------------- +info() { printf "${BLUE}[INFO]${NC} %s\n" "$1"; } +success() { printf "${GREEN}[OK]${NC} %s\n" "$1"; } +warn() { printf "${YELLOW}[WARN]${NC} %s\n" "$1"; } +error() { printf "${RED}[ERROR]${NC} %s\n" "$1" >&2; } + +# --------------------------------------------------------------------------- +# Usage / help +# --------------------------------------------------------------------------- +show_help() { + cat </dev/null; then + error "Cannot create directory: ${INSTALL_DIR}" + error "Check file permissions or run with appropriate privileges." + exit 3 + fi + + # Copy files. + for file in "${SCRIPT_DIR}"/*; do + [ -e "$file" ] || continue + local fname + fname="$(basename "$file")" + [ "$fname" = "$install_script_name" ] && continue + + if ! cp -R "$file" "${INSTALL_DIR}/" 2>/dev/null; then + error "Failed to copy ${fname} to ${INSTALL_DIR}/" + error "Check file permissions." + exit 3 + fi + file_count=$((file_count + 1)) + done + + # Copy dotfiles (if any). + for file in "${SCRIPT_DIR}"/.*; do + [ -e "$file" ] || continue + local fname + fname="$(basename "$file")" + [ "$fname" = "." ] || [ "$fname" = ".." ] && continue + + if ! cp -R "$file" "${INSTALL_DIR}/" 2>/dev/null; then + error "Failed to copy ${fname} to ${INSTALL_DIR}/" + error "Check file permissions." + exit 3 + fi + file_count=$((file_count + 1)) + done + + success "Copied ${file_count} file(s) to ${INSTALL_DIR}" +} + +# --------------------------------------------------------------------------- +# Activation instructions +# --------------------------------------------------------------------------- +print_activation_instructions() { + if $DRY_RUN; then + return 0 + fi + + printf "\n${GREEN}${BOLD}Installation complete!${NC}\n\n" + + case "$PLATFORM" in + claude-code) + printf "To activate the skill in Claude Code:\n" + printf " 1. Start a new Claude Code session.\n" + printf " 2. The skill will be loaded automatically from:\n" + printf " ${BOLD}${INSTALL_DIR}/SKILL.md${NC}\n" + printf " 3. Use trigger phrases defined in the skill's description.\n" + ;; + copilot) + printf "To activate the skill in GitHub Copilot:\n" + printf " 1. Open your project in VS Code or the GitHub CLI.\n" + printf " 2. The skill is available at:\n" + printf " ${BOLD}${INSTALL_DIR}/SKILL.md${NC}\n" + printf " 3. Reference the skill in your Copilot instructions.\n" + ;; + cursor) + printf "To activate the skill in Cursor:\n" + printf " 1. Open your project in Cursor.\n" + printf " 2. The rule is loaded automatically from:\n" + printf " ${BOLD}${INSTALL_DIR}/SKILL.md${NC}\n" + printf " 3. Use trigger phrases to invoke the skill.\n" + ;; + windsurf) + printf "To activate the skill in Windsurf:\n" + printf " 1. Open your project in Windsurf.\n" + printf " 2. The skill is available at:\n" + printf " ${BOLD}${INSTALL_DIR}/SKILL.md${NC}\n" + printf " 3. Use trigger phrases to invoke the skill.\n" + ;; + cline) + printf "To activate the skill in Cline:\n" + printf " 1. Open your project in VS Code with Cline.\n" + printf " 2. The rule is loaded from:\n" + printf " ${BOLD}${INSTALL_DIR}/SKILL.md${NC}\n" + printf " 3. Cline will pick up the rule automatically.\n" + ;; + codex) + printf "To activate the skill in OpenAI Codex CLI:\n" + printf " 1. Start a new Codex CLI session.\n" + printf " 2. The skill is available at:\n" + printf " ${BOLD}${INSTALL_DIR}/SKILL.md${NC}\n" + printf " 3. Reference the skill in your instructions.\n" + ;; + gemini) + printf "To activate the skill in Gemini CLI:\n" + printf " 1. Start a new Gemini CLI session.\n" + printf " 2. The skill is available at:\n" + printf " ${BOLD}${INSTALL_DIR}/SKILL.md${NC}\n" + printf " 3. The skill will be loaded automatically.\n" + ;; + esac + + printf "\n" +} + +# --------------------------------------------------------------------------- +# Main +# --------------------------------------------------------------------------- +main() { + printf "${BOLD}Installing skill: ${SKILL_NAME}${NC}\n" + printf "%-40s\n" "----------------------------------------" + + parse_args "$@" + validate_skill_md + detect_platform + resolve_install_path + install_files + print_activation_instructions + + if $DRY_RUN; then + info "Dry run complete. No changes were made." + else + success "Skill '${SKILL_NAME}' installed successfully for ${PLATFORM}." + fi + + exit 0 +} + +main "$@" diff --git a/scripts/security_scan.py b/scripts/security_scan.py new file mode 100644 index 0000000..64d24a8 --- /dev/null +++ b/scripts/security_scan.py @@ -0,0 +1,423 @@ +#!/usr/bin/env python3 +""" +Security Scanner for Generated Agent Skills. + +Scans a skill directory for hardcoded API keys, sensitive files, and dangerous +Python patterns that could pose security risks. + +Usage: + python3 scripts/security_scan.py path/to/skill/ + python3 scripts/security_scan.py path/to/skill/ --json + +Exit codes: + 0 - Clean (no issues found) + 1 - Issues found (one or more security issues detected) +""" + +import json +import os +import re +import sys +from pathlib import Path + + +# --- API Key Patterns --- +# Each entry: (pattern_name, compiled_regex, description, severity) + +API_KEY_PATTERNS: list[tuple[str, re.Pattern, str, str]] = [ + ( + "OpenAI API Key", + re.compile(r"sk-[a-zA-Z0-9]{20,}"), + "Hardcoded OpenAI API key detected", + "high", + ), + ( + "AWS Access Key", + re.compile(r"AKIA[A-Z0-9]{16}"), + "Hardcoded AWS access key ID detected", + "high", + ), + ( + "GitHub Personal Access Token", + re.compile(r"ghp_[a-zA-Z0-9]{36}"), + "Hardcoded GitHub personal access token detected", + "high", + ), + ( + "GitLab Personal Access Token", + re.compile(r"glpat-[a-zA-Z0-9\-]{20}"), + "Hardcoded GitLab personal access token detected", + "high", + ), + ( + "Slack Token", + re.compile(r"xox[bprs]-[a-zA-Z0-9\-]+"), + "Hardcoded Slack token detected", + "high", + ), + ( + "Generic Secret", + re.compile( + r"""(api[_\-]?key|secret|token|password)\s*[:=]\s*["'][^"']{8,}["']""", + re.IGNORECASE, + ), + "Possible hardcoded secret (generic key/token/password pattern)", + "medium", + ), +] + + +# --- Sensitive File Names --- + +SENSITIVE_FILES: dict[str, str] = { + ".env": "Environment file may contain secrets", + "credentials.json": "Credentials file may contain API keys or passwords", + "secrets.json": "Secrets file may contain sensitive data", + "api_keys.json": "API keys file may contain hardcoded keys", +} + + +# --- Dangerous Python Patterns --- +# Each entry: (pattern_name, compiled_regex, description, severity) + +PYTHON_DANGER_PATTERNS: list[tuple[str, re.Pattern, str, str]] = [ + ( + "eval() usage", + re.compile(r"\beval\s*\("), + "Use of eval() can execute arbitrary code; avoid unless strictly necessary", + "high", + ), + ( + "exec() usage", + re.compile(r"\bexec\s*\("), + "Use of exec() can execute arbitrary code; avoid unless strictly necessary", + "high", + ), + ( + "os.system() with concatenation", + re.compile(r"os\.system\s*\([^)]*[\+f\"']"), + "os.system() with string concatenation is vulnerable to shell injection", + "high", + ), + ( + "subprocess with shell=True", + re.compile(r"subprocess\.call\s*\([^)]*shell\s*=\s*True"), + "subprocess.call() with shell=True is vulnerable to shell injection", + "high", + ), + ( + "__import__() dynamic import", + re.compile(r"__import__\s*\("), + "Dynamic imports via __import__() can load arbitrary modules", + "medium", + ), +] + + +# File extensions to scan for content patterns +TEXT_EXTENSIONS: set[str] = { + ".py", ".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".cfg", + ".ini", ".sh", ".bash", ".zsh", ".env", ".conf", ".xml", ".html", + ".css", ".js", ".ts", ".jsx", ".tsx", ".sql", ".csv", ".rst", +} + +# Maximum file size to scan (skip very large files to avoid performance issues) +MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024 # 10 MB + +# Directories to skip during scanning +SKIP_DIRS: set[str] = { + ".git", "__pycache__", "node_modules", ".venv", "venv", "env", + ".pytest_cache", ".mypy_cache", "dist", "build", +} + + +def _is_text_file(file_path: Path) -> bool: + """ + Determine if a file is likely a text file that should be scanned. + + Uses the file extension to decide. Falls back to attempting to read + a small portion of the file if the extension is unrecognized. + + Args: + file_path: Path to the file. + + Returns: + True if the file should be scanned for content patterns. + """ + if file_path.suffix.lower() in TEXT_EXTENSIONS: + return True + + # For files with no extension or unrecognized extensions, try reading a sample + if file_path.suffix == "" or file_path.suffix.lower() not in { + ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".svg", + ".pdf", ".zip", ".tar", ".gz", ".bz2", ".xz", + ".exe", ".dll", ".so", ".dylib", ".whl", ".egg", + ".pyc", ".pyo", ".class", ".o", ".a", + ".mp3", ".mp4", ".wav", ".avi", ".mov", + ".ttf", ".otf", ".woff", ".woff2", ".eot", + ".sqlite", ".db", + }: + try: + with open(file_path, "rb") as f: + chunk = f.read(1024) + # Check for null bytes (binary indicator) + if b"\x00" in chunk: + return False + return True + except (OSError, PermissionError): + return False + + return False + + +def _scan_file_content( + file_path: Path, + skill_dir: Path, +) -> list[dict]: + """ + Scan a single file for security issues in its content. + + Args: + file_path: Absolute path to the file. + skill_dir: Root directory of the skill (for relative path display). + + Returns: + List of issue dictionaries found in this file. + """ + issues: list[dict] = [] + relative_path = str(file_path.relative_to(skill_dir)) + + try: + file_size = file_path.stat().st_size + except OSError: + return issues + + if file_size > MAX_FILE_SIZE_BYTES: + return issues + + if not _is_text_file(file_path): + return issues + + try: + lines = file_path.read_text(encoding="utf-8", errors="replace").splitlines() + except (OSError, PermissionError): + return issues + + is_python = file_path.suffix.lower() == ".py" + + for line_num, line in enumerate(lines, start=1): + # Check API key patterns against all text files + for pattern_name, regex, description, severity in API_KEY_PATTERNS: + match = regex.search(line) + if match: + issues.append({ + "severity": severity, + "file": relative_path, + "line": line_num, + "pattern": pattern_name, + "description": description, + }) + + # Check Python-specific patterns only in .py files + if is_python: + for pattern_name, regex, description, severity in PYTHON_DANGER_PATTERNS: + match = regex.search(line) + if match: + issues.append({ + "severity": severity, + "file": relative_path, + "line": line_num, + "pattern": pattern_name, + "description": description, + }) + + return issues + + +def security_scan(skill_path: str) -> dict: + """ + Perform a security scan on a skill directory. + + Checks for hardcoded API keys, sensitive files, and dangerous code patterns. + + Args: + skill_path: Path to the skill directory to scan. + + Returns: + Dictionary with keys: + - ``clean`` (bool): True if no issues were found. + - ``issues`` (list[dict]): List of issue dictionaries. Each has: + - ``severity`` (str): "high", "medium", or "low" + - ``file`` (str): Relative file path + - ``line`` (int): Line number (0 for file-level issues) + - ``pattern`` (str): Pattern name that triggered the issue + - ``description`` (str): Human-readable description + """ + issues: list[dict] = [] + + skill_dir = Path(skill_path).resolve() + + # --- Check: directory exists --- + if not skill_dir.exists(): + return { + "clean": False, + "issues": [{ + "severity": "high", + "file": str(skill_dir), + "line": 0, + "pattern": "missing_directory", + "description": f"Path does not exist: {skill_dir}", + }], + } + + if not skill_dir.is_dir(): + return { + "clean": False, + "issues": [{ + "severity": "high", + "file": str(skill_dir), + "line": 0, + "pattern": "not_a_directory", + "description": f"Path is not a directory: {skill_dir}", + }], + } + + # --- Check: sensitive files --- + for sensitive_name, description in SENSITIVE_FILES.items(): + sensitive_path = skill_dir / sensitive_name + if sensitive_path.exists(): + issues.append({ + "severity": "high", + "file": sensitive_name, + "line": 0, + "pattern": "Sensitive file", + "description": description, + }) + + # Also check subdirectories for .env files + for root, dirs, files in os.walk(skill_dir): + root_path = Path(root) + + # Skip excluded directories + dirs[:] = [d for d in dirs if d not in SKIP_DIRS] + + for filename in files: + file_path = root_path / filename + relative = str(file_path.relative_to(skill_dir)) + + # Check for .env files anywhere in the tree + if filename == ".env" and relative != ".env": + issues.append({ + "severity": "high", + "file": relative, + "line": 0, + "pattern": "Sensitive file", + "description": "Environment file may contain secrets", + }) + + # Check for sensitive JSON files in subdirectories + if filename in ("credentials.json", "secrets.json", "api_keys.json"): + if relative != filename: # Not already caught at root level + issues.append({ + "severity": "high", + "file": relative, + "line": 0, + "pattern": "Sensitive file", + "description": SENSITIVE_FILES.get( + filename, "Sensitive file detected" + ), + }) + + # --- Scan file contents --- + for root, dirs, files in os.walk(skill_dir): + root_path = Path(root) + + # Skip excluded directories + dirs[:] = [d for d in dirs if d not in SKIP_DIRS] + + for filename in files: + file_path = root_path / filename + file_issues = _scan_file_content(file_path, skill_dir) + issues.extend(file_issues) + + # Sort issues: high first, then medium, then low + severity_order = {"high": 0, "medium": 1, "low": 2} + issues.sort(key=lambda x: (severity_order.get(x["severity"], 3), x["file"], x["line"])) + + return { + "clean": len(issues) == 0, + "issues": issues, + } + + +def _print_human_readable(result: dict, skill_path: str) -> None: + """ + Print security scan results in a human-readable format. + + Args: + result: The scan result dictionary. + skill_path: The path that was scanned (for display). + """ + print(f"Security scan: {skill_path}") + print(f"{'=' * 60}") + + if result["clean"]: + print("Status: CLEAN") + print("\nNo security issues found.") + else: + print(f"Status: ISSUES FOUND ({len(result['issues'])})") + + # Count by severity + high = sum(1 for i in result["issues"] if i["severity"] == "high") + medium = sum(1 for i in result["issues"] if i["severity"] == "medium") + low = sum(1 for i in result["issues"] if i["severity"] == "low") + print(f"\n High: {high} Medium: {medium} Low: {low}") + + print() + for issue in result["issues"]: + severity_label = issue["severity"].upper().ljust(6) + location = issue["file"] + if issue["line"] > 0: + location += f":{issue['line']}" + print(f" [{severity_label}] {location}") + print(f" Pattern: {issue['pattern']}") + print(f" {issue['description']}") + print() + + print(f"{'=' * 60}") + + +def main() -> None: + """CLI entry point for the security scanner.""" + if len(sys.argv) < 2: + print( + "Usage: python3 scripts/security_scan.py [--json]\n" + "\n" + "Arguments:\n" + " skill-path Path to the skill directory to scan\n" + "\n" + "Options:\n" + " --json Output results as JSON to stdout\n" + "\n" + "Exit codes:\n" + " 0 Clean (no issues)\n" + " 1 Issues found (one or more security issues)\n", + file=sys.stderr, + ) + sys.exit(1) + + skill_path = sys.argv[1] + use_json = "--json" in sys.argv + + result = security_scan(skill_path) + + if use_json: + print(json.dumps(result, indent=2)) + else: + _print_human_readable(result, skill_path) + + sys.exit(0 if result["clean"] else 1) + + +if __name__ == "__main__": + main() diff --git a/scripts/validate.py b/scripts/validate.py new file mode 100644 index 0000000..1d73440 --- /dev/null +++ b/scripts/validate.py @@ -0,0 +1,387 @@ +#!/usr/bin/env python3 +""" +Spec Compliance Validator for the Agent Skills Open Standard. + +Validates a skill directory against the Agent Skills Open Standard by checking +SKILL.md existence, frontmatter structure, naming conventions, and best practices. + +Usage: + python3 scripts/validate.py path/to/skill/ + python3 scripts/validate.py path/to/skill/ --json + +Exit codes: + 0 - Valid (no errors, may have warnings) + 1 - Invalid (one or more errors found) +""" + +import json +import re +import sys +from pathlib import Path +from typing import Optional + + +# --- Constants --- + +MAX_NAME_LENGTH = 64 +MAX_DESCRIPTION_LENGTH = 1024 +MAX_BODY_LINES_WARNING = 500 + +# Pattern for valid skill names: lowercase letters, numbers, hyphens +NAME_PATTERN = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$") +CONSECUTIVE_HYPHENS_PATTERN = re.compile(r"--") + +# Pattern for local file references in markdown: [text](path) excluding http/https/mailto/# +LOCAL_LINK_PATTERN = re.compile( + r"\[([^\]]*)\]\(([^)]+)\)" +) + + +def _parse_frontmatter(content: str) -> tuple[Optional[str], Optional[str]]: + """ + Extract frontmatter and body from SKILL.md content. + + Args: + content: Full text content of SKILL.md. + + Returns: + Tuple of (frontmatter_text, body_text). Either may be None if + frontmatter is missing or malformed. + """ + if not content.startswith("---"): + return None, None + + # Find the closing --- (skip the opening one at position 0) + closing_index = content.find("---", 3) + if closing_index == -1: + return None, None + + frontmatter = content[3:closing_index].strip() + body = content[closing_index + 3:].strip() + return frontmatter, body + + +def _parse_yaml_field(frontmatter: str, field: str) -> Optional[str]: + """ + Extract a top-level scalar field value from YAML frontmatter using simple parsing. + + Handles both inline values (``name: value``) and YAML block scalars + (``description: >-`` followed by indented continuation lines). + + Args: + frontmatter: The frontmatter text (without ``---`` delimiters). + field: The field name to look for. + + Returns: + The field value as a string, or None if the field is not present. + """ + lines = frontmatter.split("\n") + for i, line in enumerate(lines): + stripped = line.strip() + if stripped.startswith(f"{field}:"): + value = stripped[len(field) + 1:].strip() + + # Check for YAML block scalar indicators (>- , |-, >, |) + if value in (">-", "|-", ">", "|", ">+", "|+"): + # Collect indented continuation lines + parts: list[str] = [] + for j in range(i + 1, len(lines)): + continuation = lines[j] + # Continuation lines must be indented + if continuation and (continuation[0] == " " or continuation[0] == "\t"): + parts.append(continuation.strip()) + else: + break + return " ".join(parts) if parts else "" + + return value + return None + + +def _field_exists_in_frontmatter(frontmatter: str, field: str) -> bool: + """ + Check whether a field name appears as a top-level key in frontmatter. + + Args: + frontmatter: The frontmatter text. + field: The field name to look for. + + Returns: + True if the field is present. + """ + for line in frontmatter.split("\n"): + stripped = line.strip() + if stripped.startswith(f"{field}:"): + return True + return False + + +def _subfield_exists(frontmatter: str, parent: str, child: str) -> bool: + """ + Check whether a sub-field exists under a parent field in YAML frontmatter. + + Args: + frontmatter: The frontmatter text. + parent: The parent field name (e.g., ``metadata``). + child: The child field name (e.g., ``author``). + + Returns: + True if the sub-field is found under the parent. + """ + lines = frontmatter.split("\n") + in_parent = False + for line in lines: + stripped = line.strip() + # Detect the parent field + if stripped.startswith(f"{parent}:"): + in_parent = True + continue + if in_parent: + # Still inside the parent block if line is indented + if line and (line[0] == " " or line[0] == "\t"): + if stripped.startswith(f"{child}:"): + return True + else: + # Left the parent block + in_parent = False + return False + + +def _extract_local_links(body: str) -> list[str]: + """ + Extract local file paths referenced in markdown links within the body. + + Filters out URLs (http, https, mailto) and anchor links (#). + + Args: + body: The markdown body text. + + Returns: + List of relative file paths referenced in the body. + """ + paths: list[str] = [] + for match in LOCAL_LINK_PATTERN.finditer(body): + target = match.group(2).strip() + # Skip external URLs and anchors + if target.startswith(("http://", "https://", "mailto:", "#")): + continue + # Strip any anchor fragment from the path + if "#" in target: + target = target.split("#")[0] + if target: + paths.append(target) + return paths + + +def validate_skill(skill_path: str) -> dict: + """ + Validate a skill directory against the Agent Skills Open Standard. + + Performs both required checks (errors) and recommended checks (warnings). + + Args: + skill_path: Path to the skill directory to validate. + + Returns: + Dictionary with keys: + - ``valid`` (bool): True if no errors were found. + - ``errors`` (list[str]): List of error messages (must fix). + - ``warnings`` (list[str]): List of warning messages (should fix). + """ + errors: list[str] = [] + warnings: list[str] = [] + + skill_dir = Path(skill_path).resolve() + + # --- Check: directory exists --- + if not skill_dir.exists(): + errors.append(f"Path does not exist: {skill_dir}") + return {"valid": False, "errors": errors, "warnings": warnings} + + if not skill_dir.is_dir(): + errors.append(f"Path is not a directory: {skill_dir}") + return {"valid": False, "errors": errors, "warnings": warnings} + + # --- Check: SKILL.md exists --- + skill_md = skill_dir / "SKILL.md" + if not skill_md.exists(): + errors.append("SKILL.md not found in skill directory") + return {"valid": False, "errors": errors, "warnings": warnings} + + # --- Read SKILL.md --- + try: + content = skill_md.read_text(encoding="utf-8") + except Exception as exc: + errors.append(f"Could not read SKILL.md: {exc}") + return {"valid": False, "errors": errors, "warnings": warnings} + + # --- Check: frontmatter exists --- + if not content.startswith("---"): + errors.append("SKILL.md must start with '---' frontmatter delimiter") + return {"valid": False, "errors": errors, "warnings": warnings} + + frontmatter, body = _parse_frontmatter(content) + + if frontmatter is None: + errors.append("SKILL.md frontmatter is not properly closed (missing closing '---')") + return {"valid": False, "errors": errors, "warnings": warnings} + + # --- Check: name field --- + name_value = _parse_yaml_field(frontmatter, "name") + if name_value is None: + errors.append("'name' field is missing from frontmatter") + else: + name_value = name_value.strip() + if len(name_value) == 0: + errors.append("'name' field is empty") + elif len(name_value) > MAX_NAME_LENGTH: + errors.append( + f"'name' field exceeds {MAX_NAME_LENGTH} characters " + f"(found {len(name_value)})" + ) + else: + # Validate name format + if not NAME_PATTERN.match(name_value): + errors.append( + f"'name' field must contain only lowercase letters, numbers, " + f"and hyphens (found: '{name_value}')" + ) + if name_value.startswith("-"): + errors.append(f"'name' must not start with a hyphen (found: '{name_value}')") + if name_value.endswith("-"): + errors.append(f"'name' must not end with a hyphen (found: '{name_value}')") + if CONSECUTIVE_HYPHENS_PATTERN.search(name_value): + errors.append( + f"'name' must not contain consecutive hyphens (found: '{name_value}')" + ) + + # --- Check: directory name matches name field --- + dir_name = skill_dir.name + if dir_name != name_value: + errors.append( + f"Directory name '{dir_name}' does not match 'name' field " + f"'{name_value}' in frontmatter" + ) + + # --- Check: description field --- + description_value = _parse_yaml_field(frontmatter, "description") + if description_value is None: + errors.append("'description' field is missing from frontmatter") + else: + description_value = description_value.strip() + if len(description_value) == 0: + errors.append("'description' field is empty") + elif len(description_value) > MAX_DESCRIPTION_LENGTH: + errors.append( + f"'description' field exceeds {MAX_DESCRIPTION_LENGTH} characters " + f"(found {len(description_value)})" + ) + + # --- Warnings --- + + # Body line count + if body is not None: + body_lines = body.split("\n") + body_line_count = len(body_lines) + if body_line_count > MAX_BODY_LINES_WARNING: + warnings.append( + f"SKILL.md body exceeds {MAX_BODY_LINES_WARNING} lines " + f"({body_line_count} lines). Consider moving content to references/." + ) + + # license field + if not _field_exists_in_frontmatter(frontmatter, "license"): + warnings.append("'license' field is missing from frontmatter") + + # metadata field + if not _field_exists_in_frontmatter(frontmatter, "metadata"): + warnings.append("'metadata' field is missing from frontmatter") + else: + if not _subfield_exists(frontmatter, "metadata", "author"): + warnings.append("'metadata.author' sub-field is missing") + if not _subfield_exists(frontmatter, "metadata", "version"): + warnings.append("'metadata.version' sub-field is missing") + + # Referenced local files + if body is not None: + local_links = _extract_local_links(body) + for link_path in local_links: + resolved = skill_dir / link_path + if not resolved.exists(): + warnings.append( + f"Referenced file does not exist: '{link_path}'" + ) + + return { + "valid": len(errors) == 0, + "errors": errors, + "warnings": warnings, + } + + +def _print_human_readable(result: dict, skill_path: str) -> None: + """ + Print validation results in a human-readable format. + + Args: + result: The validation result dictionary. + skill_path: The path that was validated (for display). + """ + print(f"Validating: {skill_path}") + print(f"{'=' * 60}") + + if result["valid"]: + print("Status: VALID") + else: + print("Status: INVALID") + + if result["errors"]: + print(f"\nErrors ({len(result['errors'])}):") + for error in result["errors"]: + print(f" [ERROR] {error}") + + if result["warnings"]: + print(f"\nWarnings ({len(result['warnings'])}):") + for warning in result["warnings"]: + print(f" [WARN] {warning}") + + if not result["errors"] and not result["warnings"]: + print("\nNo issues found.") + + print(f"{'=' * 60}") + + +def main() -> None: + """CLI entry point for the spec compliance validator.""" + if len(sys.argv) < 2: + print( + "Usage: python3 scripts/validate.py [--json]\n" + "\n" + "Arguments:\n" + " skill-path Path to the skill directory to validate\n" + "\n" + "Options:\n" + " --json Output results as JSON to stdout\n" + "\n" + "Exit codes:\n" + " 0 Valid (no errors)\n" + " 1 Invalid (one or more errors)\n", + file=sys.stderr, + ) + sys.exit(1) + + skill_path = sys.argv[1] + use_json = "--json" in sys.argv + + result = validate_skill(skill_path) + + if use_json: + print(json.dumps(result, indent=2)) + else: + _print_human_readable(result, skill_path) + + sys.exit(0 if result["valid"] else 1) + + +if __name__ == "__main__": + main()