@ngxtm/devkit 3.14.0 → 3.16.0

package/skills/youtube-automation/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: youtube-automation
+description: "Automate YouTube tasks via Rube MCP (Composio): upload videos, manage playlists, search content, get analytics, and handle comments. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# YouTube Automation via Rube MCP
+
+Automate YouTube operations through Composio's YouTube toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active YouTube connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `youtube`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `youtube`
+3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Upload and Manage Videos
+
+**When to use**: User wants to upload a video or update video metadata
+
+**Tool sequence**:
+1. `YOUTUBE_UPLOAD_VIDEO` - Upload a new video [Required]
+2. `YOUTUBE_UPDATE_VIDEO` - Update title, description, tags, privacy [Optional]
+3. `YOUTUBE_UPDATE_THUMBNAIL` - Set a custom thumbnail [Optional]
+
+**Key parameters**:
+- `title`: Video title (max 100 characters)
+- `description`: Video description (max 5000 bytes)
+- `tags`: Array of keyword tags
+- `categoryId`: YouTube category ID (e.g., '22' for People & Blogs)
+- `privacyStatus`: 'public', 'private', or 'unlisted'
+- `videoFilePath`: Object with `{name, mimetype, s3key}` for the video file
+
+**Pitfalls**:
+- UPLOAD_VIDEO consumes high quota; prefer UPDATE_VIDEO for metadata-only changes
+- videoFilePath must be an object with s3key, not a raw file path or URL
+- Tags total must not exceed 500 characters including separators
+- Angle brackets `< >` in tags are automatically stripped
+- Description limit is 5000 bytes, not characters (multibyte chars count more)
+
+### 2. Search YouTube Content
+
+**When to use**: User wants to find videos, channels, or playlists
+
+**Tool sequence**:
+1. `YOUTUBE_SEARCH_YOU_TUBE` - Search for content [Required]
+2. `YOUTUBE_VIDEO_DETAILS` - Get full details for a specific video [Optional]
+3. `YOUTUBE_GET_VIDEO_DETAILS_BATCH` - Get details for multiple videos [Optional]
+
+**Key parameters**:
+- `q`: Search query (supports exact phrases, exclusions, channel handles)
+- `type`: 'video', 'channel', or 'playlist'
+- `maxResults`: Results per page (1-50)
+- `pageToken`: For pagination
+
+**Pitfalls**:
+- Search endpoint only returns 'snippet' part; use VIDEO_DETAILS for statistics
+- Search results are capped at 500 total items
+- Search has higher quota cost (100 units) vs list endpoints (1 unit)
+- BATCH video details practical limit is ~50 IDs per call; chunk larger sets
+
+### 3. Manage Playlists
+
+**When to use**: User wants to create playlists or manage playlist contents
+
+**Tool sequence**:
+1. `YOUTUBE_LIST_USER_PLAYLISTS` - List user's existing playlists [Optional]
+2. `YOUTUBE_CREATE_PLAYLIST` - Create a new playlist [Optional]
+3. `YOUTUBE_ADD_VIDEO_TO_PLAYLIST` - Add a video to a playlist [Optional]
+4. `YOUTUBE_LIST_PLAYLIST_ITEMS` - List videos in a playlist [Optional]
+
+**Key parameters**:
+- `playlistId`: Playlist ID ('PL...' for user-created, 'UU...' for uploads)
+- `part`: Resource parts to include (e.g., 'snippet,contentDetails')
+- `maxResults`: Items per page (1-50)
+- `pageToken`: Pagination token from previous response
+
+**Pitfalls**:
+- Do NOT pass channel IDs ('UC...') as playlist IDs; convert 'UC' to 'UU' for uploads
+- Large playlists require pagination via pageToken; follow nextPageToken until absent
+- items[].id is not the videoId; use items[].snippet.resourceId.videoId
+- Creating duplicate playlist names is allowed; check existing playlists first
+
+### 4. Get Channel and Video Analytics
+
+**When to use**: User wants to analyze channel performance or video metrics
+
+**Tool sequence**:
+1. `YOUTUBE_GET_CHANNEL_ID_BY_HANDLE` - Resolve a handle to channel ID [Prerequisite]
+2. `YOUTUBE_GET_CHANNEL_STATISTICS` - Get channel subscriber/view/video counts [Required]
+3. `YOUTUBE_LIST_CHANNEL_VIDEOS` - List all videos from a channel [Optional]
+4. `YOUTUBE_GET_VIDEO_DETAILS_BATCH` - Get per-video statistics [Optional]
+5. `YOUTUBE_GET_CHANNEL_ACTIVITIES` - Get recent channel activities [Optional]
+
+**Key parameters**:
+- `channelId`: Channel ID ('UC...'), handle ('@handle'), or 'me'
+- `forHandle`: Channel handle (e.g., '@Google')
+- `id`: Comma-separated video IDs for batch details
+- `parts`: Resource parts to include (e.g., 'snippet,statistics')
+
+**Pitfalls**:
+- Channel statistics are lifetime totals, not per-period
+- BATCH video details may return fewer items than requested for private/deleted videos
+- Response data may be nested under `data` or `data_preview`; parse defensively
+- contentDetails.duration uses ISO 8601 format (e.g., 'PT4M13S')
+
+### 5. Manage Subscriptions and Comments
+
+**When to use**: User wants to subscribe to channels or view video comments
+
+**Tool sequence**:
+1. `YOUTUBE_SUBSCRIBE_CHANNEL` - Subscribe to a channel [Optional]
+2. `YOUTUBE_UNSUBSCRIBE_CHANNEL` - Unsubscribe from a channel [Optional]
+3. `YOUTUBE_LIST_USER_SUBSCRIPTIONS` - List subscriptions [Optional]
+4. `YOUTUBE_LIST_COMMENT_THREADS` - List comments on a video [Optional]
+
+**Key parameters**:
+- `channelId`: Channel to subscribe/unsubscribe
+- `videoId`: Video ID for comment threads
+- `maxResults`: Results per page
+- `pageToken`: Pagination token
+
+**Pitfalls**:
+- Subscribing to an already-subscribed channel may return an error
+- Comment threads return top-level comments with up to 5 replies each
+- Comments may be disabled on some videos
+- Unsubscribe requires the subscription ID, not the channel ID
+
+## Common Patterns
+
+### Channel ID Resolution
+
+**Handle to Channel ID**:
+```
+1. Call YOUTUBE_GET_CHANNEL_ID_BY_HANDLE with '@handle'
+2. Extract channelId from response
+3. Use in subsequent channel operations
+```
+
+**Uploads Playlist**:
+```
+1. Get channel ID (starts with 'UC')
+2. Replace 'UC' prefix with 'UU' to get uploads playlist ID
+3. Use with LIST_PLAYLIST_ITEMS to enumerate all videos
+```
+
+### Pagination
+
+- Set `maxResults` (max 50 per page)
+- Check response for `nextPageToken`
+- Pass token as `pageToken` in next request
+- Continue until `nextPageToken` is absent
+
+### Batch Video Details
+
+- Collect video IDs from search or playlist listings
+- Chunk into groups of ~50 IDs
+- Call GET_VIDEO_DETAILS_BATCH per chunk
+- Merge results across chunks
+
+## Known Pitfalls
+
+**Quota Management**:
+- YouTube API has a daily quota limit (default 10,000 units)
+- Upload = 1600 units; search = 100 units; list = 1 unit
+- Prefer list endpoints over search when possible
+- Monitor quota usage to avoid hitting daily limits
+
+**ID Formats**:
+- Video IDs: 11-character alphanumeric strings
+- Channel IDs: Start with 'UC' followed by 22 characters
+- Playlist IDs: Start with 'PL' (user) or 'UU' (uploads)
+- Do not confuse channel IDs with playlist IDs
+
+**Thumbnails**:
+- Custom thumbnails require channel phone verification
+- Must be JPG, PNG, or GIF; under 2MB
+- Recommended: 1280x720 resolution (16:9 aspect ratio)
+
+**Response Parsing**:
+- Statistics values are returned as strings, not integers; cast before math
+- Duration uses ISO 8601 format (PT#H#M#S)
+- Batch responses may wrap data under different keys
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| Upload video | YOUTUBE_UPLOAD_VIDEO | title, description, tags, categoryId, privacyStatus, videoFilePath |
+| Update video | YOUTUBE_UPDATE_VIDEO | video_id, title, description, tags |
+| Set thumbnail | YOUTUBE_UPDATE_THUMBNAIL | videoId, thumbnailUrl |
+| Search YouTube | YOUTUBE_SEARCH_YOU_TUBE | q, type, maxResults |
+| Video details | YOUTUBE_VIDEO_DETAILS | id, part |
+| Batch video details | YOUTUBE_GET_VIDEO_DETAILS_BATCH | id, parts |
+| List playlists | YOUTUBE_LIST_USER_PLAYLISTS | maxResults, pageToken |
+| Create playlist | YOUTUBE_CREATE_PLAYLIST | (check schema) |
+| Add to playlist | YOUTUBE_ADD_VIDEO_TO_PLAYLIST | (check schema) |
+| List playlist items | YOUTUBE_LIST_PLAYLIST_ITEMS | playlistId, maxResults |
+| Channel statistics | YOUTUBE_GET_CHANNEL_STATISTICS | id/forHandle/mine |
+| List channel videos | YOUTUBE_LIST_CHANNEL_VIDEOS | channelId, maxResults |
+| Channel ID by handle | YOUTUBE_GET_CHANNEL_ID_BY_HANDLE | channel_handle |
+| Subscribe | YOUTUBE_SUBSCRIBE_CHANNEL | channelId |
+| List subscriptions | YOUTUBE_LIST_USER_SUBSCRIPTIONS | (check schema) |
+| List comments | YOUTUBE_LIST_COMMENT_THREADS | videoId |
+| Channel activities | YOUTUBE_GET_CHANNEL_ACTIVITIES | (check schema) |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/skills/youtube-summarizer/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog - youtube-summarizer
+
+All notable changes to the youtube-summarizer skill 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/spec/v2.0.0.html).
+
+---
+
+## [1.2.1] - 2026-02-04
+
+### 🐛 Fixed
+
+- **Exit code propagation in `--list` mode**
+  - **Issue:** Script always exited with status 0 even when `list_available_transcripts()` failed
+  - **Risk:** Broke automation pipelines that rely on exit codes to detect failures
+  - **Root Cause:** Return value from `list_available_transcripts()` was ignored
+  - **Solution:** Now properly checks return value and exits with code 1 on failure
+  - **Impact:** Scripts in automation can now correctly detect when transcript listing fails (invalid video ID, network errors, etc.)
+
+### 🔧 Changed
+
+- `extract-transcript.py` (lines 58-60)
+  - Before: `list_available_transcripts(video_id); sys.exit(0)`
+  - After: `success = list_available_transcripts(video_id); sys.exit(0 if success else 1)`
+
+### 📝 Notes
+
+- **Breaking Change:** None - only affects error handling behavior
+- **Backward Compatibility:** Scripts that check exit codes will now work correctly
+- **Migration:** No changes needed for existing users
+
+### 🔗 Related
+
+- Identified by Codex automated review in antigravity-awesome-skills PR #62
+- Also fixed in antigravity-awesome-skills fork
+
+---
+
+## [1.2.0] - 2026-02-04
+
+### ✨ Added
+
+- Intelligent prompt workflow integration
+- LLM processing with Claude CLI or GitHub Copilot CLI
+- Progress indicators with rich terminal UI
+- Multiple output formats
+- Enhanced error handling
+
+### 🔧 Changed
+
+- Major refactor of transcript extraction logic
+- Improved documentation in SKILL.md
+- Updated installation requirements
+
+---
+
+## [1.0.0] - 2025-02-01
+
+### ✨ Initial Release
+
+- YouTube transcript extraction
+- Language detection and selection
+- Basic summarization
+- Markdown output format
+- Support for multiple languages

package/skills/youtube-summarizer/README.md

@@ -0,0 +1,365 @@
+# 🎥 youtube-summarizer
+
+> Extract transcripts from YouTube videos and generate comprehensive, detailed summaries
+
+**Version:** 1.2.0
+**Status:** ✨ Zero-Config | 🌍 Universal
+**Platforms:** GitHub Copilot CLI, Claude Code
+
+---
+
+## Overview
+
+The **youtube-summarizer** skill automates the extraction of YouTube video transcripts and generates verbose, structured summaries using the STAR + R-I-S-E framework. Perfect for documenting educational content, lectures, tutorials, or any informational videos without rewatching them.
+
+---
+
+## Features
+
+- 🎯 **Automatic transcript extraction** using `youtube-transcript-api`
+- ✅ **Video validation** - Checks if video is accessible and has transcripts
+- 🌍 **Multi-language support** - Prefers Portuguese, falls back to English
+- 📊 **Comprehensive summaries** - Prioritizes detail and completeness
+- 📝 **Structured output** - Markdown with headers, sections, insights
+- 🔍 **Metadata included** - Video title, channel, duration, URL
+- ⚡ **Error handling** - Clear messages for all failure scenarios
+- 🛠️ **Dependency management** - Offers to install requirements automatically
+- 📊 **Progress gauge** - Visual processing tracker across all steps
+- 💾 **Flexible save options** - Summary-only, summary+transcript, or transcript-only (NEW v1.2.0)
+
+---
+
+## Quick Start
+
+### Triggers
+
+Activate this skill with any of these phrases:
+
+```bash
+# English
+copilot> summarize this video: https://www.youtube.com/watch?v=VIDEO_ID
+copilot> summarize youtube video https://youtu.be/VIDEO_ID
+copilot> extract youtube transcript https://youtube.com/watch?v=VIDEO_ID
+
+# Portuguese (also supported)
+copilot> resume este video: https://www.youtube.com/watch?v=VIDEO_ID
+```
+
+### First-Time Setup
+
+The skill will automatically check for dependencies and offer to install them:
+
+```bash
+⚠️  youtube-transcript-api not installed
+
+Would you like me to install it now?
+- [x] Yes - Install with pip
+- [ ] No - I'll install manually
+```
+
+Select "Yes" and the skill handles installation automatically.
+
+---
+
+## Use Cases
+
+### 1. **Educational Video Documentation**
+
+```bash
+copilot> summarize this video: https://www.youtube.com/watch?v=abc123
+```
+
+**Output:**
+- Comprehensive summary of lecture content
+- Key concepts and terminology
+- Examples and practical applications
+- Resources mentioned in the video
+
+### 2. **Technical Tutorial Analysis**
+
+```bash
+copilot> summarize youtube video https://youtu.be/xyz789
+```
+
+**Output:**
+- Step-by-step breakdown of tutorial
+- Code snippets and commands mentioned
+- Best practices highlighted
+- Troubleshooting tips documented
+
+### 3. **Conference Talk Reference**
+
+```bash
+copilot> extract youtube transcript https://youtube.com/watch?v=def456
+```
+
+**Output:**
+- Speaker insights and arguments
+- Statistics and data points
+- Case studies and examples
+- Q&A session summary
+
+### 4. **Language Learning Content**
+
+```bash
+copilot> summarize youtube video https://youtu.be/ghi789
+```
+
+**Output:**
+- Vocabulary and expressions used
+- Grammar points explained
+- Cultural references
+- Practice exercises mentioned
+
+### 5. **Research and Investigation**
+
+```bash
+copilot> summarize youtube video https://www.youtube.com/watch?v=jkl012
+```
+
+**Output:**
+- Research findings presented
+- Methodology explained
+- Results and conclusions
+- Future work suggestions
+
+---
+
+## Output Structure
+
+Every summary follows this comprehensive structure:
+
+```markdown
+# [Video Title]
+
+**Canal:** [Channel Name]
+**Duração:** [Duration]
+**URL:** [Video URL]
+**Data de Publicação:** [Date]
+
+---
+
+## 📊 Síntese Executiva
+[High-level overview, 2-3 paragraphs]
+
+---
+
+## 📝 Resumo Detalhado
+### [Topic 1]
+[Detailed analysis with examples, data, quotes]
+
+### [Topic 2]
+[Continued breakdown...]
+
+---
+
+## 💡 Principais Insights
+- **Insight 1:** [Explanation]
+- **Insight 2:** [Explanation]
+
+---
+
+## 📚 Conceitos e Terminologia
+- **Term 1:** [Definition]
+- **Term 2:** [Definition]
+
+---
+
+## 🔗 Recursos Mencionados
+- [Resource 1]
+- [Resource 2]
+
+---
+
+## 📌 Conclusão
+[Final synthesis and key takeaways]
+```
+
+---
+
+## Requirements
+
+- **Python 3.x** (usually pre-installed on macOS/Linux)
+- **pip** (Python package manager)
+- **[youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api)** by [Julien Depoix](https://github.com/jdepoix) (installed automatically by the skill)
+
+### Manual Installation (Optional)
+
+If you prefer to install dependencies manually:
+
+```bash
+pip install youtube-transcript-api
+```
+
+---
+
+## Supported URL Formats
+
+The skill recognizes these YouTube URL formats:
+
+- `https://www.youtube.com/watch?v=VIDEO_ID`
+- `https://youtube.com/watch?v=VIDEO_ID`
+- `https://youtu.be/VIDEO_ID`
+- `https://m.youtube.com/watch?v=VIDEO_ID`
+
+---
+
+## Limitations
+
+### Videos That Work
+
+✅ Public videos with auto-generated captions  
+✅ Videos with manual subtitles/captions  
+✅ Videos with transcripts in any supported language
+
+### Videos That Don't Work
+
+❌ Private or unlisted videos  
+❌ Videos with transcripts disabled  
+❌ Age-restricted videos (may require authentication)  
+❌ Videos without any captions/subtitles
+
+---
+
+## Error Messages
+
+### No Transcript Available
+
+```
+❌ No transcript available for this video
+
+This skill requires videos with auto-generated captions or manual subtitles.
+Unfortunately, transcripts are not enabled for this video.
+```
+
+**Solution:** Try a different video that has captions enabled.
+
+### Invalid URL
+
+```
+❌ Invalid YouTube URL format
+
+Expected format examples:
+- https://www.youtube.com/watch?v=VIDEO_ID
+- https://youtu.be/VIDEO_ID
+```
+
+**Solution:** Ensure you're providing a complete, valid YouTube URL.
+
+### Video Not Accessible
+
+```
+❌ Unable to access video
+
+Possible reasons:
+1. Video is private or unlisted
+2. Video has been removed
+3. Invalid video ID
+```
+
+**Solution:** Verify the URL and ensure the video is public.
+
+---
+
+## FAQ
+
+### Q: How long does it take to generate a summary?
+
+**A:** Depends on video length:
+- Short videos (5-10 min): 30-60 seconds
+- Medium videos (20-40 min): 1-2 minutes
+- Long videos (60+ min): 2-5 minutes
+
+### Q: Can I summarize videos in languages other than English/Portuguese?
+
+**A:** Yes! The skill attempts to extract transcripts in the video's original language. If unavailable, it falls back to English.
+
+### Q: Will this work with YouTube Music videos?
+
+**A:** Only if the music video has captions/transcripts enabled. Most music videos don't have transcripts.
+
+### Q: Can I customize the summary length?
+
+**A:** The skill prioritizes completeness by design (verbose summaries). If you need shorter summaries, you can ask the AI to condense the output afterward.
+
+### Q: Does this download the video?
+
+**A:** No. Only the text transcript is extracted via YouTube's API. No video files are downloaded.
+
+### Q: Can I save the summary to a file?
+
+**A:** Yes! After the summary is generated, the skill offers flexible save options:
+- **Summary only** - Markdown file with structured summary
+- **Summary + transcript** - Markdown file with summary and raw transcript appended
+- **Transcript only** - Plain text file with raw transcript (NEW in v1.2.0)
+- **Display only** - No files saved, summary shown in terminal
+
+Files are saved as `resumo-{VIDEO_ID}-{YYYY-MM-DD}.md` (summary) or `transcript-{VIDEO_ID}-{YYYY-MM-DD}.txt` (transcript-only).
+
+### Q: When should I save just the transcript?
+
+**A:** Use the transcript-only option when you:
+- Need raw content for further analysis
+- Want to process the text with other tools
+- Prefer to create your own summary later
+- Need the transcript for documentation or archival purposes
+
+---
+
+## Installation
+
+### Global Installation (Recommended)
+
+Install the skill globally to use it across all projects:
+
+```bash
+# Clone the repository
+git clone https://github.com/ericgandrade/cli-ai-skills.git
+cd cli-ai-skills
+
+# Run the install script
+./scripts/install-skills.sh $(pwd)
+```
+
+This creates symlinks in:
+- `~/.copilot/skills/youtube-summarizer/` (GitHub Copilot CLI)
+- `~/.claude/skills/youtube-summarizer/` (Claude Code)
+
+### Repository Installation
+
+Add to a specific project:
+
+```bash
+# Copy skill to your project
+cp -r cli-ai-skills/.github/skills/youtube-summarizer .github/skills/
+```
+
+---
+
+## Contributing
+
+Found a bug or have a feature request? Contributions welcome!
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/youtube-enhancement`
+3. Commit changes: `git commit -m "feat(youtube-summarizer): add feature X"`
+4. Push and create a Pull Request
+
+---
+
+## License
+
+MIT License - see LICENSE for details.
+
+---
+
+## Acknowledgments
+
+- **[youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api)** by [Julien Depoix](https://github.com/jdepoix) - Python library for extracting YouTube video transcripts
+- **Anthropic STAR/R-I-S-E frameworks** - For structured summarization
+
+---
+
+**Built with ❤️ by Eric Andrade**
+
+*Version 1.1.0 | Last updated: February 2026*