A Skills Foundry for individuals and teams: An intelligent agent that automatically transforms natural language requirements into distributable Skill packages, with a complete Generate → Validate → Test → Package → Publish workflow, ultimately building your Personal Skills Repository.

🎯 Goal: Turn "writing requirements" into "deliverable Skills", turn "scripts" into "publishable assets".

• From 0 to 1: Write a single requirement, automatically generate structured Skill packages (code, docs, dependencies, config, assets)
• From 1 to N: Manage Skills like a codebase (versioning, testing, CI/CD, publishing)
• Controllable & Reviewable: Generated results include requirement analysis artifacts, traceable logs, and auto-validation for easy review and iteration
• Multi-Model Strategy: Support cloud/local LLMs with "latest-preferred strategy" by default, avoiding lock-in to outdated models

• 🤖 Requirement Understanding & Structured Analysis - Parse natural language requirements into executable Skill specs (.requirement.json) using LLM-powered analysis
• 🧩 Auto-Generate Runnable Code - Produce compliant Python scripts with complete implementations (no TODO placeholders), including argparse, logging, and error handling
• 🔍 TODO Detection & Auto-Completion - Automatically detect and complete TODO placeholders in generated code using LLM
• 📄 Auto-Generate Standard Documentation - Generate structured SKILL.md with YAML frontmatter, usage guides, examples, and API documentation
• 📦 Dependencies & Reproducibility - Generate requirements.txt, support uv/pip installation
• ✅ Post-Generation Validation - Static checks + compliance verification using quick_validate.py to ensure Skills are distributable
• 📦 One-Click Packaging - Output standard .skill distribution packages (ZIP format) using package_skill.py
• 🔄 Fallback Strategy - Use rule/template mode when LLM unavailable to ensure availability
• 🧾 Full-Chain Logging - Record generation process, prompts, model info (for traceability and auditing)
• 📊 Generation Record Tracking - Automatically record detailed generation info to CSV (requirements, model, duration, file structure, etc.)
• 🧪 Test & Publish Friendly - Auto-generate test scripts, CI-ready (GitHub Actions), extensible for auto-publishing to Releases/Registry

• Personal: Build your own Skills Repository (data processing, automation, scaffolding, data cleaning, report generation, etc.)
• Team: Accumulate organization-level skill assets (tooling, standardization, reusability)
• Teaching/Research: Rapidly produce runnable engineering samples for validating and iterating ideas

• Python 3.10+ (3.12 recommended)
• uv (recommended) or pip

# Clone the repository
git clone https://github.com/your-org/skill-generator-agent.git
cd skill-generator-agent

# Run setup script (recommended - automatically installs uv if needed)
bash scripts/setup.sh

# Activate virtual environment
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

Copy the environment template and fill in your API keys:

cp .env.example .env

Edit .env file with your configuration:

# ========== OpenAI ==========
OPENAI_API_KEY=sk-...
OPENAI_API_BASE=https://api.openai.com/v1  # Optional: custom endpoint
OPENAI_MODEL=gpt-5-mini                     # Recommended: Latest cost-effective model

# ========== Anthropic ==========
ANTHROPIC_API_KEY=sk-...
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022  # Recommended: Latest high-quality model

# ========== Ollama (Local, Free) ==========
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama3.2                      # Recommended: llama3.2, qwen2.5

# ========== Proxy Configuration (Optional) ==========
HTTP_PROXY=http://proxy.example.com:8118
HTTPS_PROXY=http://proxy.example.com:8118

# ========== Generation Parameters (Optional) ==========
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=4000

💡 Model Selection Strategy:

• The tool automatically detects available API keys and selects the best provider
• Priority order: OpenAI → Anthropic → Ollama
• You can override with --llm and --model command-line arguments
• Supports proxy configuration for network-restricted environments

python skill_generator_agent.py -r "Create a data processing tool"

python skill_generator_agent.py \
  -n "csv-processor" \
  -r "Create a CSV processing tool with read, filter, JSON conversion, and statistics" \
  -o ./skills \
  --yes

# Run pre-configured demo examples
bash scripts/demo.sh

# Test the complete generation → validation → packaging workflow
python tests/test_skill_workflow.py \
  -r "Create a file counter tool" \
  -n "test-counter" \
  --keep-output

python skill_generator_agent.py --interactive

# Use OpenAI with specific model
python skill_generator_agent.py --llm openai --model gpt-5-mini -r "Create a file converter"

# Use Anthropic Claude
python skill_generator_agent.py --llm anthropic --model claude-3-5-sonnet-20241022 -r "..."

# Use local Ollama
python skill_generator_agent.py --llm ollama --model llama3.2 -r "..."

my-skill/
├── SKILL.md              # Standardized documentation with YAML frontmatter
├── README.md              # User-friendly README (auto-generated)
├── requirements.txt      # Python dependencies
├── .requirement.json     # Requirement analysis artifact (traceable)
├── .gitignore            # Git ignore file (auto-generated)
├── scripts/
│   ├── main.py           # Main script (runnable, complete implementation)
│   ├── utils.py          # Utility functions (if needed)
│   ├── test_main.py      # Unit tests (auto-generated)
│   └── ...
├── references/           # Reference materials (optional, auto-generated)
│   └── api_reference.md  # API documentation (if needed)
└── assets/               # Asset files (optional)
    └── templates/        # Template files (if needed)

Requirement Input
  │
  ▼
[1] Requirement Analysis (LLM)
  │   └─ Output: Structured requirement spec
  ▼
[2] User Confirmation (optional)
  ▼
[3] Initialize Skill Directory
  │   └─ Uses init_skill.py or manual creation
  ▼
[4] Code Generation (LLM)
  │   ├─ Generate scripts with argparse, logging, error handling
  │   ├─ Complete implementations (no TODO placeholders)
  │   ├─ Auto-detect and complete any remaining TODOs
  │   └─ Output: scripts/*.py
  ▼
[5] Generate Tests
  │   └─ Output: scripts/test_*.py (auto-generated unit tests)
  ▼
[6] Documentation Generation
  │   ├─ SKILL.md (with YAML frontmatter)
  │   ├─ README.md (user-friendly guide)
  │   ├─ requirements.txt
  │   └─ .gitignore
  ▼
[7] Generate References & Assets
  │   ├─ API reference documentation (if needed)
  │   └─ Template files (if needed)
  ▼
[8] Validation (quick_validate.py)
  │   ├─ Check SKILL.md format
  │   ├─ Validate naming conventions
  │   └─ Verify required fields
  ▼
[9] Packaging (package_skill.py)
  │   └─ Output: .skill file (ZIP format)
  ▼
[10] Save Generation Record
  │   └─ CSV with timestamp, model, duration, structure
  ▼
Done ✅ (Ready for CI/CD publishing)

The complete test workflow includes:

1. Generate Skill - Create skill from requirement
2. Validate Structure - Check required files exist
3. Test Script Execution - Verify scripts can run
4. Validate Skill - Use quick_validate.py for format validation
5. Package Skill - Create .skill distribution file

Run tests with:

python tests/test_skill_workflow.py \
  -r "Your requirement" \
  -n "skill-name" \
  --keep-output

python skill_generator_agent.py \
    -n "file-counter" \
    -r "Create a file counter tool that counts files and total size in a directory" \
    -o ./examples \
    --yes

python skill_generator_agent.py \
    -n "csv-processor" \
    -r "Create a CSV processing tool that supports:
    1. Read CSV files
    2. Filter and select data
    3. Format conversion (CSV to JSON)
    4. Data statistics analysis" \
    -o ./examples \
    --yes

# Test the complete generation → validation → packaging workflow
python tests/test_skill_workflow.py \
    -r "Create a file counter tool" \
    -n "test-counter" \
    --keep-output

# Make sure Ollama is running: ollama serve
python skill_generator_agent.py \
    --llm ollama --model llama3.2 \
    -r "Create a file format conversion tool" \
    -o ./examples \
    --yes

python skill_generator_agent.py \
    --llm anthropic --model claude-3-5-sonnet-20241022 \
    -r "Create a web scraper with error handling and retry logic" \
    -o ./examples \
    --yes

python skill_generator_agent.py \
    -n "project-env-installer" \
    -r "Create a project environment installer that:
    1. Clones from GitHub or reads local project
    2. Analyzes README and dependency files
    3. Auto-installs uv if needed, creates Python 3.12 venv
    4. Installs dependencies and tests startup
    5. Auto-fixes common issues" \
    -o ./examples \
    --yes

See EXAMPLES.md for more examples.

If you're creating a new GitHub project to build your personal Skills repository, we recommend an engineering-oriented layout:

your-skills-repo/
├── skill_generator_agent.py      # Generator script
├── skills/                        # Generated skills (version control as needed)
│   ├── csv-processor/
│   ├── api-client/
│   └── ...
├── templates/                     # Specification templates (optional)
├── tests/                         # Regression tests / golden examples
├── .github/
│   └── workflows/
│       ├── validate.yml          # Validate skills on PR
│       ├── package.yml           # Package and release
│       └── test.yml              # Run tests
├── scripts/
│   ├── setup.sh                  # Environment setup
│   └── run.sh                    # Quick run script
├── .env.example                  # Environment template
├── pyproject.toml                # Python project config
├── README.md
└── CHANGELOG.md

1. PR Validation: Auto-run validate/test on PRs to prevent "bad skills" from entering main branch
2. Auto-Release: Auto-package .skill files and upload to GitHub Releases after merging to main
3. Registry (Optional): Maintain version numbers, signatures, and manifests for each Skill to form a "private registry"

• Write requirements as "acceptance criteria": The more testable your input, the more stable your output
• Generate first, review later: Treat generated results as PRs and do Code Review before merging
• Accumulate golden examples: Turn frequently-used skills into regression test cases for long-term quality improvement
• Layered model strategy: Use cost-effective models for exploration, stronger models for final review before publishing

• Write requirements as "acceptance criteria": The more testable your input, the more stable your output
• Generate first, review later: Treat generated results as PRs and do Code Review before merging
• Accumulate golden examples: Turn frequently-used skills into regression test cases for long-term quality improvement
• Layered model strategy: Use cost-effective models for exploration, stronger models for final review before publishing
• Version control: Keep generated skills in Git to track changes and iterations
• CI/CD integration: Automate validation, testing, and packaging in your workflow

# Test generation → validation → packaging workflow
python tests/test_skill_workflow.py \
    -r "Create a file counter tool" \
    -n "test-counter" \
    --keep-output

# Basic generation test
python tests/test_generator.py

# Full workflow test (detailed)
python tests/test_full_workflow.py

# After generating a skill
cd examples/your-skill/scripts
python main.py --help
pytest test_*.py -v

See TEST_RUN_GUIDE.md and HOW_TO_RUN_TESTS.md for detailed testing documentation.

# Install dev dependencies
bash scripts/setup.sh

# Run tests
pytest

# Run tests with coverage
pytest --cov=skill_generator_agent --cov-report=html

# Run workflow test
python tests/test_skill_workflow.py -r "Test requirement" -n "test" --keep-output

# Format code
black .
ruff check .

# Type checking (if mypy is installed)
mypy skill_generator_agent.py

• scripts/setup.sh - Environment setup (auto-installs uv if needed)
• scripts/demo.sh - Run demo examples
• scripts/run.sh - Quick run script
• tests/test_skill_workflow.py - Complete workflow test
• tests/test_generator.py - Basic generation test

Q: Can generated code be used directly in production?
A: We recommend treating generated results as "high-quality drafts" and using them only after review, testing, and security auditing.

Q: Can I use this without an LLM?
A: Yes. It will fall back to template/rule-based generation mode, ensuring structure and compliance but with lower intelligence.

Q: Which model should I use?
A: For best results: gpt-5-mini (cost-effective) or claude-3-5-sonnet-20241022 (high quality). For local/free: llama3.2 via Ollama.

Q: How do I add a custom LLM provider?
A: The code uses OpenAI-compatible API format. You can set OPENAI_API_BASE to point to your custom endpoint.

Q: Can I customize the generation templates?
A: Yes. Check the code for prompt templates and modify them according to your needs.

Q: How does validation work?
A: Uses quick_validate.py from skill-creator to validate SKILL.md format, naming conventions, and required fields.

Q: How does packaging work?
A: Uses package_skill.py to create .skill files (ZIP format) with all required files, excluding temporary files like __pycache__.

Q: Where are generation records saved?
A: In generation_records.csv in the output directory, containing timestamp, requirement, model, duration, file structure, etc.

MIT

• USAGE_GUIDE.md - Complete usage guide
• EXAMPLES.md - Example collection
• README_EXAMPLES.md - More examples
• SCRIPTS_AND_USAGE.md - Scripts overview
• TEST_RUN_GUIDE.md - Testing guide
• HOW_TO_RUN_TESTS.md - Quick test guide
• TEST_FLOW_DIAGRAM.md - Test flow diagram
• WORKFLOW_TEST_REPORT.md - Test report
• GENERATION_RECORDS.md - Generation records documentation
• examples/README.md - Generated examples showcase
• references/skill_patterns.md - Skill design patterns
• references/output_templates.md - Output templates reference

• OpenAI API
• Anthropic API
• Ollama
• uv - Python Package Manager

This project is inspired by the following excellent projects, and we extend our gratitude:

• OpenAI Skills - Official Skills Catalog for Codex by OpenAI
• LangGraph - Framework for building multi-agent applications
• openskills - Universal skills loader for AI coding agents

Thank you to these projects for their contributions to the AI Agent and Skills ecosystem!