### Development Setup for Skills CLI

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Instructions for setting up the development environment, including cloning the repository, installing in development mode, and running tests.

```bash
git clone https://github.com/kcchien/skills-cli.git
cd skills-cli

pip install -e ".[dev]"

pytest tests/ -v

pytest tests/test_core.py::TestParseRepoUrl -v
```

--------------------------------

### Show all installed skills

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Displays a list of all skills that are currently installed, including both global and project-specific installations. This provides a comprehensive overview of the user's skill setup.

```bash
skills-cli installed
```

--------------------------------

### Install Skills with Skills CLI

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Use the install command to add skills. Options include dry run, force overwrite with backup, installing to a project directory, or installing from a custom repository.

```bash
skills-cli install --all --dry-run
```

```bash
skills-cli install --all --force --backup
```

```bash
skills-cli install --all --project
```

```bash
skills-cli install --repo https://github.com/user/skills --all
```

--------------------------------

### Install Skills

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Commands for installing skills, including options for dry runs, force installation, project-specific installation, and installation from custom repositories.

```APIDOC
## Install Skills

### Description
Commands for installing skills, including options for dry runs, force installation, project-specific installation, and installation from custom repositories.

### Commands

*   **Dry Run**: Preview what would be installed.
    ```bash
    skills-cli install --all --dry-run
    ```
*   **Force Install with Backup**: Install, overwriting existing skills, and create a backup.
    ```bash
    skills-cli install --all --force --backup
    ```
*   **Install to Project**: Install skills to the project directory.
    ```bash
    skills-cli install --all --project
    ```
*   **Install from Custom Repo**: Install skills from a specified Git repository.
    ```bash
    skills-cli install --repo https://github.com/user/skills --all
    ```
```

--------------------------------

### Install all skills from a custom repository

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Installs all skills from a specified custom Git repository. Ensure the repository URL is correct.

```bash
skills-cli install --repo https://github.com/your-username/your-skills --all
```

--------------------------------

### Install all skills from the default repository

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Installs all available skills from the default Anthropic official skills repository. Use with caution as it may install many skills.

```bash
skills-cli install --all
```

--------------------------------

### Install Skills CLI using PowerShell for Windows

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Installs the Skills CLI using PowerShell. The command downloads the installation script and executes it.

```powershell
irm https://raw.githubusercontent.com/kcchien/skills-cli/main/install.ps1 | iex
```

--------------------------------

### Install specific skills

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Installs only the specified skills by name. This allows for selective installation of desired skills.

```bash
skills-cli install --skills pdf,xlsx,docx
```

--------------------------------

### Interactive skill installation

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Initiates an interactive prompt to select and install skills from the default repository. This allows users to choose skills one by one.

```bash
skills-cli install
```

--------------------------------

### Install Skills from a Repository

Source: https://context7.com/kcchien/skills-cli/llms.txt

Install skills to the local Claude Code directory. Supports interactive selection, dry-run, backup, force overwrite, selective install, and project-scoped installation. Use --repo for custom paths or monorepos.

```bash
# Interactive selection from default repo
skills-cli install

# Install all skills with a dry-run preview first
skills-cli install --all --dry-run

# Install specific skills with backup before overwriting
skills-cli install --skills pdf,xlsx,docx --force --backup

# Install all from a custom repo to the project-local directory
skills-cli install https://github.com/your-username/your-skills --all --project

# Install from a monorepo subdirectory
skills-cli install --repo https://github.com/org/monorepo/tree/main/packages/skills --all

# Expected output:
# ℹ Target directory: /home/user/.claude/skills
# ℹ Cloning from https://github.com/anthropics/skills.git (branch: main)
# ✓ pdf: installed
# ✓ xlsx: installed
# ✓ docx: installed
#
# ✓ Installed 3/3 skills to /home/user/.claude/skills
```

--------------------------------

### Show all available commands help

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Displays comprehensive help information for all commands available in the Skills CLI. Use this to get an overview of the CLI's capabilities.

```bash
skills-cli --help
```

--------------------------------

### Install specific skills from a custom repository

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Installs only the specified skills from a custom Git repository. This is useful for managing a large number of skills in a personal repository.

```bash
skills-cli install --repo https://github.com/your-username/your-skills --skills my-skill,another-skill
```

--------------------------------

### Show help for a specific command

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Displays detailed help for a specific command, such as 'list' or 'install'. This helps in understanding the options and arguments for individual commands.

```bash
skills-cli list --help
```

```bash
skills-cli install --help
```

--------------------------------

### Install skills from a repository subdirectory

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Installs skills located within a subdirectory of a Git repository. This is useful for monorepos or when skills are not at the root.

```bash
skills-cli install --repo https://github.com/org/monorepo/tree/main/packages/skills --all
```

--------------------------------

### Install Skills CLI from Source using pip

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Installs the Skills CLI from a local clone of the source repository using pip in editable mode. This is useful for development or when modifying the CLI.

```bash
git clone https://github.com/kcchien/skills-cli.git
cd skills-cli
pip install -e .
```

--------------------------------

### Show installed skills with source tracking details

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Displays installed skills along with detailed source tracking information, such as the original repository and commit hash. This helps in managing and auditing skill origins.

```bash
skills-cli installed --detail
```

--------------------------------

### Install Skills CLI using curl for macOS/Linux

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Installs the Skills CLI using a curl command, piping the script to bash. This is a convenient method for Unix-like systems.

```bash
curl -fsSL https://raw.githubusercontent.com/kcchien/skills-cli/main/install.sh | bash
```

--------------------------------

### Install Skills CLI using pip

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Install the CLI tool directly from its GitHub repository using pip. This is a common method for installing Python packages from source.

```bash
pip install git+https://github.com/kcchien/skills-cli.git
```

--------------------------------

### Install a Single Skill

Source: https://context7.com/kcchien/skills-cli/llms.txt

Copies a skill directory to a target location, with options for handling existing skills via force and backup. Returns a boolean indicating success and a message string.

```python
from pathlib import Path
from skills_cli import install_skill, parse_repo_url

source_path = Path("/tmp/cloned-repo/skills/pdf")
target_dir = Path.home() / ".claude" / "skills"
repo_info = parse_repo_url("https://github.com/anthropics/skills/tree/main/skills")

# Install with backup and force overwrite
success, message = install_skill(
    skill_path=source_path,
    target_dir=target_dir,
    repo_info=repo_info,
    commit_hash="a1b2c3d",
    force=True,
    backup=True,
    dry_run=False
)

if success:
    print(f"✓ pdf: {message}")   # ✓ pdf: installed  (or "updated")
else:
    print(f"✗ pdf: {message}")   # ✗ pdf: already exists (use --force to overwrite)

# Dry-run example (no files are written)
success, message = install_skill(source_path, target_dir, dry_run=True)
print(message)  # "would install to /home/user/.claude/skills/pdf"
```

--------------------------------

### Read Skill Installation Metadata

Source: https://context7.com/kcchien/skills-cli/llms.txt

Reads the .skills-cli.json tracking file from an installed skill directory. Returns metadata or None if not present.

```python
from pathlib import Path
from skills_cli import read_skill_metadata

skill_dir = Path.home() / ".claude" / "skills" / "pdf"
metadata = read_skill_metadata(skill_dir)

if metadata:
    print(f"Source:    {metadata['source_url']}")
    print(f"Branch:    {metadata['branch']}")
    print(f"Commit:    {metadata['commit']}")
    print(f"Installed: {metadata['installed_at']}")
    print(f"By:        {metadata['installed_by']}")
```

--------------------------------

### Show only project-specific installed skills

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Filters the installed skills list to show only those installed within the current project context. This is useful for isolating project-specific dependencies.

```bash
skills-cli installed --project
```

--------------------------------

### read_skill_metadata

Source: https://context7.com/kcchien/skills-cli/llms.txt

Reads the .skills-cli.json tracking file from an installed skill directory. Returns metadata about the skill's installation.

```APIDOC
## read_skill_metadata(skill_dir)

### Description
Reads the `.skills-cli.json` tracking file from an installed skill directory. Returns a dict with `source_url`, `clone_url`, `branch`, `commit`, `installed_at`, and `installed_by`, or `None` if not present.

### Parameters
#### Path Parameters
- **skill_dir** (Path) - Required - The directory path where the skill is installed.
```

--------------------------------

### List Locally Installed Skills

Source: https://context7.com/kcchien/skills-cli/llms.txt

Show installed skills, globally or project-scoped. Use --detail for source tracking information (repo, branch, commit hash) and --project to filter for project-scoped skills.

```bash
# Show all installed skills (global + project)
skills-cli installed

# Show detailed info including source repo, branch, and commit hash
skills-cli installed --detail

# Show only project-scoped skills
skills-cli installed --project

# Show skills in a custom directory
skills-cli installed --target /path/to/custom/skills

# Expected output with --detail:
# [GLOBAL] Installed skills:
#   Location: /home/user/.claude/skills
#
#   Name    Description
#   ------  --------------------------------------------------
#   pdf     Extract and analyze content from PDF files
#          ↳ https://github.com/anthropics/skills/... (main@a1b2c3d)
#
# Total: 1 skills
```

--------------------------------

### Install Skills CLI in Development Mode

Source: https://github.com/kcchien/skills-cli/blob/main/CLAUDE.md

Installs the Skills CLI package in editable mode for development. This allows changes to the code to be reflected immediately without reinstallation.

```bash
pip install -e .
```

--------------------------------

### List available skills from Anthropic's official repo

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

View the skills available in the default Anthropic official skills repository. This command helps discover what skills can be installed.

```bash
skills-cli list
```

--------------------------------

### Diagnose Issues with Skills CLI

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Run the doctor command to check the directory structure and identify common issues with your skills setup.

```bash
skills-cli doctor
```

--------------------------------

### Validate Skills

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Commands for validating installed skills or skills from a remote repository or local directory.

```APIDOC
## Validate Skills

### Description
Commands for validating installed skills or skills from a remote repository or local directory.

### Commands

*   **Validate Installed Skills**: Validate all skills currently installed.
    ```bash
    skills-cli validate
    ```
*   **Validate from Remote Repo**: Validate skills from a specified remote repository.
    ```bash
    skills-cli validate --repo https://github.com/user/skills
    ```
*   **Validate Local Directory**: Validate skills within a local directory.
    ```bash
    skills-cli validate --path ./my-skill/
    ```
```

--------------------------------

### Python API for Skills CLI

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

The core functions of the skills-cli can be imported and used programmatically in Python. This includes parsing repository URLs, discovering skills, installing, and validating them.

```python
from skills_cli import (
    parse_repo_url,
    discover_skills,
    find_skills_root,
    install_skill,
    validate_skill_md,
    get_claude_skills_dir,
)

# Parse various repo URL formats
repo_info = parse_repo_url("https://github.com/user/skills/tree/main/skills")
# {'clone_url': '...', 'branch': 'main', 'subdir': 'skills', ...}

# Discover skills in a directory
skills = discover_skills(Path("~/.claude/skills").expanduser())
# [{'name': 'pdf', 'description': '...', 'path': Path(...), ...}, ...]

# Install a skill
success, message = install_skill(
    source_path,
    target_dir,
    force=True,
    backup=True
)

# Validate a skill
issues = validate_skill_md(Path("./my-skill"))
# [] if valid, or ['Missing required field: name', ...] if issues
```

--------------------------------

### Direct Usage of Skills CLI Script

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Execute the Skills CLI directly using the Python interpreter without a formal installation. This is useful for testing or running the script from its source directory.

```bash
python skills_cli.py <command> [options]
```

--------------------------------

### Validate Skills with Skills CLI

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Use the validate command to check the integrity of installed skills or skills from a remote repository or local directory.

```bash
skills-cli validate
```

```bash
skills-cli validate --repo https://github.com/user/skills
```

```bash
skills-cli validate --path ./my-skill/
```

--------------------------------

### Run Skills CLI Directly

Source: https://github.com/kcchien/skills-cli/blob/main/CLAUDE.md

Executes the Skills CLI tool directly using the Python module. This is useful for running the CLI without installing it system-wide or for debugging.

```bash
python -m skills_cli.cli
```

--------------------------------

### Remove Installed Skills

Source: https://context7.com/kcchien/skills-cli/llms.txt

Uninstall skills from local directories. Supports interactive selection, dry-run previews, force removal, and targeting specific skills or all skills. Can target global or project-scoped directories.

```bash
# Interactive selection for removal
skills-cli remove

# Dry-run: preview what would be removed
skills-cli remove --skills pdf,xlsx --dry-run

# Remove specific skills from global directory
skills-cli remove --skills pdf,xlsx

# Remove all skills from project directory, skipping confirmation
skills-cli remove --all --project --force

# Expected output:
# The following skills will be removed:
#   - pdf
#   - xlsx
#

```

--------------------------------

### install_skill(skill_path, target_dir, ...)

Source: https://context7.com/kcchien/skills-cli/llms.txt

Copies a skill directory to the target location. Handles existing skills with force/backup options. Returns (success: bool, message: str).

```APIDOC
## install_skill(skill_path, target_dir, ...)

### Description
Installs a single skill by copying its directory to a specified target location. This function supports options for handling existing skills, such as forcing an overwrite or creating a backup. It returns a boolean indicating success and a message describing the outcome.

### Parameters
#### Path Parameters
- **skill_path** (Path) - Required - The path to the skill directory to install.
- **target_dir** (Path) - Required - The destination directory where the skill will be installed.
- **repo_info** (dict, optional) - Information about the repository the skill originates from.
- **commit_hash** (str, optional) - The commit hash of the skill in the repository.
- **force** (bool, optional) - If True, overwrite an existing skill. Defaults to False.
- **backup** (bool, optional) - If True, create a backup of an existing skill before overwriting. Defaults to False.
- **dry_run** (bool, optional) - If True, simulate the installation without writing any files. Defaults to False.

### Response
- **success** (bool) - True if the installation was successful, False otherwise.
- **message** (str) - A message describing the result of the installation attempt.

### Request Example
```python
from pathlib import Path
from skills_cli import install_skill, parse_repo_url

source_path = Path("/tmp/cloned-repo/skills/pdf")
target_dir = Path.home() / ".claude" / "skills"
repo_info = parse_repo_url("https://github.com/anthropics/skills/tree/main/skills")

# Install with backup and force overwrite
success, message = install_skill(
    skill_path=source_path,
    target_dir=target_dir,
    repo_info=repo_info,
    commit_hash="a1b2c3d",
    force=True,
    backup=True,
    dry_run=False
)

if success:
    print(f"✓ pdf: {message}")
else:
    print(f"✗ pdf: {message}")

# Dry-run example (no files are written)
success, message = install_skill(source_path, target_dir, dry_run=True)
print(message)
```
```

--------------------------------

### List skills from a custom repository with details

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Lists skills from a custom repository, including detailed descriptions. This allows for a deeper understanding of skills hosted in personal or team repositories.

```bash
skills-cli list --repo https://github.com/user/my-skills
```

--------------------------------

### Pack skills for Claude Desktop with skills-cli

Source: https://context7.com/kcchien/skills-cli/llms.txt

Use `skills-cli pack` to bundle skills into `.zip` archives compatible with Claude Desktop and generate a `manifest.json`. Specify the output directory and optionally filter skills from a custom repository.

```bash
# Pack all skills from the default repo to dist/desktop/
skills-cli pack --output dist/desktop

```

```bash
# Pack specific skills from a custom repo
skills-cli pack https://github.com/your-username/your-skills --skills pdf,xlsx --output ./releases

```

```bash
# Expected output:
# ℹ Packing 3 skills to dist/desktop
# ✓ Packed: dist/desktop/pdf.zip
# ✓ Packed: dist/desktop/xlsx.zip
# ✓ Packed: dist/desktop/docx.zip
#
# ✓ Packed 3 skills
# ✓ Generated manifest: dist/desktop/manifest.json

```

```json
# manifest.json contents:
# {
#   "skills": [
#     { "name": "pdf", "folder": "pdf", "description": "...", "zip": "pdf.zip" },
#     { "name": "xlsx", "folder": "xlsx", "description": "...", "zip": "xlsx.zip" }
#   ]
# }

```

--------------------------------

### pack_skill(skill_path, output_dir)

Source: https://context7.com/kcchien/skills-cli/llms.txt

Creates a .zip file of a skill directory for use with Claude Desktop. Returns the path to the created zip file.

```APIDOC
## pack_skill(skill_path, output_dir)

### Description
Packages a skill directory into a `.zip` archive, suitable for use with Claude Desktop. The function returns the file path of the generated zip archive.

### Parameters
#### Path Parameters
- **skill_path** (Path) - Required - The path to the skill directory to be packed.
- **output_dir** (Path) - Required - The directory where the resulting zip file will be saved.

### Response
- **zip_path** (Path) - The path to the created zip archive.

### Request Example
```python
from pathlib import Path
from skills_cli import pack_skill

skill_path = Path("./skills/pdf")
output_dir = Path("./dist/desktop")

zip_path = pack_skill(skill_path, output_dir)
print(f"Created: {zip_path}")
```
```

--------------------------------

### List skills from the official Anthropic repo with details

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Lists skills from the default Anthropic repository, including detailed descriptions for each skill. This provides more context about what each skill does.

```bash
skills-cli list --detail
```

--------------------------------

### Pack Skills for Claude Desktop

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Use the pack command to package skills into zip files for Claude Desktop. You can pack all skills or specific skills, specifying an output directory.

```bash
skills-cli pack --output dist/desktop
```

```bash
skills-cli pack --skills pdf,xlsx --output dist/
```

--------------------------------

### Pack a Skill into a Zip Archive

Source: https://context7.com/kcchien/skills-cli/llms.txt

Creates a .zip archive of a skill directory, suitable for use with Claude Desktop. Returns the path to the created zip file. The zip contains the full skill directory tree.

```python
from pathlib import Path
from skills_cli import pack_skill

skill_path = Path("./skills/pdf")
output_dir = Path("./dist/desktop")

zip_path = pack_skill(skill_path, output_dir)
print(f"Created: {zip_path}")  # Created: dist/desktop/pdf.zip

# The zip contains the full skill directory tree:
# pdf/
#   SKILL.md
#   (any other skill files)
```

--------------------------------

### List skills from a custom repository

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

List skills available from a custom Git repository. Specify the repository URL using the --repo flag.

```bash
skills-cli list --repo https://github.com/your-username/your-skills
```

--------------------------------

### skills-cli pack

Source: https://context7.com/kcchien/skills-cli/llms.txt

Bundles skills into .zip archives compatible with Claude Desktop and generates a manifest.json file listing all packed skills.

```APIDOC
## `skills-cli pack` — Pack skills for Claude Desktop

Bundle skills into `.zip` archives compatible with Claude Desktop, and generate a `manifest.json` listing all packed skills.

### Usage

```bash
# Pack all skills from the default repo to dist/desktop/
skills-cli pack --output dist/desktop

# Pack specific skills from a custom repo
skills-cli pack https://github.com/your-username/your-skills --skills pdf,xlsx --output ./releases
```

### Example Output

```
# ℹ Packing 3 skills to dist/desktop
# ✓ Packed: dist/desktop/pdf.zip
# ✓ Packed: dist/desktop/xlsx.zip
# ✓ Packed: dist/desktop/docx.zip
#
# ✓ Packed 3 skills
# ✓ Generated manifest: dist/desktop/manifest.json
```

### `manifest.json` Contents Example

```json
{
  "skills": [
    { "name": "pdf", "folder": "pdf", "description": "...", "zip": "pdf.zip" },
    { "name": "xlsx", "folder": "xlsx", "description": "...", "zip": "xlsx.zip" }
  ]
}
```
```

--------------------------------

### Sync Skills with Skills CLI

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Use the sync command to update your skills by pulling from a Git repository. Options include syncing to the personal skills directory, project directory, or a custom repository.

```bash
skills-cli sync
```

```bash
skills-cli sync --project
```

```bash
skills-cli sync --repo https://github.com/user/skills
```

--------------------------------

### List Available Skills from a Repository

Source: https://context7.com/kcchien/skills-cli/llms.txt

List skills available in a Git repository. Supports the default Anthropic repo, custom repos via URL or --repo flag, and detailed output. Use --repo for specific subdirectories or branches.

```bash
# List skills from Anthropic's official repo (default)
skills-cli list

# List with names and descriptions
skills-cli list --detail

# List from a custom repository (positional URL)
skills-cli list https://github.com/your-username/your-skills

# List from a specific subdirectory on a custom branch
skills-cli list --repo https://github.com/your-username/dotfiles/tree/master/claude --detail

# Expected output:
# Skills in https://github.com/anthropics/skills/tree/main/skills:
#
#   Name    Description
#   ------  --------------------------------------------------
#   pdf     Extract and analyze content from PDF files
#   xlsx    Read and process Excel spreadsheet data
#   docx    Parse and summarize Word document content
#
# Total: 3 skills
```

--------------------------------

### Discover Skills in a Directory

Source: https://context7.com/kcchien/skills-cli/llms.txt

Scans a specified directory for skill subdirectories. Returns a sorted list of skill dictionaries, each containing path, folder name, name, and description.

```python
from pathlib import Path
from skills_cli import discover_skills

skills_dir = Path.home() / ".claude" / "skills"
skills = discover_skills(skills_dir)

for skill in skills:
    print(f"{skill['name']} ({skill['folder_name']}): {skill['description']}")
    print(f"  Path: {skill['path']}")
```

--------------------------------

### Pack Skills for Claude Desktop

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Commands for packing skills into zip files for Claude Desktop, with options to pack all or specific skills.

```APIDOC
## Pack for Claude Desktop

### Description
Commands for packing skills into zip files for Claude Desktop, with options to pack all or specific skills.

### Commands

*   **Pack All Skills**: Pack all skills into zip files and output to a specified directory.
    ```bash
    skills-cli pack --output dist/desktop
    ```
*   **Pack Specific Skills**: Pack a comma-separated list of skills into zip files.
    ```bash
    skills-cli pack --skills pdf,xlsx --output dist/
    ```
```

--------------------------------

### Python API

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Demonstrates how to use the core functions of the skills-cli library programmatically in Python.

```APIDOC
## Python API

### Description
The core functions can be imported and used programmatically.

### Usage Examples

*   **Parse Repository URL**: Parse various repository URL formats.
    ```python
    from skills_cli import parse_repo_url
    repo_info = parse_repo_url("https://github.com/user/skills/tree/main/skills")
    # repo_info will contain {'clone_url': '...', 'branch': 'main', 'subdir': 'skills', ...}
    ```
*   **Discover Skills**: Discover skills in a specified directory.
    ```python
    from skills_cli import discover_skills
    from pathlib import Path
    skills = discover_skills(Path("~/.claude/skills").expanduser())
    # skills will be a list of skill dictionaries, e.g., [{'name': 'pdf', 'description': '...', 'path': Path(...), ...}, ...]
    ```
*   **Install Skill**: Install a skill programmatically.
    ```python
    from skills_cli import install_skill
    success, message = install_skill(
        source_path,
        target_dir,
        force=True,
        backup=True
    )
    ```
*   **Validate Skill**: Validate a skill using its path.
    ```python
    from skills_cli import validate_skill_md
    issues = validate_skill_md(Path("./my-skill"))
    # issues will be an empty list if valid, or a list of error strings if invalid, e.g., ['Missing required field: name', ...]
    ```
*   **Get Claude Skills Directory**: Get the default directory for Claude skills.
    ```python
    from skills_cli import get_claude_skills_dir
    claude_skills_dir = get_claude_skills_dir()
    ```
```

--------------------------------

### Locate Skills Root in a Repository

Source: https://context7.com/kcchien/skills-cli/llms.txt

Searches a cloned repository root for the skills directory. It checks common subdirectory names and recursively searches up to 3 levels deep. Returns the path to the skills root and a list of found skills.

```python
from pathlib import Path
from skills_cli import find_skills_root

repo_root = Path("/tmp/cloned-repo")
skills_root, skills = find_skills_root(repo_root)

print(f"Skills root: {skills_root}")
print(f"Found {len(skills)} skills:")
for skill in skills:
    print(f"  - {skill['name']}: {skill['description']}")
```

--------------------------------

### find_skills_root(repo_root)

Source: https://context7.com/kcchien/skills-cli/llms.txt

Searches a cloned repository root for the skills directory by checking root, common subdirectory names, then recursively up to 3 levels deep. Returns (skills_root_path, skills_list).

```APIDOC
## find_skills_root(repo_root)

### Description
Searches a cloned repository root for the skills directory by checking the root, common subdirectory names, and recursively up to 3 levels deep. Returns a tuple containing the path to the skills root directory and a list of found skills.

### Parameters
#### Path Parameters
- **repo_root** (Path) - Required - The root directory of the cloned repository to search within.

### Response
- **skills_root_path** (Path) - The path to the identified skills directory.
- **skills_list** (list[dict]) - A list of dictionaries, where each dictionary represents a skill found within the skills root.

### Request Example
```python
from pathlib import Path
from skills_cli import find_skills_root

repo_root = Path("/tmp/cloned-repo")
skills_root, skills = find_skills_root(repo_root)

print(f"Skills root: {skills_root}")
print(f"Found {len(skills)} skills:")
for skill in skills:
    print(f"  - {skill['name']}: {skill['description']}")
```
```

--------------------------------

### discover_skills(skills_dir)

Source: https://context7.com/kcchien/skills-cli/llms.txt

Scans a directory for skill subdirectories (those containing a SKILL.md file). Returns a sorted list of skill dicts with path, folder_name, name, and description.

```APIDOC
## discover_skills(skills_dir)

### Description
Scans a directory for skill subdirectories (those containing a `SKILL.md` file). Returns a sorted list of skill dicts with `path`, `folder_name`, `name`, and `description`.

### Parameters
#### Path Parameters
- **skills_dir** (Path) - Required - The directory to scan for skills.

### Response
- **skills** (list[dict]) - A list of dictionaries, where each dictionary represents a skill and contains 'path', 'folder_name', 'name', and 'description' keys.

### Request Example
```python
from pathlib import Path
from skills_cli import discover_skills

skills_dir = Path.home() / ".claude" / "skills"
skills = discover_skills(skills_dir)

for skill in skills:
    print(f"{skill['name']} ({skill['folder_name']}): {skill['description']}")
    print(f"  Path: {skill['path']}")
```
```

--------------------------------

### Sync skills from a repository with skills-cli

Source: https://context7.com/kcchien/skills-cli/llms.txt

Use `skills-cli sync` to clone or update skills from a Git repository. It performs a `git pull --rebase` if a `.git` folder exists, otherwise it clones fresh. Can sync to global or project-scoped directories.

```bash
# Sync from default repo to global skills directory
skills-cli sync

```

```bash
# Sync to project-scoped directory
skills-cli sync --project

```

```bash
# Sync from a custom repo to a specific directory
skills-cli sync --repo https://github.com/your-username/your-skills --target ./my-skills

```

```bash
# Expected output:
# ℹ Cloning skills to /home/user/.claude/skills
# ✓ Synced: pdf
# ✓ Synced: xlsx
# ✓ Skills synced to /home/user/.claude/skills
#
# Installed skills:
#   - pdf
#   - xlsx

```

--------------------------------

### List skills from a custom repository with a specific branch

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Lists skills from a custom repository, specifying a particular branch to retrieve the skill list from. This is useful for testing development branches.

```bash
skills-cli list --repo https://github.com/your-username/your-skills --branch develop
```

--------------------------------

### SKILL.md Format Reference

Source: https://context7.com/kcchien/skills-cli/llms.txt

Defines the required structure for a SKILL.md file, including YAML frontmatter and body content.

```markdown
---
name: my-skill
description: A short description of what this skill does (max 500 chars)
---

## Overview
Explain what this skill teaches Claude to do.

## Instructions
Step-by-step instructions for Claude to follow when using this skill.

## Examples
Provide usage examples...
```

--------------------------------

### Sync Skills

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Commands for syncing skills, equivalent to Git pull or clone operations, with options for personal or project directories and custom repositories.

```APIDOC
## Sync Skills (Git Pull/Clone)

### Description
Commands for syncing skills, equivalent to Git pull or clone operations, with options for personal or project directories and custom repositories.

### Commands

*   **Sync to Personal Directory**: Sync skills to the default personal skills directory.
    ```bash
    skills-cli sync
    ```
*   **Sync to Project Directory**: Sync skills to the project's skills directory.
    ```bash
    skills-cli sync --project
    ```
*   **Sync from Custom Repo**: Sync skills from a specified Git repository.
    ```bash
    skills-cli sync --repo https://github.com/user/skills
    ```
```

--------------------------------

### Validate a Skill's SKILL.md File

Source: https://context7.com/kcchien/skills-cli/llms.txt

Checks a skill directory for a valid SKILL.md file. It verifies YAML frontmatter, required fields (name, description), a non-empty body, and adherence to length limits. Returns a list of issue strings; an empty list indicates the skill is valid.

```python
from pathlib import Path
from skills_cli import validate_skill_md

# Validate a local skill
issues = validate_skill_md(Path("./my-skill"))

if issues:
    print("Validation failed:")
    for issue in issues:
        print(f"  - {issue}")
else:
    print("Skill is valid!")
```

--------------------------------

### skills-cli sync

Source: https://context7.com/kcchien/skills-cli/llms.txt

Clones or updates skills from a Git repository. If the target directory already has a .git folder, it performs a git pull --rebase; otherwise, it clones fresh.

```APIDOC
## `skills-cli sync` — Sync skills from a repository

Clone or update skills from a Git repository. If the target directory already has a `.git` folder, performs a `git pull --rebase`; otherwise clones fresh.

### Usage

```bash
# Sync from default repo to global skills directory
skills-cli sync

# Sync to project-scoped directory
skills-cli sync --project

# Sync from a custom repo to a specific directory
skills-cli sync --repo https://github.com/your-username/your-skills --target ./my-skills
```

### Example Output

```
# ℹ Cloning skills to /home/user/.claude/skills
# ✓ Synced: pdf
# ✓ Synced: xlsx
# ✓ Skills synced to /home/user/.claude/skills
#
# Installed skills:
#   - pdf
#   - xlsx
```
```

--------------------------------

### Detect Repository Default Branch

Source: https://context7.com/kcchien/skills-cli/llms.txt

Queries a remote repository to determine its default branch (e.g., 'main' or 'master'). Falls back to 'main' on error.

```python
from skills_cli import detect_default_branch

branch = detect_default_branch("https://github.com/anthropics/skills.git")
print(branch)  # "main"

branch = detect_default_branch("https://github.com/older-project/repo.git")
print(branch)  # "master"
```

--------------------------------

### Remove Skills with Skills CLI

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Use the remove command to uninstall skills. Options include interactive selection, removing specific skills, removing all skills, previewing removals, or forcing removal without confirmation.

```bash
skills-cli remove
```

```bash
skills-cli remove --skills pdf,xlsx
```

```bash
skills-cli remove --all
```

```bash
skills-cli remove --all --dry-run
```

```bash
skills-cli remove --all --force
```

--------------------------------

### get_claude_skills_dir(scope)

Source: https://context7.com/kcchien/skills-cli/llms.txt

Returns the platform-appropriate path for the Claude Code skills directory without creating it.

```APIDOC
## get_claude_skills_dir(scope)

### Description
Resolves and returns the platform-appropriate file path for the Claude Code skills directory. This function does not create the directory if it does not exist.

### Parameters
#### Path Parameters
- **scope** (str) - Required - The scope for the skills directory. Accepted values are 'personal' for the global user skills directory or 'project' for a project-scoped directory.

### Response
- **skills_dir_path** (Path) - The platform-appropriate path to the Claude skills directory.

### Request Example
```python
from skills_cli import get_claude_skills_dir

# Global (personal) skills directory
global_dir = get_claude_skills_dir("personal")
print(global_dir)

# Project-scoped skills directory (relative to cwd)
project_dir = get_claude_skills_dir("project")
print(project_dir)
```
```

--------------------------------

### Parse Git repository URLs with parse_repo_url

Source: https://context7.com/kcchien/skills-cli/llms.txt

The `parse_repo_url` function from `skills_cli` parses various Git repository URL formats (GitHub, GitLab, SSH, HTTPS) into a normalized dictionary containing clone URL, branch, subdirectory, and host. Handles URLs with or without tree paths.

```python
from skills_cli import parse_repo_url

# GitHub tree URL with subdirectory
info = parse_repo_url("https://github.com/anthropics/skills/tree/main/skills")
# {'url': '...', 'clone_url': 'https://github.com/anthropics/skills.git',
#  'branch': 'main', 'subdir': 'skills', 'host': 'github'}

```

```python
# GitLab URL
info = parse_repo_url("https://gitlab.com/team/repo/-/tree/develop/claude-skills")
# {'clone_url': 'https://gitlab.com/team/repo.git', 'branch': 'develop',
#  'subdir': 'claude-skills', 'host': 'gitlab'}

```

```python
# SSH URL
info = parse_repo_url("git@github.com:your-username/skills.git")
# {'clone_url': 'git@github.com:your-username/skills.git',
#  'branch': 'main', 'subdir': None, 'host': 'github.com'}

```

```python
# Plain HTTPS (no tree path)
info = parse_repo_url("https://github.com/your-username/my-skills")
# {'clone_url': 'https://github.com/your-username/my-skills.git',
#  'branch': 'main', 'subdir': None, 'host': 'github.com'}

```

--------------------------------

### Diagnose skills directory issues with skills-cli doctor

Source: https://context7.com/kcchien/skills-cli/llms.txt

Run `skills-cli doctor` to inspect global and project skills directories for structural problems, including orphaned folders, validation issues, and leftover backup directories. It reports found issues and a summary.

```bash
skills-cli doctor

```

```bash
# Expected output:
# Skills CLI Doctor
#
#   Global skills: /home/user/.claude/skills
#     ✓ Directory exists (2 skills)
#
#   Project skills: /project/.claude/skills
#     ○ Directory does not exist (this is normal)
#
#   Checking for orphaned directories...
#     ✗ old-skill (no SKILL.md)
#
#   Checking for backup directories...
#     ✓ No backup directories
#
# Summary:
#   ✗ 1 issues found
#     - Orphaned directory (no SKILL.md): /home/user/.claude/skills/old-skill

```

--------------------------------

### Run Skills CLI Tests

Source: https://github.com/kcchien/skills-cli/blob/main/CLAUDE.md

Executes the test suite for the Skills CLI project using pytest. Ensure all tests pass to verify the integrity of the code.

```bash
pytest
```

--------------------------------

### validate_skill_md(skill_path)

Source: https://context7.com/kcchien/skills-cli/llms.txt

Checks that a skill directory contains a valid SKILL.md with proper YAML frontmatter, required fields (name, description), a non-empty body, and within length limits. Returns a list of issue strings (empty list = valid).

```APIDOC
## validate_skill_md(skill_path)

### Description
Validates the `SKILL.md` file within a given skill directory. It checks for proper YAML frontmatter, presence of required fields (`name`, `description`), a non-empty body, and adherence to length limits. Returns a list of strings detailing any issues found; an empty list indicates the skill is valid.

### Parameters
#### Path Parameters
- **skill_path** (Path) - Required - The path to the skill directory to validate.

### Response
- **issues** (list[str]) - A list of strings, where each string describes a validation issue. An empty list signifies a valid `SKILL.md`.

### Request Example
```python
from pathlib import Path
from skills_cli import validate_skill_md

# Validate a local skill
issues = validate_skill_md(Path("./my-skill"))

if issues:
    print("Validation failed:")
    for issue in issues:
        print(f"  - {issue}")
else:
    print("Skill is valid!")
```
```

--------------------------------

### Diagnose Issues

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Command to diagnose common issues and check directory structure.

```APIDOC
## Diagnose Issues

### Description
Command to diagnose common issues and check directory structure.

### Command

*   **Doctor**: Run diagnostic checks.
    ```bash
    skills-cli doctor
    ```
```

--------------------------------

### skills-cli doctor

Source: https://context7.com/kcchien/skills-cli/llms.txt

Inspects global and project skills directories for structural problems, including orphaned folders, validation issues, and leftover backup directories.

```APIDOC
## `skills-cli doctor` — Diagnose skills directory issues

Inspect global and project skills directories for structural problems: orphaned folders (no `SKILL.md`), validation issues, and leftover backup directories.

### Usage

```bash
skills-cli doctor
```

### Example Output

```
# Skills CLI Doctor
#
#   Global skills: /home/user/.claude/skills
#     ✓ Directory exists (2 skills)
#
#   Project skills: /project/.claude/skills
#     ○ Directory does not exist (this is normal)
#
#   Checking for orphaned directories...
#     ✗ old-skill (no SKILL.md)
#
#   Checking for backup directories...
#     ✓ No backup directories
#
# Summary:
#   ✗ 1 issues found
#     - Orphaned directory (no SKILL.md): /home/user/.claude/skills/old-skill
```
```

--------------------------------

### Resolve Claude Skills Directory Path

Source: https://context7.com/kcchien/skills-cli/llms.txt

Returns the platform-appropriate path for the Claude Code skills directory without creating it. Supports 'personal' scope for the global directory and 'project' scope for a directory relative to the current working directory.

```python
from skills_cli import get_claude_skills_dir

# Global (personal) skills directory
global_dir = get_claude_skills_dir("personal")
print(global_dir)  # /home/user/.claude/skills  (Linux/macOS)
                   # C:\Users\user\.claude\skills  (Windows)

# Project-scoped skills directory (relative to cwd)
project_dir = get_claude_skills_dir("project")
print(project_dir)  # /current/working/dir/.claude/skills
```

--------------------------------

### parse_repo_url(url)

Source: https://context7.com/kcchien/skills-cli/llms.txt

Parses Git repository URLs (GitHub, GitLab, HTTPS, SSH) into a normalized dictionary containing clone URL, branch, subdirectory, and host information.

```APIDOC
## Python API

Skills CLI exposes a full programmatic API for embedding skill management logic into other Python tools.

### `parse_repo_url(url)` — Parse Git repository URLs

Parses GitHub, GitLab, plain HTTPS, and SSH URLs into a normalized dict containing `clone_url`, `branch`, `subdir`, and `host`.

### Usage

```python
from skills_cli import parse_repo_url

# GitHub tree URL with subdirectory
info = parse_repo_url("https://github.com/anthropics/skills/tree/main/skills")
# {'url': '...', 'clone_url': 'https://github.com/anthropics/skills.git',
#  'branch': 'main', 'subdir': 'skills', 'host': 'github'}

# GitLab URL
info = parse_repo_url("https://gitlab.com/team/repo/-/tree/develop/claude-skills")
# {'clone_url': 'https://gitlab.com/team/repo.git', 'branch': 'develop',
#  'subdir': 'claude-skills', 'host': 'gitlab'}

# SSH URL
info = parse_repo_url("git@github.com:your-username/skills.git")
# {'clone_url': 'git@github.com:your-username/skills.git',
#  'branch': 'main', 'subdir': None, 'host': 'github.com'}

# Plain HTTPS (no tree path)
info = parse_repo_url("https://github.com/your-username/my-skills")
# {'clone_url': 'https://github.com/your-username/my-skills.git',
#  'branch': 'main', 'subdir': None, 'host': 'github.com'}
```
```

--------------------------------

### Validate SKILL.md format with skills-cli

Source: https://context7.com/kcchien/skills-cli/llms.txt

Use `skills-cli validate` to check if skill definitions adhere to the required SKILL.md format, including YAML frontmatter, non-empty body, and field length constraints. It can validate local skills, remote repositories, or project-scoped skills.

```bash
# Validate all locally installed skills
skills-cli validate

```

```bash
# Validate a specific local skill directory
skills-cli validate --path ./my-custom-skill/

```

```bash
# Validate skills in a remote repository before installing
skills-cli validate --repo https://github.com/your-username/your-skills

```

```bash
# Validate project-scoped skills
skills-cli validate --project

```

```bash
# Expected output:
# Validating 3 skills...
#
#   ✓ pdf
#   ✓ xlsx
#   ✗ my-skill
#     - Missing required field: description
#     - Empty skill body (no instructions after frontmatter)
#
# ⚠ Found 2 issues in 3 skills

```

--------------------------------

### skills-cli validate

Source: https://context7.com/kcchien/skills-cli/llms.txt

Validates that skill definitions conform to the required SKILL.md format, including YAML frontmatter, non-empty body, and field length constraints.

```APIDOC
## `skills-cli validate` — Validate SKILL.md format

Check that skill definitions conform to the required SKILL.md format: YAML frontmatter with `name` and `description` fields, a non-empty body, and field length constraints.

### Usage

```bash
# Validate all locally installed skills
skills-cli validate

# Validate a specific local skill directory
skills-cli validate --path ./my-custom-skill/

# Validate skills in a remote repository before installing
skills-cli validate --repo https://github.com/your-username/your-skills

# Validate project-scoped skills
skills-cli validate --project
```

### Example Output

```
# Validating 3 skills...
#
#   ✓ pdf
#   ✓ xlsx
#   ✗ my-skill
#     - Missing required field: description
#     - Empty skill body (no instructions after frontmatter)
#
# ⚠ Found 2 issues in 3 skills
```
```

--------------------------------

### detect_default_branch

Source: https://context7.com/kcchien/skills-cli/llms.txt

Auto-detects a repository's default branch by querying the remote repository.

```APIDOC
## detect_default_branch(clone_url)

### Description
Queries a remote repository via `git ls-remote --symref` to determine whether the default branch is `main`, `master`, or something else. Falls back to `"main"` on timeout or error.

### Parameters
#### Path Parameters
- **clone_url** (str) - Required - The URL of the remote repository.
```

--------------------------------

### Remove Skills

Source: https://github.com/kcchien/skills-cli/blob/main/README.md

Commands for removing skills, with options for interactive selection, specific skill removal, mass removal, dry runs, and forcing removal.

```APIDOC
## Remove Skills

### Description
Commands for removing skills, with options for interactive selection, specific skill removal, mass removal, dry runs, and forcing removal.

### Commands

*   **Interactive Selection**: Remove skills interactively.
    ```bash
    skills-cli remove
    ```
*   **Remove Specific Skills**: Remove a comma-separated list of skills.
    ```bash
    skills-cli remove --skills pdf,xlsx
    ```
*   **Remove All Skills**: Remove all installed skills (requires confirmation).
    ```bash
    skills-cli remove --all
    ```
*   **Dry Run Removal**: Preview what would be removed without actually removing.
    ```bash
    skills-cli remove --all --dry-run
    ```
*   **Force Removal**: Skip confirmation and force removal of all skills.
    ```bash
    skills-cli remove --all --force
    ```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.