295ddb086e
Initialize built-in registry at ./registry so teams can publish and discover skills without managing a separate repo. Updated README examples to use the simpler default --registry path. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
568 lines
18 KiB
Markdown
568 lines
18 KiB
Markdown
# Agent Skill Creator
|
|
|
|
**Create cross-platform agent skills from natural language workflow descriptions.**
|
|
|
|
[](https://github.com/anthropics/agent-skills-spec)
|
|
[]()
|
|
[]()
|
|
|
|
---
|
|
|
|
## What Is This?
|
|
|
|
Agent Skill Creator is a **meta-skill** -- a skill that creates other skills. Describe a repetitive workflow in plain English and it generates a complete, validated, cross-platform agent skill through an autonomous 5-phase pipeline.
|
|
|
|
**Input**: *"Every day I download stock data, analyze trends, and create reports"*
|
|
**Output**: A ready-to-install skill directory with functional scripts, documentation, cross-platform installer, and spec-compliant SKILL.md.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Claude Code
|
|
|
|
```bash
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.claude/skills/agent-skill-creator
|
|
```
|
|
|
|
### GitHub Copilot
|
|
|
|
```bash
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .github/skills/agent-skill-creator
|
|
```
|
|
|
|
### Cursor
|
|
|
|
```bash
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .cursor/rules/agent-skill-creator
|
|
```
|
|
|
|
After installing, open your agent and type:
|
|
|
|
```
|
|
Create a skill for analyzing CSV files
|
|
```
|
|
|
|
The skill creator activates and walks you through the full pipeline.
|
|
|
|
For Windsurf, Cline, Codex CLI, Gemini CLI, and other platforms see [Setup by Platform](#setup-by-platform-complete-guide) below.
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### Trigger Phrases
|
|
|
|
Say any of these to 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"
|
|
"Automate this workflow"
|
|
"I need to automate [repetitive task]"
|
|
"Validate this skill"
|
|
"Export this skill for Cursor and Copilot"
|
|
"Migrate this skill to v4"
|
|
```
|
|
|
|
### What Happens
|
|
|
|
The creator runs a **5-phase autonomous pipeline**:
|
|
|
|
```
|
|
Phase 1: DISCOVERY Research APIs, data sources, and domain knowledge
|
|
|
|
|
Phase 2: DESIGN Define use cases, methodologies, and outputs
|
|
|
|
|
Phase 3: ARCHITECTURE Structure skill directory (simple vs. complex suite)
|
|
|
|
|
Phase 4: DETECTION Generate description + keywords for reliable activation
|
|
|
|
|
Phase 5: IMPLEMENTATION Create all files, run validation, run security scan
|
|
```
|
|
|
|
Output: a complete skill directory you can install on any supported platform.
|
|
|
|
---
|
|
|
|
## Setup by Platform (Complete Guide)
|
|
|
|
Each platform installs with a single `git clone` directly into the right location. Replace `agent-skill-creator` with the skill name when installing generated skills.
|
|
|
|
### Claude Code
|
|
|
|
```bash
|
|
# Personal skill (available in all projects)
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.claude/skills/agent-skill-creator
|
|
|
|
# Per-project (scoped to one repo)
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .claude/skills/agent-skill-creator
|
|
```
|
|
|
|
### GitHub Copilot (CLI + VS Code)
|
|
|
|
```bash
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .github/skills/agent-skill-creator
|
|
```
|
|
|
|
### Cursor
|
|
|
|
```bash
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .cursor/rules/agent-skill-creator
|
|
```
|
|
|
|
Cursor reads SKILL.md natively alongside its `.mdc` rules.
|
|
|
|
### Windsurf
|
|
|
|
```bash
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .windsurf/skills/agent-skill-creator
|
|
```
|
|
|
|
### Cline
|
|
|
|
```bash
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .clinerules/agent-skill-creator
|
|
```
|
|
|
|
### OpenAI Codex CLI
|
|
|
|
```bash
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .codex/skills/agent-skill-creator
|
|
```
|
|
|
|
### Gemini CLI
|
|
|
|
```bash
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .gemini/skills/agent-skill-creator
|
|
```
|
|
|
|
### Claude Desktop / claude.ai (Export)
|
|
|
|
These platforms use `.zip` upload instead of directory copying:
|
|
|
|
1. Export: `python3 scripts/export_utils.py ./agent-skill-creator/ --variant desktop`
|
|
2. Open Claude Desktop or claude.ai
|
|
3. Go to Settings > Skills > Upload skill
|
|
4. Select the generated `.zip` file
|
|
|
|
### Claude API (Programmatic)
|
|
|
|
```bash
|
|
python3 scripts/export_utils.py ./agent-skill-creator/ --variant api
|
|
```
|
|
|
|
```python
|
|
import anthropic
|
|
|
|
client = anthropic.Anthropic()
|
|
|
|
with open("agent-skill-creator-api-v4.0.0.zip", "rb") as f:
|
|
skill = client.skills.create(file=f, name="agent-skill-creator")
|
|
|
|
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"],
|
|
)
|
|
```
|
|
|
|
Note: API sandbox has no network access, no pip install at runtime, and an 8 MB size limit.
|
|
|
|
### Updating
|
|
|
|
To update an installed skill, just `git pull` from inside the skill directory:
|
|
|
|
```bash
|
|
cd ~/.claude/skills/agent-skill-creator && git pull
|
|
```
|
|
|
|
---
|
|
|
|
## How It Works
|
|
|
|
| Phase | What Happens | Key Output |
|
|
|-------|-------------|------------|
|
|
| **Discovery** | Researches the domain, identifies APIs and data sources | Domain model, API list |
|
|
| **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 | SKILL.md frontmatter, trigger phrases |
|
|
| **Implementation** | Generates all code, docs, installer; validates and scans | Complete skill directory |
|
|
|
|
For full pipeline documentation, see [references/pipeline-phases.md](references/pipeline-phases.md).
|
|
|
|
---
|
|
|
|
## Generated Skill Format
|
|
|
|
Every generated skill follows the Agent Skills Open Standard:
|
|
|
|
```
|
|
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 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.
|
|
|
|
**Naming rules**: `kebab-case`, 1-64 characters, pattern `^[a-z][a-z0-9-]*[a-z0-9]$`, must match directory name.
|
|
|
|
---
|
|
|
|
## Tools
|
|
|
|
### Validate a Skill
|
|
|
|
Check spec compliance against the Agent Skills Open Standard:
|
|
|
|
```bash
|
|
python3 scripts/validate.py ./my-skill/
|
|
|
|
# JSON output (for CI/CD)
|
|
python3 scripts/validate.py ./my-skill/ --json
|
|
```
|
|
|
|
**Checks**: SKILL.md existence, valid frontmatter, kebab-case name (1-64 chars), description under 1024 chars, body under 500 lines, required directory structure, install.sh exists and is executable.
|
|
|
|
**Exit codes**: `0` = valid (may have warnings), `1` = invalid (errors found).
|
|
|
|
### Security Scan
|
|
|
|
Scan for common security issues before sharing or deploying:
|
|
|
|
```bash
|
|
python3 scripts/security_scan.py ./my-skill/
|
|
|
|
# JSON output
|
|
python3 scripts/security_scan.py ./my-skill/ --json
|
|
```
|
|
|
|
**Detects**: hardcoded API keys (OpenAI, AWS, GitHub, GitLab), tokens and secrets, command injection patterns, unsafe file operations, credential exposure in config files.
|
|
|
|
**Exit codes**: `0` = clean, `1` = issues found.
|
|
|
|
### Export for Other Platforms
|
|
|
|
Package skills for distribution:
|
|
|
|
```bash
|
|
# Desktop/Web (.zip for Claude Desktop, claude.ai)
|
|
python3 scripts/export_utils.py ./my-skill/ --variant desktop
|
|
|
|
# API (.zip for Claude API, <=8MB)
|
|
python3 scripts/export_utils.py ./my-skill/ --variant api
|
|
|
|
# All variants
|
|
python3 scripts/export_utils.py ./my-skill/
|
|
```
|
|
|
|
Output goes to `exports/`. See [references/export-guide.md](references/export-guide.md) for full documentation.
|
|
|
|
### Skill Registry
|
|
|
|
Share and discover skills across your team. The registry lives inside this repo (`registry/`) so one `git pull` gives everyone access to all published skills.
|
|
|
|
**First-time setup** (once per organization):
|
|
|
|
```bash
|
|
python3 scripts/skill_registry.py init --name "Acme Corp Skills"
|
|
```
|
|
|
|
**Typical workflow:**
|
|
|
|
```bash
|
|
# Someone describes a workflow, the agent creates a skill
|
|
# "Every week I pull sales data, clean it, and make a report"
|
|
# → agent creates ./sales-report-builder/
|
|
|
|
# Publish it so the team can use it
|
|
python3 scripts/skill_registry.py publish ./sales-report-builder/ --tags sales,reports
|
|
|
|
# Browse what the team has built
|
|
python3 scripts/skill_registry.py list
|
|
python3 scripts/skill_registry.py search "sales"
|
|
|
|
# Get details about a skill
|
|
python3 scripts/skill_registry.py info sales-report-builder
|
|
|
|
# Install a skill to your platform (auto-detects Claude Code, Cursor, etc.)
|
|
python3 scripts/skill_registry.py install sales-report-builder
|
|
|
|
# Install for a specific platform or at project level
|
|
python3 scripts/skill_registry.py install sales-report-builder --platform cursor --project
|
|
|
|
# Remove a skill from the registry
|
|
python3 scripts/skill_registry.py remove sales-report-builder --force
|
|
```
|
|
|
|
After publishing, commit and push so colleagues can `git pull` and install the new skill.
|
|
|
|
All commands support `--json` for machine-readable output. Use `--force` to overwrite duplicates or bypass confirmation prompts.
|
|
|
|
**Exit codes**: `0` = success, `1` = error.
|
|
|
|
---
|
|
|
|
## Architecture Decisions
|
|
|
|
The creator automatically decides simple vs. complex based on scope:
|
|
|
|
| Factor | Simple Skill | Complex Suite |
|
|
|--------|-------------|---------------|
|
|
| Workflows | 1-2 | 3+ distinct |
|
|
| Code size | <1000 lines | >2000 lines |
|
|
| Structure | Single SKILL.md | Multiple component SKILL.md files |
|
|
|
|
For detailed decision logic, see [references/architecture-guide.md](references/architecture-guide.md).
|
|
|
|
---
|
|
|
|
## For AI Agents (Machine-Readable Reference)
|
|
|
|
This section provides structured metadata for AI agents ingesting this README as context.
|
|
|
|
### Activation Triggers
|
|
|
|
```
|
|
create an agent for [objective]
|
|
create a skill for [domain]
|
|
develop a custom skill
|
|
automate this workflow
|
|
every day I [task]
|
|
I repeatedly need to [process]
|
|
I need to automate [task]
|
|
create a cross-platform skill for [objective]
|
|
validate this skill
|
|
check if this skill is spec-compliant
|
|
export this skill for [platform]
|
|
package this skill for [platform]
|
|
migrate this skill to v4
|
|
update this skill to the new standard
|
|
create a multi-agent suite for [objective]
|
|
create a skill from the [name] template
|
|
```
|
|
|
|
### Install Commands
|
|
|
|
```bash
|
|
# Claude Code (personal)
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git ~/.claude/skills/agent-skill-creator
|
|
# GitHub Copilot
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .github/skills/agent-skill-creator
|
|
# Cursor
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .cursor/rules/agent-skill-creator
|
|
# Windsurf
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .windsurf/skills/agent-skill-creator
|
|
# Cline
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .clinerules/agent-skill-creator
|
|
# Codex CLI
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .codex/skills/agent-skill-creator
|
|
# Gemini CLI
|
|
git clone https://github.com/FrancyJGLisboa/agent-skill-creator.git .gemini/skills/agent-skill-creator
|
|
# Update
|
|
cd <install-path>/agent-skill-creator && git pull
|
|
```
|
|
|
|
### Tool Commands
|
|
|
|
```bash
|
|
# Validate
|
|
python3 scripts/validate.py PATH # Human output
|
|
python3 scripts/validate.py PATH --json # Machine output
|
|
|
|
# Security scan
|
|
python3 scripts/security_scan.py PATH
|
|
python3 scripts/security_scan.py PATH --json
|
|
|
|
# Export
|
|
python3 scripts/export_utils.py PATH --variant desktop
|
|
python3 scripts/export_utils.py PATH --variant api
|
|
|
|
# Registry (default --registry ./registry)
|
|
python3 scripts/skill_registry.py init --name "Team Name"
|
|
python3 scripts/skill_registry.py publish SKILL_PATH --tags T1,T2
|
|
python3 scripts/skill_registry.py list [--json]
|
|
python3 scripts/skill_registry.py search QUERY [--json]
|
|
python3 scripts/skill_registry.py install SKILL_NAME [--platform PLATFORM] [--project]
|
|
python3 scripts/skill_registry.py info SKILL_NAME [--json]
|
|
python3 scripts/skill_registry.py remove SKILL_NAME --force
|
|
```
|
|
|
|
### Platform Paths
|
|
|
|
| Platform | Path | Scope |
|
|
|----------|------|-------|
|
|
| Claude Code | `~/.claude/skills/` | User-level |
|
|
| Claude Code | `.claude/skills/` | Project-level |
|
|
| GitHub Copilot | `.github/skills/` | Project-level |
|
|
| Cursor | `.cursor/rules/` | Workspace |
|
|
| Windsurf | `.windsurf/skills/` | Workspace |
|
|
| Cline | `.clinerules/` | Workspace |
|
|
| Codex CLI | `.codex/skills/` | Workspace |
|
|
| Gemini CLI | `.gemini/skills/` | Workspace |
|
|
| Claude Desktop | `.zip` upload | App-level |
|
|
| claude.ai | `.zip` upload | Web |
|
|
| Claude API | `.zip` via API | Programmatic |
|
|
|
|
### SKILL.md Spec (Required Fields)
|
|
|
|
```yaml
|
|
---
|
|
name: kebab-case-name # 1-64 chars, ^[a-z][a-z0-9-]*[a-z0-9]$
|
|
description: >- # 1-1024 chars, include activation keywords
|
|
What this skill does...
|
|
license: MIT
|
|
metadata:
|
|
author: Author Name
|
|
version: X.Y.Z
|
|
---
|
|
# Body: <500 lines. Move detailed content to references/.
|
|
```
|
|
|
|
### Pipeline Phases
|
|
|
|
```
|
|
DISCOVERY -> DESIGN -> ARCHITECTURE -> DETECTION -> IMPLEMENTATION
|
|
```
|
|
|
|
Each phase is documented in `references/phase{1..5}-*.md`.
|
|
|
|
---
|
|
|
|
## Migration from v3.x
|
|
|
|
Key changes in v4.0:
|
|
|
|
- `-cskill` suffix removed from skill names (use standard kebab-case)
|
|
- SKILL.md body limited to 500 lines (move detail to `references/`)
|
|
- `install.sh` cross-platform installer added
|
|
- Spec validation and security scanning tools added
|
|
- `marketplace.json` simplified (optional for simple skills)
|
|
|
|
Quick migration:
|
|
|
|
```bash
|
|
mv my-skill-cskill/ my-skill/
|
|
# Update SKILL.md name field to remove -cskill suffix
|
|
python3 scripts/validate.py ./my-skill/
|
|
```
|
|
|
|
For the complete migration guide, see [MIGRATION.md](MIGRATION.md).
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
**Skill not activating**: Ensure SKILL.md `description` field contains the trigger phrases you expect. The description is the primary activation mechanism.
|
|
|
|
**Validation fails on name**: Names must be kebab-case, 1-64 characters, no consecutive hyphens, no leading/trailing hyphens. Pattern: `^[a-z][a-z0-9-]*[a-z0-9]$`.
|
|
|
|
**SKILL.md too long**: Body must be under 500 lines. Move detailed documentation to `references/` and link from the main SKILL.md.
|
|
|
|
**Export fails with size error**: API exports have an 8 MB limit. Reduce asset sizes or exclude large files.
|
|
|
|
**install.sh not executable**: Run `chmod +x install.sh` before executing.
|
|
|
|
**Platform not auto-detected**: Use `./install.sh --platform <name>` to specify explicitly.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
agent-skill-creator/
|
|
SKILL.md # Meta-skill definition
|
|
README.md # This file
|
|
MIGRATION.md # v3.x to v4.0 migration guide
|
|
scripts/
|
|
validate.py # Spec compliance validator
|
|
security_scan.py # Security scanner
|
|
export_utils.py # Cross-platform export tool
|
|
skill_registry.py # Git-based shared skill registry
|
|
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
|
|
registry/ # Shared skill catalog (git-tracked)
|
|
registry.json # Skill manifest
|
|
skills/ # Published skill directories
|
|
integrations/
|
|
agentdb_bridge.py # AgentDB integration bridge
|
|
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/
|
|
CHANGELOG.md # Version history
|
|
NAMING_CONVENTIONS.md # Naming rules reference
|
|
PIPELINE_ARCHITECTURE.md # Pipeline internals
|
|
DECISION_LOGIC.md # Architecture decision logic
|
|
```
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
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
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT License.
|
|
|
|
---
|
|
|
|
## 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)
|