share-skill

What this skill does

# Share Skill

Migrate user's locally created temporary skills to a project repository via symlinks, and initialize Git for version tracking.

## Usage

| Command | Description |
|---------|-------------|
| `/share-skill <skill-name>` | Migrate specified skill to code repository and initialize git |
| `/share-skill config` | Configure code_root and other settings |
| `/share-skill <skill-name> --remote <url>` | Migrate and configure remote URL |
| `/share-skill list` | List all local skills available for migration |
| `/share-skill remote <alias> <endpoint>` | Configure Git remote alias |
| `/share-skill remote list` | List configured remote aliases |
| `/share-skill docs` | Generate documentation website for the repository |
| `/share-skill docs --style <name>` | Generate docs with specified design style |
| `/share-skill docs --skill <ui-skill>` | Use specified UI skill to design docs |
| `/share-skill docs config` | Configure default design style or UI skill |
| `/share-skill allow` | One-time authorization for this skill's permissions |
| Natural language | e.g., "Help me open source port-allocator and push to github" |

## Configuration File

All settings are stored in `~/.claude/share-skill-config.json`:

```json
{
  "code_root": "~/Codes",
  "skills_repo": "skills",
  "github_username": "guo-yu",
  "remotes": {
    "github": "[email protected]:guo-yu/skills",
    "gitlab": "[email protected]:guo-yu/skills"
  },
  "default_remote": "github",
  "auto_detected": true,
  "docs": {
    "style": "botanical",
    "custom_skill": null,
    "custom_domain": null
  }
}
```

**Configuration Fields:**

| Field | Description | Default |
|-------|-------------|---------|
| `code_root` | Base directory for code repositories | `~/Codes` |
| `skills_repo` | Name of skills repository folder | `skills` |
| `github_username` | GitHub username for URLs | Auto-detected |
| `remotes` | Git remote aliases | Auto-configured |
| `docs.custom_domain` | Custom domain for docs site | `null` (use GitHub Pages) |

**Path Variables:**

Throughout this document, the following variables are used:
- `{code_root}` → Value of `code_root` config (e.g., `~/Codes`)
- `{skills_repo}` → Value of `skills_repo` config (e.g., `skills`)
- `{skills_path}` → `{code_root}/{skills_repo}` (e.g., `~/Codes/skills`)
- `{username}` → Value of `github_username` config

### Auto-detection on First Run

On first invocation of share-skill, it automatically detects settings:

**Auto-detection Logic:**

1. **Check if config file exists**
   ```bash
   if [ ! -f ~/.claude/share-skill-config.json ]; then
     # First run, perform auto-detection
   fi
   ```

2. **Detect code_root directory**
   ```bash
   # Check common code directory locations in order
   for dir in ~/Codes ~/Code ~/Projects ~/Dev ~/Development ~/repos; do
     if [ -d "$dir" ]; then
       CODE_ROOT="$dir"
       break
     fi
   done

   # If none found, default to ~/Codes
   CODE_ROOT="${CODE_ROOT:-~/Codes}"
   ```

3. **Read Git global config for username**
   ```bash
   # Try to get username
   USERNAME=$(git config --global user.name)

   # If username contains spaces, try extracting from GitHub email
   if [[ "$USERNAME" == *" "* ]]; then
     EMAIL=$(git config --global user.email)
     # Extract from [email protected]
     USERNAME=$(echo "$EMAIL" | grep -oP '^\d+-?\K[^@]+(?=@users\.noreply\.github\.com)')
   fi

   # If still unable to determine, try extracting from remote URL
   if [ -z "$USERNAME" ]; then
     USERNAME=$(git config --global --get-regexp "url.*github.com" | grep -oP 'github\.com[:/]\K[^/]+' | head -1)
   fi
   ```

4. **Generate default config**
   ```json
   {
     "code_root": "<detected-code-root>",
     "skills_repo": "skills",
     "github_username": "<detected-username>",
     "remotes": {
       "github": "[email protected]:<detected-username>/skills"
     },
     "default_remote": "github",
     "auto_detected": true,
     "docs": {
       "style": "botanical",
       "custom_skill": null,
       "custom_domain": null
     }
   }
   ```

5. **Output detection result**
   ```
   First run, auto-detecting settings...

   Detected settings:
     Code root: ~/Codes
     GitHub username: guo-yu

   Auto-configured:
     Skills path: ~/Codes/skills
     Remote: [email protected]:guo-yu/skills

   Config file: ~/.claude/share-skill-config.json

   To modify, use:
     /share-skill config
   ```

### Command: `/share-skill config`

Interactive configuration for share-skill settings:

**TUI Interface (AskUserQuestion):**
```
Configure share-skill settings:

Code root directory:
  Current: ~/Codes
  [ ] ~/Codes
  [ ] ~/Code
  [ ] ~/Projects
  [ ] Other... (enter custom path)

Custom domain for documentation:
  Current: (none - using GitHub Pages)
  [ ] No custom domain (use {username}.github.io/{repo})
  [ ] Enter custom domain...
```

**Implementation:**
```bash
# Read current config
CONFIG=$(cat ~/.claude/share-skill-config.json 2>/dev/null || echo '{}')

# After user selection, update config
# Example: Update code_root
jq --arg root "$NEW_CODE_ROOT" '.code_root = $root' <<< "$CONFIG" > ~/.claude/share-skill-config.json
```

### Handling Detection Failure

If settings cannot be auto-detected, prompt user to configure:

```
Unable to auto-detect settings

Please configure manually:
  /share-skill config

Or specify when migrating:
  /share-skill <skill-name> --remote [email protected]:your-username/skills.git
```

## Natural Language Invocation

When user invokes via natural language, intelligent analysis is needed:

### 1. Identify User's Referenced Skill

User might say:
- "Help me open source xxx skill" -> Extract skill name `xxx`
- "Share the skill I just created" -> Find most recently modified skill
- "Migrate this skill to repository" -> Determine from current context
- "Open source port-allocator" -> Use name directly

### 2. Identify Remote Address

**Default behavior:** Use auto-detected username + default repository name `skills`

User might say:
- "Help me open source xxx" -> Use default: `[email protected]:<username>/skills/<skill-name>.git`
- "push to github" -> Use default github config
- "Push to [email protected]:other-user/repo.git" -> **Must explicitly specify full address**
- "Open source to my my-tools repository" -> **Must explicitly specify repository name**

**Important rule: Modifying remote path requires explicit specification**

If user wants to use non-default remote path, must **explicitly specify** via:

1. **Explicit command-line specification**
   ```bash
   /share-skill <skill-name> --remote [email protected]:other-user/other-repo.git
   ```

2. **Explicit path in natural language**
   ```
   OK: "Help me push port-allocator to [email protected]:my-org/tools.git"
   OK: "Open source to gitlab, address is [email protected]:team/shared-skills.git"

   NOT OK: "Help me push to somewhere else" (unclear, will ask for specific address)
   NOT OK: "Use another repository" (unclear, will ask for specific address)
   ```

**Address Resolution Rules:**
```
"Help me open source xxx"
  -> Use default config: [email protected]:<auto-detected-user>/skills
  -> Final address: [email protected]:<user>/skills/<skill-name>.git

"Push to [email protected]:other-user/repo.git"
  -> Detected full address, use directly

"Open source to gitlab" (gitlab not configured)
  -> Prompt: Please specify full GitLab address
```

### 3. Auto-search Skill Location

Skills may exist at the following locations, searched by priority:

```bash
# 1. Standard skills directory
~/.claude/skills/<skill-name>/SKILL.md

# 2. User custom skills directory
~/.claude/skills/*/<skill-name>/SKILL.md

# 3. Standalone skill file
~/.claude/skills/<skill-name>.md

# 4. Project-level skills (current working directory)
.claude/skills/<skill-name>/SKILL.md
```

**Search command:**
```bash
# Search for directories containing SKILL.md under ~/.claude
find ~/.claude -name "SKILL.md" -type f 2>/dev/null | while read f; do
  dir=$(dirname "$f")
  name=$(basename "$d