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

## Plugin Marketplace

share-skill automatically creates a Claude Code Plugin Marketplace structure, enabling users to install skills via the `/plugin` command.

### Installation via Marketplace

Once your skills repository is set up, users can install skills with:

```bash
# Add the marketplace (one-time setup)
/plugin marketplace add {username}/{skills_repo}

# Install individual skills
/plugin install port-allocator@{username}-{skills_repo}
/plugin install share-skill@{username}-{skills_repo}
```

### Marketplace Structure

The repository requires two types of manifest files:

**1. Root marketplace.json** (`{skills_path}/.claude-plugin/marketplace.json`):
```json
{
  "name": "{username}-{skills_repo}",
  "owner": {
    "name": "{display-name}",
    "email": "{username}@users.noreply.github.com"
  },
  "metadata": {
    "description": "A collection of productivity skills for Claude Code",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "skill-name",
      "source": "./skill-name",
      "description": "Skill description from SKILL.md frontmatter"
    }
  ]
}
```

**2. Plugin manifest** (`{skills_path}/<skill-name>/.claude-plugin/plugin.json`):
```json
{
  "name": "skill-name",
  "description": "Skill description",
  "version": "1.0.0"
}
```

### Directory Structure with Plugin Support

```
{skills_path}/
├── .claude-plugin/
│   └── marketplace.json         # Root marketplace config
├── port-allocator/
│   ├── .claude-plugin/
│   │   └── plugin.json          # Plugin manifest
│   ├── SKILL.md
│   └── ...
├── share-skill/
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── SKILL.md
│   └── ...
└── docs/
    └── ...
```

### Marketplace Commands Reference

| Command | Description |
|---------|-------------|
| `/plugin marketplace add <repo>` | Add a marketplace (GitHub: `owner/repo`) |
| `/plugin marketplace update` | Update all marketplace indexes |
| `/plugin install <name>@<marketplace>` | Install a plugin from marketplace |
| `/plugin validate .` | Validate marketplace structure |

### 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 + defau