moai-adk 0.4.7__py3-none-any.whl → 0.4.8__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-cc-skills/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: "Creating and Optimizing Claude Code Skills"
+description: "Design reusable knowledge capsules with progressive disclosure (metadata → content → resources). Apply freedom levels (high/medium/low), create examples, validate YAML. Use when building domain-specific guidance or automating recurring patterns."
+allowed-tools: "Read, Write, Edit, Glob, Bash"
+---
+
+# Creating and Optimizing Claude Code Skills
+
+Skills are modular, reusable knowledge capsules that load via Progressive Disclosure. They combine templates, patterns, and best practices without blocking user workflow.
+
+## Skill File Structure
+
+**Location**: `.claude/skills/skill-name/`
+
+```
+skill-name/
+├── SKILL.md              # Main instructions (~400 lines)
+├── reference.md          # Detailed reference (optional)
+├── examples.md           # Real-world examples (optional)
+├── CHECKLIST.md          # Validation guide (optional)
+├── scripts/              # Utility scripts
+│   ├── validator.sh
+│   └── formatter.py
+└── templates/            # Reusable templates
+    ├── config.json
+    └── main.md
+```
+
+## YAML Frontmatter
+
+```yaml
+---
+name: "Skill Name (Gerund + Domain)"
+description: "[Capability]. Use when [trigger 1], [trigger 2], [trigger 3]."
+allowed-tools: "Read, Write, Bash(python:*)"
+---
+```
+
+### Field Rules
+
+| Field | Max | Format | Example |
+|-------|-----|--------|---------|
+| `name` | 64 chars | Gerund + Domain | "Processing CSV Files with Python" |
+| `description` | 1024 chars | 3rd person, 3+ triggers | "Extract data, validate schema, merge datasets. Use when processing CSV, Excel files, or data cleaning." |
+| `allowed-tools` | — | Comma-separated minimal list | "Read, Bash(python:*), Bash(grep:*)" |
+
+## Freedom Level Framework
+
+| Freedom | % | Use Case | Content Style |
+|---------|---|----------|----------------|
+| **High** | 20-30% | Flexible, creative | Principles, trade-offs, decision trees |
+| **Medium** | 50-60% | Standard patterns | Pseudocode, flowcharts, templates |
+| **Low** | 10-20% | Deterministic, error-prone | Scripts, error handling, validation |
+
+### High-Freedom: Architecture Design
+
+```markdown
+## Architecture Trade-offs
+
+| Pattern | Pros | Cons | When |
+|---------|------|------|------|
+| Monolith | Simple, unified | Scales poorly | MVP, <10 people |
+| Microservices | Scalable, independent | Complex, distributed tracing | 10+ teams |
+| Serverless | Zero ops, elastic | Cold starts, vendor lock-in | Event-driven |
+
+Choose based on:
+1. **Team size**: Monolith if <5 devs
+2. **Scale**: Microservices if >10M requests/month
+3. **Budget**: Serverless if unpredictable workload
+```
+
+### Medium-Freedom: Data Validation Pattern
+
+```pseudocode
+## Validation Workflow
+
+1. Load data source (CSV, JSON, API)
+2. For each record:
+   a. Check required fields exist
+   b. Validate data types
+   c. Verify constraints (range, format)
+   d. Check references (foreign keys)
+3. Collect errors with row numbers
+4. Report summary + fix suggestions
+5. Proceed only if all errors fixed
+
+## Example: CSV Validation
+   - Input: data.csv
+   - Schema: validators/schema.json
+   - Output: validation_report.json
+```
+
+### Low-Freedom: Security Validator Script
+
+```python
+#!/usr/bin/env python3
+"""Validate code for OWASP Top 10 risks"""
+import re
+import sys
+
+PATTERNS = [
+    (r"eval\(", "OWASP-A1: Code injection risk"),
+    (r"SELECT.*\$", "OWASP-A3: SQL injection risk"),
+    (r"os\.system\(", "OWASP-A6: Command injection risk"),
+]
+
+def validate_file(filepath):
+    with open(filepath) as f:
+        content = f.read()
+
+    issues = []
+    for pattern, risk in PATTERNS:
+        if re.search(pattern, content):
+            issues.append(risk)
+
+    return issues
+
+if __name__ == "__main__":
+    for filepath in sys.argv[1:]:
+        issues = validate_file(filepath)
+        if issues:
+            print(f"⚠️  {filepath}:")
+            for issue in issues:
+                print(f"  • {issue}")
+```
+
+## Progressive Disclosure Pattern
+
+**Level 1**: Metadata (always loaded)
+```yaml
+name: "Database Query Optimization"
+description: "Profile slow queries, analyze execution plans, suggest indexes..."
+allowed-tools: "Read, Bash(sqlite3:*)"
+```
+
+**Level 2**: Main content (on demand)
+- Overview + quick start
+- 3-4 core patterns
+- Decision tree
+
+**Level 3**: Resources (when referenced)
+- `reference.md` — Detailed specs
+- `examples.md` — Real-world scenarios
+- `scripts/` — Utility tools
+
+## Skill Discovery Keywords
+
+Embed in description for auto-activation:
+
+✅ **DO** include:
+- Problem domain: "CSV", "SQL", "React", "API"
+- Operation: "parsing", "validation", "optimization", "debugging"
+- Tech stack: "Python", "TypeScript", "Go"
+
+Example description:
+```
+"Parse CSV files, validate data schemas, clean datasets.
+Use when processing CSV, Excel, JSON data or when user mentions
+data cleaning, validation, or transformation."
+```
+
+## Medium-Freedom: Example Skill Template
+
+```yaml
+---
+name: "Testing React Components with Vitest"
+description: "Write unit tests for React components, mock hooks, test async behavior. Use when testing React components, setting up Vitest, or debugging test failures."
+allowed-tools: "Read, Write, Bash(npm:*), Bash(npm run:*)"
+---
+
+# Testing React Components with Vitest
+
+## Quick Start
+
+1. Install: `npm install -D vitest @testing-library/react`
+2. Create test: `src/Component.test.tsx`
+3. Run: `npm run test`
+
+## Core Patterns
+
+### Pattern 1: Basic Component Test
+```typescript
+import { render, screen } from '@testing-library/react'
+import { Button } from './Button'
+
+it('renders button with text', () => {
+  render(<Button>Click me</Button>)
+  expect(screen.getByText('Click me')).toBeInTheDocument()
+})
+```
+
+### Pattern 2: Mock Hooks
+```typescript
+import { useUserStore } from './store'
+
+vi.mock('./store', () => ({
+  useUserStore: vi.fn(() => ({ user: null }))
+}))
+```
+
+## Examples
+
+See [examples.md](examples.md) for integration with Redux, React Query, form testing.
+```
+
+## Skill Validation Checklist
+
+- [ ] `name` is specific (not "React Helper")
+- [ ] `description` includes 3+ discovery keywords
+- [ ] Main content ≤ 500 lines
+- [ ] At least 2 concrete examples
+- [ ] Progressive Disclosure applied (metadata → content → resources)
+- [ ] Freedom levels mixed appropriately
+- [ ] No hardcoded paths or time-sensitive data
+- [ ] YAML frontmatter is valid
+- [ ] Paths use forward slashes (`/` not `\`)
+
+## Skill Optimization Patterns
+
+### Anti-pattern 1: Too Generic
+```yaml
+❌ name: "Python Helper"
+✅ name: "Testing Python Code with pytest"
+```
+
+### Anti-pattern 2: No Examples
+```yaml
+❌ Only principles, no code samples
+✅ Each concept has working example
+```
+
+### Anti-pattern 3: Nested Files
+```yaml
+❌ docs/api/v2/reference/security.md
+✅ reference.md (one level)
+```
+
+### Anti-pattern 4: Absolute Paths
+```yaml
+❌ /Users/name/project/config.json
+✅ ./config.json or ${PROJECT_DIR}/config.json
+```
+
+## Best Practices
+
+✅ **DO**:
+- Keep < 500 lines per SKILL.md
+- Use relative paths with forward slashes
+- Provide working code examples
+- Design for reusability across projects
+- Include both success and error paths
+
+❌ **DON'T**:
+- Mix too many domains (split into separate Skills)
+- Explain fundamentals (trust Claude already knows)
+- Create nested directory structures
+- Include time-sensitive info (dates, versions)
+- Use Windows-style paths
+
+## Skill Lifecycle
+
+1. **Create**: Design persona, scope, freedom levels
+2. **Implement**: Write SKILL.md + examples
+3. **Test**: Verify with Haiku, Sonnet, Opus
+4. **Deploy**: Add to `.claude/skills/`
+5. **Iterate**: Get feedback, update as needed
+
+---
+
+**Reference**: Claude Code Skills official documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-skills/templates/SKILL-template.md

@@ -0,0 +1,15 @@
+---
+name: "Skill Name (Gerund + Domain)"
+description: "[Capability]. Use when [trigger 1], [trigger 2], [trigger 3]."
+allowed-tools: "Read, Write, Bash(python:*)"
+---
+
+# Skill Name
+
+## Quick Start
+
+## Core Patterns
+
+## Examples
+
+See examples.md for real-world scenarios.

moai_adk/templates/.claude/skills/moai-skill-factory/EXAMPLES.md

@@ -1,52 +1,278 @@
-# moai-skill-factory - Working Examples
+# Skill Factory Examples
+
+> Real-world skill creation scenarios
 
 _Last updated: 2025-10-22_
 
-## Example 1: Creating a New Language Skill
+---
+
+## Example 1: Creating a Python Testing Skill (Complete Workflow)
 
-```bash
-# Phase 1: Interactive Discovery
-User: "Create a new Skill for TypeScript development"
-→ skill-factory activates moai-alfred-tui-survey
-→ User answers questions about scope, tools, patterns
-→ Skill metadata drafted
+### Phase 1: Discovery (15 min)
+
+**Problem Statement**:
+"Developers need guidance on Python testing best practices with pytest, coverage, and fixtures."
+
+**Trigger Keywords**:
+`python`, `pytest`, `testing`, `fixtures`, `coverage`, `unittest`, `tdd`
+
+**Reference URLs**:
+- https://docs.pytest.org/en/stable/
+- https://coverage.readthedocs.io/
+- https://realpython.com/pytest-python-testing/
 
-# Phase 2: Web Research
-→ skill-factory uses WebSearch for latest TypeScript versions
-→ Fetches official docs: https://typescriptlang.org/docs
-→ Validates tool versions (TypeScript 5.7, Vitest 2.1, etc.)
+**Target Tier**: Language (moai-lang-python-testing)
 
-# Phase 3: Skill Generation
-→ Creates SKILL.md with v2.0.0 structure
-→ Generates examples.md with working code samples
-→ Creates reference.md with CLI commands
-→ Dual deployment to .claude/skills and templates/
+---
+
+### Phase 2: Design (20 min)
+
+**Metadata**:
+```yaml
+---
+name: Testing Python Applications with pytest
+description: Write and run Python tests using pytest, manage fixtures, measure coverage, and integrate with CI/CD. Use when testing Python code, setting up test environments, or when the user mentions pytest, coverage, fixtures, or TDD.
+allowed-tools: Read, Bash
+---
 ```
 
-## Example 2: Updating Existing Skills
+**Content Outline**:
+```
+1. Introduction (High Freedom - 10%)
+   - Why pytest over unittest
+   - Testing philosophy
 
-```bash
-# Batch update workflow
-User: "Update all Python Skills to latest versions"
-→ skill-factory analyzes current SKILL.md
-→ WebSearch for latest tool versions (pytest 8.4.2, ruff 0.13.1)
-→ Detects outdated patterns (black → ruff migration)
-→ Generates update report with changelog
-→ Applies updates across all affected Skills
+2. Core Concepts (Medium Freedom - 40%)
+   - Test discovery patterns
+   - Fixture usage
+   - Parametrization
+   - Mocking strategies
+
+3. Examples (Medium Freedom - 30%)
+   - Simple unit test
+   - Fixture example
+   - Parametrized test
+   - Integration test
+
+4. Coverage & CI (Low Freedom - 20%)
+   - Coverage command
+   - CI configuration (GitHub Actions)
 ```
 
-## Example 3: Skill Quality Validation
+---
+
+### Phase 3: Production (60 min)
+
+**SKILL.md Excerpt**:
+
+```markdown
+# Testing Python Applications with pytest
+
+## Quick Start
 
 ```bash
-# Pre-publication checklist
-→ Validates YAML frontmatter (v2.0.0 schema)
-→ Checks keywords field exists
-→ Verifies tool version matrix present
-→ Ensures examples.md and reference.md exist
-→ Confirms dual deployment sync
-→ Reports validation results
+# Install pytest
+pip install pytest pytest-cov
+
+# Run tests
+pytest
+
+# With coverage
+pytest --cov=src --cov-report=term-missing
 ```
 
+## Core Concepts
+
+### Test Discovery
+
+pytest automatically discovers tests matching these patterns:
+- Files: `test_*.py` or `*_test.py`
+- Functions: `test_*`
+- Classes: `Test*`
+
+### Fixtures
+
+Fixtures provide reusable test setup:
+
+```python
+import pytest
+
+@pytest.fixture
+def user_data():
+    return {"name": "Alice", "age": 30}
+
+def test_user_creation(user_data):
+    assert user_data["name"] == "Alice"
+```
+
+For complete reference, see [reference.md](reference.md).
+```
+
+**reference.md Excerpt**:
+
+```markdown
+# pytest Reference
+
+## Fixture Scopes
+
+- `function` (default): Run once per test function
+- `class`: Run once per test class
+- `module`: Run once per module
+- `session`: Run once per test session
+
+## Parametrization
+
+```python
+@pytest.mark.parametrize("input,expected", [
+    (2, 4),
+    (3, 9),
+    (4, 16),
+])
+def test_square(input, expected):
+    assert input ** 2 == expected
+```
+```
+
+**examples.md Excerpt**:
+
+```markdown
+# pytest Examples
+
+## Example 1: API Testing with Fixtures
+
+```python
+import pytest
+import requests
+
+@pytest.fixture
+def api_client():
+    return requests.Session()
+
+@pytest.fixture
+def base_url():
+    return "https://api.example.com"
+
+def test_get_user(api_client, base_url):
+    response = api_client.get(f"{base_url}/users/1")
+    assert response.status_code == 200
+    assert "id" in response.json()
+```
+```
+
+---
+
+### Phase 4: Validation (20 min)
+
+**Checklist Results**:
+- ✅ Name: 45 characters (gerund format)
+- ✅ Description: 256 characters (includes 7 keywords)
+- ✅ SKILL.md: 420 lines
+- ✅ Examples: 4 scenarios included
+- ✅ Tested with Haiku and Sonnet
+
+---
+
+## Example 2: Creating a Git Workflow Skill (Abbreviated)
+
+### Discovery
+
+**Problem**: "Developers need GitFlow automation with commit conventions and PR templates."
+
+**Keywords**: `git`, `gitflow`, `commit`, `pr`, `pull request`, `branch`, `merge`
+
+### Design
+
+```yaml
+name: Automating Git Workflows with GitFlow
+description: Manage Git branches using GitFlow, write conventional commits, create pull requests, and automate releases. Use when working with Git repositories, feature branches, or when the user mentions GitFlow, commits, or pull requests.
+allowed-tools: Read, Bash
+```
+
+### Content Structure
+- 35% High Freedom: Branch strategy philosophy
+- 45% Medium Freedom: Commit patterns, PR templates
+- 20% Low Freedom: Git commands, automation scripts
+
+---
+
+## Example 3: Creating a Security Scanning Skill (Abbreviated)
+
+### Discovery
+
+**Problem**: "Projects need automated security scanning for dependencies and SAST."
+
+**Keywords**: `security`, `sast`, `vulnerabilities`, `dependencies`, `owasp`, `audit`
+
+### Design
+
+```yaml
+name: Securing Applications with SAST and Dependency Scanning
+description: Run static application security testing (SAST), scan dependencies for vulnerabilities, enforce OWASP Top 10 compliance, and integrate security checks into CI/CD. Use when performing security audits, scanning for vulnerabilities, or when the user mentions SAST, OWASP, or security scanning.
+allowed-tools: Read, Bash
+```
+
+### Freedom Breakdown
+- 25% High: Security principles, threat modeling
+- 35% Medium: Scanning patterns, report interpretation
+- 40% Low: Specific scanning commands per language
+
+---
+
+## Common Skill Creation Mistakes
+
+### Mistake 1: Too Generic
+
+❌ **Bad Name**: "Python Helper"
+✅ **Good Name**: "Testing Python Applications with pytest"
+
+### Mistake 2: Missing Keywords
+
+❌ **Bad Description**: "Helps with Python testing."
+✅ **Good Description**: "Write and run Python tests using pytest, fixtures, parametrization, and coverage reporting."
+
+### Mistake 3: No Examples
+
+❌ **Bad Practice**: Only provide theory and no code examples
+✅ **Good Practice**: Include 3-4 complete, runnable examples
+
+### Mistake 4: Outdated Information
+
+❌ **Bad**: "Use Python 2.7 with unittest"
+✅ **Good**: "Use Python 3.11+ with pytest (latest stable version)"
+
+---
+
+## Skill Creation Time Estimates
+
+| Skill Complexity | Discovery | Design | Production | Validation | Total |
+|-----------------|-----------|---------|-----------|------------|-------|
+| **Simple** (single tool) | 10 min | 15 min | 30 min | 10 min | ~1 hour |
+| **Medium** (multi-tool, 3-5 examples) | 15 min | 20 min | 60 min | 20 min | ~2 hours |
+| **Complex** (multi-domain, 5+ examples) | 30 min | 30 min | 90 min | 30 min | ~3 hours |
+
+---
+
+## Quick Skill Creation Checklist
+
+- [ ] Problem statement (1-2 sentences)
+- [ ] 5+ trigger keywords identified
+- [ ] 3+ reference URLs collected
+- [ ] Name written (gerund + domain, ≤64 chars)
+- [ ] Description written (capabilities + triggers, ≤1024 chars)
+- [ ] Allowed tools listed (minimal set)
+- [ ] Content outline (High/Medium/Low freedom %)
+- [ ] SKILL.md written (≤500 lines)
+- [ ] reference.md created (detailed docs)
+- [ ] examples.md created (3-4 scenarios)
+- [ ] CHECKLIST.md validation passed
+- [ ] Tested with Haiku and Sonnet
+
+---
+
+**For complete skill creation reference, see [reference.md](reference.md)**
+
 ---
 
-_For more examples, see SKILL.md and supporting documentation_
+**Last Updated**: 2025-10-22
+**Examples**: 3 complete workflows + mistake patterns
+**Maintained by**: MoAI-ADK Foundation Team

moai_adk/templates/.claude/skills/moai-skill-factory/INTERACTIVE-DISCOVERY.md

@@ -1,6 +1,6 @@
 # Interactive Discovery: TUI-Based Skill Requirement Gathering
 
-This guide covers using **moai-alfred-tui-survey** Skill to engage users through interactive dialogue and clarify Skill requirements.
+This guide covers using **moai-alfred-interactive-questions** Skill to engage users through interactive dialogue and clarify Skill requirements.
 
 ---
 
@@ -242,13 +242,13 @@ framework_versions = {
 
 **Available Stable Version Matrix** (referenced as source of truth):
 
-| Framework | Latest | LTS | EOL Date | Ref |
-|---|---|---|---|---|
-| **Python** | 3.13.1 | 3.12.7 | 3.12: 2028-10 | [python.org](https://python.org) |
-| **Node.js** | 23.0.0 | 22.11.0 | 22.x: 2025-10 | [nodejs.org](https://nodejs.org) |
-| **Go** | 1.23.3 | 1.22.x | 1.22: 2025-02 | [golang.org](https://golang.org) |
-| **Rust** | 1.82.0 | MSRV: 1.70 | N/A | [rust-lang.org](https://rust-lang.org) |
-| **Java** | 23.0.1 | 21.0.x | 21: 2028-09 | [oracle.com](https://oracle.com) |
+| Framework   | Latest | LTS        | EOL Date      | Ref                                    |
+| ----------- | ------ | ---------- | ------------- | -------------------------------------- |
+| **Python**  | 3.13.1 | 3.12.7     | 3.12: 2028-10 | [python.org](https://python.org)       |
+| **Node.js** | 23.0.0 | 22.11.0    | 22.x: 2025-10 | [nodejs.org](https://nodejs.org)       |
+| **Go**      | 1.23.3 | 1.22.x     | 1.22: 2025-02 | [golang.org](https://golang.org)       |
+| **Rust**    | 1.82.0 | MSRV: 1.70 | N/A           | [rust-lang.org](https://rust-lang.org) |
+| **Java**    | 23.0.1 | 21.0.x     | 21: 2028-09   | [oracle.com](https://oracle.com)       |
 
 **When This Survey Is Needed**:
 - ✅ Creating a new Skill (always)
@@ -501,12 +501,12 @@ WebSearch findings INFORM the Skill
 
 Map survey answers to research queries:
 
-| Survey Answer | WebSearch Topic | Example Query |
-|---|---|---|
-| Python 3.12 | Latest version | "Python 3.12 best practices 2025" |
-| Async testing | Modern pattern | "async/await testing patterns 2025" |
-| Performance | Optimization | "performance profiling tools 2025" |
-| Security | Compliance | "OWASP security patterns 2025" |
+| Survey Answer | WebSearch Topic | Example Query                       |
+| ------------- | --------------- | ----------------------------------- |
+| Python 3.12   | Latest version  | "Python 3.12 best practices 2025"   |
+| Async testing | Modern pattern  | "async/await testing patterns 2025" |
+| Performance   | Optimization    | "performance profiling tools 2025"  |
+| Security      | Compliance      | "OWASP security patterns 2025"      |
 
 ---
 
@@ -515,7 +515,7 @@ Map survey answers to research queries:
 - [SKILL.md](SKILL.md) — Main Skill framework
 - [WEB-RESEARCH.md](WEB-RESEARCH.md) — Using discoveries in research
 - [skill-factory.md](../../agents/alfred/skill-factory.md) — Sub-Agent orchestration
-- `moai-alfred-tui-survey` Skill — TUI implementation
+- `moai-alfred-interactive-questions` Skill — TUI implementation
 
 ---