Improve CLI experience: enhanced skills + fix --version/-v flag handling

.kilo/skills/context7-docs/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: context7-docs
+description: Get documentation for a library from Context7. Use when you need up-to-date library documentation, API references, code examples, or specific topic information from Context7.
+license: MIT
+compatibility: Requires Node.js >=18. The @vedanth/context7 CLI can be installed globally, installed as a project dependency, or used via npx (zero install).
+metadata:
+  author: Kilo
+  version: "1.0.1"
+allowed-tools: Bash
+---
+
+# Context7 Documentation Fetch Skill
+
+This skill provides instructions for fetching library documentation using the c7 CLI tool from Context7.
+
+## Overview
+
+Context7 provides version-specific, up-to-date documentation for programming libraries and frameworks. This skill helps you retrieve documentation directly from the terminal.
+
+## How to Use
+
+### Basic Documentation Fetch
+
+```bash
+# Using docs subcommand explicitly
+c7 docs <library> [topic]
+
+# Using shorthand syntax (more convenient)
+c7 <library> [topic]
+
+# Using with npx (no installation required)
+npx @vedanth/context7 <library> [topic]
+```
+
+### Options
+
+- `--tokens <n>`: Maximum tokens to return (default: 5000)
+- `--api-key <key>`: Provide Context7 API key (or set CONTEXT7_API_KEY environment variable)
+
+### Examples
+
+```bash
+# Get React hooks documentation (using shorthand)
+c7 react hooks
+
+# Get React hooks documentation (using explicit docs subcommand)
+c7 docs react hooks
+
+# Get Next.js app router docs with more tokens
+c7 docs nextjs "app router" --tokens 10000
+
+# Get Express middleware documentation
+c7 express middleware
+
+# Get Tailwind CSS dark mode docs
+c7 tailwindcss "dark mode"
+
+# Use exact Context7 ID
+c7 docs /vercel/next.js "image optimization"
+
+# Use with npx (no installation required)
+npx @vedanth/context7 vue "composition api"
+```
+
+### Advanced Usage
+
+#### Piping Output
+
+```bash
+# Copy to clipboard (macOS)
+c7 react hooks | pbcopy
+
+# Copy to clipboard (Linux)
+c7 react hooks | xclip -selection clipboard
+
+# Save to file
+c7 express middleware >> docs.txt
+
+# Feed into LLM (if claude command is available)
+c7 nextjs "api routes" | claude "summarize these docs"
+
+# Process with other CLI tools
+c7 react "component lifecycle" | grep -A 5 -B 5 "useEffect"
+```
+
+#### Environment Variable
+
+Set your API key for higher rate limits:
+
+```bash
+export CONTEXT7_API_KEY=your-api-key-here
+```
+
+### Output Format
+
+Returns plain text documentation that can be piped to other tools, saved to files, or used in scripts.
+
+### Practical Use Cases
+
+1. **Quick API Reference Lookup**
+   ```bash
+   # Quickly find method signatures
+   c7 lodash "debounce" | head -10
+   ```
+
+2. **Integration With Coding Assistants**
+   ```bash
+   # Create a contextual prompt for an AI
+   c7 express "middleware" > express-middleware-docs.txt
+   echo "Using the following documentation, help me create middleware:" | cat - express-middleware-docs.txt | claude
+   ```
+
+3. **Automated Documentation Workflows**
+   ```bash
+   # Generate documentation snippets for a project
+   mkdir project-docs
+   c7 react "hooks" > project-docs/react-hooks.md
+   c7 redux "selectors" > project-docs/redux-selectors.md
+   ```
+
+### Error Handling
+
+- If the library name can't be resolved automatically, use `c7 resolve` first to find the exact ID
+- For version-specific docs, use the full Context7 ID path like `/vercel/next.js`
+- Check your API key if you hit rate limits
+- If getting "command not found" errors, ensure the CLI is properly installed or use npx
+
+### Installation Options
+
+Choose the best installation method for your needs:
+
+```bash
+# Option 1: Global installation (recommended for frequent use)
+npm install -g @vedanth/context7
+
+# Option 2: Use with npx (no installation required)
+npx @vedanth/context7 <library> [topic]
+
+# Option 3: Install as a project dependency
+npm install @vedanth/context7 --save-dev
+```
+
+### Troubleshooting
+
+Common issues and solutions:
+
+1. **"command not found"**: Install globally or use npx:
+   ```bash
+   # Install globally
+   npm install -g @vedanth/context7
+
+   # Or use npx for one-time use
+   npx @vedanth/context7 react hooks
+   ```
+
+2. **"No libraries found"**: The library name might differ from common assumptions:
+   ```bash
+   # Search for alternative names
+   c7 resolve vue
+   c7 resolve angular
+   ```
+
+3. **Rate limiting**: Set an API key to increase rate limits:
+   ```bash
+   export CONTEXT7_API_KEY=your-key-here
+   # Add to ~/.zshrc or ~/.bashrc for persistence
+   echo 'export CONTEXT7_API_KEY=your-key-here' >> ~/.zshrc
+   ```
+
+### Integration with Development Workflows
+
+1. **In Package.json Scripts**
+   ```json
+   {
+     "scripts": {
+       "docs-react": "c7 react 'hooks guide' > docs/react-hooks.md",
+       "docs-express": "c7 express middleware > docs/express-middleware.md"
+     }
+   }
+   ```
+
+2. **In CI/CD Pipelines**
+   ```bash
+   # Generate documentation artifacts during build
+   c7 "$FRAMEWORK" "best practices" > docs/$FRAMEWORK-best-practices.md
+   ```
+
+3. **With Editor Integration**
+   ```bash
+    # Create helper scripts for your editor
+    cat > ~/bin/context7-search << 'SCRIPT'
+#!/bin/bash
+c7 "$@"
+SCRIPT
+    chmod +x ~/bin/context7-search
+    ```
+
+### Use Cases
+
+- Quick API reference lookup
+- Getting code examples for specific features
+- Comparing documentation across versions
+- Feeding documentation into AI coding assistants
+- Building documentation into automation scripts
+- Creating project-specific documentation bundles
+- Onboarding new team members with relevant docs

.kilo/skills/context7-resolve/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: context7-resolve
+description: Find Context7 library IDs for a given library name. Use when you need to resolve library names to their Context7 identifiers for documentation retrieval.
+license: MIT
+compatibility: Requires Node.js >=18. The @vedanth/context7 CLI can be installed globally, installed as a project dependency, or used via npx (zero install).
+metadata:
+  author: Kilo
+  version: "1.0.1"
+allowed-tools: Bash
+---
+
+# Context7 Library Resolution Skill
+
+This skill provides instructions for resolving library names to Context7 identifiers using the c7 CLI tool.
+
+## Overview
+
+Context7 provides version-specific, up-to-date library documentation. Resolving a library name converts common names (e.g. "nextjs", "react") into Context7 canonical IDs (e.g. `/vercel/next.js`, `/facebook/react`), which can then be used with `c7 docs` for targeted documentation retrieval.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- You know the common name of a library but `c7 docs <name>` fails with "No libraries found"
+- You need to find the exact Context7 ID for version-specific or vendor-scoped documentation
+- You want to see what libraries are available before choosing one
+- You need to explore alternative naming conventions for a library
+
+## How to Use
+
+### Basic Resolution
+
+```bash
+c7 resolve <library-name>
+
+# Using shorthand alias
+c7 r <library-name>
+
+# Using with npx (no installation required)
+npx @vedanth/context7 resolve <library-name>
+
+# Using shorthand alias with npx
+npx @vedanth/context7 r <library-name>
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--json` | Output raw JSON instead of formatted text | off |
+| `--api-key <key>` | Context7 API key (or set CONTEXT7_API_KEY env var) | none |
+
+### Examples
+
+```bash
+# Simple lookup
+c7 resolve nextjs
+# → /vercel/next.js
+
+# Resolve with JSON output for programmatic use
+c7 resolve react --json
+
+# Disambiguate between similar libraries
+c7 resolve express
+c7 resolve koa
+
+# Explore available libraries
+c7 resolve state management
+c7 resolve css framework
+
+# Non-obvious naming
+c7 resolve rn  # React Native
+c7 resolve nv  # Neovim
+c7 resolve shadcn
+```
+
+### JSON Output Format
+
+When using `--json`, returns an array of results:
+
+```json
+[
+  {
+    "id": "/facebook/react",
+    "title": "React",
+    "description": "A JavaScript library for building user interfaces"
+  }
+]
+```
+
+### Working with Resolve Results
+
+#### Chain with docs in a script
+
+```bash
+# Resolve, extract ID, then fetch docs
+ID=$(c7 resolve react --json | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');process.stdout.write(JSON.parse(d)[0].id)")
+c7 docs "$ID" "hooks"
+```
+
+#### Use shorthands for known libraries
+
+Once you know the ID, you can use it directly:
+
+```bash
+c7 docs /facebook/react hooks
+c7 docs /vercel/next.js "app router"
+```
+
+### Error Handling
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "No libraries found for X" | Library not in Context7 index | Try synonyms, check spelling, or use a more general query |
+| "Search failed: 429" | Rate limited | Set `CONTEXT7_API_KEY` for higher limits |
+| "Error: fetch failed" | Network issue | Check internet connection |
+| "command not found: c7" | CLI not installed | Use `npx @vedanth/context7` or run `npm install -g @vedanth/context7` |
+
+### When Resolution Fails
+
+If `c7 resolve` returns no results, try these strategies in order:
+
+1. **Use a more general name**: `react` → `reactjs`, `vue` → `vuejs`
+2. **Try the ecosystem name**: `chakra` → `chakra-ui`, `tailwind` → `tailwindcss`
+3. **Search by category**: `c7 resolve css framework` or `c7 resolve react component library`
+4. **Use the library's GitHub org/repo name**: Look at the library's GitHub URL and try `/org/repo` format
+5. **Check if it needs version qualification**: Some libraries have multiple version IDs
+
+### Installation Options
+
+```bash
+# Global install (recommended for frequent use)
+npm install -g @vedanth/context7
+
+# Use with npx (zero install)
+npx @vedanth/context7 resolve <library>
+
+# Project install
+npm install @vedanth/context7 --save-dev
+```
+
+### Integration Patterns
+
+#### In Makefile
+
+```makefile
+resolve-lib:
+	@c7 resolve $(LIB) --json | node -e "\
+		const data = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));\
+		data.forEach(r => console.log(r.id, '-', r.description));"
+
+docs:
+	c7 docs $(shell c7 resolve $(LIB) --json | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');process.stdout.write(JSON.parse(d)[0].id)") "$(TOPIC)"
+```
+
+#### In Automation Scripts
+
+```bash
+#!/usr/bin/env bash
+# fetch-docs.sh — resolve and fetch docs in one step
+LIB=$1
+TOPIC=$2
+ID=$(npx @vedanth/context7 r "$LIB" --json | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');process.stdout.write(JSON.parse(d)[0].id)")
+npx @vedanth/context7 docs "$ID" "$TOPIC"
+```
+
+### Frequently Resolved Libraries
+
+| Common Name | Context7 ID |
+|-------------|-------------|
+| react | `/facebook/react` |
+| nextjs | `/vercel/next.js` |
+| express | `/expressjs/express` |
+| tailwindcss | `/tailwindlabs/tailwindcss` |
+| vue | `/vuejs/core` |
+| prisma | `/prisma/prisma` |
+| lodash | `/lodash/lodash` |
+| axios | `/axios/axios` |