feat: add Claude Code skill for Bit CLI reference

contrib/claude-skill-bit-cli/README.md

@@ -0,0 +1,94 @@
+# Bit CLI Skill for Claude Code
+
+This skill provides Claude Code with accurate Bit CLI command reference, eliminating trial-and-error when running bit commands.
+
+## Installation
+
+### Quick Install (recommended)
+
+```bash
+# Create the skill directory
+mkdir -p ~/.claude/skills/bit-cli
+
+# Download the skill files
+curl -fsL https://raw.githubusercontent.com/teambit/bit/master/contrib/claude-skill-bit-cli/SKILL.md \
+  -o ~/.claude/skills/bit-cli/SKILL.md
+
+curl -fsL https://raw.githubusercontent.com/teambit/bit/master/contrib/claude-skill-bit-cli/bit-cli-lookup \
+  -o ~/.claude/skills/bit-cli/bit-cli-lookup
+
+# Make the lookup script executable
+chmod +x ~/.claude/skills/bit-cli/bit-cli-lookup
+
+# Download the CLI reference (or let it auto-download on first use)
+~/.claude/skills/bit-cli/bit-cli-lookup --update
+```
+
+### One-liner
+
+```bash
+mkdir -p ~/.claude/skills/bit-cli && cd ~/.claude/skills/bit-cli && curl -fsLO https://raw.githubusercontent.com/teambit/bit/master/contrib/claude-skill-bit-cli/SKILL.md && curl -fsLO https://raw.githubusercontent.com/teambit/bit/master/contrib/claude-skill-bit-cli/bit-cli-lookup && chmod +x bit-cli-lookup && ./bit-cli-lookup --update
+```
+
+### Manual Install
+
+1. Copy the following files to `~/.claude/skills/bit-cli/`:
+
+   - `SKILL.md`
+   - `bit-cli-lookup`
+
+2. Make the lookup script executable:
+
+   ```bash
+   chmod +x ~/.claude/skills/bit-cli/bit-cli-lookup
+   ```
+
+3. Download the CLI reference:
+   ```bash
+   ~/.claude/skills/bit-cli/bit-cli-lookup --update
+   ```
+
+## Requirements
+
+- `jq` - JSON processor (install with `brew install jq` or `apt install jq`)
+- `curl` - For downloading updates
+
+## How It Works
+
+1. Claude Code automatically discovers this skill when you ask about bit commands
+2. Instead of loading the full 5000+-line CLI reference, Claude runs the lookup script
+3. The script returns only the relevant command info (~20-50 lines)
+4. Claude uses the accurate flags without trial-and-error
+
+## Usage (for humans)
+
+You can also use the lookup script directly:
+
+```bash
+# Look up a specific command
+~/.claude/skills/bit-cli/bit-cli-lookup snap
+~/.claude/skills/bit-cli/bit-cli-lookup tag
+~/.claude/skills/bit-cli/bit-cli-lookup export
+
+# List all commands
+~/.claude/skills/bit-cli/bit-cli-lookup --list
+
+# Update to latest CLI reference
+~/.claude/skills/bit-cli/bit-cli-lookup --update
+```
+
+## Keeping Updated
+
+The CLI reference is fetched from the Bit repository. To update:
+
+```bash
+~/.claude/skills/bit-cli/bit-cli-lookup --update
+```
+
+## Troubleshooting
+
+**"jq not found"**: Install jq with your package manager
+
+**"CLI reference not found"**: Run `bit-cli-lookup --update` to download it
+
+**Command not found**: Check spelling, or run `bit-cli-lookup --list` to see available commands

contrib/claude-skill-bit-cli/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: bit-cli
+description: Bit CLI command reference with all flags and options. Use this skill BEFORE running any bit command to get the correct syntax, flags, and arguments. Covers all bit commands including snap, tag, export, import, install, status, compile, test, add, remove, and 100+ more.
+---
+
+# Bit CLI Reference
+
+This skill provides accurate command syntax for the Bit CLI. **Always use the lookup script before running bit commands** to avoid trial-and-error with flags.
+
+## Usage
+
+To find the correct syntax for any bit command:
+
+```bash
+~/.claude/skills/bit-cli/bit-cli-lookup <command-name>
+```
+
+### Examples
+
+```bash
+# Get snap command syntax
+~/.claude/skills/bit-cli/bit-cli-lookup snap
+
+# Get tag command syntax
+~/.claude/skills/bit-cli/bit-cli-lookup tag
+
+# Get export command syntax
+~/.claude/skills/bit-cli/bit-cli-lookup export
+
+# Search for commands containing "env"
+~/.claude/skills/bit-cli/bit-cli-lookup env
+
+# List all available commands
+~/.claude/skills/bit-cli/bit-cli-lookup --list
+```
+
+## Important Notes
+
+- The lookup returns the exact flags with short (`-m`) and long (`--message`) forms
+- Subcommands are included (e.g., `env set`, `env get`, `lane merge`)
+- Arguments show whether they're required `<arg>` or optional `[arg]`
+- Always check before using unfamiliar flags
+
+## Common Commands Quick Reference
+
+| Command   | Description                       |
+| --------- | --------------------------------- |
+| `snap`    | Create a snapshot (dev version)   |
+| `tag`     | Create a semver release version   |
+| `export`  | Push components to remote scope   |
+| `import`  | Pull components from remote scope |
+| `install` | Install dependencies              |
+| `status`  | Show workspace status             |
+| `compile` | Compile components                |
+| `test`    | Run component tests               |
+| `build`   | Run full build pipeline           |
+| `add`     | Track new components              |
+| `remove`  | Remove components                 |
+| `lane`    | Work with lanes (branches)        |

contrib/claude-skill-bit-cli/bit-cli-lookup

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+#
+# bit-cli-lookup - Query Bit CLI command reference
+# Usage: bit-cli-lookup <command-name>
+#        bit-cli-lookup --list
+#        bit-cli-lookup --update
+#
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI_REF="$SCRIPT_DIR/cli-reference.json"
+CLI_REF_URL="https://raw.githubusercontent.com/teambit/bit/master/scopes/harmony/cli-reference/cli-reference.json"
+
+# Colors (disabled if not a terminal)
+if [ -t 1 ]; then
+    BOLD='\033[1m'
+    DIM='\033[2m'
+    CYAN='\033[36m'
+    GREEN='\033[32m'
+    YELLOW='\033[33m'
+    RESET='\033[0m'
+else
+    BOLD='' DIM='' CYAN='' GREEN='' YELLOW='' RESET=''
+fi
+
+usage() {
+    echo "Usage: bit-cli-lookup <command-name>"
+    echo "       bit-cli-lookup --list      List all commands"
+    echo "       bit-cli-lookup --update    Update CLI reference from GitHub"
+    echo ""
+    echo "Examples:"
+    echo "  bit-cli-lookup snap"
+    echo "  bit-cli-lookup tag"
+    echo "  bit-cli-lookup lane"
+    exit 1
+}
+
+check_jq() {
+    if ! command -v jq &> /dev/null; then
+        echo "Error: jq is required but not installed."
+        echo "Install jq using your system's package manager (e.g. 'brew install jq' on macOS or 'apt install jq' on Debian/Ubuntu)"
+        exit 1
+    fi
+}
+
+check_cli_ref() {
+    if [ ! -f "$CLI_REF" ]; then
+        echo "CLI reference not found. Downloading..."
+        update_cli_ref
+    fi
+}
+
+update_cli_ref() {
+    echo "Updating CLI reference from GitHub..."
+    if curl -fsL "$CLI_REF_URL" -o "$CLI_REF.tmp"; then
+        # Validate that the downloaded file is valid JSON before replacing the existing reference
+        if jq empty "$CLI_REF.tmp" >/dev/null 2>&1; then
+            mv "$CLI_REF.tmp" "$CLI_REF"
+            echo "Updated successfully."
+        else
+            echo "Error: Downloaded CLI reference is not valid JSON."
+            rm -f "$CLI_REF.tmp"
+            exit 1
+        fi
+    else
+        echo "Error: Failed to download CLI reference."
+        rm -f "$CLI_REF.tmp"
+        exit 1
+    fi
+}
+
+list_commands() {
+    echo -e "${BOLD}Available Bit Commands:${RESET}\n"
+    jq -r '
+        .[] |
+        select(.private != true) |
+        "  \(.name)\(.alias | if . != "" then " (alias: \(.))" else "" end)"
+    ' "$CLI_REF" | sort
+}
+
+format_command() {
+    jq -r --arg cmd "$1" '
+        def format_cmd:
+            . as $c |
+            "\n\u001b[1m\u001b[36mCommand: bit \(.name)\u001b[0m" +
+            (if .alias != "" then "\n\u001b[2mAlias: \(.alias)\u001b[0m" else "" end) +
+            "\n\n\(.description)" +
+            (if .extendedDescription != "" then "\n\n\(.extendedDescription)" else "" end) +
+
+            # Arguments
+            (if (.arguments // []) | length > 0 then
+                "\n\n\u001b[1mArguments:\u001b[0m\n" +
+                ([.arguments[] | "  \(.name): \(.description // "")"] | join("\n"))
+            else "" end) +
+
+            # Options
+            (if (.options // []) | length > 0 then
+                "\n\n\u001b[1mOptions:\u001b[0m\n" +
+                ([.options[] |
+                    "  " +
+                    (if .[0] != "" then "-\(.[0]), " else "    " end) +
+                    "--\(.[1])" +
+                    (if .[2] != "" then "\n      \(.[2])" else "" end)
+                ] | join("\n"))
+            else "" end) +
+
+            # Examples
+            (if (.examples // []) | length > 0 then
+                "\n\n\u001b[1mExamples:\u001b[0m\n" +
+                ([.examples[] | "  bit \(.cmd)\n      \(.description)"] | join("\n"))
+            else "" end) +
+
+            # Subcommands
+            (if (.commands // []) | length > 0 then
+                "\n\n\u001b[1mSubcommands:\u001b[0m\n" +
+                ([.commands[] | "  \(.name): \(.description)"] | join("\n"))
+            else "" end);
+
+        # Search for matching commands (main commands and subcommands)
+        [
+            # Match main commands
+            (.[] | select(
+                (.name | ascii_downcase | split(" ")[0]) == ($cmd | ascii_downcase) or
+                (.name | ascii_downcase | startswith($cmd | ascii_downcase)) or
+                (.alias | ascii_downcase) == ($cmd | ascii_downcase)
+            )),
+            # Match subcommands
+            (.[] | .commands // [] | .[] | select(
+                (.name | ascii_downcase) == ($cmd | ascii_downcase) or
+                (.name | ascii_downcase | startswith($cmd | ascii_downcase))
+            ))
+        ] |
+        if length == 0 then
+            "No command found matching: \($cmd)\n\nTry: bit-cli-lookup --list"
+        else
+            .[] | format_cmd
+        end
+    ' "$CLI_REF"
+}
+
+# Main
+check_jq
+
+case "${1:-}" in
+    "")
+        usage
+        ;;
+    --help|-h)
+        usage
+        ;;
+    --list|-l)
+        check_cli_ref
+        list_commands
+        ;;
+    --update|-u)
+        update_cli_ref
+        ;;
+    *)
+        check_cli_ref
+        format_command "$1"
+        ;;
+esac