diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..87a83b0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,56 @@ +name: Bug Report +description: Report an error or issue in the guide +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting this issue! + + - type: dropdown + id: section + attributes: + label: Guide Section + description: Which section contains the error? + options: + - Getting Started + - Installation + - Configuration + - MCP Servers + - Tools & Commands + - Best Practices + - Security + - Agent Teams + - Advanced Topics + - Examples + - Other + validations: + required: true + + - type: textarea + id: description + attributes: + label: Description + description: What's the issue? + placeholder: "The guide says X but actually Y is correct" + validations: + required: true + + - type: textarea + id: location + attributes: + label: Location + description: Where in the guide is this issue? + placeholder: "Section 5.3, paragraph 2 OR guide/05-tools/mcp-servers.md line 42" + validations: + required: true + + - type: textarea + id: correction + attributes: + label: Suggested Correction + description: What should it say instead? + placeholder: "It should say..." + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..99999d5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,65 @@ +name: Feature Request +description: Suggest new content or improvements for the guide +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement! + + - type: dropdown + id: type + attributes: + label: Type + description: What kind of addition is this? + options: + - New section/chapter + - New example + - Expand existing section + - New best practice + - New MCP server documentation + - New tool documentation + - Tutorial/walkthrough + - Cheatsheet addition + - Other + validations: + required: true + + - type: textarea + id: topic + attributes: + label: Topic + description: What topic should be covered? + placeholder: "I'd like to see coverage of..." + validations: + required: true + + - type: textarea + id: rationale + attributes: + label: Why is this important? + description: What problem does this solve? Who would benefit? + placeholder: "This would help users who..." + validations: + required: true + + - type: textarea + id: outline + attributes: + label: Suggested Outline + description: What should this cover? (optional) + placeholder: | + - Key concept 1 + - Key concept 2 + - Example + validations: + required: false + + - type: textarea + id: resources + attributes: + label: Relevant Resources + description: Links to documentation, examples, or references + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..02aca06 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,52 @@ +name: Question +description: Ask about Claude Code usage or guide content +title: "[Question]: " +labels: ["question"] +body: + - type: markdown + attributes: + value: | + Before asking, please check: + - [The Guide](https://cc.bruniaux.com/) + - [Existing Issues](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/issues) + - [Official Docs](https://docs.claude.ai/) + + - type: dropdown + id: category + attributes: + label: Category + description: What's your question about? + options: + - Claude Code usage + - MCP servers + - Configuration + - Tools & commands + - Best practices + - Security + - Agent teams + - Installation + - Troubleshooting + - Guide content + - Other + validations: + required: true + + - type: textarea + id: question + attributes: + label: Question + description: What would you like to know? + placeholder: "How do I..." + validations: + required: true + + - type: textarea + id: context + attributes: + label: Context + description: What have you tried? What's your use case? + placeholder: | + I'm trying to... + I've looked at... + validations: + required: false diff --git a/docs/images/session-summary-v3.png b/docs/images/session-summary-v3.png new file mode 100644 index 0000000..8deab10 Binary files /dev/null and b/docs/images/session-summary-v3.png differ diff --git a/examples/skills/ccboard/.claude-plugin/plugin.json b/examples/skills/ccboard/.claude-plugin/plugin.json new file mode 100644 index 0000000..df76bbb --- /dev/null +++ b/examples/skills/ccboard/.claude-plugin/plugin.json @@ -0,0 +1,46 @@ +{ + "name": "ccboard", + "version": "0.1.0", + "description": "Comprehensive TUI/Web dashboard for Claude Code monitoring and management", + "author": "Florian Bruniaux", + "homepage": "https://github.com/FlorianBruniaux/ccboard", + "repository": "https://github.com/FlorianBruniaux/ccboard", + "license": "MIT OR Apache-2.0", + "requires": { + "binary": "ccboard", + "rustVersion": "1.70+", + "cargo": true + }, + "keywords": [ + "dashboard", + "monitoring", + "tui", + "mcp", + "sessions", + "costs", + "analytics", + "visualization" + ], + "categories": [ + "productivity", + "development-tools", + "monitoring" + ], + "commands": [ + "/dashboard", + "/mcp-status", + "/costs", + "/sessions", + "/ccboard-web", + "/ccboard-install" + ], + "features": [ + "8 interactive tabs (Dashboard, Sessions, Config, Hooks, Agents, Costs, History, MCP)", + "Real-time monitoring with file watcher", + "MCP server management and status detection", + "Cost tracking and analytics", + "Session exploration and search", + "File editing with $EDITOR integration", + "Dual interface: TUI (Ratatui) and Web (Axum)" + ] +} diff --git a/examples/skills/ccboard/README.md b/examples/skills/ccboard/README.md new file mode 100644 index 0000000..8ba6a12 --- /dev/null +++ b/examples/skills/ccboard/README.md @@ -0,0 +1,185 @@ +# ccboard - Claude Code Dashboard Plugin + +> Comprehensive TUI/Web dashboard for monitoring and managing Claude Code + +[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](../../LICENSE) +[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org) + +## Quick Start + +### Installation + +```bash +# Using Claude Code command +/ccboard-install + +# Or manually via cargo +cargo install ccboard +``` + +### Launch Dashboard + +```bash +# Launch TUI +/dashboard + +# Or run directly +ccboard +``` + +## Commands + +| Command | Description | +|---------|-------------| +| `/dashboard` | Launch interactive TUI dashboard | +| `/mcp-status` | Monitor MCP servers (press `8`) | +| `/costs` | View cost analytics (press `6`) | +| `/sessions` | Browse conversation history (press `2`) | +| `/ccboard-web` | Launch web interface | +| `/ccboard-install` | Install or update ccboard | + +## Features + +- **8 Interactive Tabs**: Dashboard, Sessions, Config, Hooks, Agents, Costs, History, MCP +- **Real-time Monitoring**: File watcher for live updates +- **MCP Management**: Server status and configuration +- **Cost Tracking**: Token usage and pricing analytics (e.g., $9,145 total) +- **Session Explorer**: Browse 1.2K+ conversations across 33+ projects +- **File Editing**: Press `e` to edit files in $EDITOR +- **Dual Interface**: Terminal (TUI) and Web UI from single binary + +## Navigation + +**Jump to Tab**: +- `1` Dashboard +- `2` Sessions +- `3` Config +- `4` Hooks +- `5` Agents +- `6` Costs +- `7` History +- `8` MCP + +**Common Keys**: +- `Tab` / `Shift+Tab` : Navigate tabs +- `e` : Edit file in editor +- `o` : Reveal file in finder +- `q` : Quit +- `F5` : Refresh + +## MCP Server Monitoring + +The MCP tab (press `8`) provides: + +- **Live Status**: ● Running, ○ Stopped, ? Unknown +- **Server Details**: Full command, args, environment variables +- **Quick Actions**: + - `e` : Edit `claude_desktop_config.json` + - `o` : Reveal config in finder + - `r` : Refresh server status + +## Cost Analytics + +Track your Claude Code spending: + +- Total tokens: 17.32M +- Total cost: $9,145.20 +- Breakdown by model: Opus 4.5 (76%), Sonnet 4.5 (14%) +- Cache hit rate: 99.9% + +## Session Explorer + +Browse and search conversations: + +- 1.2K+ sessions across 33+ projects +- Full-text search (press `/`) +- Metadata: timestamps, tokens, models +- Edit JSONL files directly + +## Web Interface + +```bash +# Launch web UI +/ccboard-web + +# Or with custom port +ccboard web --port 8080 + +# Run both TUI and Web +ccboard both --port 3333 +``` + +## Requirements + +- **Rust 1.70+** and Cargo +- **Claude Code** installed (reads from `~/.claude/`) + +## Architecture + +Single Rust binary (2.4MB) with: +- **TUI**: Ratatui-based terminal interface +- **Web**: Axum + Leptos web interface +- **Core**: Shared data layer with file watcher + +## Data Sources + +ccboard reads from: +- `~/.claude/stats-cache.json` - Statistics +- `~/.claude/claude_desktop_config.json` - MCP config +- `~/.claude/projects/*/` - Session JSONL files +- `.claude/settings.json` - Configuration + +**Read-only**: Non-invasive monitoring, safe to run with Claude Code. + +## Performance + +- Initial load: <2s for 1,000+ sessions +- Memory: ~50MB typical usage +- Lazy loading: Session content loaded on-demand + +## Limitations + +Current version (0.1.0): + +- **Read-only**: No write operations +- **MCP status**: Unix only (macOS/Linux) +- **Web UI**: In development + +## Troubleshooting + +### ccboard not found +```bash +which ccboard # Check if installed +/ccboard-install # Install if needed +``` + +### No data visible +```bash +ls ~/.claude/ # Verify Claude Code directory +cat ~/.claude/stats-cache.json # Check stats file +``` + +### MCP status "Unknown" +- Requires Unix (macOS/Linux) +- Windows shows "Unknown" by default +- Verify server running: `ps aux | grep ` + +## Documentation + +- **Full Guide**: See [SKILL.md](SKILL.md) for complete documentation +- **Commands**: See [commands/](commands/) directory +- **Scripts**: See [scripts/](scripts/) directory + +## Links + +- **Repository**: https://github.com/FlorianBruniaux/ccboard +- **Issues**: https://github.com/FlorianBruniaux/ccboard/issues +- **Claude Code**: https://claude.ai/code + +## License + +MIT OR Apache-2.0 + +--- + +**Made with ❤️ for the Claude Code community** diff --git a/examples/skills/ccboard/SKILL.md b/examples/skills/ccboard/SKILL.md new file mode 100644 index 0000000..43a5f74 --- /dev/null +++ b/examples/skills/ccboard/SKILL.md @@ -0,0 +1,398 @@ +--- +name: ccboard +description: Comprehensive TUI/Web dashboard for Claude Code monitoring +version: 0.1.0 +category: monitoring +keywords: [dashboard, tui, mcp, sessions, costs, analytics] +tags: [dashboard, tui, monitoring, claude-code, costs] +--- + +# ccboard - Claude Code Dashboard + +Comprehensive TUI/Web dashboard for monitoring and managing your Claude Code usage. + +## Overview + +ccboard provides a unified interface to visualize and explore all your Claude Code data: + +- **Sessions**: Browse all conversations across your projects +- **Statistics**: Real-time token usage, cache hit rates, activity trends +- **MCP Servers**: Monitor and manage Model Context Protocol servers +- **Costs**: Track spending with detailed token breakdown and pricing +- **Configuration**: View cascading settings (Global > Project > Local) +- **Hooks**: Explore pre/post execution hooks and automation +- **Agents**: Manage custom agents, commands, and skills +- **History**: Search across all messages with full-text search + +## Installation + +### Via Cargo (Recommended) + +```bash +# Using Claude Code command +/ccboard-install + +# Or manually +cargo install ccboard +``` + +### Requirements + +- Rust 1.70+ and Cargo +- Claude Code installed (reads from `~/.claude/`) + +## Commands + +| Command | Description | Shortcut | +|---------|-------------|----------| +| `/dashboard` | Launch TUI dashboard | `ccboard` | +| `/mcp-status` | Open MCP servers tab | Press `8` | +| `/costs` | Open costs analysis | Press `6` | +| `/sessions` | Browse sessions | Press `2` | +| `/ccboard-web` | Launch web UI | `ccboard web` | +| `/ccboard-install` | Install/update ccboard | - | + +## Features + +### 8 Interactive Tabs + +#### 1. Dashboard (Press `1`) +- Token usage statistics (17.32M total) +- Session count (1.2K tracked) +- Messages sent (327.7K) +- Cache hit ratio (99.9%) +- MCP server count (3 servers) +- 7-day activity sparkline +- Top 5 models usage gauges + +#### 2. Sessions (Press `2`) +- Dual-pane: Project tree (33 projects) + Session list (1.2K sessions) +- Metadata: timestamps, duration, tokens, models +- Search: Filter by project, message, or model (press `/`) +- File operations: `e` to edit JSONL, `o` to reveal in finder + +#### 3. Config (Press `3`) +- 4-column cascading view: Global | Project | Local | Merged +- Settings inheritance visualization +- MCP servers configuration +- Rules (CLAUDE.md) preview +- Permissions, hooks, environment variables +- Edit config with `e` key + +#### 4. Hooks (Press `4`) +- Event-based hook browsing (PreToolUse, UserPromptSubmit) +- Hook bash script preview +- Match patterns and conditions +- File path tracking for easy editing + +#### 5. Agents (Press `5`) +- 3 sub-tabs: Agents (12) | / Commands (5) | ★ Skills (0) +- Frontmatter metadata extraction +- File preview and editing +- Recursive directory scanning + +#### 6. Costs (Press `6`) +- 3 views: Overview | By Model | Daily Trend +- Token breakdown: input, output, cache read/write +- Pricing: $9,145.20 total estimated +- Model distribution: Opus 4.5 (76%), Sonnet 4.5 (14%) + +#### 7. History (Press `7`) +- Full-text search across 2,311 sessions +- Activity by hour histogram (24h) +- 7-day sparkline +- 297.9K messages searchable + +#### 8. MCP (Press `8`) **NEW** +- Dual-pane: Server list (35%) | Details (65%) +- Live status detection: ● Running, ○ Stopped, ? Unknown +- Full server details: command, args, environment vars +- Quick actions: `e` edit config, `o` reveal file, `r` refresh status + +### Navigation + +**Global Keys**: +- `1-8` : Jump to tab +- `Tab` / `Shift+Tab` : Navigate tabs +- `q` : Quit +- `F5` : Refresh data + +**Vim-style**: +- `h/j/k/l` : Navigate (left/down/up/right) +- `←/→/↑/↓` : Arrow alternatives + +**Common Actions**: +- `Enter` : View details / Focus pane +- `e` : Edit file in $EDITOR +- `o` : Reveal file in finder +- `/` : Search (in Sessions/History tabs) +- `Esc` : Close popup / Cancel + +### Real-time Monitoring + +ccboard includes a file watcher that monitors `~/.claude/` for changes: + +- **Stats updates**: Live refresh when `stats-cache.json` changes +- **Session updates**: New sessions appear automatically +- **Config updates**: Settings changes reflected in UI +- **500ms debounce**: Prevents excessive updates + +### File Editing + +Press `e` on any item to open in your preferred editor: + +- Uses `$VISUAL` > `$EDITOR` > platform default (nano/notepad) +- Supports: Sessions (JSONL), Config (JSON), Hooks (Shell), Agents (Markdown) +- Terminal state preserved (alternate screen mode) +- Cross-platform (macOS, Linux, Windows) + +### MCP Server Management + +The MCP tab provides comprehensive server monitoring: + +**Status Detection** (Unix): +- Checks running processes via `ps aux` +- Extracts package name from command +- Displays PID when running +- Windows shows "Unknown" status + +**Server Details**: +- Full command and arguments +- Environment variables with values +- Config file path (`~/.claude/claude_desktop_config.json`) +- Quick edit/reveal actions + +**Navigation**: +- `h/l` or `←/→` : Switch between list and details +- `j/k` or `↑/↓` : Select server +- `Enter` : Focus detail pane +- `e` : Edit MCP config +- `o` : Reveal config in finder +- `r` : Refresh server status + +## Usage Examples + +### Daily Monitoring + +```bash +# Launch dashboard +/dashboard + +# Check activity and costs +# Press '1' for overview +# Press '6' for costs breakdown +# Press '7' for recent history +``` + +### MCP Troubleshooting + +```bash +# Open MCP tab +/mcp-status + +# Or: ccboard then press '8' + +# Check server status (● green = running) +# Press 'e' to edit config if needed +# Press 'r' to refresh status after changes +``` + +### Session Analysis + +```bash +# Browse sessions +/sessions + +# Press '/' to search +# Filter by project: /aristote +# Filter by model: /opus +# Press 'e' on session to view full JSONL +``` + +### Cost Tracking + +```bash +# View costs +/costs + +# Press '1' for overview +# Press '2' for breakdown by model +# Press '3' for daily trend + +# Identify expensive sessions +# Track cache efficiency (99.9% hit rate) +``` + +## Web Interface + +Launch browser-based interface for remote monitoring: + +```bash +# Launch web UI +/ccboard-web + +# Or with custom port +ccboard web --port 8080 + +# Access at http://localhost:3333 +``` + +**Features**: +- Same data as TUI (shared backend) +- Server-Sent Events (SSE) for live updates +- Responsive design (desktop/tablet/mobile) +- Concurrent multi-user access + +**Run both simultaneously**: +```bash +ccboard both --port 3333 +``` + +## Architecture + +ccboard is a single Rust binary with dual frontends: + +``` +ccboard/ +├── ccboard-core/ # Parsers, models, data store, watcher +├── ccboard-tui/ # Ratatui frontend (8 tabs) +└── ccboard-web/ # Axum + Leptos frontend +``` + +**Data Sources**: +- `~/.claude/stats-cache.json` - Statistics +- `~/.claude/claude_desktop_config.json` - MCP config +- `~/.claude/projects/*/` - Session JSONL files +- `~/.claude/settings.json` - Global settings +- `.claude/settings.json` - Project settings +- `.claude/settings.local.json` - Local overrides +- `.claude/CLAUDE.md` - Rules and behavior + +## Troubleshooting + +### ccboard not found + +```bash +# Check installation +which ccboard + +# Install if needed +/ccboard-install +``` + +### No data visible + +```bash +# Verify Claude Code is installed +ls ~/.claude/ + +# Check stats file exists +cat ~/.claude/stats-cache.json + +# Run with specific project +ccboard --project ~/path/to/project +``` + +### MCP status shows "Unknown" + +- Status detection requires Unix (macOS/Linux) +- Windows shows "Unknown" by default +- Check if server process is actually running: `ps aux | grep ` + +### File watcher not working + +- Ensure `notify` crate supports your platform +- Check file permissions on `~/.claude/` +- Restart ccboard if file system events missed + +## Advanced Usage + +### Command-line Options + +```bash +ccboard --help # Show all options +ccboard --claude-home PATH # Custom Claude directory +ccboard --project PATH # Specific project +ccboard stats # Print stats and exit +ccboard web --port 8080 # Web UI on port 8080 +ccboard both # TUI + Web simultaneously +``` + +### Environment Variables + +```bash +# Editor preference +export EDITOR=vim +export VISUAL=code + +# Custom Claude home +export CLAUDE_HOME=~/custom/.claude +``` + +### Integration with Claude Code + +ccboard reads **read-only** from Claude Code directories: + +- Non-invasive monitoring +- No modifications to Claude data +- Safe to run concurrently with Claude Code +- File watcher detects changes in real-time + +## Performance + +- **Binary size**: 2.4MB (release build) +- **Initial load**: <2s for 1,000+ sessions +- **Memory**: ~50MB typical usage +- **CPU**: <5% during monitoring +- **Lazy loading**: Session content loaded on-demand + +## Limitations + +Current version (0.1.0): + +- **Read-only**: No write operations to Claude data +- **MCP status**: Unix only (Windows shows "Unknown") +- **Web UI**: In development (TUI is primary interface) +- **Search**: Basic substring matching (no fuzzy search yet) + +Future roadmap: + +- Enhanced MCP server management (start/stop) +- MCP protocol health checks +- Export reports (PDF, JSON, CSV) +- Config editing (write settings.json) +- Session resume integration +- Enhanced search with fuzzy matching + +## Contributing + +ccboard is open source (MIT OR Apache-2.0). + +Repository: https://github.com/FlorianBruniaux/ccboard + +Contributions welcome: +- Bug reports and feature requests +- Pull requests for new features +- Documentation improvements +- Platform-specific testing (Windows, Linux) + +## Credits + +Built with: +- [Ratatui](https://ratatui.rs/) - Terminal UI framework +- [Axum](https://github.com/tokio-rs/axum) - Web framework +- [Leptos](https://leptos.dev/) - Reactive frontend +- [Notify](https://github.com/notify-rs/notify) - File watcher +- [Serde](https://serde.rs/) - Serialization + +## License + +MIT OR Apache-2.0 + +--- + +**Questions?** + +- GitHub Issues: https://github.com/FlorianBruniaux/ccboard/issues +- Documentation: https://github.com/FlorianBruniaux/ccboard +- Claude Code: https://claude.ai/code diff --git a/examples/skills/ccboard/commands/costs.md b/examples/skills/ccboard/commands/costs.md new file mode 100644 index 0000000..324a03b --- /dev/null +++ b/examples/skills/ccboard/commands/costs.md @@ -0,0 +1,84 @@ +--- +name: costs +description: Open ccboard costs analysis tab +category: analytics +--- + +# Costs Analysis Command + +Launch ccboard and jump directly to the costs tracking and analytics tab. + +## Features + +- **3 Views**: + - Overview: Total costs and breakdown + - By Model: Cost per AI model (Opus, Sonnet, Haiku) + - Daily Trend: Cost evolution over time + +- **Token Breakdown**: + - Input tokens (prompt) + - Output tokens (generation) + - Cache read tokens (reused) + - Cache write tokens (stored) + +- **Pricing**: Automatic calculation based on 2024 Anthropic rates + +## Usage + +```bash +# Open costs tab directly +/costs + +# Alternative: run with tab argument +ccboard --tab costs +``` + +## Costs Tab Navigation + +- `1` : Overview view +- `2` : By Model view +- `3` : Daily Trend view +- `Tab` : Switch between views +- `↑/↓` : Scroll through data + +## Example Output + +``` +Total Tokens: 17.32M +Total Cost: $9,145.20 + +Breakdown by Model: +- Opus 4.5: 76% ($7,828) ████████████████ +- Sonnet 4.5: 14% ($1,314) ███ +- Haiku 3.5: 10% ($3) █ + +Token Distribution: +- Input: 10.70M (65%) +- Output: 4.58M (28%) +- Cache Read: 1.01M (6%) +- Cache Write: 1.04B (1%) +``` + +## Requirements + +ccboard must be installed. Run `/ccboard-install` if needed. + +## Implementation + +```bash +#!/bin/bash + +# Check if ccboard is installed +if ! command -v ccboard &> /dev/null; then + echo "❌ ccboard is not installed" + echo "Run: /ccboard-install" + exit 1 +fi + +# Launch ccboard with Costs tab (tab index 5, accessible with '6' key) +# For now, launch and user presses '6' +exec ccboard +``` + +**Note**: Currently launches ccboard in dashboard view. Press `6` to access Costs tab. +Future version will support `ccboard --tab costs` for direct access. diff --git a/examples/skills/ccboard/commands/dashboard.md b/examples/skills/ccboard/commands/dashboard.md new file mode 100644 index 0000000..f95f0d7 --- /dev/null +++ b/examples/skills/ccboard/commands/dashboard.md @@ -0,0 +1,65 @@ +--- +name: dashboard +description: Launch ccboard TUI dashboard +category: monitoring +--- + +# Dashboard Command + +Launch the interactive ccboard TUI to visualize and monitor your Claude Code usage. + +## Features + +- **8 Interactive Tabs**: Dashboard, Sessions, Config, Hooks, Agents, Costs, History, MCP +- **Real-time Monitoring**: File watcher for live updates +- **MCP Management**: Server status and configuration +- **Cost Tracking**: Token usage and pricing analytics +- **Session Explorer**: Browse and search conversation history +- **File Editing**: Press `e` to edit files in $EDITOR + +## Usage + +```bash +# Launch TUI dashboard +/dashboard + +# Alternative: run directly +ccboard +``` + +## Navigation + +- `1-8` : Jump to specific tab +- `Tab` / `Shift+Tab` : Navigate tabs +- `q` : Quit +- `F5` : Refresh data +- `e` : Edit selected file +- `o` : Reveal file in finder + +## Requirements + +ccboard must be installed. If not installed, run: +```bash +/ccboard-install +``` + +## Implementation + +```bash +#!/bin/bash + +# Check if ccboard is installed +if ! command -v ccboard &> /dev/null; then + echo "❌ ccboard is not installed" + echo "" + echo "Install with:" + echo " /ccboard-install" + echo "" + echo "Or manually:" + echo " cargo install ccboard" + exit 1 +fi + +# Launch ccboard TUI +exec ccboard +``` diff --git a/examples/skills/ccboard/commands/install.md b/examples/skills/ccboard/commands/install.md new file mode 100644 index 0000000..d8aab26 --- /dev/null +++ b/examples/skills/ccboard/commands/install.md @@ -0,0 +1,110 @@ +--- +name: ccboard-install +description: Install or update ccboard +category: setup +--- + +# Install ccboard Command + +Install or update the ccboard binary via cargo. + +## What is ccboard? + +ccboard is a comprehensive TUI/Web dashboard for monitoring and managing Claude Code: + +- **8 Interactive Tabs**: Dashboard, Sessions, Config, Hooks, Agents, Costs, History, MCP +- **Real-time Monitoring**: File watcher for live updates +- **MCP Management**: Server status and configuration +- **Cost Analytics**: Token usage and pricing tracking +- **Session Explorer**: Browse and search conversation history +- **Dual Interface**: Terminal (TUI) and Web UI + +## Requirements + +- **Rust**: Version 1.70 or higher +- **Cargo**: Rust package manager (comes with Rust) + +If Rust is not installed: +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +## Usage + +```bash +# Install ccboard +/ccboard-install + +# Or manually +cargo install ccboard +``` + +## Installation Process + +1. Checks if cargo is installed +2. Detects existing ccboard installation +3. Prompts for update confirmation if already installed +4. Installs via `cargo install ccboard --force` +5. Verifies installation and shows version + +## After Installation + +Once installed, use these commands: + +- `/dashboard` - Launch TUI dashboard +- `/mcp-status` - Open MCP servers tab +- `/costs` - Open costs analysis +- `/sessions` - Browse sessions history +- `/ccboard-web` - Launch web interface + +Or run directly: +```bash +ccboard # Launch TUI +ccboard web # Launch web UI +ccboard --help # Show all options +``` + +## Troubleshooting + +### Cargo not found +```bash +# Install Rust and cargo +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + +# Reload shell +source $HOME/.cargo/env +``` + +### Installation fails +```bash +# Update Rust toolchain +rustup update + +# Try manual installation from source +git clone https://github.com/FlorianBruniaux/ccboard +cd ccboard +cargo install --path crates/ccboard +``` + +### Permission denied +```bash +# Ensure ~/.cargo/bin is in PATH +echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + +## Implementation + +```bash +#!/bin/bash + +# Run installation script +exec "$(dirname "$0")/../scripts/install-ccboard.sh" +``` + +## Uninstallation + +To remove ccboard: +```bash +cargo uninstall ccboard +``` diff --git a/examples/skills/ccboard/commands/mcp-status.md b/examples/skills/ccboard/commands/mcp-status.md new file mode 100644 index 0000000..35bd93c --- /dev/null +++ b/examples/skills/ccboard/commands/mcp-status.md @@ -0,0 +1,68 @@ +--- +name: mcp-status +description: Open ccboard MCP servers tab +category: monitoring +--- + +# MCP Status Command + +Launch ccboard and jump directly to the MCP servers management tab. + +## Features + +- **Server List**: All configured MCP servers from `claude_desktop_config.json` +- **Status Detection**: Live status (● Running, ○ Stopped, ? Unknown) +- **Server Details**: Full command, arguments, environment variables +- **Quick Actions**: + - `e` : Edit MCP configuration + - `o` : Reveal config in finder + - `r` : Refresh server status + +## Usage + +```bash +# Open MCP tab directly +/mcp-status + +# Alternative: run with tab argument +ccboard --tab mcp +``` + +## MCP Tab Navigation + +- `h/j/k/l` or `←/→/↑/↓` : Navigate +- `Enter` : Focus detail pane +- `e` : Edit `~/.claude/claude_desktop_config.json` +- `o` : Reveal config file +- `r` : Refresh server status + +## Server Status + +- **● Green** : Server process is running +- **○ Red** : Server process is stopped +- **? Gray** : Status unknown (Windows or detection failed) + +## Requirements + +ccboard must be installed. Run `/ccboard-install` if needed. + +## Implementation + +```bash +#!/bin/bash + +# Check if ccboard is installed +if ! command -v ccboard &> /dev/null; then + echo "❌ ccboard is not installed" + echo "Run: /ccboard-install" + exit 1 +fi + +# Launch ccboard with MCP tab (tab index 7, accessible with '8' key) +# For now, launch and user presses '8' +# TODO: Add --tab flag to ccboard CLI in future version +exec ccboard +``` + +**Note**: Currently launches ccboard in dashboard view. Press `8` to access MCP tab. +Future version will support `ccboard --tab mcp` for direct access. diff --git a/examples/skills/ccboard/commands/sessions.md b/examples/skills/ccboard/commands/sessions.md new file mode 100644 index 0000000..4e2cc67 --- /dev/null +++ b/examples/skills/ccboard/commands/sessions.md @@ -0,0 +1,90 @@ +--- +name: sessions +description: Browse Claude Code sessions history +category: exploration +--- + +# Sessions Browser Command + +Launch ccboard and jump directly to the sessions exploration tab. + +## Features + +- **Project Tree**: Navigate 33+ projects with nested structure +- **Session List**: 1.2K+ sessions with metadata +- **Search**: Filter sessions by project, message, or model (press `/`) +- **Session Details**: + - Timestamps (start, end, duration) + - Token usage breakdown + - Models used + - First message preview +- **File Operations**: + - `e` : Open session JSONL in editor + - `o` : Reveal session file in finder + +## Usage + +```bash +# Open sessions tab directly +/sessions + +# Alternative: run with tab argument +ccboard --tab sessions +``` + +## Sessions Tab Navigation + +- `←/→` : Switch between project tree and session list +- `↑/↓` : Navigate items +- `Enter` : View session details +- `/` : Open search input +- `e` : Edit selected session JSONL file +- `o` : Reveal session file + +## Session Metadata + +Each session shows: +- **ID**: Unique session identifier +- **Started**: First message timestamp +- **Duration**: Total conversation time +- **Messages**: Message count +- **Tokens**: Total tokens used +- **Models**: AI models used (e.g., opus-4.5, sonnet-4.5) +- **Preview**: First user message (200 chars) + +## Search Examples + +``` +# Search by project name +/aristote + +# Search by model +/opus + +# Search by message content +/implement feature +``` + +## Requirements + +ccboard must be installed. Run `/ccboard-install` if needed. + +## Implementation + +```bash +#!/bin/bash + +# Check if ccboard is installed +if ! command -v ccboard &> /dev/null; then + echo "❌ ccboard is not installed" + echo "Run: /ccboard-install" + exit 1 +fi + +# Launch ccboard with Sessions tab (tab index 1, accessible with '2' key) +# For now, launch and user presses '2' +exec ccboard +``` + +**Note**: Currently launches ccboard in dashboard view. Press `2` to access Sessions tab. +Future version will support `ccboard --tab sessions` for direct access. diff --git a/examples/skills/ccboard/commands/web.md b/examples/skills/ccboard/commands/web.md new file mode 100644 index 0000000..e74a899 --- /dev/null +++ b/examples/skills/ccboard/commands/web.md @@ -0,0 +1,94 @@ +--- +name: ccboard-web +description: Launch ccboard web interface +category: monitoring +--- + +# Web Interface Command + +Launch the ccboard web UI for browser-based monitoring and visualization. + +## Features + +- **Web Dashboard**: Access ccboard from any browser +- **Live Updates**: Server-Sent Events (SSE) for real-time data +- **Responsive Design**: Works on desktop, tablet, mobile +- **Same Data**: Shares data layer with TUI (single binary) +- **Concurrent Access**: Multiple users can view simultaneously + +## Usage + +```bash +# Launch web UI on default port 3333 +/ccboard-web + +# Or specify custom port +ccboard web --port 8080 +``` + +## Access + +Once launched, open in your browser: +``` +http://localhost:3333 +``` + +## Modes + +ccboard supports 3 execution modes: + +1. **TUI only** (default): + ```bash + ccboard + ``` + +2. **Web only**: + ```bash + ccboard web --port 3333 + ``` + +3. **Both simultaneously**: + ```bash + ccboard both --port 3333 + ``` + Runs TUI in terminal + web server on port 3333 + +## Web UI Features + +- Dashboard with real-time stats +- Sessions browser with pagination +- Configuration viewer (read-only) +- Hooks, agents, costs visualization +- MCP server status +- History and search + +## Requirements + +ccboard must be installed. Run `/ccboard-install` if needed. + +## Implementation + +```bash +#!/bin/bash + +# Check if ccboard is installed +if ! command -v ccboard &> /dev/null; then + echo "❌ ccboard is not installed" + echo "Run: /ccboard-install" + exit 1 +fi + +# Default port +PORT="${1:-3333}" + +echo "🌐 Launching ccboard web interface..." +echo "Access at: http://localhost:$PORT" +echo "" +echo "Press Ctrl+C to stop" +echo "" + +# Launch web UI +exec ccboard web --port "$PORT" +``` + +**Note**: Web UI is currently in development. TUI is the primary interface with full feature set. diff --git a/examples/skills/ccboard/scripts/check-install.sh b/examples/skills/ccboard/scripts/check-install.sh new file mode 100755 index 0000000..ef08d03 --- /dev/null +++ b/examples/skills/ccboard/scripts/check-install.sh @@ -0,0 +1,38 @@ +#!/bin/bash +# Check if ccboard is installed and return status + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +echo "🔍 Checking ccboard installation..." +echo "" + +# Check if ccboard is in PATH +if command -v ccboard &> /dev/null; then + CCBOARD_PATH=$(which ccboard) + CCBOARD_VERSION=$(ccboard --version 2>&1 | head -n1 || echo "unknown") + + echo -e "${GREEN}✅ ccboard is installed${NC}" + echo " Location: $CCBOARD_PATH" + echo " Version: $CCBOARD_VERSION" + echo "" + echo "Run with:" + echo " ccboard # Launch TUI" + echo " ccboard web # Launch web UI" + echo " ccboard --help # Show all options" + exit 0 +else + echo -e "${RED}❌ ccboard is not installed${NC}" + echo "" + echo "Install with:" + echo " cargo install ccboard" + echo "" + echo "Or use Claude Code command:" + echo " /ccboard-install" + exit 1 +fi diff --git a/examples/skills/ccboard/scripts/install-ccboard.sh b/examples/skills/ccboard/scripts/install-ccboard.sh new file mode 100755 index 0000000..e1a4714 --- /dev/null +++ b/examples/skills/ccboard/scripts/install-ccboard.sh @@ -0,0 +1,85 @@ +#!/bin/bash +# Install ccboard via cargo + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +CYAN='\033[0;36m' +NC='\033[0m' # No Color + +echo -e "${CYAN}📦 ccboard Installation${NC}" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "" + +# Check if cargo is installed +if ! command -v cargo &> /dev/null; then + echo -e "${RED}❌ Error: cargo is not installed${NC}" + echo "" + echo "Install Rust and cargo from: https://rustup.rs" + echo "" + echo "Run:" + echo " curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh" + exit 1 +fi + +echo -e "${GREEN}✅ cargo found${NC}" +echo "" + +# Check if ccboard is already installed +if command -v ccboard &> /dev/null; then + CURRENT_VERSION=$(ccboard --version 2>&1 | head -n1 || echo "unknown") + echo -e "${YELLOW}⚠️ ccboard is already installed: $CURRENT_VERSION${NC}" + echo "" + read -p "Do you want to update to the latest version? (y/N) " -n 1 -r + echo "" + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "Installation cancelled." + exit 0 + fi + echo "" +fi + +# Install ccboard +echo -e "${CYAN}Installing ccboard...${NC}" +echo "" + +if cargo install ccboard --force; then + echo "" + echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo -e "${GREEN}✅ ccboard installed successfully!${NC}" + echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo "" + + # Get installed version + INSTALLED_VERSION=$(ccboard --version 2>&1 | head -n1 || echo "unknown") + echo "Version: $INSTALLED_VERSION" + echo "Location: $(which ccboard)" + echo "" + + echo "Quick start:" + echo " ccboard # Launch TUI dashboard" + echo " ccboard web # Launch web interface" + echo " ccboard --help # Show all options" + echo "" + echo "Or use Claude Code commands:" + echo " /dashboard # Launch TUI" + echo " /mcp-status # Open MCP tab" + echo " /costs # Open costs analysis" +else + echo "" + echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo -e "${RED}❌ Installation failed${NC}" + echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo "" + echo "Troubleshooting:" + echo " 1. Ensure cargo is up to date: rustup update" + echo " 2. Check network connection" + echo " 3. Try manual installation from source:" + echo " git clone https://github.com/FlorianBruniaux/ccboard" + echo " cd ccboard" + echo " cargo install --path crates/ccboard" + exit 1 +fi diff --git a/examples/skills/guide-recap/SKILL.md b/examples/skills/guide-recap/SKILL.md new file mode 100644 index 0000000..85910a1 --- /dev/null +++ b/examples/skills/guide-recap/SKILL.md @@ -0,0 +1,217 @@ +--- +name: guide-recap +description: Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Newsletter, Slack) in FR + EN. Use after releases or weekly to generate ready-to-post content from guide updates. +argument-hint: " [--interactive] [--format=linkedin|twitter|newsletter|slack] [--lang=fr|en] [--save]" +--- + +# Guide Recap + +Generate social media content from CHANGELOG.md entries. Produces 8 outputs by default (4 formats x 2 languages). + +## When to Use + +- After running `/release` to create social announcements +- Weekly to summarize multiple releases +- Before posting on LinkedIn, Twitter/X, newsletter, or Slack + +## Usage + +``` +/guide-recap latest # Latest released version +/guide-recap v3.20.5 # Specific version +/guide-recap week # Current week (Monday to today) +/guide-recap week 2026-01-27 # Specific week (Monday to Sunday) +``` + +### Flags + +| Flag | Effect | Default | +|------|--------|---------| +| `--interactive` | Guide mode: choose angle, audience, highlight | Off (auto-draft) | +| `--format=X` | Single format: `linkedin`, `twitter`, `newsletter`, `slack` | All 4 formats | +| `--lang=X` | Single language: `fr`, `en` | Both FR + EN | +| `--save` | Save output to `claudedocs/social-posts/` | Display only | +| `--force` | Generate even if only maintenance entries | Skip low-score | + +## Workflow (7 Steps) + +### Step 1: Parse Input + +Parse `$ARGUMENTS` to determine mode: + +| Input | Mode | Target | +|-------|------|--------| +| `latest` | Single version | First `## [X.Y.Z]` after `[Unreleased]` | +| `vX.Y.Z` or `X.Y.Z` | Single version | Exact version match | +| `week` | Week range | Monday of current week -> today | +| `week YYYY-MM-DD` | Week range | That Monday -> following Sunday | + +If no argument or invalid argument, display usage and exit. + +### Step 2: Extract CHANGELOG Entries + +Read `CHANGELOG.md` from the project root. + +**Single version:** +1. Find line matching `## [{version}]` +2. Extract all content until next `## [` line +3. Parse `### Added`, `### Changed`, `### Fixed` sections + +**Week range:** +1. Collect all `## [X.Y.Z] - YYYY-MM-DD` entries where date falls in range +2. Parse all sections from all matching versions + +**Error: version not found** -> List last 5 versions, suggest `latest`. +**Error: week has no entries** -> Show date of last release, suggest that version. + +### Step 3: Categorize Entries + +For each top-level entry (first-level bullet under `###`), assign a category: + +| Category | Weight | Detection | +|----------|--------|-----------| +| `NEW_CONTENT` | 3 | New files, new sections, new diagrams, new quiz questions | +| `GROWTH_METRIC` | 2 | Line count growth, item count changes | +| `RESEARCH` | 1 | Resource evaluations, external source integrations | +| `FIX` | 1 | Under `### Fixed`, corrections | +| `MAINTENANCE` | 0 | README updates, badge syncs, landing syncs, count updates | + +See `references/changelog-parsing-rules.md` for detailed classification rules. + +### Step 4: Transform to User Value + +Apply mappings from `references/content-transformation.md`: + +- Technical language -> user benefit +- Extract concrete numbers +- Credit named sources +- Cluster related entries + +Validate against `references/tone-guidelines.md` DO/DON'T checklist. + +### Step 4b: Interactive Mode (--interactive only) + +If `--interactive` flag is set, insert between steps 4 and 5: + +1. Display candidate highlights with scores: + ``` + Highlights (by score): + [14] 4 new ASCII diagrams (16 -> 20) [NEW_CONTENT] + [ 9] 30 new quiz questions (227 -> 257) [NEW_CONTENT] + [ 6] Docker sandbox isolation guide [NEW_CONTENT] + [ 1] README updated [MAINTENANCE] + ``` + +2. Ask angle: + - Auto (highest scored = hook) + - User picks specific entry as hook + - Custom angle (user provides theme) + +3. Ask target audience: + - `devs` (technical depth) + - `tech-leads` (impact focus) + - `general` (accessible language) + - `all` (default, balanced) + +4. Ask primary highlight: + - Auto (top score) + - User selects from list + +5. Confirm selection and proceed to step 5. + +### Step 5: Score and Select + +Compute score for each entry: + +``` +score = (category_weight * 3) + + (has_number * 2) + + (named_source * 1) + + (new_file * 1) + + (min(impact_files, 3)) + + (breaking * 2) +``` + +Select top 3-4 entries by score. Highest score = hook line. + +**If all scores < 3**: Output "No social content recommended for this version. Use `--force` to generate anyway." and exit (unless `--force`). + +### Step 6: Generate Content + +For each requested format (default: all 4) and language (default: both): + +1. Read the corresponding template from `assets/` +2. Fill template fields using scored and transformed entries +3. Apply tone-guidelines.md quality checklist + +**Links:** + +| Format | Link Target | +|--------|-------------| +| LinkedIn | Landing site URL | +| Twitter | GitHub repo URL | +| Newsletter | Both (landing + GitHub) | +| Slack | GitHub repo URL | + +**URLs:** +- Landing: `https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/` +- GitHub: `https://github.com/FlorianBruniaux/claude-code-ultimate-guide` + +### Step 7: Output + +Display each generated post in a fenced code block, labeled by format and language: + +``` +## LinkedIn (FR) + +```text +[content] +`` ` + +## LinkedIn (EN) + +```text +[content] +`` ` + +## Twitter/X (FR) + +```text +[content] +`` ` + +... +``` + +If `--save` flag: write all outputs to `claudedocs/social-posts/YYYY-MM-DD-vX.Y.Z.md` (for version) or `claudedocs/social-posts/YYYY-MM-DD-week.md` (for week). Create `claudedocs/social-posts/` directory if it doesn't exist. + +## Error Handling + +| Error | Response | +|-------|----------| +| No argument | Display usage block | +| Invalid argument | Display usage block with examples | +| Version not found | List 5 most recent versions, suggest `latest` | +| Week has no entries | Show date of last release, suggest version | +| All entries MAINTENANCE (score 0) | "No social content recommended. Use `--force` to override." | +| CHANGELOG.md not found | "CHANGELOG.md not found in project root." | + +## Reference Files + +- `references/tone-guidelines.md` - DO/DON'T rules, emoji budget, language register +- `references/changelog-parsing-rules.md` - CHANGELOG format, extraction, scoring algorithm +- `references/content-transformation.md` - Technical -> user value mappings (30+) +- `assets/linkedin-template.md` - ~1300 chars, hook + bullets + CTA + hashtags +- `assets/twitter-template.md` - 280 chars single or 2-3 tweet thread +- `assets/newsletter-template.md` - ~500 words, structured sections +- `assets/slack-template.md` - Compact, emoji-rich, Slack formatting +- `examples/version-output.md` - Full example output for v3.20.5 +- `examples/week-output.md` - Full example output for week 2026-01-27 + +## Tips + +- Run `/guide-recap latest` right after `/release` to prepare social posts +- Use `--interactive` the first few times to understand the scoring +- Use `--format=linkedin --lang=fr` when you only need one specific output +- `--save` outputs are gitignored via `claudedocs/` convention +- Review and personalize before posting (these are drafts, not final copy) diff --git a/examples/skills/guide-recap/assets/linkedin-template.md b/examples/skills/guide-recap/assets/linkedin-template.md new file mode 100644 index 0000000..7852ab6 --- /dev/null +++ b/examples/skills/guide-recap/assets/linkedin-template.md @@ -0,0 +1,101 @@ +# LinkedIn Template + +Target: ~1300 characters. Structure: hook + context + bullets + CTA + hashtags. + +## FR Template + +``` +{hook_line_fr} + +{context_line_fr} + +{bullet_1_fr} +{bullet_2_fr} +{bullet_3_fr} + +{cta_fr} + +#ClaudeCode #CodingWithAI #DeveloperTools +``` + +## EN Template + +``` +{hook_line_en} + +{context_line_en} + +{bullet_1_en} +{bullet_2_en} +{bullet_3_en} + +{cta_en} + +#ClaudeCode #CodingWithAI #DeveloperTools +``` + +## Field Rules + +### hook_line (1 line, max 150 chars) + +The highest-scored highlight, transformed to user value. May include 0-1 emoji. + +| Pattern | FR Example | EN Example | +|---------|------------|------------| +| Number-led | `30 nouvelles questions quiz pour tester vos connaissances Claude Code` | `30 new quiz questions to test your Claude Code knowledge` | +| Question | `Vous apprenez mieux en visuel ? 4 nouveaux diagrammes ASCII` | `Visual learner? 4 new ASCII diagrams just added` | +| Source-led | `Pat Cullen partage son workflow de code review multi-agent` | `Pat Cullen shares his multi-agent code review workflow` | + +### context_line (1-2 lines, max 200 chars) + +Version reference + what changed at a high level. + +``` +FR: "Guide v3.20.5 - mise a jour de la reference visuelle." +EN: "Guide v3.20.5 - visual reference update." +``` + +For week mode: +``` +FR: "N releases cette semaine dans le Claude Code Ultimate Guide." +EN: "N releases this week in the Claude Code Ultimate Guide." +``` + +### bullets (3 items, each max 200 chars) + +Top 3 highlights by score. Each starts with a relevant emoji (max 1 per bullet). + +``` +FR: +- [emoji] [Transformed highlight in vous-form] +- [emoji] [Transformed highlight in vous-form] +- [emoji] [Transformed highlight in vous-form] + +EN: +- [emoji] [Transformed highlight, direct "you" address] +- [emoji] [Transformed highlight, direct "you" address] +- [emoji] [Transformed highlight, direct "you" address] +``` + +### cta (1 line, max 150 chars) + +Soft value statement or genuine question. Links to landing site. + +``` +FR: "Guide complet disponible en open source : {landing_url}" +EN: "Full guide available open source: {landing_url}" +``` + +### hashtags (1 line, exactly 3) + +Fixed: `#ClaudeCode #CodingWithAI #DeveloperTools` + +Add 1 topic-specific tag if clearly relevant: `#CodeReview`, `#Security`, `#TDD` + +## Constraints + +- Total post: 1100-1500 characters +- Emoji budget: 3-4 total (0-1 hook, 1 per bullet, 0-1 CTA) +- No hype words (see tone-guidelines.md) +- FR: vouvoiement +- EN: American English diff --git a/examples/skills/guide-recap/assets/newsletter-template.md b/examples/skills/guide-recap/assets/newsletter-template.md new file mode 100644 index 0000000..3d8f53e --- /dev/null +++ b/examples/skills/guide-recap/assets/newsletter-template.md @@ -0,0 +1,124 @@ +# Newsletter Template + +Target: ~500 words. Structured sections with depth. + +## FR Template + +```markdown +# {title_fr} + +{intro_paragraph_fr} + +## Ce qui a change + +{highlights_section_fr} + +## En detail + +{detail_section_fr} + +## A retenir + +{takeaway_fr} + +--- + +[Guide complet]({landing_url}) | [GitHub]({github_url}) +``` + +## EN Template + +```markdown +# {title_en} + +{intro_paragraph_en} + +## What changed + +{highlights_section_en} + +## In detail + +{detail_section_en} + +## Key takeaway + +{takeaway_en} + +--- + +[Full guide]({landing_url}) | [GitHub]({github_url}) +``` + +## Field Rules + +### title (max 80 chars) + +Version or week framing, descriptive. + +``` +FR: "Guide v3.20.5 : Reference visuelle enrichie" +EN: "Guide v3.20.5: Enhanced Visual Reference" + +FR: "Semaine du 27 janvier : 4 releases, 9 patterns avances" +EN: "Week of January 27: 4 releases, 9 advanced patterns" +``` + +### intro_paragraph (2-3 sentences, max 150 words) + +What happened and why it matters. No hype. + +``` +FR: "La version 3.20.5 du Claude Code Ultimate Guide ajoute 4 nouveaux +diagrammes ASCII a la reference visuelle. Le guide contient maintenant +20 diagrammes couvrant TDD, securite et workflows d'apprentissage." + +EN: "Version 3.20.5 of the Claude Code Ultimate Guide adds 4 new ASCII +diagrams to the visual reference. The guide now contains 20 diagrams +covering TDD, security, and learning workflows." +``` + +### highlights_section (bullet list, 3-5 items) + +Top scored entries, transformed. Each bullet: 1-2 sentences max. + +``` +FR: +- **Cycle TDD Red-Green-Refactor** : Diagramme du flux iteratif test-code-refactor +- **Protocole UVAL** : Visualisation du framework Comprendre-Verifier-Appliquer-Apprendre +- **Defense securite 3 couches** : Prevention, detection, reponse avec guide d'adoption +- **Timeline d'exposition de secrets** : Actions d'urgence par fenetre temporelle (15min/1h/24h) + +EN: +- **TDD Red-Green-Refactor Cycle**: Diagram of the iterative test-code-refactor flow +- **UVAL Protocol Flow**: Visualization of the Understand-Verify-Apply-Learn framework +- **Security 3-Layer Defense**: Prevention, detection, response with adoption guide +- **Secret Exposure Timeline**: Emergency actions by time window (15min/1h/24h) +``` + +### detail_section (1-2 paragraphs, max 200 words) + +Expand on the most interesting highlight. Provide context, explain what the user gains. +Credit sources if applicable. + +### takeaway (1-2 sentences) + +Single actionable insight or summary. + +``` +FR: "Si vous apprenez mieux en visuel, les 20 diagrammes du guide couvrent +maintenant les workflows les plus frequents, de TDD a la gestion d'incidents." + +EN: "If you're a visual learner, the guide's 20 diagrams now cover the most +common workflows, from TDD to incident management." +``` + +## Constraints + +- Total: 400-600 words +- Emoji budget: 2-3 (section headers only) +- No hype words +- FR: vouvoiement +- EN: American English +- Both links (landing + GitHub) in footer +- Credit all named sources diff --git a/examples/skills/guide-recap/assets/slack-template.md b/examples/skills/guide-recap/assets/slack-template.md new file mode 100644 index 0000000..f41769a --- /dev/null +++ b/examples/skills/guide-recap/assets/slack-template.md @@ -0,0 +1,86 @@ +# Slack Template + +Compact, scannable, emoji-rich. Ready to paste. + +## FR Template + +``` +:newspaper: *{title_fr}* + +{highlights_fr} + +:link: {link} +``` + +## EN Template + +``` +:newspaper: *{title_en}* + +{highlights_en} + +:link: {link} +``` + +## Field Rules + +### title (max 60 chars) + +``` +FR: "Guide v3.20.5 - Reference visuelle" +EN: "Guide v3.20.5 - Visual reference" + +FR: "Recap semaine : 4 releases" +EN: "Week recap: 4 releases" +``` + +### highlights (3-5 lines) + +Each line: Slack emoji + short description. No bold in bullet text. + +``` +FR: +:art: 4 nouveaux diagrammes ASCII (TDD, UVAL, securite, incidents) +:brain: 30 nouvelles questions quiz (257 total) +:shield: Guide sandbox isolation Docker +:mag: 9 patterns avances identifies via claudelog.com + +EN: +:art: 4 new ASCII diagrams (TDD, UVAL, security, incidents) +:brain: 30 new quiz questions (257 total) +:shield: Docker sandbox isolation guide +:mag: 9 advanced patterns identified via claudelog.com +``` + +### link + +GitHub repo URL. + +## Slack Emoji Reference + +Use standard Slack emojis that render in all workspaces: + +| Emoji | Code | Use For | +|-------|------|---------| +| :newspaper: | `:newspaper:` | Title marker | +| :art: | `:art:` | Visual content, diagrams, UI | +| :brain: | `:brain:` | Quiz, learning, knowledge | +| :shield: | `:shield:` | Security content | +| :mag: | `:mag:` | Research, analysis, competitive intel | +| :wrench: | `:wrench:` | Tools, workflows, configuration | +| :books: | `:books:` | New guides, documentation | +| :chart_with_upwards_trend: | `:chart_with_upwards_trend:` | Growth metrics | +| :white_check_mark: | `:white_check_mark:` | Fixes, corrections | +| :link: | `:link:` | Link marker | +| :arrow_right: | `:arrow_right:` | Growth indicator (X -> Y) | + +## Constraints + +- Max 500 characters total +- Emoji budget: 4-6 (1 title + 1 per highlight + 1 link) +- No hype words +- FR: tutoiement +- EN: American English +- Single link (GitHub) +- No hashtags (not a Slack convention) +- Use Slack formatting: `*bold*`, `_italic_`, `:emoji:` codes diff --git a/examples/skills/guide-recap/assets/twitter-template.md b/examples/skills/guide-recap/assets/twitter-template.md new file mode 100644 index 0000000..d6bfb8f --- /dev/null +++ b/examples/skills/guide-recap/assets/twitter-template.md @@ -0,0 +1,145 @@ +# Twitter/X Template + +Two modes: single tweet (280 chars) or thread (2-3 tweets). + +## Single Tweet + +Use when: 1-2 highlights, simple version update. + +### FR Template + +``` +{hook_line_fr} + +{highlight_fr} + +{link} +``` + +### EN Template + +``` +{hook_line_en} + +{highlight_en} + +{link} +``` + +### Rules + +- Max 280 characters total (including link) +- Max 2 emojis +- Link to GitHub repo +- FR: tutoiement +- EN: direct address + +## Thread (2-3 tweets) + +Use when: 3+ highlights, rich version/week. + +### FR Template + +``` +Tweet 1/N: +{hook_line_fr} + +{context_fr} + +Thread [down_arrow] + +--- + +Tweet 2/N: +{highlight_1_fr} +{highlight_2_fr} + +--- + +Tweet 3/N (optional): +{highlight_3_fr} + +{cta_fr} +{link} +``` + +### EN Template + +``` +Tweet 1/N: +{hook_line_en} + +{context_en} + +Thread [down_arrow] + +--- + +Tweet 2/N: +{highlight_1_en} +{highlight_2_en} + +--- + +Tweet 3/N (optional): +{highlight_3_en} + +{cta_en} +{link} +``` + +## Field Rules + +### hook_line (max 100 chars) + +Shortest form of top highlight. Must fit in first tweet with context. + +| Pattern | FR | EN | +|---------|-----|-----| +| Number-led | `30 nouvelles questions quiz Claude Code` | `30 new Claude Code quiz questions` | +| Direct | `Nouveau guide : sandbox isolation Docker` | `New guide: Docker sandbox isolation` | + +### context (max 80 chars) + +``` +FR: "Guide v3.20.5 vient de sortir" +EN: "Guide v3.20.5 just dropped" +``` + +### highlights (max 120 chars each) + +Transformed entries, one per line. No bullet points (use line breaks). + +``` +FR: "4 diagrammes ASCII pour TDD, UVAL, securite" +EN: "4 ASCII diagrams for TDD, UVAL, security" +``` + +### cta (max 60 chars) + +``` +FR: "Tout est open source" +EN: "All open source" +``` + +### link + +GitHub repo URL. Counts toward 280 char limit (23 chars for t.co). + +## Decision: Single vs Thread + +| Condition | Format | +|-----------|--------| +| 1-2 highlights, all fit in 280 chars | Single tweet | +| 3+ highlights or rich content | Thread (2-3 tweets) | +| Week with multiple versions | Thread | +| Only maintenance changes | Single tweet (or skip) | + +## Constraints + +- Each tweet: max 280 characters +- Emoji budget: 2 total across thread +- No hype words +- FR: tutoiement +- EN: American English +- Thread max: 3 tweets (not 5+) diff --git a/examples/skills/guide-recap/examples/version-output.md b/examples/skills/guide-recap/examples/version-output.md new file mode 100644 index 0000000..5806be3 --- /dev/null +++ b/examples/skills/guide-recap/examples/version-output.md @@ -0,0 +1,145 @@ +# Example: /guide-recap v3.20.5 + +Input: `/guide-recap v3.20.5` + +## Scoring + +| Entry | Category | Score | Breakdown | +|-------|----------|-------|-----------| +| 4 new ASCII diagrams (16 -> 20) | NEW_CONTENT | 14 | (3*3)+(1*2)+(0*1)+(1*1)+(2)+(0*2) = 14 | +| README: Added Visual Reference to table | MAINTENANCE | 1 | (0*3)+(0*2)+(0*1)+(0*1)+(1)+(0*2) = 1 | + +Selected highlights: #1 only (1 entry above threshold). +Hook line: "4 new ASCII diagrams (16 -> 20)" + +## Output + +### LinkedIn (FR) + +```text +4 nouveaux diagrammes ASCII dans le guide Claude Code (16 -> 20 au total) + +Guide v3.20.5 - La reference visuelle s'enrichit. + +- Cycle TDD Red-Green-Refactor : le flux iteratif test-code-refactor en un coup d'oeil +- Protocole UVAL : le framework Comprendre-Verifier-Appliquer-Apprendre visualise +- Defense securite 3 couches : prevention, detection, reponse avec parcours d'adoption par taille d'equipe +- Timeline d'exposition de secrets : actions d'urgence par fenetre (15min/1h/24h) + +Guide complet disponible en open source : https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/ + +#ClaudeCode #CodingWithAI #DeveloperTools +``` + +### LinkedIn (EN) + +```text +4 new ASCII diagrams in the Claude Code guide (16 -> 20 total) + +Guide v3.20.5 - Visual reference update. + +- TDD Red-Green-Refactor Cycle: the iterative test-code-refactor flow at a glance +- UVAL Protocol Flow: the Understand-Verify-Apply-Learn framework visualized +- Security 3-Layer Defense: prevention, detection, response with adoption path by team size +- Secret Exposure Timeline: emergency actions by time window (15min/1h/24h) + +Full guide available open source: https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/ + +#ClaudeCode #CodingWithAI #DeveloperTools +``` + +### Twitter/X (FR) + +```text +4 nouveaux diagrammes ASCII dans le guide Claude Code + +TDD, UVAL, securite 3 couches, timeline incidents - reference visuelle v3.20.5 + +https://github.com/FlorianBruniaux/claude-code-ultimate-guide +``` + +### Twitter/X (EN) + +```text +4 new ASCII diagrams added to the Claude Code guide + +TDD, UVAL, 3-layer security, incident timeline - visual reference v3.20.5 + +https://github.com/FlorianBruniaux/claude-code-ultimate-guide +``` + +### Newsletter (FR) + +```markdown +# Guide v3.20.5 : Reference visuelle enrichie + +La version 3.20.5 du Claude Code Ultimate Guide ajoute 4 nouveaux diagrammes ASCII a la reference visuelle. Le guide contient maintenant 20 diagrammes couvrant TDD, securite et workflows d'apprentissage. + +## Ce qui a change + +- **Cycle TDD Red-Green-Refactor** : Diagramme du flux iteratif test-code-refactor, montrant la boucle cyclique entre ecriture du test, code minimal et refactoring +- **Protocole UVAL** : Visualisation du framework Comprendre-Verifier-Appliquer-Apprendre avec les chemins de retour en cas d'echec +- **Defense securite 3 couches** : Vue d'ensemble Prevention/Detection/Reponse avec parcours d'adoption selon la taille de l'equipe +- **Timeline d'exposition de secrets** : Actions d'urgence par fenetre temporelle (15min/1h/24h) avec guide de severite + +## En detail + +Les 4 nouveaux diagrammes (#17-#20) couvrent des workflows que le guide documentait deja en texte, mais qui beneficient d'une representation visuelle pour une comprehension rapide. Le diagramme TDD est le plus demande : il montre la boucle Red-Green-Refactor comme un cycle continu, pas comme des etapes lineaires. Le diagramme UVAL est le premier a montrer les chemins de retour en cas d'echec a chaque etape du framework d'apprentissage. + +## A retenir + +Si vous apprenez mieux en visuel, les 20 diagrammes du guide couvrent maintenant les workflows les plus frequents, de TDD a la gestion d'incidents securite. + +--- + +[Guide complet](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) | [GitHub](https://github.com/FlorianBruniaux/claude-code-ultimate-guide) +``` + +### Newsletter (EN) + +```markdown +# Guide v3.20.5: Enhanced Visual Reference + +Version 3.20.5 of the Claude Code Ultimate Guide adds 4 new ASCII diagrams to the visual reference. The guide now contains 20 diagrams covering TDD, security, and learning workflows. + +## What changed + +- **TDD Red-Green-Refactor Cycle**: Diagram of the iterative test-code-refactor flow, showing the cyclic loop between writing tests, minimal code, and refactoring +- **UVAL Protocol Flow**: Visualization of the Understand-Verify-Apply-Learn framework with failure backtrack paths +- **Security 3-Layer Defense**: Prevention/Detection/Response overview with adoption path by team size +- **Secret Exposure Timeline**: Emergency actions by time window (15min/1h/24h) with severity guide + +## In detail + +The 4 new diagrams (#17-#20) cover workflows the guide already documented in text, but that benefit from visual representation for quick comprehension. The TDD diagram is the most requested: it shows the Red-Green-Refactor loop as a continuous cycle, not linear steps. The UVAL diagram is the first to show failure backtrack paths at each step of the learning framework. + +## Key takeaway + +If you're a visual learner, the guide's 20 diagrams now cover the most common workflows, from TDD to security incident management. + +--- + +[Full guide](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) | [GitHub](https://github.com/FlorianBruniaux/claude-code-ultimate-guide) +``` + +### Slack (FR) + +```text +:newspaper: *Guide v3.20.5 - Reference visuelle* + +:art: 4 nouveaux diagrammes ASCII (TDD, UVAL, securite, incidents) +:arrow_right: 16 -> 20 diagrammes au total + +:link: https://github.com/FlorianBruniaux/claude-code-ultimate-guide +``` + +### Slack (EN) + +```text +:newspaper: *Guide v3.20.5 - Visual reference* + +:art: 4 new ASCII diagrams (TDD, UVAL, security, incidents) +:arrow_right: 16 -> 20 diagrams total + +:link: https://github.com/FlorianBruniaux/claude-code-ultimate-guide +``` diff --git a/examples/skills/guide-recap/examples/week-output.md b/examples/skills/guide-recap/examples/week-output.md new file mode 100644 index 0000000..7d813f4 --- /dev/null +++ b/examples/skills/guide-recap/examples/week-output.md @@ -0,0 +1,203 @@ +# Example: /guide-recap week 2026-01-27 + +Input: `/guide-recap week 2026-01-27` + +Date range: 2026-01-27 (Monday) to 2026-02-02 (Sunday) + +## Versions in Range + +| Version | Date | Entries | +|---------|------|---------| +| 3.20.5 | 2026-01-31 | 2 entries | +| 3.20.4 | 2026-01-31 | 3 entries | +| 3.20.3 | 2026-01-31 | 5 entries | +| 3.20.2 | 2026-01-31 | 4 entries | +| 3.20.1 | 2026-01-30 | 2 entries | +| 3.20.0 | 2026-01-30 | 5 entries | + +**6 releases this week.** + +## Scoring (Top Entries) + +| Entry | Version | Category | Score | +|-------|---------|----------|-------| +| 9 Gaps from claudelog.com (9 new patterns) | 3.20.3 | NEW_CONTENT | 15 | +| 30 New Quiz Questions (227 -> 257) | 3.20.4 | NEW_CONTENT | 14 | +| 4 new ASCII diagrams (16 -> 20) | 3.20.5 | NEW_CONTENT | 14 | +| Multi-Agent PR Review (Pat Cullen) | 3.20.0 | NEW_CONTENT | 13 | +| Docker sandbox isolation | 3.20.2 | NEW_CONTENT | 11 | +| Contribution Metrics (Anthropic blog) | 3.20.2 | RESEARCH | 8 | + +Selected: top 4 (scores 15, 14, 14, 13). + +## Output + +### LinkedIn (FR) + +```text +6 releases cette semaine dans le Claude Code Ultimate Guide + +Semaine du 27 janvier : la plus grosse semaine de contenu depuis le lancement du guide. + +- 9 patterns avances identifies via claudelog.com : Permutation Frameworks, Split-Role Agents, Mechanic Stacking et 6 autres +- 30 nouvelles questions quiz (257 au total) couvrant 11 categories +- 4 nouveaux diagrammes ASCII pour TDD, UVAL, securite et incidents +- Workflow de code review multi-agent base sur le travail de Pat Cullen : 3 agents specialises, regles anti-hallucination, classification de severite + +Guide complet en open source : https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/ + +#ClaudeCode #CodingWithAI #DeveloperTools +``` + +### LinkedIn (EN) + +```text +6 releases this week in the Claude Code Ultimate Guide + +Week of January 27: the biggest content week since the guide launched. + +- 9 advanced patterns identified via claudelog.com: Permutation Frameworks, Split-Role Agents, Mechanic Stacking and 6 more +- 30 new quiz questions (257 total) across 11 categories +- 4 new ASCII diagrams for TDD, UVAL, security, and incidents +- Multi-agent code review workflow based on Pat Cullen's work: 3 specialized agents, anti-hallucination rules, severity classification + +Full guide available open source: https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/ + +#ClaudeCode #CodingWithAI #DeveloperTools +``` + +### Twitter/X (FR) + +```text +Tweet 1/3: +6 releases cette semaine dans le Claude Code Ultimate Guide + +La plus grosse semaine de contenu du guide + +--- + +Tweet 2/3: +9 patterns avances (Permutation Frameworks, Split-Role Agents...) +30 nouvelles questions quiz (257 total) +4 diagrammes ASCII (TDD, UVAL, securite) + +--- + +Tweet 3/3: +Code review multi-agent (Pat Cullen) +Sandbox isolation Docker +Metriques Anthropic : +67% PRs/jour + +https://github.com/FlorianBruniaux/claude-code-ultimate-guide +``` + +### Twitter/X (EN) + +```text +Tweet 1/3: +6 releases this week in the Claude Code Ultimate Guide + +Biggest content week since the guide launched + +--- + +Tweet 2/3: +9 advanced patterns (Permutation Frameworks, Split-Role Agents...) +30 new quiz questions (257 total) +4 ASCII diagrams (TDD, UVAL, security) + +--- + +Tweet 3/3: +Multi-agent code review (Pat Cullen) +Docker sandbox isolation +Anthropic metrics: +67% PRs/day + +https://github.com/FlorianBruniaux/claude-code-ultimate-guide +``` + +### Newsletter (FR) + +```markdown +# Semaine du 27 janvier : 6 releases, 9 patterns avances + +La semaine du 27 janvier a ete la plus dense du Claude Code Ultimate Guide avec 6 releases. Voici les changements les plus significatifs. + +## Ce qui a change + +- **9 patterns avances (claudelog.com)** : Analyse systematique de 313 pages communautaires. Nouveaux patterns : Permutation Frameworks, Split-Role Agents, Mechanic Stacking, Rev the Engine, Task Lists as Diagnostic, "You Are the Main Thread" +- **30 nouvelles questions quiz** : 257 questions au total, couvrant 11 categories dont Advanced Patterns (+8), MCP Servers (+3), Architecture (+3) +- **4 diagrammes ASCII** : TDD Red-Green-Refactor, UVAL Protocol, Defense securite 3 couches, Timeline d'exposition de secrets +- **Code review multi-agent** : Workflow de production de Pat Cullen avec 3 agents specialises (Consistency, SOLID, Defensive Code), regles anti-hallucination et boucle de convergence + +## En detail + +Le travail de veille contre claudelog.com a permis d'identifier 9 gaps dans le guide. Le pattern Permutation Frameworks est le plus interessant : il propose une approche systematique pour tester des variations d'architecture (REST vs GraphQL vs tRPC) en utilisant CLAUDE.md comme driver. Mechanic Stacking combine 5 couches d'intelligence (Plan Mode, Extended Thinking, Rev, Split-Role, Permutation) avec une matrice de decision selon l'impact. + +Le workflow de code review de Pat Cullen apporte des safeguards anti-hallucination concrets : verification des patterns avec Grep/Glob avant toute recommandation, regle d'occurrence (>10 = etabli, 3-10 = emergent, <3 = non etabli), et lecture du contexte complet. + +## A retenir + +Cette semaine marque un tournant vers les patterns avances et la qualite de code. Si vous utilisez Claude Code pour des reviews, le workflow multi-agent merite d'etre explore. + +--- + +[Guide complet](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) | [GitHub](https://github.com/FlorianBruniaux/claude-code-ultimate-guide) +``` + +### Newsletter (EN) + +```markdown +# Week of January 27: 6 Releases, 9 Advanced Patterns + +The week of January 27 was the densest week for the Claude Code Ultimate Guide with 6 releases. Here are the most significant changes. + +## What changed + +- **9 advanced patterns (claudelog.com)**: Systematic analysis of 313 community pages. New patterns: Permutation Frameworks, Split-Role Agents, Mechanic Stacking, Rev the Engine, Task Lists as Diagnostic, "You Are the Main Thread" +- **30 new quiz questions**: 257 total, covering 11 categories including Advanced Patterns (+8), MCP Servers (+3), Architecture (+3) +- **4 ASCII diagrams**: TDD Red-Green-Refactor, UVAL Protocol, Security 3-Layer Defense, Secret Exposure Timeline +- **Multi-agent code review**: Pat Cullen's production workflow with 3 specialized agents (Consistency, SOLID, Defensive Code), anti-hallucination rules, and convergence loop + +## In detail + +The competitive analysis against claudelog.com identified 9 gaps in the guide. The Permutation Frameworks pattern is the most interesting: it proposes a systematic approach to testing architecture variations (REST vs GraphQL vs tRPC) using CLAUDE.md as a driver. Mechanic Stacking combines 5 intelligence layers (Plan Mode, Extended Thinking, Rev, Split-Role, Permutation) with a decision matrix based on impact level. + +Pat Cullen's code review workflow brings concrete anti-hallucination safeguards: pattern verification with Grep/Glob before any recommendation, occurrence rule (>10 = established, 3-10 = emerging, <3 = not established), and full file context reading. + +## Key takeaway + +This week marks a shift toward advanced patterns and code quality. If you use Claude Code for reviews, the multi-agent workflow is worth exploring. + +--- + +[Full guide](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) | [GitHub](https://github.com/FlorianBruniaux/claude-code-ultimate-guide) +``` + +### Slack (FR) + +```text +:newspaper: *Recap semaine : 6 releases (27 jan - 31 jan)* + +:mag: 9 patterns avances via claudelog.com (Permutation Frameworks, Split-Role Agents...) +:brain: 30 nouvelles questions quiz (257 total) +:art: 4 diagrammes ASCII (TDD, UVAL, securite, incidents) +:wrench: Code review multi-agent (Pat Cullen) : 3 agents, anti-hallucination, convergence +:shield: Guide sandbox isolation Docker + +:link: https://github.com/FlorianBruniaux/claude-code-ultimate-guide +``` + +### Slack (EN) + +```text +:newspaper: *Week recap: 6 releases (Jan 27 - Jan 31)* + +:mag: 9 advanced patterns via claudelog.com (Permutation Frameworks, Split-Role Agents...) +:brain: 30 new quiz questions (257 total) +:art: 4 ASCII diagrams (TDD, UVAL, security, incidents) +:wrench: Multi-agent code review (Pat Cullen): 3 agents, anti-hallucination, convergence +:shield: Docker sandbox isolation guide + +:link: https://github.com/FlorianBruniaux/claude-code-ultimate-guide +``` diff --git a/examples/skills/guide-recap/references/changelog-parsing-rules.md b/examples/skills/guide-recap/references/changelog-parsing-rules.md new file mode 100644 index 0000000..91932bc --- /dev/null +++ b/examples/skills/guide-recap/references/changelog-parsing-rules.md @@ -0,0 +1,142 @@ +# CHANGELOG Parsing Rules + +How to extract and categorize entries from `CHANGELOG.md` for social content generation. + +## CHANGELOG Format + +The project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +``` +## [Unreleased] + +## [X.Y.Z] - YYYY-MM-DD + +### Added +- **Title**: Description + - Sub-detail 1 + - Sub-detail 2 + +### Changed +- **Title**: Description + +### Fixed +- **Title**: Description + +--- +(horizontal rule separates grouped entries within same version) +``` + +## Extraction Methods + +### By Version (`/guide-recap v3.20.5`) + +1. Read CHANGELOG.md +2. Find line matching `## [3.20.5]` +3. Extract everything until next `## [` line +4. Parse all `### Added/Changed/Fixed` sections + +### Latest (`/guide-recap latest`) + +1. Read CHANGELOG.md +2. Skip `## [Unreleased]` +3. Extract first `## [X.Y.Z]` block (= latest released version) + +### By Week (`/guide-recap week` or `/guide-recap week 2026-01-27`) + +1. Determine date range: + - `week` with no date: Monday of current week -> today + - `week YYYY-MM-DD`: That Monday -> following Sunday +2. Read CHANGELOG.md +3. Collect all `## [X.Y.Z] - YYYY-MM-DD` entries where date falls in range +4. Aggregate all entries across versions + +## Entry Structure + +Each top-level bullet under `### Added/Changed/Fixed` is one **entry**. Parse: + +| Field | Source | Example | +|-------|--------|---------| +| `title` | Bold text after `- **` | `Visual Reference` | +| `description` | Text after `:` or `--` on same line | `4 new high-value ASCII diagrams (16 -> 20 total)` | +| `sub_items` | Indented bullets below | List of detail lines | +| `section` | Parent `###` header | `Added`, `Changed`, `Fixed` | +| `files` | Filenames/paths in description | `guide/ultimate-guide.md`, `machine-readable/reference.yaml` | +| `source` | URLs or named references | `Pat Cullen's Final Review Gist` | +| `metrics` | Numbers in description | `227 -> 257`, `+522 lines`, `4 new` | +| `score` | Evaluation score if present | `Score: 4/5` | + +## Category Classification + +Each entry gets exactly one category with a weight: + +| Category | Weight | Pattern | +|----------|--------|---------| +| `NEW_CONTENT` | 3 | New guide sections, new files, new diagrams, new quiz questions | +| `GROWTH_METRIC` | 2 | Line count increases, template counts, quiz count changes | +| `RESEARCH` | 1 | Resource evaluations, external source integrations | +| `FIX` | 1 | Bug fixes, corrections, accuracy improvements | +| `MAINTENANCE` | 0 | README updates, badge updates, count syncs, landing syncs | + +### Classification Rules + +1. If entry creates a new `.md` file or new section -> `NEW_CONTENT` +2. If entry contains `-> ` with numbers (growth) -> `GROWTH_METRIC` +3. If entry references external source with evaluation score -> `RESEARCH` +4. If entry is under `### Fixed` -> `FIX` +5. If entry only updates counts, badges, or sync -> `MAINTENANCE` +6. If entry has sub-items with substantial content -> upgrade one level +7. When ambiguous, prefer higher-weight category + +### Examples + +``` +"4 new ASCII diagrams (16 -> 20)" -> NEW_CONTENT (new diagrams) +"30 New Quiz Questions (227 -> 257)" -> NEW_CONTENT (new questions) +"Quiz badge updated (227 -> 257)" -> MAINTENANCE (badge sync) +"Guide line count: 15,771 -> 16,293" -> GROWTH_METRIC (growth) +"Score: 4/5 - Docker Sandboxes" -> RESEARCH (evaluation) +"Fixed 14 -> 15 categories in landing" -> FIX (correction) +"README.md: Added Visual Reference to table" -> MAINTENANCE (nav update) +``` + +## Scoring Algorithm + +For each entry, compute: + +``` +score = (category_weight * 3) + + (has_number * 2) + + (named_source * 1) + + (new_file * 1) + + (min(impact_files, 3)) + + (breaking * 2) +``` + +| Factor | Value | Detection | +|--------|-------|-----------| +| `category_weight` | 0-3 | From category table above | +| `has_number` | 0 or 1 | Entry contains numeric change (`N -> M`, `+N lines`, `N new`) | +| `named_source` | 0 or 1 | Entry credits a person or external source | +| `new_file` | 0 or 1 | Entry mentions creating a new file (`NEW`, new `.md`) | +| `impact_files` | 0-3 | Count of distinct files mentioned (capped at 3) | +| `breaking` | 0 or 1 | Entry is under `### Breaking` or mentions breaking change | + +### Score Interpretation + +| Score | Action | +|-------|--------| +| 10+ | Lead highlight (hook line) | +| 6-9 | Secondary highlight (bullet point) | +| 3-5 | Include if space allows | +| 0-2 | Skip (maintenance noise) | + +Select top 3-4 entries by score. If all scores < 3, flag as "no social content recommended." + +## Week Aggregation Rules + +When generating for a week with multiple versions: + +1. Score all entries across all versions in the date range +2. De-duplicate: if same topic appears in multiple versions, keep highest-scored one +3. Prefix week output with version count: `X releases this week` +4. Use date range in header, not individual version numbers diff --git a/examples/skills/guide-recap/references/content-transformation.md b/examples/skills/guide-recap/references/content-transformation.md new file mode 100644 index 0000000..b7d58a0 --- /dev/null +++ b/examples/skills/guide-recap/references/content-transformation.md @@ -0,0 +1,139 @@ +# Content Transformation + +Maps technical CHANGELOG language to user-facing social value. Apply tone-guidelines.md rules to all outputs. + +## Transformation Principle + +``` +Technical fact (CHANGELOG) -> User benefit (social post) +``` + +Never invent benefits. Every transformation must trace back to a concrete CHANGELOG line. + +## Mapping Table + +### New Content + +| Technical (CHANGELOG) | Social (User Value) | +|---|---| +| `N new ASCII diagrams (X -> Y total)` | `Visual learner? N new diagrams for [topics]` | +| `N New Quiz Questions (X -> Y total)` | `Test your Claude Code knowledge: N new questions covering [top categories]` | +| `New [guide-name].md (N lines)` | `New guide: [topic in plain language]` | +| `New section: [Section Name] (~N lines)` | `[What you can now learn/do]: [plain description]` | +| `New workflow: [name]` | `Step-by-step: how to [action] with Claude Code` | +| `Enhanced [command/agent] (+N lines)` | `[Command] now supports [new capability]` | +| `N new entries in reference.yaml` | Skip (internal indexing, no user value) | + +### Research & Sources + +| Technical (CHANGELOG) | Social (User Value) | +|---|---| +| `Score: 5/5 - [Source]` | `Critical finding from [Author]: [key insight]` | +| `Score: 4/5 - [Source]` | `From [Author]'s research: [practical takeaway]` | +| `Score: 3/5 - [Source]` | `[Author] confirms: [relevant finding]` | +| `Source: [URL] ([Author], [Date])` | `Based on [Author]'s work` | +| `Competitive Analysis: N Gaps from [source]` | `N advanced patterns identified: [top 2-3 names]` | +| `Resource evaluation: [file]` | Skip (internal process, not user-facing) | +| `Fact-checked: N/N claims verified` | Can mention as credibility signal: `All N claims verified` | + +### Growth Metrics + +| Technical (CHANGELOG) | Social (User Value) | +|---|---| +| `Guide line count: X -> Y (+N lines)` | `+N lines of documentation added this [week/version]` | +| `X -> Y total [items]` | `Now Y [items] (was X)` | +| `+N lines: X -> Y` | `[Feature] expanded with N lines of [content type]` | + +### Fixes & Changes + +| Technical (CHANGELOG) | Social (User Value) | +|---|---| +| `Fixed [technical issue]` | `Corrected: [what users see fixed]` | +| `[File]: Updated [field] (X -> Y)` | Skip unless user-visible change | +| `Landing synced` | Skip (infrastructure) | +| `Badge updated` | Skip (infrastructure) | + +### Maintenance (Usually Skip) + +| Technical (CHANGELOG) | Social Value | +|---|---| +| `README.md: Added [X] to table` | Skip | +| `Updated counts in [files]` | Skip | +| `Sync: [description]` | Skip | +| `reference.yaml: +N entries` | Skip | +| `CLAUDE.md: [update]` | Skip | + +## Pattern Recognition + +### Numbers to Highlight + +When an entry contains numeric changes, extract and format: + +``` +"30 New Quiz Questions (227 -> 257)" +-> number: 30 +-> growth: "227 -> 257" +-> highlight: "30 new questions" or "now 257 questions" + +"4 new ASCII diagrams (16 -> 20 total)" +-> number: 4 +-> growth: "16 -> 20" +-> highlight: "4 new diagrams" or "now 20 diagrams" + +"+522 lines" +-> number: 522 +-> highlight: "+522 lines of new content" +``` + +### Named Sources to Credit + +Extract author names and give proper attribution: + +``` +"Pat Cullen's Final Review Gist" -> "From Pat Cullen's production workflow" +"Addy Osmani's 80% Problem" -> "Based on Addy Osmani's research" +"Shen & Tamkin RCT" -> "From Shen & Tamkin's study (Anthropic)" +"claudelog.com (InventorBlack)" -> "Identified via claudelog.com community" +"Jude Gao (Vercel)" -> "From Vercel's benchmarks (Jude Gao)" +``` + +### Topic Clustering + +When multiple entries share a theme, cluster them: + +``` +Entries about code review: +- "Multi-Agent PR Review" +- "Enhanced /review-pr command" +- "Enhanced code-reviewer agent" +-> Cluster: "Code review overhaul: multi-agent workflow, anti-hallucination rules, severity classification" + +Entries about security: +- "Docker sandbox isolation" +- "Security 3-Layer Defense diagram" +- "Secret Exposure Timeline diagram" +-> Cluster: "Security focus: sandbox isolation, defense layers, incident response timeline" +``` + +## Version vs Week Framing + +### Single Version + +``` +FR: "Claude Code Ultimate Guide v3.20.5" +EN: "Claude Code Ultimate Guide v3.20.5" +``` + +### Week (Multiple Versions) + +``` +FR: "Cette semaine dans le guide (N releases)" +EN: "This week in the guide (N releases)" +``` + +### Week (Single Version) + +``` +FR: "Cette semaine : guide v3.20.5" +EN: "This week: guide v3.20.5" +``` diff --git a/examples/skills/guide-recap/references/tone-guidelines.md b/examples/skills/guide-recap/references/tone-guidelines.md new file mode 100644 index 0000000..60387fc --- /dev/null +++ b/examples/skills/guide-recap/references/tone-guidelines.md @@ -0,0 +1,77 @@ +# Tone Guidelines + +Rules for social content generated from CHANGELOG entries. Central principle: **engagement through value, not hype**. + +## DO / DON'T Checklist + +### DO + +- Use concrete numbers from the CHANGELOG (`227 -> 257`, `+522 lines`, `4 new diagrams`) +- State what the user can do now (`Test your knowledge`, `New visual guide for...`) +- Ask genuine questions (`Visual learner?`, `How do you review PRs?`) +- Credit named sources (`Based on Pat Cullen's workflow`, `From Addy Osmani's research`) +- Use precise action verbs (`added`, `integrated`, `documented`, `evaluated`) +- Reference specific patterns by name (`Permutation Frameworks`, `Split-Role Agents`) + +### DON'T + +- Use hype words: `game-changer`, `revolutionary`, `incredible`, `amazing`, `must-have` +- Use FOMO: `You're missing out`, `Don't fall behind`, `Everyone is using this` +- Use fake urgency: `Act now`, `Limited time`, `Before it's too late` +- Use clickbait hooks: `This ONE trick`, `You won't believe`, `Hidden feature` +- Invent metrics: `10x faster`, `saves hours`, `boosts productivity by 300%` +- Use more than 3-4 emojis per LinkedIn post, 2 per tweet +- Over-promise: `The only guide you'll ever need`, `Complete mastery` + +## Language Rules + +### French (FR) + +| Format | Register | Example | +|--------|----------|---------| +| LinkedIn | Vouvoiement | `Vous utilisez Claude Code au quotidien ?` | +| Newsletter | Vouvoiement | `Vous trouverez dans cette version...` | +| Twitter/X | Tutoiement | `Tu connais les Permutation Frameworks ?` | +| Slack | Tutoiement | `Nouvelle version dispo, check ca` | + +### English (EN) + +- Direct address (`you`) in all formats +- American English spelling (`optimize`, `analyze`, not `optimise`, `analyse`) +- No British idioms or spellings + +## Emoji Budget + +| Format | Max Emojis | Placement | +|--------|-----------|-----------| +| LinkedIn | 3-4 | Hook line (0-1), bullets (1 each, max 3), CTA (0-1) | +| Twitter | 2 | Hook (1), key point (1) | +| Newsletter | 2-3 | Section headers only | +| Slack | 4-6 | Status markers, emphasis | + +Allowed emojis: `+`, `->`, technical symbols preferred over decorative ones. +Avoid: fire, rocket, explosion, 100, mind-blown (marketing cliches). + +## CTA Rules + +| Format | CTA Style | Link Target | +|--------|-----------|-------------| +| LinkedIn | Soft question or value statement | Landing site URL | +| Twitter | Short action or link | GitHub repo | +| Newsletter | Explicit link with context | Landing site URL | +| Slack | Direct link | GitHub repo | + +No `Click here`, `Check this out`, `Link in bio` patterns. + +## Quality Checklist (Pre-Output) + +Before outputting any social content, verify: + +1. [ ] Every number comes from the actual CHANGELOG entry +2. [ ] No hype words (grep against DON'T list) +3. [ ] Emoji count within budget +4. [ ] FR register matches format (vous/tu) +5. [ ] EN uses American spelling +6. [ ] CTA links to correct target +7. [ ] Named sources credited when used +8. [ ] No invented metrics or percentages diff --git a/examples/skills/landing-page-generator/SKILL.md b/examples/skills/landing-page-generator/SKILL.md new file mode 100644 index 0000000..8a8d0f2 --- /dev/null +++ b/examples/skills/landing-page-generator/SKILL.md @@ -0,0 +1,238 @@ +--- +name: landing-page-generator +description: Generate complete landing pages from repositories. Analyzes README, features, and structure to create static sites following established patterns. Use for new project landings, open-source showcases, documentation portals. +tags: [landing-page, static-site, github-pages, marketing] +--- + +# Landing Page Generator + +Generate a complete, deploy-ready landing page from any repository by analyzing its documentation and structure. + +## When to Use This Skill + +- Creating a landing page for a GitHub repository +- Generating static sites from existing documentation +- Standardizing landing pages across multiple projects +- Converting README content to marketing/showcase pages + +## What This Skill Does + +1. **Analyze Repository**: Read README.md, CHANGELOG.md, package.json/VERSION, docs/, assets/ +2. **Extract Content**: Identify title, tagline, features, installation, screenshots +3. **Map to Sections**: Hero, Features, Install, FAQ, Footer (+ optional: Risk Banner, Pricing) +4. **Generate Landing**: Create complete static site (HTML + CSS + JS) +5. **Deploy-Ready Output**: Include GitHub Actions workflow for GitHub Pages + +## How to Use + +### Basic Usage + +``` +/landing-page-generator from ~/path/to/repo +``` + +### With Options + +``` +/landing-page-generator from ~/path/to/repo --risk-banner --pricing-table +``` + +### Available Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--risk-banner` | Add prominent warning/disclaimer banner above fold | false | +| `--pricing-table` | Include pricing comparison section | false | +| `--screenshots ` | Path to screenshots folder | ./assets/ | +| `--theme [dark\|light]` | Color theme variant | dark | +| `--search` | Enable Cmd+K search | true | +| `--output ` | Output directory | ./[repo-name]-landing/ | + +## Workflow + +### Step 1: Repository Analysis + +Read and analyze these files from the source repo: + +``` +README.md → Primary content source (title, tagline, features, install) +CHANGELOG.md → Version info, recent changes +package.json → Version number, dependencies, metadata +VERSION → Alternative version source +docs/ → Additional documentation pages +assets/ → Screenshots, images +LICENSE → License type for badge +``` + +### Step 2: Content Extraction Map + +| Source | Target Section | Extraction Method | +|--------|---------------|-------------------| +| README title/badges | Hero | First H1 + shield.io badge lines | +| README TL;DR | Hero tagline | First paragraph or blockquote after title | +| README features | Features grid | H2/H3 sections with bullet lists | +| README install | Quick Start | Code blocks with shell commands | +| README usage | Examples | Code blocks with examples | +| README FAQ | FAQ | Details/summary or H3+P patterns | +| CHANGELOG | What's New | Latest 1-3 releases | +| assets/*.png | Screenshots | Gallery section | + +### Step 3: Section Generation + +Generate these sections in order: + +1. **Header** (sticky) + - Logo/project name + - Nav links: Features, Install, FAQ + - Actions: Search (Cmd+K), GitHub Star, primary CTA + +2. **Risk Banner** (if `--risk-banner`) + - Orange/warning style above fold + - Clear, visible disclaimer text + - Link to detailed disclosure section + +3. **Hero Section** + - Title from README H1 + - Tagline from TL;DR/first paragraph + - Stats badges (version, license, platform) + - CTAs: "Quick Start" (primary), "View on GitHub" (secondary) + +4. **Architecture/Overview** (if diagram in README) + - ASCII diagram converted to styled block + - Or overview cards + +5. **Features Grid** + - 4-6 feature cards from README features + - Icon + title + description pattern + +6. **Pricing Table** (if `--pricing-table`) + - Plans comparison table + - Multipliers/usage table if present + +7. **Screenshots Gallery** (if assets exist) + - Tab-based or carousel gallery + - Captions from alt text + +8. **Quick Start Section** + - One-liner install command (featured code block) + - Setup steps + - First usage example + +9. **Risk Disclosure** (if `--risk-banner`) + - Full disclaimer section + - ToS considerations + - Recommendations + +10. **FAQ Section** + - Generated from README FAQ or common questions + - Collapsible details pattern + +11. **Related Projects** (if links in README) + - Cards linking to dependencies/related repos + +12. **Footer** + - Quick links + - License badge + - Version info + - Author/repo links + +### Step 4: Output Structure + +``` +[project-name]-landing/ +├── index.html # Main landing page +├── styles.css # Complete stylesheet +├── search.js # Cmd+K search functionality +├── search-data.js # Search index (FAQ, features) +├── favicon.svg # Generated or copied +├── robots.txt # SEO +├── CLAUDE.md # Project instructions +├── README.md # Landing repo documentation +├── assets/ # Copied screenshots +│ └── [copied from source] +└── .github/ + └── workflows/ + └── static.yml # GitHub Pages deployment +``` + +## Tech Stack + +- **No build step**: Pure HTML + CSS + JS +- **Search**: MiniSearch lazy-loaded from CDN with fallback +- **Deployment**: GitHub Pages via Actions +- **Styling**: CSS custom properties, responsive, dark theme default +- **Accessibility**: Skip links, ARIA labels, keyboard navigation + +## CSS Patterns (from established landings) + +### Component Classes + +```css +/* Buttons */ +.btn, .btn-primary, .btn-secondary, .btn-github-star, .btn-outline + +/* Cards */ +.feature-card, .comparison-card, .path-card + +/* Layout */ +.container, .features-grid, .hero, .section + +/* Utilities */ +.visually-hidden, .skip-link +``` + +### CSS Variables + +```css +:root { + --color-bg: #0d1117; + --color-surface: #161b22; + --color-border: #30363d; + --color-text: #c9d1d9; + --color-text-muted: #8b949e; + --color-primary: #58a6ff; + --color-success: #3fb950; + --color-warning: #d29922; + --color-danger: #f85149; + --space-xs: 0.25rem; + --space-sm: 0.5rem; + --space-md: 1rem; + --space-lg: 1.5rem; + --space-xl: 2rem; + --radius: 6px; +} +``` + +## Example + +**User**: `/landing-page-generator from ~/Sites/perso/cc-copilot-bridge --risk-banner --pricing-table` + +**Output**: + +Creates `/Users/florianbruniaux/Sites/perso/cc-copilot-bridge-landing/` with: +- Complete landing page showcasing the multi-provider router +- Prominent ToS risk banner (orange, above fold) +- Provider cards (Anthropic, Copilot, Ollama) +- Pricing tables from README +- Screenshots gallery +- GitHub Pages deployment ready + +## Tips + +- Always include `--risk-banner` for projects with legal/ToS considerations +- Screenshots significantly improve landing quality - ensure assets/ is populated +- The skill preserves README language (English/French) +- Review generated FAQ - may need customization +- Test responsive design after generation + +## Related Use Cases + +- Open-source project showcases +- Documentation portals +- Product landing pages +- Tool/utility marketing sites + +## References + +See `references/landing-pattern.md` for detailed pattern documentation. +See `assets/` for reusable templates and snippets. \ No newline at end of file diff --git a/examples/skills/landing-page-generator/assets/search-base.js b/examples/skills/landing-page-generator/assets/search-base.js new file mode 100644 index 0000000..d0d92cd --- /dev/null +++ b/examples/skills/landing-page-generator/assets/search-base.js @@ -0,0 +1,401 @@ +/** + * Global Search - Cmd+K / Ctrl+K + * Lazy loads MiniSearch on first use + * Customize SEARCH_* arrays in search-data.js + */ + +(function() { + 'use strict'; + + let searchReady = false; + let miniSearch = null; + let searchIndex = []; + let selectedIndex = -1; + let lastFocusedElement = null; + + // DOM elements (cached after init) + let modal, input, results, statusEl; + + /** + * Load script dynamically + */ + function loadScript(src) { + return new Promise((resolve, reject) => { + const script = document.createElement('script'); + script.src = src; + script.onload = resolve; + script.onerror = reject; + document.head.appendChild(script); + }); + } + + /** + * Build search index from available sources + * Customize by adding your own window.SEARCH_* arrays + */ + function buildIndex() { + const items = []; + + // Features + if (window.SEARCH_FEATURES) { + items.push(...window.SEARCH_FEATURES); + } + + // FAQ + if (window.SEARCH_FAQ) { + items.push(...window.SEARCH_FAQ); + } + + // Docs + if (window.SEARCH_DOCS) { + items.push(...window.SEARCH_DOCS); + } + + // Custom items + if (window.SEARCH_CUSTOM) { + items.push(...window.SEARCH_CUSTOM); + } + + return items; + } + + /** + * Initialize search (called on first Cmd+K) + */ + async function initSearch() { + if (searchReady) return true; + + // Build index + searchIndex = buildIndex(); + + if (searchIndex.length === 0) { + console.warn('Search: No items to index'); + return false; + } + + // Try to load MiniSearch from CDN + if (!window.MiniSearch) { + try { + await loadScript('https://cdn.jsdelivr.net/npm/minisearch@7/dist/umd/index.min.js'); + } catch (e) { + console.warn('Search: MiniSearch CDN failed, using fallback'); + } + } + + // Initialize MiniSearch or fallback + if (window.MiniSearch) { + miniSearch = new MiniSearch({ + fields: ['title', 'content', 'category'], + storeFields: ['title', 'type', 'url', 'category'], + searchOptions: { + fuzzy: 0.2, + prefix: true, + boost: { title: 2 } + } + }); + miniSearch.addAll(searchIndex); + } else { + // Fallback: simple substring search + miniSearch = { + search: (query) => { + const q = query.toLowerCase(); + return searchIndex.filter(item => + item.title.toLowerCase().includes(q) || + item.content.toLowerCase().includes(q) || + (item.category && item.category.toLowerCase().includes(q)) + ).map(item => ({ ...item, score: 1 })); + } + }; + } + + searchReady = true; + return true; + } + + /** + * Perform search and return results + */ + function search(query) { + if (!searchReady || !query.trim()) return []; + + const searchResults = miniSearch.search(query); + + // Group by type and limit + const grouped = {}; + searchResults.forEach(r => { + const type = r.type || 'item'; + if (!grouped[type]) grouped[type] = []; + if (grouped[type].length < 5) { + grouped[type].push(r); + } + }); + + // Flatten all groups + return Object.values(grouped).flat(); + } + + /** + * Render search results + */ + function renderResults(items) { + if (!results) return; + + selectedIndex = -1; + + if (items.length === 0) { + results.innerHTML = '
  • No results found
    • '; + announceResults(0); + return; + } + + const typeIcons = { + feature: '⚡', + faq: '❓', + doc: '📖', + install: '📦', + provider: '🔌', + default: '📄' + }; + + results.innerHTML = items.map((item, i) => ` +
  • + ${typeIcons[item.type] || typeIcons.default} ${item.type || 'item'} + ${escapeHtml(item.title)} + ${item.category ? `${item.category}` : ''} +
    • + `).join(''); + + // Add click handlers + results.querySelectorAll('.search-result-item').forEach((el, i) => { + el.addEventListener('click', () => navigateTo(items[i].url)); + }); + + announceResults(items.length); + } + + /** + * Announce results to screen readers + */ + function announceResults(count) { + if (statusEl) { + statusEl.textContent = count === 0 + ? 'No results found' + : `${count} result${count > 1 ? 's' : ''} found. Use arrow keys to navigate.`; + } + } + + /** + * Navigate to result URL + */ + function navigateTo(url) { + closeModal(); + window.location.href = url; + } + + /** + * Update selected item + */ + function updateSelection(newIndex) { + const items = results.querySelectorAll('.search-result-item'); + if (items.length === 0) return; + + // Wrap around + if (newIndex < 0) newIndex = items.length - 1; + if (newIndex >= items.length) newIndex = 0; + + // Update aria-selected + items.forEach((el, i) => { + el.setAttribute('aria-selected', i === newIndex ? 'true' : 'false'); + }); + + // Scroll into view + items[newIndex].scrollIntoView({ block: 'nearest' }); + + selectedIndex = newIndex; + } + + /** + * Handle keyboard navigation + */ + function handleKeydown(e) { + const items = results.querySelectorAll('.search-result-item'); + + switch (e.key) { + case 'ArrowDown': + e.preventDefault(); + updateSelection(selectedIndex + 1); + break; + + case 'ArrowUp': + e.preventDefault(); + updateSelection(selectedIndex - 1); + break; + + case 'Enter': + e.preventDefault(); + if (selectedIndex >= 0 && items[selectedIndex]) { + const url = items[selectedIndex].dataset.url; + if (url) navigateTo(url); + } + break; + + case 'Home': + e.preventDefault(); + updateSelection(0); + break; + + case 'End': + e.preventDefault(); + updateSelection(items.length - 1); + break; + + case 'Escape': + e.preventDefault(); + closeModal(); + break; + } + } + + /** + * Open search modal + */ + async function openModal() { + if (!modal) return; + + // Initialize search on first open + const ready = await initSearch(); + if (!ready) { + console.error('Search: Failed to initialize'); + return; + } + + // Save current focus + lastFocusedElement = document.activeElement; + + // Show modal + modal.hidden = false; + document.body.style.overflow = 'hidden'; + + // Focus input + setTimeout(() => { + input.value = ''; + input.focus(); + renderResults([]); + }, 10); + } + + /** + * Close search modal + */ + function closeModal() { + if (!modal) return; + + modal.hidden = true; + document.body.style.overflow = ''; + + // Restore focus + if (lastFocusedElement) { + lastFocusedElement.focus(); + } + } + + /** + * Escape HTML + */ + function escapeHtml(str) { + const div = document.createElement('div'); + div.textContent = str; + return div.innerHTML; + } + + /** + * Focus trap for accessibility + */ + function trapFocus(e) { + if (!modal || modal.hidden) return; + + const focusable = modal.querySelectorAll( + 'input, button, [tabindex]:not([tabindex="-1"])' + ); + const first = focusable[0]; + const last = focusable[focusable.length - 1]; + + if (e.shiftKey && document.activeElement === first) { + e.preventDefault(); + last.focus(); + } else if (!e.shiftKey && document.activeElement === last) { + e.preventDefault(); + first.focus(); + } + } + + /** + * Initialize when DOM is ready + */ + function init() { + // Get DOM elements + modal = document.getElementById('search-modal'); + input = document.getElementById('search-input'); + results = document.getElementById('search-results'); + statusEl = document.getElementById('search-status'); + + if (!modal || !input || !results) { + console.warn('Search: Modal elements not found'); + return; + } + + // Input handler with debounce + let debounceTimer; + input.addEventListener('input', (e) => { + clearTimeout(debounceTimer); + debounceTimer = setTimeout(() => { + const items = search(e.target.value); + renderResults(items); + }, 150); + }); + + // Keyboard navigation + input.addEventListener('keydown', handleKeydown); + + // Close on backdrop click + modal.querySelector('.search-modal-backdrop')?.addEventListener('click', closeModal); + + // Global keyboard shortcut: Cmd+K / Ctrl+K + document.addEventListener('keydown', (e) => { + if ((e.metaKey || e.ctrlKey) && e.key === 'k') { + e.preventDefault(); + if (modal.hidden) { + openModal(); + } else { + closeModal(); + } + } + }); + + // Focus trap + modal.addEventListener('keydown', (e) => { + if (e.key === 'Tab') { + trapFocus(e); + } + }); + + // Search trigger button + document.querySelectorAll('.search-trigger').forEach(btn => { + btn.addEventListener('click', (e) => { + e.preventDefault(); + openModal(); + }); + }); + } + + // Initialize on DOM ready + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', init); + } else { + init(); + } +})(); diff --git a/examples/skills/landing-page-generator/assets/section-snippets/faq.html b/examples/skills/landing-page-generator/assets/section-snippets/faq.html new file mode 100644 index 0000000..a8b607b --- /dev/null +++ b/examples/skills/landing-page-generator/assets/section-snippets/faq.html @@ -0,0 +1,62 @@ + +
    +
    +

    Frequently Asked Questions

    + +
    + +
    + {{FAQ_1_QUESTION}} +
    +

    {{FAQ_1_ANSWER}}

    +
    +
    + + +
    + {{FAQ_2_QUESTION}} +
    +

    {{FAQ_2_ANSWER}}

    +
    +
    + + +
    + {{FAQ_3_QUESTION}} +
    +

    {{FAQ_3_ANSWER}}

    +
    +
    + + +
    + {{FAQ_4_QUESTION}} +
    +

    {{FAQ_4_ANSWER}}

    +
    +
    + + +
    + {{FAQ_5_QUESTION}} +
    +

    {{FAQ_5_ANSWER}}

    +
    +
    +
    +
    +
    + + diff --git a/examples/skills/landing-page-generator/assets/section-snippets/features-grid.html b/examples/skills/landing-page-generator/assets/section-snippets/features-grid.html new file mode 100644 index 0000000..80098a6 --- /dev/null +++ b/examples/skills/landing-page-generator/assets/section-snippets/features-grid.html @@ -0,0 +1,59 @@ + +
    +
    +

    Features

    + +
    + +
    +
    {{FEATURE_1_ICON}}
    +

    {{FEATURE_1_TITLE}}

    +

    {{FEATURE_1_DESC}}

    +
    + + +
    +
    {{FEATURE_2_ICON}}
    +

    {{FEATURE_2_TITLE}}

    +

    {{FEATURE_2_DESC}}

    +
    + + +
    +
    {{FEATURE_3_ICON}}
    +

    {{FEATURE_3_TITLE}}

    +

    {{FEATURE_3_DESC}}

    +
    + + +
    +
    {{FEATURE_4_ICON}}
    +

    {{FEATURE_4_TITLE}}

    +

    {{FEATURE_4_DESC}}

    +
    + + +
    +
    {{FEATURE_5_ICON}}
    +

    {{FEATURE_5_TITLE}}

    +

    {{FEATURE_5_DESC}}

    +
    + + +
    +
    {{FEATURE_6_ICON}}
    +

    {{FEATURE_6_TITLE}}

    +

    {{FEATURE_6_DESC}}

    +
    +
    +
    +
    + + diff --git a/examples/skills/landing-page-generator/assets/section-snippets/footer.html b/examples/skills/landing-page-generator/assets/section-snippets/footer.html new file mode 100644 index 0000000..559c41b --- /dev/null +++ b/examples/skills/landing-page-generator/assets/section-snippets/footer.html @@ -0,0 +1,40 @@ + + + + diff --git a/examples/skills/landing-page-generator/assets/section-snippets/header.html b/examples/skills/landing-page-generator/assets/section-snippets/header.html new file mode 100644 index 0000000..60e0c17 --- /dev/null +++ b/examples/skills/landing-page-generator/assets/section-snippets/header.html @@ -0,0 +1,54 @@ + +
    +
    + +
    +
    + + diff --git a/examples/skills/landing-page-generator/assets/section-snippets/hero.html b/examples/skills/landing-page-generator/assets/section-snippets/hero.html new file mode 100644 index 0000000..97be21d --- /dev/null +++ b/examples/skills/landing-page-generator/assets/section-snippets/hero.html @@ -0,0 +1,42 @@ + +
    +
    + +
    + MIT License + Version + Platform +
    + + +

    {{PROJECT_TITLE}}

    + + +

    {{PROJECT_TAGLINE}}

    + + +
    + {{STAT_1_VALUE}} {{STAT_1_LABEL}} + {{STAT_2_VALUE}} {{STAT_2_LABEL}} + {{STAT_3_VALUE}} {{STAT_3_LABEL}} +
    + + +
    + Quick Start + View on GitHub +
    +
    +
    + + diff --git a/examples/skills/landing-page-generator/assets/section-snippets/install.html b/examples/skills/landing-page-generator/assets/section-snippets/install.html new file mode 100644 index 0000000..7698eb1 --- /dev/null +++ b/examples/skills/landing-page-generator/assets/section-snippets/install.html @@ -0,0 +1,90 @@ + +
    +
    +

    Quick Start

    + + +
    +

    Get started in {{INSTALL_TIME}}:

    + +
    +
    + bash + +
    + 
    {{INSTALL_COMMAND}}
    +
    +
    + + +
    +

    Setup

    + +
    +
    + bash + +
    + 
    {{SETUP_COMMANDS}}
    +
    +
    + + +
    +

    First Usage

    + +
    +
    + bash + +
    + 
    {{USAGE_EXAMPLE}}
    +
    +
    + + +

    + Full installation guide → +

    +
    +
    + + + + diff --git a/examples/skills/landing-page-generator/assets/section-snippets/risk-banner.html b/examples/skills/landing-page-generator/assets/section-snippets/risk-banner.html new file mode 100644 index 0000000..66d44b7 --- /dev/null +++ b/examples/skills/landing-page-generator/assets/section-snippets/risk-banner.html @@ -0,0 +1,22 @@ + + + + diff --git a/examples/skills/landing-page-generator/assets/section-snippets/search-modal.html b/examples/skills/landing-page-generator/assets/section-snippets/search-modal.html new file mode 100644 index 0000000..14dcf52 --- /dev/null +++ b/examples/skills/landing-page-generator/assets/section-snippets/search-modal.html @@ -0,0 +1,40 @@ + + + + diff --git a/examples/skills/landing-page-generator/assets/static-workflow.yml b/examples/skills/landing-page-generator/assets/static-workflow.yml new file mode 100644 index 0000000..f2c9e97 --- /dev/null +++ b/examples/skills/landing-page-generator/assets/static-workflow.yml @@ -0,0 +1,43 @@ +# Simple workflow for deploying static content to GitHub Pages +name: Deploy static content to Pages + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Single deploy job since we're just deploying + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + # Upload entire repository + path: '.' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/examples/skills/landing-page-generator/assets/styles-base.css b/examples/skills/landing-page-generator/assets/styles-base.css new file mode 100644 index 0000000..58a19d3 --- /dev/null +++ b/examples/skills/landing-page-generator/assets/styles-base.css @@ -0,0 +1,917 @@ +/* ============================================ + Landing Page Base Styles + Dark Theme - GitHub-inspired + ============================================ */ + +/* CSS Custom Properties */ +:root { + /* Colors - Dark Theme */ + --bg-primary: #0d1117; + --bg-secondary: #161b22; + --bg-tertiary: #21262d; + --text-primary: #c9d1d9; + --text-secondary: #9ca3af; + --text-muted: #8b949e; + --accent: #58a6ff; + --accent-hover: #79b8ff; + --accent-secondary: #4f46e5; + --accent-secondary-hover: #6366f1; + --border: #30363d; + --border-light: #21262d; + --success: #3fb950; + --warning: #d29922; + --danger: #f85149; + + /* Typography */ + --font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; + --font-mono: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace; + + /* Spacing */ + --space-xs: 0.25rem; + --space-sm: 0.5rem; + --space-md: 1rem; + --space-lg: 1.5rem; + --space-xl: 2rem; + --space-2xl: 3rem; + --space-3xl: 4rem; + + /* Layout */ + --max-width: 1200px; + --border-radius: 8px; + --border-radius-lg: 12px; + + /* Transitions */ + --transition-fast: 150ms ease; + --transition-normal: 250ms ease; +} + +/* Reset & Base */ +*, *::before, *::after { + box-sizing: border-box; + margin: 0; + padding: 0; +} + +html { + scroll-behavior: smooth; + font-size: 16px; +} + +body { + font-family: var(--font-sans); + background-color: var(--bg-primary); + color: var(--text-primary); + line-height: 1.6; + -webkit-font-smoothing: antialiased; +} + +/* Container */ +.container { + max-width: var(--max-width); + margin: 0 auto; + padding: 0 var(--space-lg); +} + +/* Typography */ +h1, h2, h3, h4, h5, h6 { + font-weight: 600; + line-height: 1.3; + color: var(--text-primary); +} + +a { + color: var(--accent); + text-decoration: none; + transition: color var(--transition-fast); +} + +a:hover { + color: var(--accent-hover); +} + +code { + font-family: var(--font-mono); + background-color: var(--bg-tertiary); + padding: 0.15em 0.4em; + border-radius: 4px; + font-size: 0.9em; +} + +kbd { + display: inline-block; + padding: 0.2em 0.5em; + font-family: var(--font-mono); + font-size: 0.85em; + background-color: var(--bg-tertiary); + border: 1px solid var(--border); + border-radius: 4px; +} + +/* Skip Link */ +.skip-link { + position: absolute; + top: -40px; + left: 0; + padding: 8px; + background-color: var(--accent); + color: var(--bg-primary); + z-index: 1000; +} + +.skip-link:focus { + top: 0; +} + +/* ============================================ + Buttons + ============================================ */ +.btn { + display: inline-flex; + align-items: center; + justify-content: center; + gap: var(--space-sm); + padding: 0.75rem 1.5rem; + font-size: 1rem; + font-weight: 500; + border-radius: var(--border-radius); + border: none; + cursor: pointer; + transition: all var(--transition-fast); + text-decoration: none; +} + +.btn:hover { + text-decoration: none; +} + +.btn-primary { + background-color: var(--accent-secondary); + color: #ffffff; + font-weight: 600; +} + +.btn-primary:hover { + background-color: var(--accent-secondary-hover); + color: #ffffff; + transform: translateY(-2px); +} + +.btn-secondary { + background: transparent; + color: var(--text-primary); + border: 1px solid var(--border); +} + +.btn-secondary:hover { + border-color: var(--accent); + color: var(--accent); +} + +.btn-github-star { + background: linear-gradient(135deg, #24292e 0%, #1a1e22 100%); + color: #ffffff; + border: 1px solid rgba(255, 255, 255, 0.1); + font-weight: 600; + padding: 0.5rem 1rem; +} + +.btn-github-star:hover { + background: linear-gradient(135deg, #2f363d 0%, #24292e 100%); + transform: translateY(-2px); +} + +/* ============================================ + Header + ============================================ */ +.header { + position: sticky; + top: 0; + z-index: 100; + background-color: rgba(13, 17, 23, 0.95); + backdrop-filter: blur(8px); + border-bottom: 1px solid var(--border); +} + +.nav { + display: flex; + align-items: center; + justify-content: space-between; + height: 64px; +} + +.logo { + display: flex; + align-items: center; + gap: var(--space-sm); + font-weight: 600; + font-size: 1.1rem; + color: var(--text-primary); +} + +.logo:hover { + color: var(--text-primary); + text-decoration: none; +} + +.logo-icon { + font-family: var(--font-mono); + color: var(--accent); +} + +.nav-links { + display: flex; + align-items: center; + gap: var(--space-lg); +} + +.nav-links a { + color: var(--text-secondary); + font-size: 0.95rem; +} + +.nav-links a:hover { + color: var(--text-primary); + text-decoration: none; +} + +.nav-actions { + display: flex; + align-items: center; + gap: 1rem; +} + +/* ============================================ + Risk Banner + ============================================ */ +.risk-banner { + background: linear-gradient(90deg, rgba(210, 153, 34, 0.15), rgba(248, 81, 73, 0.15)); + border-bottom: 1px solid var(--warning); + padding: var(--space-md) 0; +} + +.risk-banner .container { + display: flex; + align-items: center; + gap: var(--space-md); + flex-wrap: wrap; +} + +.risk-icon { + font-size: 1.25rem; +} + +.risk-text { + flex: 1; + font-size: 0.95rem; +} + +.risk-text strong { + color: var(--warning); +} + +.risk-link { + color: var(--warning); + font-weight: 500; + white-space: nowrap; +} + +.risk-link:hover { + color: var(--danger); +} + +/* ============================================ + Hero + ============================================ */ +.hero { + padding: var(--space-3xl) 0; + text-align: center; +} + +.hero-badges { + display: flex; + justify-content: center; + gap: var(--space-sm); + margin-bottom: var(--space-lg); + flex-wrap: wrap; +} + +.hero-badges img { + height: 20px; +} + +.hero-title { + font-size: 3rem; + font-weight: 700; + margin-bottom: var(--space-md); + background: linear-gradient(135deg, var(--text-primary), var(--accent)); + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; + background-clip: text; +} + +.hero-tagline { + font-size: 1.25rem; + color: var(--text-secondary); + max-width: 700px; + margin: 0 auto var(--space-lg); +} + +.hero-stats { + display: flex; + justify-content: center; + gap: var(--space-xl); + margin-bottom: var(--space-xl); +} + +.hero-stats .stat { + color: var(--text-secondary); +} + +.hero-stats strong { + color: var(--accent); +} + +.hero-ctas { + display: flex; + justify-content: center; + gap: var(--space-md); + flex-wrap: wrap; +} + +/* ============================================ + Sections + ============================================ */ +section { + padding: var(--space-3xl) 0; +} + +.section-title { + font-size: 2rem; + text-align: center; + margin-bottom: var(--space-2xl); +} + +/* ============================================ + Features Grid + ============================================ */ +.features-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); + gap: var(--space-xl); +} + +.feature-card { + background-color: var(--bg-secondary); + border: 1px solid var(--border); + border-radius: var(--border-radius-lg); + padding: var(--space-xl); + transition: transform var(--transition-fast), box-shadow var(--transition-fast); +} + +.feature-card:hover { + transform: translateY(-4px); + box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3); +} + +.feature-icon { + font-size: 2rem; + margin-bottom: var(--space-md); +} + +.feature-title { + font-size: 1.1rem; + margin-bottom: var(--space-sm); +} + +.feature-desc { + color: var(--text-secondary); + font-size: 0.95rem; +} + +/* ============================================ + Provider Cards + ============================================ */ +.providers-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); + gap: var(--space-xl); +} + +.provider-card { + background-color: var(--bg-secondary); + border: 1px solid var(--border); + border-radius: var(--border-radius-lg); + padding: var(--space-xl); + position: relative; + overflow: hidden; +} + +.provider-card::before { + content: ''; + position: absolute; + top: 0; + left: 0; + right: 0; + height: 4px; +} + +.provider-card.anthropic::before { + background: linear-gradient(90deg, #d97706, #ea580c); +} + +.provider-card.copilot::before { + background: linear-gradient(90deg, #58a6ff, #3b82f6); +} + +.provider-card.ollama::before { + background: linear-gradient(90deg, #3fb950, #22c55e); +} + +.provider-header { + display: flex; + align-items: center; + gap: var(--space-md); + margin-bottom: var(--space-md); +} + +.provider-icon { + font-size: 2rem; +} + +.provider-name { + font-size: 1.25rem; + font-weight: 600; +} + +.provider-command { + font-family: var(--font-mono); + color: var(--accent); + font-size: 0.9rem; +} + +.provider-desc { + color: var(--text-secondary); + margin-bottom: var(--space-md); +} + +.provider-meta { + display: flex; + gap: var(--space-md); + font-size: 0.9rem; + color: var(--text-muted); +} + +/* ============================================ + Code Blocks + ============================================ */ +.code-block { + background-color: var(--bg-secondary); + border: 1px solid var(--border); + border-radius: var(--border-radius); + overflow: hidden; + margin: var(--space-md) 0; +} + +.code-header { + display: flex; + justify-content: space-between; + align-items: center; + padding: var(--space-sm) var(--space-md); + background-color: var(--bg-tertiary); + border-bottom: 1px solid var(--border); +} + +.code-lang { + color: var(--text-muted); + font-size: 0.85rem; + font-family: var(--font-mono); +} + +.copy-btn { + background: none; + border: none; + color: var(--text-secondary); + cursor: pointer; + font-size: 0.85rem; + padding: var(--space-xs) var(--space-sm); + border-radius: 4px; + transition: all var(--transition-fast); +} + +.copy-btn:hover { + color: var(--text-primary); + background-color: var(--bg-tertiary); +} + +.code-block pre { + padding: var(--space-md); + overflow-x: auto; + margin: 0; +} + +.code-block code { + background: none; + padding: 0; + font-size: 0.9rem; + color: var(--text-primary); +} + +/* ============================================ + Pricing Table + ============================================ */ +.pricing-table { + width: 100%; + border-collapse: collapse; + margin: var(--space-xl) 0; +} + +.pricing-table th, +.pricing-table td { + padding: var(--space-md); + text-align: left; + border-bottom: 1px solid var(--border); +} + +.pricing-table th { + background-color: var(--bg-secondary); + font-weight: 600; +} + +.pricing-table tr:hover { + background-color: var(--bg-secondary); +} + +.pricing-highlight { + color: var(--success); + font-weight: 600; +} + +/* ============================================ + Screenshots Gallery + ============================================ */ +.screenshots-tabs { + display: flex; + justify-content: center; + gap: var(--space-sm); + margin-bottom: var(--space-xl); + flex-wrap: wrap; +} + +.screenshot-tab { + padding: var(--space-sm) var(--space-md); + background: none; + border: 1px solid var(--border); + border-radius: var(--border-radius); + color: var(--text-secondary); + cursor: pointer; + transition: all var(--transition-fast); +} + +.screenshot-tab:hover, +.screenshot-tab.active { + border-color: var(--accent); + color: var(--accent); + background-color: rgba(88, 166, 255, 0.1); +} + +.screenshot-content { + display: none; + text-align: center; +} + +.screenshot-content.active { + display: block; +} + +.screenshot-content img { + max-width: 100%; + border-radius: var(--border-radius-lg); + border: 1px solid var(--border); +} + +/* ============================================ + FAQ + ============================================ */ +.faq-list { + max-width: 800px; + margin: 0 auto; +} + +.faq-item { + border: 1px solid var(--border); + border-radius: var(--border-radius); + margin-bottom: var(--space-md); + overflow: hidden; +} + +.faq-question { + padding: var(--space-md) var(--space-lg); + cursor: pointer; + font-weight: 500; + list-style: none; + display: flex; + justify-content: space-between; + align-items: center; +} + +.faq-question::-webkit-details-marker { + display: none; +} + +.faq-question::after { + content: '+'; + font-size: 1.5rem; + color: var(--text-muted); + transition: transform var(--transition-fast); +} + +.faq-item[open] .faq-question::after { + transform: rotate(45deg); +} + +.faq-answer { + padding: 0 var(--space-lg) var(--space-lg); + color: var(--text-secondary); +} + +/* ============================================ + Risk Disclosure Section + ============================================ */ +.risk-disclosure { + background-color: rgba(248, 81, 73, 0.05); + border: 1px solid rgba(248, 81, 73, 0.3); + border-radius: var(--border-radius-lg); + padding: var(--space-xl); +} + +.risk-disclosure h3 { + color: var(--danger); + margin-bottom: var(--space-md); +} + +.risk-disclosure ul { + list-style: disc; + padding-left: var(--space-xl); + color: var(--text-secondary); +} + +.risk-disclosure li { + margin-bottom: var(--space-sm); +} + +/* ============================================ + Footer + ============================================ */ +.footer { + background-color: var(--bg-secondary); + border-top: 1px solid var(--border); + padding: var(--space-2xl) 0; +} + +.footer-content { + display: flex; + justify-content: space-between; + align-items: center; + flex-wrap: wrap; + gap: var(--space-lg); +} + +.footer-brand { + display: flex; + flex-direction: column; + gap: var(--space-xs); +} + +.footer-tagline { + color: var(--text-muted); + font-size: 0.9rem; +} + +.footer-links { + display: flex; + gap: var(--space-lg); +} + +.footer-links a { + color: var(--text-secondary); + font-size: 0.9rem; +} + +.footer-links a:hover { + color: var(--text-primary); +} + +.footer-meta { + display: flex; + gap: var(--space-md); + color: var(--text-muted); + font-size: 0.85rem; +} + +/* ============================================ + Search Modal + ============================================ */ +.search-modal { + position: fixed; + inset: 0; + z-index: 1000; + display: flex; + align-items: flex-start; + justify-content: center; + padding-top: 15vh; +} + +.search-modal[hidden] { + display: none; +} + +.search-modal-backdrop { + position: absolute; + inset: 0; + background-color: rgba(0, 0, 0, 0.7); +} + +.search-modal-content { + position: relative; + width: 100%; + max-width: 600px; + background-color: var(--bg-secondary); + border: 1px solid var(--border); + border-radius: var(--border-radius-lg); + overflow: hidden; + margin: 0 var(--space-md); +} + +.search-input-wrapper { + display: flex; + align-items: center; + padding: var(--space-md); + border-bottom: 1px solid var(--border); +} + +.search-input { + flex: 1; + background: none; + border: none; + color: var(--text-primary); + font-size: 1.1rem; + outline: none; +} + +.search-input::placeholder { + color: var(--text-muted); +} + +.search-results { + max-height: 400px; + overflow-y: auto; + list-style: none; +} + +.search-result-item { + padding: var(--space-md) var(--space-lg); + cursor: pointer; + display: flex; + align-items: center; + gap: var(--space-md); + border-bottom: 1px solid var(--border-light); +} + +.search-result-item:hover, +.search-result-item[aria-selected="true"] { + background-color: var(--bg-tertiary); +} + +.search-result-type { + font-size: 0.8rem; + color: var(--text-muted); + min-width: 80px; +} + +.search-result-title { + flex: 1; +} + +.search-result-category { + font-size: 0.8rem; + color: var(--text-muted); + background-color: var(--bg-tertiary); + padding: 2px 8px; + border-radius: 4px; +} + +.search-no-results { + padding: var(--space-xl); + text-align: center; + color: var(--text-muted); +} + +.search-status { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + border: 0; +} + +/* Search trigger button */ +.search-trigger { + display: flex; + align-items: center; + gap: var(--space-sm); + padding: var(--space-sm) var(--space-md); + background-color: var(--bg-tertiary); + border: 1px solid var(--border); + border-radius: var(--border-radius); + color: var(--text-muted); + cursor: pointer; + transition: all var(--transition-fast); +} + +.search-trigger:hover { + border-color: var(--accent); + color: var(--text-primary); +} + +/* ============================================ + Responsive + ============================================ */ +@media (max-width: 768px) { + .hero-title { + font-size: 2rem; + } + + .hero-tagline { + font-size: 1.1rem; + } + + .nav-links { + display: none; + } + + .hero-ctas { + flex-direction: column; + align-items: center; + } + + .footer-content { + flex-direction: column; + text-align: center; + } + + .risk-banner .container { + flex-direction: column; + text-align: center; + } +} + +@media (max-width: 480px) { + .hero { + padding: var(--space-2xl) 0; + } + + .hero-stats { + flex-direction: column; + gap: var(--space-sm); + } + + section { + padding: var(--space-2xl) 0; + } +} + +/* ============================================ + Utilities + ============================================ */ +.visually-hidden { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + border: 0; +} + +/* Focus visible for accessibility */ +:focus-visible { + outline: 2px solid var(--accent); + outline-offset: 2px; +} + +/* Reduced motion */ +@media (prefers-reduced-motion: reduce) { + *, *::before, *::after { + animation-duration: 0.01ms !important; + animation-iteration-count: 1 !important; + transition-duration: 0.01ms !important; + } + + html { + scroll-behavior: auto; + } +} diff --git a/examples/skills/landing-page-generator/references/landing-pattern.md b/examples/skills/landing-page-generator/references/landing-pattern.md new file mode 100644 index 0000000..4458430 --- /dev/null +++ b/examples/skills/landing-page-generator/references/landing-pattern.md @@ -0,0 +1,478 @@ +# Landing Page Pattern Reference + +Documentation of the established landing page pattern used in `claude-code-ultimate-guide-landing` and `claude-cowork-guide-landing`. + +## Tech Stack + +| Component | Choice | Rationale | +|-----------|--------|-----------| +| Framework | None (vanilla) | Simplicity, no build step, easy hosting | +| Styling | Single CSS file | Maintainable, no preprocessor needed | +| JavaScript | Vanilla + MiniSearch CDN | Minimal dependencies, lazy-loaded | +| Deployment | GitHub Pages + Actions | Free, automatic, reliable | +| Search | MiniSearch with fallback | Client-side, fast, no backend needed | + +## File Structure + +``` +project-landing/ +├── index.html # Main landing (all sections) +├── styles.css # Complete stylesheet (~3000 lines) +├── search.js # Search modal + keyboard nav +├── search-data.js # Search index arrays +├── *-data.js # Additional data files (optional) +├── favicon.svg # Project icon +├── robots.txt # SEO +├── CLAUDE.md # Claude instructions +├── README.md # Repo documentation +├── assets/ # Images, screenshots +└── .github/workflows/ + └── static.yml # Pages deployment +``` + +## HTML Structure + +### Document Head + +```html + + + + + + [Project Name] - [Tagline] + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Body Structure + +```html + + + +
    ...
    + +
    +
    ...
    +
    ...
    +
    ...
    +
    ...
    + +
    + +
    ...
    + + + + + + + + +``` + +## Section Patterns + +### Header + +```html +
    +
    + + +
    + + + ⭐ Star on GitHub + +
    +
    +
    +``` + +### Hero Section + +```html +
    +
    +
    + ... + +
    +

    [Main Title]

    +

    [Tagline/TL;DR]

    +
    + [N] features + [N] examples +
    +
    + Quick Start + View on GitHub +
    +
    +
    +``` + +### Risk Banner (Optional) + +```html + +``` + +### Features Grid + +```html +
    +
    +

    Features

    +
    +
    +
    [emoji/icon]
    +

    [Title]

    +

    [Description]

    +
    + +
    +
    +
    +``` + +### Code Block with Copy + +```html +
    +
    + [language] + +
    + 
    [code content]
    +
    +``` + +### FAQ Section + +```html +
    +
    +

    FAQ

    +
    +
    + [Question]? +
    +

    [Answer]

    +
    +
    + +
    +
    +
    +``` + +### Footer + +```html +
    +
    +
    +
    + +

    [Short tagline]

    +
    + +
    + MIT License + v[version] +
    +
    +
    +
    +``` + +## CSS Architecture + +### Custom Properties (Theme) + +```css +:root { + /* Colors - Dark Theme */ + --color-bg: #0d1117; + --color-surface: #161b22; + --color-surface-hover: #21262d; + --color-border: #30363d; + --color-text: #c9d1d9; + --color-text-muted: #8b949e; + --color-heading: #f0f6fc; + --color-primary: #58a6ff; + --color-primary-hover: #79b8ff; + --color-success: #3fb950; + --color-warning: #d29922; + --color-danger: #f85149; + + /* Spacing */ + --space-xs: 0.25rem; + --space-sm: 0.5rem; + --space-md: 1rem; + --space-lg: 1.5rem; + --space-xl: 2rem; + --space-2xl: 3rem; + --space-3xl: 4rem; + + /* Typography */ + --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; + --font-mono: 'SF Mono', Consolas, 'Liberation Mono', monospace; + --font-size-sm: 0.875rem; + --font-size-base: 1rem; + --font-size-lg: 1.125rem; + --font-size-xl: 1.25rem; + --font-size-2xl: 1.5rem; + --font-size-3xl: 2rem; + --font-size-4xl: 2.5rem; + + /* Layout */ + --container-max: 1200px; + --radius: 6px; + --radius-lg: 12px; + + /* Shadows */ + --shadow-sm: 0 1px 2px rgba(0,0,0,0.3); + --shadow-md: 0 4px 6px rgba(0,0,0,0.3); + --shadow-lg: 0 10px 15px rgba(0,0,0,0.3); +} +``` + +### Component Patterns + +```css +/* Container */ +.container { + max-width: var(--container-max); + margin: 0 auto; + padding: 0 var(--space-lg); +} + +/* Buttons */ +.btn { + display: inline-flex; + align-items: center; + gap: var(--space-sm); + padding: var(--space-sm) var(--space-lg); + border-radius: var(--radius); + font-weight: 500; + text-decoration: none; + transition: all 0.2s; +} + +.btn-primary { + background: var(--color-primary); + color: var(--color-bg); +} + +.btn-secondary { + background: var(--color-surface); + color: var(--color-text); + border: 1px solid var(--color-border); +} + +/* Cards */ +.feature-card { + background: var(--color-surface); + border: 1px solid var(--color-border); + border-radius: var(--radius-lg); + padding: var(--space-xl); + transition: transform 0.2s, box-shadow 0.2s; +} + +.feature-card:hover { + transform: translateY(-2px); + box-shadow: var(--shadow-md); +} + +/* Grids */ +.features-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); + gap: var(--space-xl); +} +``` + +### Responsive Breakpoints + +```css +/* Tablet */ +@media (max-width: 768px) { + .hero-title { font-size: var(--font-size-3xl); } + .header-actions { display: none; } + .nav { display: none; } + /* Mobile nav toggle */ +} + +/* Mobile */ +@media (max-width: 480px) { + .hero-ctas { flex-direction: column; } + .features-grid { grid-template-columns: 1fr; } +} +``` + +## JavaScript Patterns + +### Search Implementation + +```javascript +(function() { + 'use strict'; + + let searchIndex = null; + let miniSearchLoaded = false; + + // Lazy load MiniSearch + async function loadMiniSearch() { + if (miniSearchLoaded) return; + await loadScript('https://cdn.jsdelivr.net/npm/minisearch@7/dist/umd/index.min.js'); + miniSearchLoaded = true; + } + + // Build index from window.SEARCH_* data + function buildIndex() { + const items = [ + ...(window.SEARCH_FEATURES || []), + ...(window.SEARCH_FAQ || []), + ]; + // ... index building + } + + // Keyboard navigation + document.addEventListener('keydown', (e) => { + if ((e.metaKey || e.ctrlKey) && e.key === 'k') { + e.preventDefault(); + openSearchModal(); + } + }); +})(); +``` + +### Copy Code Function + +```javascript +async function copyCode(button) { + const codeBlock = button.closest('.code-block'); + const code = codeBlock.querySelector('code').textContent; + + try { + await navigator.clipboard.writeText(code); + button.textContent = '✓ Copied!'; + setTimeout(() => { + button.textContent = '📋 Copy'; + }, 2000); + } catch (err) { + console.error('Copy failed:', err); + } +} +``` + +## Deployment + +### GitHub Actions Workflow + +```yaml +name: Deploy to GitHub Pages + +on: + push: + branches: ["main"] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/configure-pages@v5 + - uses: actions/upload-pages-artifact@v3 + with: + path: '.' + - id: deployment + uses: actions/deploy-pages@v4 +``` + +## Accessibility Checklist + +- [ ] Skip link to main content +- [ ] Semantic HTML (header, main, section, footer) +- [ ] ARIA labels on interactive elements +- [ ] Keyboard navigation for modals +- [ ] Focus visible styles +- [ ] Color contrast WCAG AA +- [ ] Reduced motion respect +- [ ] Alt text on images + +## SEO Checklist + +- [ ] Descriptive title tag +- [ ] Meta description +- [ ] Canonical URL +- [ ] Open Graph tags +- [ ] Twitter Card tags +- [ ] Structured data (Schema.org) +- [ ] robots.txt +- [ ] Semantic heading hierarchy \ No newline at end of file diff --git a/examples/skills/release-notes-generator/SKILL.md b/examples/skills/release-notes-generator/SKILL.md new file mode 100644 index 0000000..db053ec --- /dev/null +++ b/examples/skills/release-notes-generator/SKILL.md @@ -0,0 +1,259 @@ +--- +name: release-notes-generator +description: Generate release notes in 3 formats (CHANGELOG.md, PR body, Slack announcement) from git commits. Automatically categorizes changes and converts technical language to user-friendly messaging. Use when preparing a production release. +--- + +# Release Notes Generator + +Generate comprehensive release notes in 3 formats from git commits, optimized for the Methode Aristote project workflow. + +## When to Use This Skill + +- Preparing a production release (develop -> main) +- Creating release PR with proper documentation +- Generating Slack announcement for stakeholders +- Updating CHANGELOG.md with new version +- Analyzing commits since last release + +## What This Skill Does + +1. **Analyzes Git History**: Scans commits since last release tag or specified version +2. **Fetches PR Details**: Gets PR titles, descriptions, and labels via `gh api` +3. **Categorizes Changes**: Groups into features, bug fixes, improvements, security, breaking changes +4. **Generates 3 Outputs**: + - **CHANGELOG.md section** (technical, complete) + - **PR Release body** (semi-technical, checklist) + - **Slack message** (product-focused, user-friendly) +5. **Transforms Language**: Converts technical jargon to accessible messaging +6. **Migration Alert**: Displays prominent warning if database migrations are required + +## How to Use + +### Basic Usage + +``` +Generate release notes since last release +``` + +``` +Create release notes for version 0.18.0 +``` + +### With Specific Range + +``` +Generate release notes from v0.17.0 to HEAD +``` + +### Preview Only + +``` +Preview release notes without writing files +``` + +## Output Formats + +### 1. CHANGELOG.md Section + +Technical format for developers: + +```markdown +## [0.18.0] - 2025-12-08 + +### Objectif +[1-2 sentence summary] + +### Nouvelles Fonctionnalites +#### [Feature Name] (#PR) +- **Description**: ... +- **Impact**: ... + +### Corrections de Bugs +- **[Module]**: Description (#issue, Sentry ISSUE-XX) + +### Ameliorations Techniques +#### Performance / UI/UX / Architecture +- [Description] + +### Migrations Base de Donnees +[If applicable] + +### Statistiques +- PRs: X +- Features: Y +- Bugs: Z +``` + +### 2. PR Release Body + +Uses template from `.github/PULL_REQUEST_TEMPLATE/release.md`: +- Objective summary +- Features with specs links +- Bug fixes with Sentry references +- Improvements by category +- Migration instructions +- Deployment checklist + +### 3. Slack Announcement + +Product-focused format from `.github/COMMUNICATION_TEMPLATE/slack-release.md`: +- **PR link** included for traceability +- Non-technical language +- Focus on user impact (tuteurs, eleves, admin) +- Emojis for readability +- Statistics summary + +## Workflow Integration + +This skill integrates with the release workflow in CLAUDE.md Section VI.5: + +``` +1. Analyze commits: git log ..HEAD +2. Determine version number (MAJOR.MINOR.PATCH) +3. Generate 3 outputs +4. Create PR develop -> main with "Release" label +5. Update CHANGELOG.md +6. After merge: create git tag +7. Generate Slack announcement +``` + +## Tech-to-Product Transformation + +The skill automatically transforms technical language: + +| Technical | Product | +|-----------|---------| +| "Optimisation N+1 queries avec DataLoader" | "Chargement plus rapide des listes" | +| "Implementation embeddings AI avec pgvector" | "Nouvelle recherche intelligente d'activites" | +| "Correction scope permissions dans getPermissionScope()" | "Correction d'un bug d'acces aux sessions" | +| "Migration webpack -> Turbopack" | *Ne pas communiquer* | +| "Refactorisation hooks React" | *Ne pas communiquer* | +| "Fix N+1 in user loaders" | "Amelioration des performances" | +| "Add retry logic for Prisma P1001" | "Meilleure stabilite de connexion" | + +## Commit Categories + +Commits are categorized by conventional commit prefix: + +| Prefix | Category | Include in Slack? | +|--------|----------|-------------------| +| `feat:` | Nouvelles Fonctionnalites | Yes | +| `fix:` | Corrections de Bugs | Yes (if user-facing) | +| `perf:` | Performance | Yes (simplified) | +| `security:` | Securite | Yes | +| `refactor:` | Architecture | No | +| `chore:` | Maintenance | No | +| `docs:` | Documentation | No | +| `test:` | Tests | No | +| `style:` | Style | No | + +## Console Output Format + +When generating release notes, ALWAYS display a clear summary in the console with: + +### Migration Alert (CRITICAL) + +If migrations are detected, display prominently: + +``` +╔══════════════════════════════════════════════════════════════════╗ +║ ⚠️ [ATTENTION] MIGRATIONS BASE DE DONNÉES REQUISES ║ +╠══════════════════════════════════════════════════════════════════╣ +║ ║ +║ Cette release contient X migration(s) Prisma : ║ +║ ║ +║ • 20251210123456_add_activity_description ║ +║ • 20251211094532_update_session_status ║ +║ ║ +║ Action requise AVANT déploiement : ║ +║ → Exécuter : pnpm prisma migrate deploy ║ +║ ║ +╚══════════════════════════════════════════════════════════════════╝ +``` + +If NO migrations: + +``` +✅ [OK] Aucune migration base de données requise +``` + +### Detection Method + +Check for new migration files since last release: + +```bash +# Find new migrations since last tag +git diff ..HEAD --name-only -- prisma/migrations/ +``` + +## Example + +**User**: "Generate release notes since v0.17.0" + +**Output**: + +``` +Analyzing commits from v0.17.0 to HEAD... + +Found: +- 15 commits +- 8 PRs merged +- 2 new features +- 5 bug fixes +- 3 improvements + +╔══════════════════════════════════════════════════════════════════╗ +║ ⚠️ [ATTENTION] MIGRATIONS BASE DE DONNÉES REQUISES ║ +╠══════════════════════════════════════════════════════════════════╣ +║ Cette release contient 1 migration(s) Prisma : ║ +║ • 20251208143021_add_user_preferences ║ +║ Action requise : pnpm prisma migrate deploy ║ +╚══════════════════════════════════════════════════════════════════╝ + +--- CHANGELOG.md Section --- +[Technical format output] + +--- PR Release Body --- +[Semi-technical format output] + +--- Slack Announcement --- +[Product-focused format output] + +Write to files? (CHANGELOG.md, clipboard for PR/Slack) +``` + +## Commands Used + +```bash +# Get last release tag +git tag --sort=-v:refname | head -n 1 + +# List commits since tag +git log ..HEAD --oneline --no-merges + +# Get PR details +gh api repos/{owner}/{repo}/pulls/{number} + +# Get commit details +git show --stat +``` + +## Tips + +- Run from repository root +- Ensure `gh` CLI is authenticated +- Review generated content before publishing +- Adjust product language for your audience +- Use `--preview` to see output without writing + +## Reference Files + +- `assets/changelog-template.md` - CHANGELOG section template +- `assets/slack-template.md` - Slack announcement template +- `references/tech-to-product-mappings.md` - Transformation rules +- `references/commit-categories.md` - Categorization rules + +## Related Skills + +- `github-actions-templates` - For CI/CD workflows +- `changelog-generator` - Original inspiration (ComposioHQ) diff --git a/examples/skills/release-notes-generator/assets/README.md b/examples/skills/release-notes-generator/assets/README.md new file mode 100644 index 0000000..c0e0b41 --- /dev/null +++ b/examples/skills/release-notes-generator/assets/README.md @@ -0,0 +1,18 @@ +# Assets + +This directory contains templates, images, and boilerplate code. + +**Note**: Assets are NOT automatically loaded into context. They must be explicitly referenced. + +## Guidelines + +- Use descriptive filenames +- Include usage instructions in file headers +- Keep templates minimal and customizable + +## Files + +Add your assets here. Examples: +- `template.md` - Output template +- `boilerplate.ts` - Code boilerplate +- `config.json` - Configuration template diff --git a/examples/skills/release-notes-generator/assets/changelog-template.md b/examples/skills/release-notes-generator/assets/changelog-template.md new file mode 100644 index 0000000..ca394b9 --- /dev/null +++ b/examples/skills/release-notes-generator/assets/changelog-template.md @@ -0,0 +1,93 @@ +# CHANGELOG Section Template + +Use this template for generating CHANGELOG.md entries. + +```markdown +## [X.Y.Z] - YYYY-MM-DD + +### Objectif +[Resume en 1-2 phrases de cette release] + +### Nouvelles Fonctionnalites + +#### [Feature Name] (#PR_NUMBER) +- **Description** : [Description fonctionnelle claire] +- **Spec Notion** : [Lien vers la spec si disponible] +- **Composants impactes** : `component-a`, `service-b`, etc. +- **Impact** : [Qui est concerne : Tuteurs / Eleves / Admin / Tous] + +### Corrections de Bugs + +#### [Module/Composant] (#PR_NUMBER) +- **Issue** : [Description du bug] +- **Cause** : [Cause racine identifiee] +- **Fix** : [Description de la correction] +- **Sentry** : METHODE-ARISTOTE-APP-XX (si applicable) + +### Ameliorations Techniques + +#### Performance +- [Description optimisation avec impact mesurable si possible] + +#### UI/UX +- [Description amelioration interface] + +#### Architecture +- [Description refactoring important] + +### Securite +- **[CVE-XXXX-XXXXX]** : [Description et impact] + +### Migrations Base de Donnees + +#### Processus de Deploiement + +**Etape 1 : Appliquer les migrations Prisma** +```bash +pnpm prisma migrate deploy +``` + +**Etape 2 : Scripts de data migration** (si applicable) +```bash +pnpm dotenv -e .env.production -- tsx scripts/db/migrations/[script-name].ts +``` + +**Verification post-migration** +```sql +-- Requetes de verification +SELECT COUNT(*) FROM [table]; +``` + +### Breaking Changes + +**Aucun** ou: + +- **[Composant/API]** : Description du breaking change + - **Migration requise** : Comment migrer + - **Impact** : Qui est affecte + +### Deprecations + +**Aucune** ou: + +- **[Fonctionnalite X]** : Depreciee dans cette version + - **Raison** : Pourquoi + - **Alternative** : Quoi utiliser a la place + - **Suppression prevue** : Version X.Y.Z + +### Tests +- [X] tests unitaires pour [feature] +- [X] tests d'integration pour [module] + +### Statistiques +- **PRs** : #XX, #YY, #ZZ +- **Fichiers impactes** : XX+ +- **Nouvelles tables** : [liste si applicable] +- **Migrations Prisma** : X migrations +- **Breaking changes** : 0 + +### Liens +- PR: https://github.com/methode-aristote/app/pull/XXX +- PRs incluses : #XX, #YY, #ZZ +- Issues Sentry : METHODE-ARISTOTE-APP-XX +``` diff --git a/examples/skills/release-notes-generator/assets/slack-template.md b/examples/skills/release-notes-generator/assets/slack-template.md new file mode 100644 index 0000000..76f032a --- /dev/null +++ b/examples/skills/release-notes-generator/assets/slack-template.md @@ -0,0 +1,85 @@ +# Slack Announcement Template + +Use this template for generating product-focused Slack messages. + +``` +Version X.Y.Z - Deployee en production + +PR : [URL de la PR de release, ex: https://github.com/methode-aristote/app/pull/XXX] + +En bref : [Phrase decrivant l'objectif principal de cette release] + +--- + +Nouvelles fonctionnalites + +[Nom Feature 1] +> [Description en 1-2 phrases de ce que ca apporte aux utilisateurs] +> Qui est concerne : [Tuteurs / Eleves / Admin / Tous] + +[Nom Feature 2] +> [Description en 1-2 phrases] +> Qui est concerne : [Roles] + +--- + +Corrections importantes + +- [Description du bug corrige en langage utilisateur] +- [Description du bug corrige en langage utilisateur] + +--- + +Ameliorations + +- [Amelioration UX/UI ou workflow en langage utilisateur] +- [...] + +--- + +En chiffres + +- X nouvelles fonctionnalites +- Y bugs corriges +- Z ameliorations + +--- + +Questions ? Contactez @florian ou l'equipe tech +``` + +## Guidelines + +### A FAIRE +- Utiliser un langage accessible (pas de jargon technique) +- Focus sur l'impact utilisateur +- Etre concis (max 10 lignes par section) +- Utiliser des emojis avec parcimonie + +### A EVITER +- "Implementation du pattern DataLoader pour resoudre les N+1 queries" +- "Refactorisation complete du systeme de permissions avec scope ANY/ASSIGNED" +- "Migration de webpack vers Turbopack" + +### Transformation Tech -> Produit + +| Technique | Produit | +|-----------|---------| +| Optimisation N+1 queries avec DataLoader | Chargement plus rapide des listes d'utilisateurs et de sessions | +| Implementation embeddings AI avec pgvector | Nouvelle recherche intelligente d'activites similaires | +| Correction scope permissions dans getPermissionScope() | Correction d'un bug qui empechait certains utilisateurs d'acceder a leurs sessions | +| Migration vers kebab-case pour les fichiers | *Ne pas communiquer (purement technique)* | +| Fix Prisma P1001 avec retry logic | Meilleure stabilite de connexion a la base de donnees | +| Add Sentry monitoring for orphan chats | Detection automatique des conversations orphelines | + +### Sections Optionnelles + +Si la release contient des elements importants, ajouter: + +Points d'attention +- [Information importante que les utilisateurs doivent savoir] +- [Changement de comportement qu'ils pourraient remarquer] + +A venir prochainement +- [Teaser de la prochaine grosse feature] +- [Feature en cours de developpement qui arrive bientot] diff --git a/examples/skills/release-notes-generator/references/README.md b/examples/skills/release-notes-generator/references/README.md new file mode 100644 index 0000000..98bb9c3 --- /dev/null +++ b/examples/skills/release-notes-generator/references/README.md @@ -0,0 +1,17 @@ +# References + +This directory contains documentation that will be loaded contextually during skill execution. + +## Guidelines + +- Keep files focused and well-organized +- Use markdown format for readability +- Include concrete examples where possible +- Update when domain knowledge changes + +## Files + +Add your reference documents here. Examples: +- `api-docs.md` - API documentation +- `style-guide.md` - Formatting guidelines +- `domain-knowledge.md` - Domain-specific information diff --git a/examples/skills/release-notes-generator/references/commit-categories.md b/examples/skills/release-notes-generator/references/commit-categories.md new file mode 100644 index 0000000..05fef0d --- /dev/null +++ b/examples/skills/release-notes-generator/references/commit-categories.md @@ -0,0 +1,124 @@ +# Commit Categorization Rules + +This document defines how to categorize commits based on Conventional Commits format. + +## Primary Categories + +### Features (`feat:`) +**CHANGELOG**: Nouvelles Fonctionnalites +**Slack**: Yes - always include +**Examples**: +- `feat(session): add parent report system` +- `feat(activity): add multi-level topics` +- `feat(search): add accent-insensitive search` + +### Bug Fixes (`fix:`) +**CHANGELOG**: Corrections de Bugs +**Slack**: Yes - if user-facing; No - if internal +**Examples**: +- `fix(session): correct status transition` -> Include in Slack +- `fix(test): correct mock setup` -> Do NOT include in Slack + +### Performance (`perf:`) +**CHANGELOG**: Ameliorations Techniques > Performance +**Slack**: Yes - simplified ("Performances ameliorees") +**Examples**: +- `perf(loader): optimize N+1 queries with batching` +- `perf(build): reduce bundle size by 30%` + +### Security (`security:` or `fix(security):`) +**CHANGELOG**: Securite +**Slack**: Yes - always, with appropriate detail level +**Examples**: +- `security: fix CVE-2025-55182 React2Shell RCE` +- `fix(security): prevent XSS in chat messages` + +## Secondary Categories (CHANGELOG only) + +### Refactoring (`refactor:`) +**CHANGELOG**: Ameliorations Techniques > Architecture +**Slack**: No +**Examples**: +- `refactor(hooks): migrate to new pattern` +- `refactor(permissions): extract to service layer` + +### Documentation (`docs:`) +**CHANGELOG**: Documentation (if significant) +**Slack**: No +**Examples**: +- `docs: update CLAUDE.md with new patterns` +- `docs(api): add tRPC endpoint documentation` + +### Tests (`test:`) +**CHANGELOG**: Tests (count only) +**Slack**: No +**Examples**: +- `test(activity): add prompt resolver tests` +- `test(e2e): add session workflow tests` + +### Chores (`chore:`) +**CHANGELOG**: No (unless significant) +**Slack**: No +**Examples**: +- `chore: update dependencies` +- `chore(ci): fix workflow permissions` + +### Style (`style:`) +**CHANGELOG**: No +**Slack**: No +**Examples**: +- `style: apply prettier formatting` +- `style(eslint): fix linting errors` + +## Scope Patterns + +Common scopes in Methode Aristote: + +| Scope | Area | +|-------|------| +| `session` | Session management | +| `activity` | Activities and prompts | +| `chat` | Chat and AI features | +| `user` | User management | +| `auth` | Authentication | +| `visio` | Video conferencing | +| `training` | Training/Formation system | +| `admin` | Admin panel | +| `calendar` | Calendar and scheduling | +| `permissions` | Permission system | +| `db` | Database and migrations | +| `api` | API endpoints | +| `ui` | UI components | + +## Breaking Changes + +Indicated by `!` after type/scope or `BREAKING CHANGE:` in footer: +- `feat(api)!: change session status enum` +- `fix(auth)!: require new token format` + +**CHANGELOG**: Breaking Changes section +**Slack**: Yes - with migration instructions + +## PR Number Extraction + +Extract PR numbers from: +1. Commit message: `(#123)` +2. Merge commit: `Merge pull request #123` +3. GitHub API: cross-reference with commit SHA + +## Sentry Issue Linking + +Match patterns: +- `Sentry: METHODE-ARISTOTE-APP-XX` +- `fixes METHODE-ARISTOTE-APP-XX` +- `closes #XX` (GitHub issue) + +## Statistics Calculation + +Count for release stats: +- **PRs**: Unique PR numbers +- **Features**: `feat:` commits +- **Bugs**: `fix:` commits (excluding test/internal) +- **Improvements**: `perf:` + `refactor:` + UI improvements +- **Security**: `security:` commits +- **Breaking**: Commits with `!` or `BREAKING CHANGE` \ No newline at end of file diff --git a/examples/skills/release-notes-generator/references/tech-to-product-mappings.md b/examples/skills/release-notes-generator/references/tech-to-product-mappings.md new file mode 100644 index 0000000..044613f --- /dev/null +++ b/examples/skills/release-notes-generator/references/tech-to-product-mappings.md @@ -0,0 +1,91 @@ +# Tech-to-Product Transformation Rules + +This document defines how to transform technical commit messages into user-friendly product language. + +## Transformation Categories + +### 1. COMMUNICATE (Transform to product language) + +| Technical Pattern | Product Message | +|-------------------|-----------------| +| `N+1 queries`, `DataLoader`, `batching` | "Chargement plus rapide des listes" | +| `embeddings`, `vector search`, `pgvector` | "Recherche intelligente amelioree" | +| `permissions`, `scope`, `access control` | "Correction d'un bug d'acces" | +| `retry logic`, `resilience`, `P1001` | "Meilleure stabilite de connexion" | +| `SSE`, `real-time`, `WebSocket` | "Mises a jour en temps reel" | +| `cache`, `memoization` | "Performances ameliorees" | +| `responsive`, `mobile` | "Meilleure experience mobile" | +| `accessibility`, `a11y`, `WCAG` | "Accessibilite amelioree" | +| `Sentry`, `monitoring`, `alerting` | "Meilleur suivi des erreurs" | +| `validation`, `sanitization` | "Securite renforcee" | + +### 2. DO NOT COMMUNICATE (Internal/Technical only) + +These patterns should NOT appear in Slack announcements: + +| Technical Pattern | Reason | +|-------------------|--------| +| `refactor`, `refactoring` | Internal code quality | +| `webpack`, `turbopack`, `bundler` | Build tooling | +| `eslint`, `prettier`, `linting` | Code style | +| `kebab-case`, `naming convention` | Internal standards | +| `TypeScript`, `type safety` | Developer experience | +| `test`, `spec`, `coverage` | Testing infrastructure | +| `chore`, `maintenance` | Routine maintenance | +| `docs`, `documentation` | Internal docs | +| `deps`, `dependencies`, `bump` | Dependency updates | +| `CI`, `CD`, `workflow` | DevOps infrastructure | + +### 3. SECURITY (Always communicate, simplified) + +| Technical | Product | +|-----------|---------| +| `CVE-XXXX-XXXXX` | "Correction d'une vulnerabilite de securite" | +| `XSS`, `injection` | "Renforcement de la protection des donnees" | +| `authentication`, `auth bypass` | "Securite de connexion amelioree" | +| `CORS`, `CSRF` | "Protection contre les attaques web" | + +## Context-Aware Transformations + +### Session-related +- "Fix session status transition" -> "Correction du suivi des seances" +- "Add session conflict detection" -> "Detection automatique des conflits de planning" +- "Improve visio sync" -> "Synchronisation video amelioree" + +### User-related +- "Fix user profile access" -> "Correction de l'acces aux profils" +- "Add accent-insensitive search" -> "Recherche amelioree (accents non sensibles)" +- "Improve user loader performance" -> "Chargement des utilisateurs plus rapide" + +### Activity-related +- "Fix activity prompt resolution" -> "Correction de l'affichage des activites" +- "Add multi-level topics" -> "Organisation des activites par niveau amelioree" +- "Improve embeddings generation" -> "Recherche d'activites similaires amelioree" + +### Chat-related +- "Fix streaming race condition" -> "Stabilite du chat amelioree" +- "Add vocal history" -> "Historique des messages vocaux" +- "Prevent empty messages" -> "Correction des messages vides" + +## Role-Based Impact + +Always specify who is affected: + +| Impact | Roles | +|--------|-------| +| Dashboard changes | Tuteurs, Eleves, Admin | +| Session management | Tuteurs, Admin | +| Activity library | Tuteurs, Admin | +| Chat/AI features | Tuteurs, Eleves | +| Admin panel | Admin only | +| Billing/Payment | Admin, Parents | +| Reports/Analytics | Admin, Tuteurs | + +## Severity Indicators + +Use these prefixes when appropriate: + +- **Critique** : Production-blocking issues +- **Important** : User-facing bugs +- **Mineur** : Quality of life improvements +- *Ne pas mentionner* : Internal fixes diff --git a/examples/skills/release-notes-generator/scripts/README.md b/examples/skills/release-notes-generator/scripts/README.md new file mode 100644 index 0000000..a5ca780 --- /dev/null +++ b/examples/skills/release-notes-generator/scripts/README.md @@ -0,0 +1,17 @@ +# Scripts + +This directory contains executable scripts for deterministic, repeatable tasks. + +## Guidelines + +- Scripts should be self-contained and well-documented +- Include usage examples in script headers +- Handle errors gracefully with clear messages +- Use appropriate exit codes (0 for success, 1 for failure) + +## Files + +Add your scripts here. Examples: +- `generate.py` - Main generation script +- `validate.py` - Validation utilities +- `transform.py` - Data transformation helpers diff --git a/examples/skills/skill-creator/SKILL.md b/examples/skills/skill-creator/SKILL.md new file mode 100644 index 0000000..fe697c0 --- /dev/null +++ b/examples/skills/skill-creator/SKILL.md @@ -0,0 +1,186 @@ +--- +name: skill-creator +description: Create new Claude Code skills with proper structure, YAML frontmatter, and bundled resources. Generates skill templates following best practices for modular, self-contained capability packages. +tags: [meta, skill, generator, claude-code] +--- + +# Skill Creator + +This skill helps you create new Claude Code skills with proper structure and best practices. + +## When to Use This Skill + +- Creating a new custom skill for your project +- Standardizing skill structure across your team +- Generating skill templates with scripts, references, and assets +- Packaging skills for distribution + +## Skill Structure + +A Claude skill consists of: + +``` +skill-name/ +├── SKILL.md # Required: Main skill file with YAML frontmatter +├── scripts/ # Optional: Executable code for deterministic tasks +├── references/ # Optional: Documentation loaded contextually +└── assets/ # Optional: Templates, images, boilerplate (not loaded into context) +``` + +## SKILL.md Format + +Every skill requires a `SKILL.md` file with: + +```markdown +--- +name: skill-name +description: One-line description of what the skill does and when to use it. +--- + +# Skill Name + +Brief introduction explaining the skill's purpose. + +## When to Use This Skill + +- Trigger condition 1 +- Trigger condition 2 +- Trigger condition 3 + +## What This Skill Does + +1. **Step 1**: Description +2. **Step 2**: Description +3. **Step 3**: Description + +## How to Use + +### Basic Usage +[Examples of how to invoke the skill] + +### With Options +[Advanced usage patterns] + +## Example + +**User**: "Example prompt" + +**Output**: +[Example output] + +## Tips + +- Best practice 1 +- Best practice 2 + +## Related Use Cases + +- Related task 1 +- Related task 2 +``` + +## How to Use + +### Create a New Skill + +``` +Create a new skill called "my-skill-name" in ~/.claude/skills/ +``` + +### Create with Specific Purpose + +``` +Create a skill for generating release notes from git commits, +with templates for CHANGELOG.md and Slack announcements +``` + +### Initialize Skill Structure + +Run the initialization script: + +```bash +python3 ~/.claude/skills/skill-creator/scripts/init_skill.py --path +``` + +### Package Skill for Distribution + +```bash +python3 ~/.claude/skills/skill-creator/scripts/package_skill.py [output-directory] +``` + +## Design Principles + +### Progressive Disclosure + +Context loads hierarchically to optimize token usage: +1. **Metadata** (~100 words): Always present via skill description +2. **SKILL.md** (<5k words): Loaded when skill is triggered +3. **Bundled resources**: Loaded as needed during execution + +### Organizational Patterns + +Choose the pattern that fits your skill: + +| Pattern | Best For | Structure | +|---------|----------|-----------| +| **Workflow-Based** | Sequential procedures | Step-by-step instructions | +| **Task-Based** | Multiple operations | Collection of tasks | +| **Reference/Guidelines** | Standards, specs | Rules and examples | +| **Capabilities-Based** | Interrelated features | Feature descriptions | + +### Naming Conventions + +- Use `kebab-case` for skill names: `release-notes-generator` +- Use descriptive names that indicate purpose +- Keep names concise but meaningful + +## Bundled Resources + +### scripts/ + +Executable code for deterministic, repeatable tasks: +- `init_skill.py` - Initialize new skill structure +- `package_skill.py` - Package skill for distribution + +### references/ + +Documentation loaded contextually: +- API documentation +- Style guides +- Domain knowledge + +### assets/ + +Templates and resources (not auto-loaded): +- Output templates +- Boilerplate code +- Images and fonts + +## Example: Creating a Release Notes Skill + +**User**: "Create a skill for generating release notes with 3 output formats: CHANGELOG.md, PR body, and Slack message" + +**Steps**: +1. Initialize structure: `init_skill.py release-notes-generator --path ~/.claude/skills/` +2. Add templates to `assets/`: + - `changelog-template.md` + - `pr-release-template.md` + - `slack-template.md` +3. Add transformation rules to `references/`: + - `tech-to-product-mappings.md` +4. Complete `SKILL.md` with usage instructions +5. Package: `package_skill.py ~/.claude/skills/release-notes-generator` + +## Tips + +- Keep SKILL.md under 5000 words for efficient context usage +- Use references/ for domain knowledge that doesn't change often +- Put templates in assets/ so they're not auto-loaded +- Test your skill with real use cases before packaging +- Include concrete examples in your SKILL.md + +## Related Use Cases + +- Creating project-specific automation skills +- Building team-shared development workflows +- Packaging reusable Claude capabilities diff --git a/examples/skills/skill-creator/scripts/init_skill.py b/examples/skills/skill-creator/scripts/init_skill.py new file mode 100755 index 0000000..7891647 --- /dev/null +++ b/examples/skills/skill-creator/scripts/init_skill.py @@ -0,0 +1,228 @@ +#!/usr/bin/env python3 +""" +Initialize a new Claude Code skill with proper directory structure. + +Usage: + python3 init_skill.py --path + +Example: + python3 init_skill.py release-notes-generator --path ~/.claude/skills/ +""" + +import argparse +import os +import sys +from pathlib import Path + + +SKILL_MD_TEMPLATE = '''--- +name: {skill_name} +description: [One-line description of what this skill does and when to use it] +--- + +# {skill_title} + +[Brief introduction explaining the skill's purpose] + +## When to Use This Skill + +- [Trigger condition 1] +- [Trigger condition 2] +- [Trigger condition 3] + +## What This Skill Does + +1. **[Step 1]**: [Description] +2. **[Step 2]**: [Description] +3. **[Step 3]**: [Description] + +## How to Use + +### Basic Usage + +``` +[Example prompt that triggers this skill] +``` + +### With Options + +``` +[Advanced usage example with parameters] +``` + +## Example + +**User**: "[Example user prompt]" + +**Output**: +```markdown +[Example output from the skill] +``` + +## Tips + +- [Best practice 1] +- [Best practice 2] +- [Best practice 3] + +## Related Use Cases + +- [Related task 1] +- [Related task 2] +''' + +SCRIPTS_README = '''# Scripts + +This directory contains executable scripts for deterministic, repeatable tasks. + +## Guidelines + +- Scripts should be self-contained and well-documented +- Include usage examples in script headers +- Handle errors gracefully with clear messages +- Use appropriate exit codes (0 for success, 1 for failure) + +## Files + +Add your scripts here. Examples: +- `generate.py` - Main generation script +- `validate.py` - Validation utilities +- `transform.py` - Data transformation helpers +''' + +REFERENCES_README = '''# References + +This directory contains documentation that will be loaded contextually during skill execution. + +## Guidelines + +- Keep files focused and well-organized +- Use markdown format for readability +- Include concrete examples where possible +- Update when domain knowledge changes + +## Files + +Add your reference documents here. Examples: +- `api-docs.md` - API documentation +- `style-guide.md` - Formatting guidelines +- `domain-knowledge.md` - Domain-specific information +''' + +ASSETS_README = '''# Assets + +This directory contains templates, images, and boilerplate code. + +**Note**: Assets are NOT automatically loaded into context. They must be explicitly referenced. + +## Guidelines + +- Use descriptive filenames +- Include usage instructions in file headers +- Keep templates minimal and customizable + +## Files + +Add your assets here. Examples: +- `template.md` - Output template +- `boilerplate.ts` - Code boilerplate +- `config.json` - Configuration template +''' + + +def validate_skill_name(name: str) -> bool: + """Validate skill name follows kebab-case convention.""" + if not name: + return False + if not all(c.isalnum() or c == '-' for c in name): + return False + if name.startswith('-') or name.endswith('-'): + return False + if '--' in name: + return False + return True + + +def skill_name_to_title(name: str) -> str: + """Convert kebab-case skill name to Title Case.""" + return ' '.join(word.capitalize() for word in name.split('-')) + + +def create_skill(skill_name: str, output_path: str) -> bool: + """Create a new skill with proper directory structure.""" + + if not validate_skill_name(skill_name): + print(f"Invalid skill name: '{skill_name}'") + print(" Use kebab-case (e.g., 'my-skill-name')") + return False + + output_dir = Path(output_path).expanduser().resolve() + skill_dir = output_dir / skill_name + + if skill_dir.exists(): + print(f"Skill already exists: {skill_dir}") + return False + + try: + print(f"Creating skill: {skill_name}") + + skill_dir.mkdir(parents=True, exist_ok=True) + print(f" Created {skill_dir}") + + for subdir in ['scripts', 'references', 'assets']: + (skill_dir / subdir).mkdir(exist_ok=True) + print(f" Created {subdir}/") + + skill_title = skill_name_to_title(skill_name) + skill_md_content = SKILL_MD_TEMPLATE.format( + skill_name=skill_name, + skill_title=skill_title + ) + (skill_dir / 'SKILL.md').write_text(skill_md_content) + print(" Created SKILL.md") + + (skill_dir / 'scripts' / 'README.md').write_text(SCRIPTS_README) + (skill_dir / 'references' / 'README.md').write_text(REFERENCES_README) + (skill_dir / 'assets' / 'README.md').write_text(ASSETS_README) + print(" Created README files") + + print(f"\nSkill '{skill_name}' created successfully!") + print(f"\nLocation: {skill_dir}") + print("\nNext steps:") + print(" 1. Edit SKILL.md with your skill's instructions") + print(" 2. Add scripts to scripts/ for automation") + print(" 3. Add reference docs to references/") + print(" 4. Add templates to assets/") + print(f" 5. Test with: skill: \"{skill_name}\"") + + return True + + except Exception as e: + print(f"Error creating skill: {e}") + return False + + +def main(): + parser = argparse.ArgumentParser( + description='Initialize a new Claude Code skill' + ) + + parser.add_argument( + 'skill_name', + help='Name of the skill (kebab-case, e.g., "my-skill-name")' + ) + + parser.add_argument( + '--path', + required=True, + help='Output directory where skill folder will be created' + ) + + args = parser.parse_args() + + success = create_skill(args.skill_name, args.path) + sys.exit(0 if success else 1) + + +if __name__ == '__main__': + main() \ No newline at end of file diff --git a/examples/skills/skill-creator/scripts/package_skill.py b/examples/skills/skill-creator/scripts/package_skill.py new file mode 100755 index 0000000..d315ce2 --- /dev/null +++ b/examples/skills/skill-creator/scripts/package_skill.py @@ -0,0 +1,135 @@ +#!/usr/bin/env python3 +""" +Package a Claude Code skill into a distributable zip file. + +Usage: + python3 package_skill.py [output-directory] + +Example: + python3 package_skill.py ~/.claude/skills/my-skill ./dist +""" + +import argparse +import os +import sys +import zipfile +from pathlib import Path + + +def validate_skill(skill_path: Path) -> tuple[bool, list[str]]: + """Validate skill structure and return (is_valid, errors).""" + errors = [] + + # Check SKILL.md exists + skill_md = skill_path / 'SKILL.md' + if not skill_md.exists(): + errors.append("Missing required file: SKILL.md") + else: + # Check SKILL.md has frontmatter + content = skill_md.read_text() + if not content.startswith('---'): + errors.append("SKILL.md missing YAML frontmatter (must start with ---)") + elif content.count('---') < 2: + errors.append("SKILL.md frontmatter not properly closed (needs second ---)") + else: + # Check required frontmatter fields + frontmatter_end = content.index('---', 3) + frontmatter = content[3:frontmatter_end] + if 'name:' not in frontmatter: + errors.append("SKILL.md frontmatter missing 'name' field") + if 'description:' not in frontmatter: + errors.append("SKILL.md frontmatter missing 'description' field") + + return len(errors) == 0, errors + + +def package_skill(skill_path: str, output_dir: str = '.') -> bool: + """Package skill folder into a zip file.""" + + skill_dir = Path(skill_path).expanduser().resolve() + output_path = Path(output_dir).expanduser().resolve() + + # Validate skill folder exists + if not skill_dir.exists(): + print(f"Skill folder not found: {skill_dir}") + return False + + if not skill_dir.is_dir(): + print(f"Not a directory: {skill_dir}") + return False + + # Validate skill structure + print(f"Validating skill: {skill_dir.name}") + is_valid, errors = validate_skill(skill_dir) + + if not is_valid: + print("Validation failed:") + for error in errors: + print(f" - {error}") + return False + + print(" Validation passed") + + # Create output directory if needed + output_path.mkdir(parents=True, exist_ok=True) + + # Create zip file + zip_name = f"{skill_dir.name}.zip" + zip_path = output_path / zip_name + + try: + print(f"Packaging skill...") + + with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf: + for file_path in skill_dir.rglob('*'): + if file_path.is_file(): + # Skip common ignored files + if file_path.name.startswith('.'): + continue + if file_path.name == '__pycache__': + continue + if file_path.suffix == '.pyc': + continue + + arcname = file_path.relative_to(skill_dir.parent) + zipf.write(file_path, arcname) + print(f" Added: {arcname}") + + print(f"\nSkill packaged successfully!") + print(f"Output: {zip_path}") + print(f"Size: {zip_path.stat().st_size / 1024:.1f} KB") + + return True + + except Exception as e: + print(f"Error packaging skill: {e}") + if zip_path.exists(): + zip_path.unlink() + return False + + +def main(): + parser = argparse.ArgumentParser( + description='Package a Claude Code skill into a zip file' + ) + + parser.add_argument( + 'skill_path', + help='Path to the skill folder' + ) + + parser.add_argument( + 'output_dir', + nargs='?', + default='.', + help='Output directory for the zip file (default: current directory)' + ) + + args = parser.parse_args() + + success = package_skill(args.skill_path, args.output_dir) + sys.exit(0 if success else 1) + + +if __name__ == '__main__': + main() \ No newline at end of file