---
slug: "timonclaeys-pi-github-skill-installer"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/TimonClaeys/pi-github-skill-installer@main/README.md"
repo: "https://github.com/TimonClaeys/pi-github-skill-installer"
source_file: "README.md"
branch: "main"
---
# pi-github-skill-installer

A [pi](https://pi.dev) extension that installs agent skills directly from GitHub repositories. Supports both global (`~/.pi/agent/skills/`) and project-local (`.pi/skills/`) installations.

## Features

- **LLM-callable tool** — The agent can autonomously install skills from GitHub URLs when asked.
- **Interactive command** — Use `/install-skill <url>` to install skills manually.
- **Recursive fetching** — Downloads all files in a skill directory, including subdirectories.
- **Smart name detection** — Extracts the skill name from SKILL.md frontmatter, falling back to the directory name.
- **Multiple URL formats** — Supports blob URLs, tree URLs, raw CDN URLs, and shorthand notation.
- **Project-local installation** — Use `--project` or `project_local: true` to install in the current project.

## Installation

### Global (recommended)

```bash
pi install git:github.com/TimonClaeys/pi-github-skill-installer
# or from npm once published:
pi install npm:@timonclaeys/pi-github-skill-installer
```

Or from a local path:

```bash
pi install /path/to/pi-github-skill-installer
```

### Temporary (try without installing)

```bash
pi -e ./path/to/extensions/install-github-skill.ts
```

## Usage

### Via the agent (tool)

Simply ask pi to install a skill from a GitHub URL:

```
Install the brave-search skill from github.com/badlogic/pi-skills
```

The agent will automatically invoke the `install_github_skill` tool.

### Via the command

```
/install-skill https://github.com/user/repo/tree/main/skills/my-skill
```

For project-local installation:

```
/install-skill https://github.com/user/repo/tree/main/skills/my-skill --project
```

Or via the tool with explicit agent instruction:

```
Install the skill from https://github.com/user/repo/tree/main/skills/my-skill
Make it project-local.
```

## Supported URL Formats

### GitHub blob/tree URLs

```
https://github.com/owner/repo/tree/branch/path/to/skill
https://github.com/owner/repo/blob/branch/path/to/skill/SKILL.md
https://github.com/owner/repo
```

### Raw CDN URLs

```
https://raw.githubusercontent.com/owner/repo/branch/path/to/skill/SKILL.md
```

### Shorthand

```
owner/repo/path/to/skill
```

## How It Works

1. **Parse** the GitHub URL to extract owner, repo, branch/ref, and path.
2. **List** all files in the target directory using the [GitHub Contents API](https://docs.github.com/en/rest/repos/contents).
3. **Fetch** each file's content from `raw.githubusercontent.com`.
4. **Install** the files to the appropriate skill directory:
   - Global: `~/.pi/agent/skills/<skill-name>/`
   - Project-local: `.pi/skills/<skill-name>/`
5. **Detect** the skill name from SKILL.md frontmatter's `name:` field, or use the directory name.
6. **Report** the installation result, including any warnings (e.g., missing SKILL.md).

### Reloading

After installation, run `/reload` or restart pi for the new skill to appear in the available skills list.

## Package Structure

```
@timonclaeys/pi-github-skill-installer/
├── package.json                        # npm package manifest with pi metadata
├── README.md                           # This file
├── LICENSE                             # MIT license
├── .gitignore                          # Git exclusion rules
├── .npmignore                          # npm publish exclusion rules
└── extensions/
    └── install-github-skill.ts         # Main extension source (~500 lines)
```

## Publishing

To publish the package to npm:

```bash
npm login
npm publish --access public
```

> **Note:** Scoped packages publish as private by default. The `--access public` flag makes it publicly installable.

## License

MIT