@xaviele/ag-kit 1.0.0

package/template/.agent/skills/skills/claudekit-ai-multimodal/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: "ai-multimodal"
+description: "Process and generate multimedia content using Google Gemini API. Capabilities include analyze audio files (transcription with timestamps, summarization, speech understanding, music/sound analysis up to 9.5 hours), understand images (captioning, object detection, OCR, visual Q&A, segmentation), process videos (scene detection, Q&A, temporal analysis, YouTube URLs, up to 6 hours), extract from documents (PDF tables, forms, charts, diagrams, multi-page), generate images (text-to-image, editing, composition, refinement). Use when working with audio/video files, analyzing images or screenshots, processing PDF documents, extracting structured data from media, creating images from text prompts, or implementing multimodal AI features. Supports multiple models (Gemini 2.5/2.0) with context windows up to 2M tokens."
+version: 1.0.0
+category: build
+---
+
+# AI Multimodal Processing Skill
+
+Process audio, images, videos, documents, and generate images using Google Gemini's multimodal API. Unified interface for all multimedia content understanding and generation.
+
+## Core Capabilities
+
+### Audio Processing
+- Transcription with timestamps (up to 9.5 hours)
+- Audio summarization and analysis
+- Speech understanding and speaker identification
+- Music and environmental sound analysis
+- Text-to-speech generation with controllable voice
+
+### Image Understanding
+- Image captioning and description
+- Object detection with bounding boxes (2.0+)
+- Pixel-level segmentation (2.5+)
+- Visual question answering
+- Multi-image comparison (up to 3,600 images)
+- OCR and text extraction
+
+### Video Analysis
+- Scene detection and summarization
+- Video Q&A with temporal understanding
+- Transcription with visual descriptions
+- YouTube URL support
+- Long video processing (up to 6 hours)
+- Frame-level analysis
+
+### Document Extraction
+- Native PDF vision processing (up to 1,000 pages)
+- Table and form extraction
+- Chart and diagram analysis
+- Multi-page document understanding
+- Structured data output (JSON schema)
+- Format conversion (PDF to HTML/JSON)
+
+### Image Generation
+- Text-to-image generation
+- Image editing and modification
+- Multi-image composition (up to 3 images)
+- Iterative refinement
+- Multiple aspect ratios (1:1, 16:9, 9:16, 4:3, 3:4)
+- Controllable style and quality
+
+## Capability Matrix
+
+| Task | Audio | Image | Video | Document | Generation |
+|------|:-----:|:-----:|:-----:|:--------:|:----------:|
+| Transcription | ✓ | - | ✓ | - | - |
+| Summarization | ✓ | ✓ | ✓ | ✓ | - |
+| Q&A | ✓ | ✓ | ✓ | ✓ | - |
+| Object Detection | - | ✓ | ✓ | - | - |
+| Text Extraction | - | ✓ | - | ✓ | - |
+| Structured Output | ✓ | ✓ | ✓ | ✓ | - |
+| Creation | TTS | - | - | - | ✓ |
+| Timestamps | ✓ | - | ✓ | - | - |
+| Segmentation | - | ✓ | - | - | - |
+
+## Model Selection Guide
+
+### Gemini 2.5 Series (Recommended)
+- **gemini-2.5-pro**: Highest quality, all features, 1M-2M context
+- **gemini-2.5-flash**: Best balance, all features, 1M-2M context
+- **gemini-2.5-flash-lite**: Lightweight, segmentation support
+- **gemini-2.5-flash-image**: Image generation only
+
+### Gemini 2.0 Series
+- **gemini-2.0-flash**: Fast processing, object detection
+- **gemini-2.0-flash-lite**: Lightweight option
+
+### Feature Requirements
+- **Segmentation**: Requires 2.5+ models
+- **Object Detection**: Requires 2.0+ models
+- **Multi-video**: Requires 2.5+ models
+- **Image Generation**: Requires flash-image model
+
+### Context Windows
+- **2M tokens**: ~6 hours video (low-res) or ~2 hours (default)
+- **1M tokens**: ~3 hours video (low-res) or ~1 hour (default)
+- **Audio**: 32 tokens/second (1 min = 1,920 tokens)
+- **PDF**: 258 tokens/page (fixed)
+- **Image**: 258-1,548 tokens based on size
+
+## Quick Start
+
+### Prerequisites
+
+**API Key Setup**: Supports both Google AI Studio and Vertex AI.
+
+The skill checks for `GEMINI_API_KEY` in this order:
+1. Process environment: `export GEMINI_API_KEY="your-key"`
+2. Project root: `.env`
+3. `.claude/.env`
+4. `.claude/skills/.env`
+5. `.claude/skills/ai-multimodal/.env`
+
+**Get API key**: https://aistudio.google.com/apikey
+
+**For Vertex AI**:
+```bash
+export GEMINI_USE_VERTEX=true
+export VERTEX_PROJECT_ID=your-gcp-project-id
+export VERTEX_LOCATION=us-central1  # Optional
+```
+
+**Install SDK**:
+```bash
+pip install google-genai python-dotenv pillow
+```
+
+### Common Patterns
+
+**Transcribe Audio**:
+```bash
+python scripts/gemini_batch_process.py \
+  --files audio.mp3 \
+  --task transcribe \
+  --model gemini-2.5-flash
+```
+
+**Analyze Image**:
+```bash
+python scripts/gemini_batch_process.py \
+  --files image.jpg \
+  --task analyze \
+  --prompt "Describe this image" \
+  --output docs/assets/<output-name>.md \
+  --model gemini-2.5-flash
+```
+
+**Process Video**:
+```bash
+python scripts/gemini_batch_process.py \
+  --files video.mp4 \
+  --task analyze \
+  --prompt "Summarize key points with timestamps" \
+  --output docs/assets/<output-name>.md \
+  --model gemini-2.5-flash
+```
+
+**Extract from PDF**:
+```bash
+python scripts/gemini_batch_process.py \
+  --files document.pdf \
+  --task extract \
+  --prompt "Extract table data as JSON" \
+  --output docs/assets/<output-name>.md \
+  --format json
+```
+
+**Generate Image**:
+```bash
+python scripts/gemini_batch_process.py \
+  --task generate \
+  --prompt "A futuristic city at sunset" \
+  --output docs/assets/<output-file-name> \
+  --model gemini-2.5-flash-image \
+  --aspect-ratio 16:9
+```
+
+**Optimize Media**:
+```bash
+# Prepare large video for processing
+python scripts/media_optimizer.py \
+  --input large-video.mp4 \
+  --output docs/assets/<output-file-name> \
+  --target-size 100MB
+
+# Batch optimize multiple files
+python scripts/media_optimizer.py \
+  --input-dir ./videos \
+  --output-dir docs/assets/optimized \
+  --quality 85
+```
+
+**Convert Documents to Markdown**:
+```bash
+# Convert to PDF
+python scripts/document_converter.py \
+  --input document.docx \
+  --output docs/assets/document.md
+
+# Extract pages
+python scripts/document_converter.py \
+  --input large.pdf \
+  --output docs/assets/chapter1.md \
+  --pages 1-20
+```
+
+## Supported Formats
+
+### Audio
+- WAV, MP3, AAC, FLAC, OGG Vorbis, AIFF
+- Max 9.5 hours per request
+- Auto-downsampled to 16 Kbps mono
+
+### Images
+- PNG, JPEG, WEBP, HEIC, HEIF
+- Max 3,600 images per request
+- Resolution: ≤384px = 258 tokens, larger = tiled
+
+### Video
+- MP4, MPEG, MOV, AVI, FLV, MPG, WebM, WMV, 3GPP
+- Max 6 hours (low-res) or 2 hours (default)
+- YouTube URLs supported (public only)
+
+### Documents
+- PDF only for vision processing
+- Max 1,000 pages
+- TXT, HTML, Markdown supported (text-only)
+
+### Size Limits
+- **Inline**: <20MB total request
+- **File API**: 2GB per file, 20GB project quota
+- **Retention**: 48 hours auto-delete
+
+## Reference Navigation
+
+For detailed implementation guidance, see:
+
+### Audio Processing
+- `references/audio-processing.md` - Transcription, analysis, TTS
+  - Timestamp handling and segment analysis
+  - Multi-speaker identification
+  - Non-speech audio analysis
+  - Text-to-speech generation
+
+### Image Understanding
+- `references/vision-understanding.md` - Captioning, detection, OCR
+  - Object detection and localization
+  - Pixel-level segmentation
+  - Visual question answering
+  - Multi-image comparison
+
+### Video Analysis
+- `references/video-analysis.md` - Scene detection, temporal understanding
+  - YouTube URL processing
+  - Timestamp-based queries
+  - Video clipping and FPS control
+  - Long video optimization
+
+### Document Extraction
+- `references/document-extraction.md` - PDF processing, structured output
+  - Table and form extraction
+  - Chart and diagram analysis
+  - JSON schema validation
+  - Multi-page handling
+
+### Image Generation
+- `references/image-generation.md` - Text-to-image, editing
+  - Prompt engineering strategies
+  - Image editing and composition
+  - Aspect ratio selection
+  - Safety settings
+
+## Cost Optimization
+
+### Token Costs
+**Input Pricing**:
+- Gemini 2.5 Flash: $1.00/1M input, $0.10/1M output
+- Gemini 2.5 Pro: $3.00/1M input, $12.00/1M output
+- Gemini 1.5 Flash: $0.70/1M input, $0.175/1M output
+
+**Token Rates**:
+- Audio: 32 tokens/second (1 min = 1,920 tokens)
+- Video: ~300 tokens/second (default) or ~100 (low-res)
+- PDF: 258 tokens/page (fixed)
+- Image: 258-1,548 tokens based on size
+
+**TTS Pricing**:
+- Flash TTS: $10/1M tokens
+- Pro TTS: $20/1M tokens
+
+### Best Practices
+1. Use `gemini-2.5-flash` for most tasks (best price/performance)
+2. Use File API for files >20MB or repeated queries
+3. Optimize media before upload (see `media_optimizer.py`)
+4. Process specific segments instead of full videos
+5. Use lower FPS for static content
+6. Implement context caching for repeated queries
+7. Batch process multiple files in parallel
+
+## Rate Limits
+
+**Free Tier**:
+- 10-15 RPM (requests per minute)
+- 1M-4M TPM (tokens per minute)
+- 1,500 RPD (requests per day)
+
+**YouTube Limits**:
+- Free tier: 8 hours/day
+- Paid tier: No length limits
+- Public videos only
+
+**Storage Limits**:
+- 20GB per project
+- 2GB per file
+- 48-hour retention
+
+## Error Handling
+
+Common errors and solutions:
+- **400**: Invalid format/size - validate before upload
+- **401**: Invalid API key - check configuration
+- **403**: Permission denied - verify API key restrictions
+- **404**: File not found - ensure file uploaded and active
+- **429**: Rate limit exceeded - implement exponential backoff
+- **500**: Server error - retry with backoff
+
+## Scripts Overview
+
+All scripts support unified API key detection and error handling:
+
+**gemini_batch_process.py**: Batch process multiple media files
+- Supports all modalities (audio, image, video, PDF)
+- Progress tracking and error recovery
+- Output formats: JSON, Markdown, CSV
+- Rate limiting and retry logic
+- Dry-run mode
+
+**media_optimizer.py**: Prepare media for Gemini API
+- Compress videos/audio for size limits
+- Resize images appropriately
+- Split long videos into chunks
+- Format conversion
+- Quality vs size optimization
+
+**document_converter.py**: Convert documents to PDF
+- Convert DOCX, XLSX, PPTX to PDF
+- Extract page ranges
+- Optimize PDFs for Gemini
+- Extract images from PDFs
+- Batch conversion support
+
+Run any script with `--help` for detailed usage.
+
+## Resources
+
+- [Audio API Docs](https://ai.google.dev/gemini-api/docs/audio)
+- [Image API Docs](https://ai.google.dev/gemini-api/docs/image-understanding)
+- [Video API Docs](https://ai.google.dev/gemini-api/docs/video-understanding)
+- [Document API Docs](https://ai.google.dev/gemini-api/docs/document-processing)
+- [Image Gen Docs](https://ai.google.dev/gemini-api/docs/image-generation)
+- [Get API Key](https://aistudio.google.com/apikey)
+- [Pricing](https://ai.google.dev/pricing)

package/template/.agent/skills/skills/document/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: document
+description: "Audit your project's documentation health and identify gaps. Scans for README, changelog, API docs, ADRs, runbooks, onboarding guides, and diagrams. Scores coverage against project maturity tier and recommends specific sub-skills to fill missing docs. Use when you need a documentation audit, want to check doc coverage, find missing documentation, or assess documentation quality."
+version: 2.0.0
+category: docs
+---
+
+You are in AUTONOMOUS MODE. Do NOT ask questions. Analyze the project's
+documentation landscape and produce a comprehensive health report.
+
+INPUT:
+$ARGUMENTS
+
+If no arguments provided, perform a full documentation audit of the current project.
+If a specific doc type is mentioned (e.g., "api", "adr", "runbook"), focus the audit
+on that area and route to the appropriate sub-skill.
+
+============================================================
+PHASE 1: AUTO-DETECT PROJECT CONTEXT
+============================================================
+
+Detect the project's tech stack and maturity level:
+
+Step 1.1 -- Tech Stack Detection
+
+Scan for config files to determine the stack:
+- package.json, tsconfig.json (Node.js / TypeScript)
+- pubspec.yaml (Flutter / Dart)
+- Cargo.toml (Rust)
+- go.mod (Go)
+- pyproject.toml, requirements.txt, setup.py (Python)
+- Gemfile (Ruby)
+- pom.xml, build.gradle (Java / Kotlin)
+- docker-compose.yml, Dockerfile (containerized)
+- .github/workflows/ (CI/CD)
+
+Step 1.2 -- Maturity Assessment
+
+Classify the project into a maturity tier:
+
+| Tier | Criteria |
+|------|----------|
+| Greenfield | < 20 commits, no tests, no CI |
+| Active Development | 20-200 commits, some tests, basic CI |
+| Mature | 200+ commits, test suite, CI/CD, deployments |
+| Production | All of Mature + monitoring, runbooks, on-call |
+
+Record the tier -- it determines which docs are expected.
+
+============================================================
+PHASE 2: DOCUMENTATION INVENTORY
+============================================================
+
+Scan the project for existing documentation artifacts:
+
+Step 2.1 -- Core Docs
+
+Check for each of these files/directories and record status (present/missing/stale):
+
+| Document | Paths to Check |
+|----------|---------------|
+| README | README.md, README, readme.md |
+| Changelog | CHANGELOG.md, CHANGES.md, HISTORY.md |
+| Contributing | CONTRIBUTING.md, docs/contributing.md |
+| License | LICENSE, LICENSE.md, COPYING |
+| Code of Conduct | CODE_OF_CONDUCT.md |
+
+Step 2.2 -- API Documentation
+
+Check for:
+- OpenAPI/Swagger specs: openapi.yaml, openapi.json, swagger.yaml, swagger.json
+- docs/api/, api-docs/ directories
+- Inline API doc comments (JSDoc @route, Python docstrings with endpoint info)
+- GraphQL schema files: schema.graphql, *.graphqls
+- Postman collections: *.postman_collection.json
+
+Step 2.3 -- Architecture Docs
+
+Check for:
+- docs/adr/, adr/, decisions/ directories
+- Architecture diagrams: docs/diagrams/, docs/architecture/
+- Mermaid files: *.mmd, *.mermaid
+- Draw.io files: *.drawio
+- C4 model files
+
+Step 2.4 -- Operations Docs
+
+Check for:
+- Runbooks: docs/runbook/, runbook/, playbooks/
+- Deployment docs: docs/deployment/, DEPLOYMENT.md
+- Incident response: docs/incidents/, INCIDENT.md
+- Monitoring: docs/monitoring/, alerts/
+
+Step 2.5 -- Onboarding Docs
+
+Check for:
+- CONTRIBUTING.md, docs/onboarding.md, docs/getting-started.md
+- .env.example, .env.template (environment setup docs)
+- Makefile, scripts/ (developer workflow tooling)
+- docs/development.md, DEVELOPMENT.md
+
+============================================================
+PHASE 3: GAP ANALYSIS
+============================================================
+
+Score each documentation area based on project maturity tier:
+
+SCORING MATRIX:
+
+| Document Type | Greenfield | Active Dev | Mature | Production |
+|--------------|-----------|-----------|--------|-----------|
+| README | Required | Required | Required | Required |
+| Changelog | Optional | Recommended | Required | Required |
+| API Docs | Optional | Recommended | Required | Required |
+| ADRs | Optional | Optional | Recommended | Required |
+| Runbook | N/A | Optional | Recommended | Required |
+| Onboarding | Optional | Recommended | Required | Required |
+| Diagrams | Optional | Optional | Recommended | Required |
+| License | Required | Required | Required | Required |
+
+For each doc type, assign a status:
+- PASS: Document exists and appears current (modified within last 30 days or content matches code)
+- STALE: Document exists but may be outdated (last modified 90+ days ago)
+- MISSING: Document does not exist but is Required/Recommended for this tier
+- N/A: Not expected for this maturity tier
+
+Calculate coverage score: (PASS count / Required+Recommended count) * 100
+
+============================================================
+PHASE 4: ROUTE TO SUB-SKILLS
+============================================================
+
+Based on identified gaps, recommend specific sub-skills to run:
+
+| Gap | Sub-Skill | Command |
+|-----|-----------|---------|
+| Missing/stale README | /readme | Generate comprehensive README |
+| Missing API docs | /api-docs | Auto-generate OpenAPI spec |
+| Missing changelog | /changelog | Generate from git history |
+| Missing ADRs | /adr | Create ADR directory + retrospective ADRs |
+| Missing runbook | /runbook | Generate operations runbook |
+| Missing onboarding | /onboarding | Generate developer onboarding guide |
+| Missing diagrams | /diagram | Generate architecture diagrams |
+
+If $ARGUMENTS specifies a particular doc type, execute that sub-skill's work
+inline rather than just recommending it.
+
+============================================================
+PHASE 5: DOCUMENTATION HEALTH REPORT
+============================================================
+
+OUTPUT:
+
+## Documentation Health Report
+
+### Project Context
+- **Project:** [name from config]
+- **Tech Stack:** [detected stack]
+- **Maturity Tier:** [tier]
+- **Total Commits:** [count]
+
+### Coverage Score: [X]%
+
+### Documentation Inventory
+
+| Document | Status | Path | Last Updated | Notes |
+|----------|--------|------|-------------|-------|
+| README | PASS/STALE/MISSING | path or -- | date or -- | details |
+| Changelog | ... | ... | ... | ... |
+| API Docs | ... | ... | ... | ... |
+| ADRs | ... | ... | ... | ... |
+| Runbook | ... | ... | ... | ... |
+| Onboarding | ... | ... | ... | ... |
+| Diagrams | ... | ... | ... | ... |
+| License | ... | ... | ... | ... |
+
+### Priority Actions
+
+Ordered list of documentation gaps to address, highest priority first:
+
+1. **[MISSING/STALE] [Doc Type]** -- [Why it matters for this project]
+   Run: `/[sub-skill]`
+2. ...
+
+### Documentation Quality Notes
+
+- [Any observations about existing doc quality, consistency, accuracy]
+- [Suggestions for improving existing docs that are present but weak]
+
+
+============================================================
+SELF-HEALING VALIDATION (max 2 iterations)
+============================================================
+
+After producing documentation, validate completeness:
+
+1. Verify all required sections are present and non-empty.
+2. Verify internal cross-references and links resolve correctly.
+3. Verify no placeholder text remains ("{TODO}", "[TBD]", "...", "etc.").
+4. Verify code examples are syntactically valid.
+
+IF VALIDATION FAILS:
+- Identify which sections are incomplete or contain placeholders
+- Re-generate only the deficient sections
+- Repeat up to 2 iterations
+
+
+============================================================
+SELF-EVOLUTION TELEMETRY
+============================================================
+
+After producing output, record execution metadata for the /evolve pipeline.
+
+Check if a project memory directory exists:
+- Look for the project path in `~/.claude/projects/`
+- If found, append to `skill-telemetry.md` in that memory directory
+
+Entry format:
+```
+### /document — {{YYYY-MM-DD}}
+- Outcome: {{SUCCESS | PARTIAL | FAILED}}
+- Self-healed: {{yes — what was healed | no}}
+- Iterations used: {{N}} / {{N max}}
+- Bottleneck: {{phase that struggled or "none"}}
+- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
+```
+
+Only log if the memory directory exists. Skip silently if not found.
+Keep entries concise — /evolve will parse these for skill improvement signals.
+
+============================================================
+DO NOT
+============================================================
+
+- Do NOT create or modify any documentation files in this orchestrator skill.
+  Only audit and report. Sub-skills handle the actual generation.
+- Do NOT guess about project features. Only report what you can verify.
+- Do NOT count auto-generated files (lock files, build output) as documentation.
+- Do NOT recommend docs that are genuinely unnecessary for the project type
+  (e.g., runbooks for a CLI tool with no deployment).
+
+NEXT STEPS:
+
+After reviewing the health report:
+- "Run `/api-docs` to generate OpenAPI documentation for your API."
+- "Run `/changelog` to generate a changelog from git history."
+- "Run `/adr retrospective` to create ADRs from existing codebase decisions."
+- "Run `/runbook` to generate an operations runbook."
+- "Run `/onboarding` to generate a developer onboarding guide."
+- "Run `/diagram` to generate architecture diagrams."