--- name: Share Skill slug: share-skill category: DevOps description: Share Skill migrates local Claude skills into a code repository, initializes Git, and configures remotes for version tracking. Use it to open source skills, list local skills, and generate docs for a skills repository. github: "https://github.com/guo-yu/skills/tree/master/share-skill" language: Shell stars: 239 forks: 18 install: "npx degit https://github.com/guo-yu/skills/tree/master/share-skill ~/.claude/skills/share-skill" installs_to: ~/.claude/skills/share-skill source_path: share-skill/SKILL.md collection_size: 5 category_size: 868 collection_url: "https://dirskills.com/collections/guo-yu/skills" added: 2026-09-03T06:03:59.161Z last_synced: 2026-09-03T06:03:59.161Z canonical_url: "https://dirskills.com/skills/share-skill" --- # Share Skill Share Skill migrates local Claude skills into a code repository, initializes Git, and configures remotes for version tracking. Use it to open source skills, list local skills, and generate docs for a skills repository. **Install:** ```bash npx degit https://github.com/guo-yu/skills/tree/master/share-skill ~/.claude/skills/share-skill ``` ## README # 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 ` | Migrate specified skill to code repository and initialize git | | `/share-skill config` | Configure code_root and other settings | | `/share-skill --remote ` | Migrate and configure remote URL | | `/share-skill list` | List all local skills available for migration | | `/share-skill remote ` | 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 ` | Generate docs with specified design style | | `/share-skill docs --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": "git@github.com:guo-yu/skills", "gitlab": "git@gitlab.com: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}//.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 ` | Add a marketplace (GitHub: `owner/repo`) | | `/plugin marketplace update` | Update all marketplace indexes | | `/plugin install @` | 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 xxx@users.noreply.github.com 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": "", "skills_repo": "skills", "github_username": "", "remotes": { "github": "git@github.com:/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: git@github.com: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 --remote git@github.com: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: `git@github.com:/skills/.git` - "push to github" -> Use default github config - "Push to git@github.com: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 --remote git@github.com:other-user/other-repo.git ``` 2. **Explicit path in natural language** ``` OK: "Help me push port-allocator to git@github.com:my-org/tools.git" OK: "Open source to gitlab, address is git@gitlab.com: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: git@github.com:/skills -> Final address: git@github.com:/skills/.git "Push to git@github.com: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.md # 2. User custom skills directory ~/.claude/skills/*//SKILL.md # 3. Standalone skill file ~/.claude/skills/.md # 4. Project-level skills (current working directory) .claude/skills//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 "$dir") echo "$name: $dir" done # Or search for specific name find ~/.claude -type d -name "" 2>/dev/null ``` ### 4. Post-confirmation Actions After finding skill: 1. Display found location, ask user to confirm 2. If multiple matches found, list options for user to choose 3. Execute migration after confirmation 4. **If user didn't specify remote, ask whether to configure after migration completes** ## Execution Steps ### Command: `/share-skill remote ` Configure Git remote alias: 1. **Read existing config** ```bash cat ~/.claude/share-skill-config.json 2>/dev/null || echo '{"remotes":{}}' ``` 2. **Update config** ```json { "remotes": { "": "" } } ``` 3. **Write config file** (preserve existing config) 4. **Output confirmation** ``` Remote alias configured Alias: github Address: git@github.com:guo-yu/skills Usage: /share-skill --remote github or: "Help me open source xxx to github" ``` ### Command: `/share-skill remote list` List configured remote aliases: ```bash cat ~/.claude/share-skill-config.json | jq '.remotes' ``` **Output format:** ``` Configured remote aliases: github -> git@github.com:guo-yu/skills gitlab -> git@gitlab.com:guo-yu/skills gitee -> git@gitee.com:guo-yu/skills Default: github ``` ### Command: `/share-skill [--remote ]` Migrate specified skill from `~/.claude/` directory to `{skills_path}/`: 1. **Search skill location** ```bash # First check standard location if [ -d ~/.claude/skills/ ]; then SKILL_PATH=~/.claude/skills/ else # Recursive search SKILL_PATH=$(find ~/.claude -type d -name "" 2>/dev/null | head -1) fi ``` - If not found, error and exit - If already a symlink, prompt already migrated and show link target - If multiple found, list for user to choose 2. **Check target directory** ```bash ls {skills_path}/ 2>/dev/null ``` - If target exists, error and exit (avoid overwriting) 3. **Execute migration** ```bash # Create target directory (if doesn't exist) mkdir -p {skills_path} # Move skill to code directory mv ~/.claude/skills/ {skills_path}/ # Create symlink ln -s {skills_path}/ ~/.claude/skills/ ``` 4. **Create .gitignore** ```bash cat > {skills_path}//.gitignore << 'EOF' # OS .DS_Store Thumbs.db # Editor .vscode/ .idea/ *.swp *.swo # Logs *.log # Temp tmp/ temp/ EOF ``` 5. **Initialize Git** ```bash cd {skills_path}/ git init git add . git commit -m "Initial commit: skill" ``` 6. **Configure remote (if specified)** If user specified `--remote`: ```bash # If it's an alias, resolve to full address if [ "" is alias ]; then ENDPOINT=$(read alias's endpoint from config) REMOTE_URL="${ENDPOINT}/.git" else REMOTE_URL="" fi cd {skills_path}/ git remote add origin "$REMOTE_URL" git push -u origin master ``` 7. **Ask when remote not specified** If user didn't specify remote, ask after migration using AskUserQuestion: ``` Do you want to configure Git remote address? Options: - Use github (git@github.com:guo-yu/skills/.git) - Use gitlab (git@gitlab.com:guo-yu/skills/.git) - Enter custom address - Skip for now ``` 8. **Post-migration automation (automatic, no interaction)** After migration completes, automatically update all related files: **8.1 Update docs/js/main.js SKILLS config** ```javascript // Add new skill to SKILLS object const SKILLS = { // ... existing skills '': { name: '', description: '', path: '' } }; ``` **8.2 Update docs/js/main.js SKILL_MARKETING config** ```javascript // Generate marketing content for the new skill const SKILL_MARKETING = { // ... existing skills '': { en: { headline: '', why: '', painPoints: [ { icon: '🔥', title: '...', desc: '...' }, { icon: '🧠', title: '...', desc: '...' }, { icon: '💥', title: '...', desc: '...' } ], triggers: [ '', '' ] }, 'zh-CN': { /* Chinese translation including triggers */ }, ja: { /* Japanese translation including triggers */ } } }; ``` **8.3 Update all README files** Add new skill to the skills table in all language versions: ```bash # Files to update: # - {skills_path}/README.md # - {skills_path}/README.zh-CN.md # - {skills_path}/README.ja.md # Extract description from SKILL.md frontmatter DESCRIPTION=$(grep -A1 "^description:" {skills_path}//SKILL.md | tail -1 | sed 's/^description: //') # Add row to skills table in each README # English: | [skill-name](./skill-name/) | Description | # Chinese: | [skill-name](./skill-name/) | 中文描述 | # Japanese: | [skill-name](./skill-name/) | 日本語説明 | ``` **8.4 (Automatic) Skill lists are dynamically generated** The skill lists in navigation dropdown, mobile menu, and sidebar are dynamically generated from the `SKILLS` object in `main.js`. No manual HTML editing required - step 8.1 handles this automatically. **Icon SVG path guidelines** (for step 8.1): | Skill Type | SVG Icon Path | |------------|---------------| | Port/Network | `` | | Sharing/Export | `...(share icon)` | | Security/Permissions | `` | | Translation/i18n | `` | **8.5 Generate translations using skill-i18n** Automatically invoke skill-i18n to translate SKILL.md: ```bash # Check if skill-i18n is available if [ -d ~/.claude/skills/skill-i18n ] || [ -L ~/.claude/skills/skill-i18n ]; then # Use Skill tool to invoke skill-i18n with integration flags # Skill: skill-i18n # Args: --lang zh-CN,ja --files SKILL.md --skill --no-prompt --overwrite # # This generates: # - {skills_path}//SKILL.zh-CN.md # - {skills_path}//SKILL.ja.md fi ``` **Implementation:** Use the `Skill` tool to invoke skill-i18n: ``` Skill(skill: "skill-i18n", args: "--lang zh-CN,ja --files SKILL.md --skill --no-prompt --overwrite") ``` If skill-i18n is not available, skip this step and output: ``` ⚠ skill-i18n not found, skipping translations Install with: ln -s {skills_path}/skill-i18n ~/.claude/skills/skill-i18n ``` **8.6 Update cache version** ```bash # Update version numbers in docs/index.html VERSION=$(date +%s) sed -i '' "s/main.js?v=[0-9]*/main.js?v=$VERSION/" {skills_path}/docs/index.html sed -i '' "s/custom.css?v=[0-9]*/custom.css?v=$VERSION/" {skills_path}/docs/index.html ``` **8.7 Create/Update Plugin Marketplace structure** To enable installation via `/plugin marketplace`, create the plugin manifest files: ```bash # Create plugin.json for the new skill mkdir -p {skills_path}//.claude-plugin cat > {skills_path}//.claude-plugin/plugin.json << EOF { "name": "", "description": "", "version": "1.0.0" } EOF ``` Update the root marketplace.json to include the new skill: ```bash # Read existing marketplace.json and add new plugin entry # File: {skills_path}/.claude-plugin/marketplace.json # Add to plugins array: { "name": "", "source": "./", "description": "" } ``` **Marketplace structure after migration:** ``` {skills_path}/ ├── .claude-plugin/ │ └── marketplace.json # Root marketplace config ├── / │ ├── .claude-plugin/ │ │ └── plugin.json # Plugin manifest │ ├── SKILL.md │ └── ... └── ... ``` **8.8 Commit all changes** ```bash cd {skills_path} git add . git commit -m "Add : update docs, README, translations, and plugin manifest" git push # If remote is configured ``` **Post-migration output:** ``` Post-migration updates completed: ✓ Updated docs/js/main.js (SKILLS + SKILL_MARKETING) ✓ Updated README.md, README.zh-CN.md, README.ja.md ✓ Generated SKILL.zh-CN.md, SKILL.ja.md ✓ Updated cache version in docs/index.html ✓ Created .claude-plugin/plugin.json ✓ Updated .claude-plugin/marketplace.json ✓ Committed and pushed changes Note: Skill lists (navbar, mobile menu, sidebar, install commands) are dynamically generated from SKILLS config - no HTML editing needed. ``` ### Command: `/share-skill list` List all local skills available for migration (excluding symlinks): ```bash # Search for all directories containing SKILL.md under ~/.claude echo "Discovered skills:" find ~/.claude -name "SKILL.md" -type f 2>/dev/null | while read f; do dir=$(dirname "$f") name=$(basename "$dir") if [ -L "$dir" ]; then target=$(readlink "$dir") echo " $name -> $target (migrated)" else ec