Skills

---
name: github
description: "Interact with GitHub using the `gh` CLI"
required-bins:
  - gh
---

# GitHub Skill

Use the `gh` CLI to interact with GitHub repositories.

## Pull Requests

```bash
gh pr list --repo owner/repo
gh pr checks 55 --repo owner/repo

gh issue list --repo owner/repo --state open

### Frontmatter Fields

The YAML frontmatter between `---` delimiters is parsed to extract skill metadata. The parser reads simple `key: value` lines from the frontmatter block.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Skill identifier. Should match the folder name. |
| `description` | string | Yes | What the skill does. Shown to the agent and in the UI. |
| `required-os` | string[] | No | Restrict to specific platforms: `macos`, `linux`, `windows`. |
| `required-bins` | string[] | No | CLI tools that must exist in `PATH` for the skill to load. |
| `required-env` | string[] | No | Environment variables that must be set. |
| `user-invocable` | boolean | No | Whether users can invoke the skill directly. Default: `true`. |
| `disable-model-invocation` | boolean | No | If `true`, the skill content is not injected into prompts. |
| `primary-env` | string | No | Primary runtime environment: `node`, `python`, `shell`. |
| `command-dispatch` | string | No | How commands are dispatched (e.g., `shell`). |
| `command-tool` | string | No | Tool used for command execution (e.g., `bash`). |
| `metadata` | object | No | Arbitrary additional data (JSON object). |

**Parsing behavior:** The frontmatter parser extracts `name` and `description` from simple `key: value` lines. If the frontmatter is missing or malformed, Eliza falls back to reading the first markdown heading as the skill name and the first non-heading paragraph as the description.

---

## Skill Locations

Eliza discovers skills from multiple directories. Skills found in later (higher-precedence) directories override earlier ones with the same name.

### 1. Bundled Skills (lowest precedence)

Shipped with the `@elizaos/plugin-agent-skills` package. These are automatically available when the plugin is loaded. The bundled skills directory is resolved at startup via `getSkillsDir()` and passed to the runtime as `BUNDLED_SKILLS_DIRS`.

### 2. Extra Directories

Additional directories configured in `~/.eliza/eliza.json`:

```json
{
  "skills": {
    "load": {
      "extraDirs": [
        "/path/to/shared-team-skills",
        "/path/to/another-skills-dir"
      ]
    }
  }
}

~/.eliza/skills/
├── my-custom-skill/
│   └── SKILL.md
└── team-shared-skill/
    └── SKILL.md

~/.eliza/workspace/skills/
├── project-specific-skill/
│   └── SKILL.md
└── override-bundled-skill/
    └── SKILL.md

~/.eliza/workspace/skills/.marketplace/
├── content-marketer/
│   ├── SKILL.md
│   └── .scan-results.json
└── seo-optimizer/
    ├── SKILL.md
    └── .scan-results.json

{
  "skills": {
    "allowBundled": ["github", "weather", "coding-agent"],
    "denyBundled": ["deprecated-skill"],
    "entries": {
      "github": { "enabled": true },
      "noisy-skill": { "enabled": false }
    }
  }
}

export ELIZA_SKILLSMP_API_KEY="your-api-key"

GET /api/skills/marketplace/search?q=content+marketing&limit=20

{
  "ok": true,
  "results": [
    {
      "id": "content-marketer",
      "slug": "content-marketer",
      "name": "Content Marketer",
      "description": "Generate blog posts and social media content",
      "repository": "owner/repo",
      "githubUrl": "https://github.com/owner/repo",
      "path": "skills/content-marketer",
      "tags": ["marketing", "content"],
      "score": 0.95,
      "source": "clawhub"
    }
  ]
}

POST /api/skills/marketplace/install
Content-Type: application/json

{ "slug": "content-marketer" }

POST /api/skills/marketplace/install
Content-Type: application/json

{
  "githubUrl": "https://github.com/owner/repo/tree/main/skills/my-skill",
  "name": "my-skill",
  "source": "clawhub"
}

POST /api/skills/marketplace/install
Content-Type: application/json

{
  "repository": "owner/repo",
  "path": "skills/my-skill"
}

GET /api/skills/marketplace/installed

POST /api/skills/marketplace/uninstall
Content-Type: application/json

{ "id": "content-marketer" }

Skill "bad-skill" blocked by security scan: Binary executable file detected (.exe); Symbolic link points outside skill directory

{
  "scannedAt": "2026-02-19T12:00:00.000Z",
  "status": "clean",
  "summary": {
    "scannedFiles": 5,
    "critical": 0,
    "warn": 0,
    "info": 0
  },
  "findings": [],
  "manifestFindings": [],
  "skillPath": "/Users/you/.eliza/workspace/skills/.marketplace/my-skill"
}

GET /api/skills/:id/scan

{
  slug: string;           // Unique identifier
  displayName: string;    // Human-readable name
  summary: string | null; // Short description
  tags: Record<string, string>;
  stats: {
    comments: number;
    downloads: number;
    installsAllTime: number;
    installsCurrent: number;
    stars: number;
    versions: number;
  };
  createdAt: number;      // Unix timestamp
  updatedAt: number;
  latestVersion: {
    version: string;
    createdAt: number;
    changelog: string;
  } | null;
}

my-skill/
├── SKILL.md              # Required -- frontmatter + instructions
├── scripts/              # Optional -- executable scripts
│   └── setup.sh
├── references/           # Optional -- additional docs to load
│   └── api-reference.md
└── assets/               # Optional -- templates, config files
    └── template.json

mkdir -p ~/.eliza/workspace/skills/my-tool

mkdir -p ~/.eliza/skills/my-tool

---
name: my-tool
description: "Use my-tool CLI for data processing"
required-bins:
  - my-tool
required-env:
  - MY_TOOL_API_KEY
---

# My Tool Skill

This skill teaches you how to use the `my-tool` CLI.

## Authentication

Set your API key:

```bash
export MY_TOOL_API_KEY="your-key-here"

my-tool list --format json

my-tool create --name "New Item" --type standard

### Step 3: Add Scripts (Optional)

```bash
#!/bin/bash
# scripts/setup.sh
set -e

echo "Checking my-tool installation..."
if ! command -v my-tool &> /dev/null; then
    echo "Installing my-tool..."
    bun install -g my-tool
fi

echo "my-tool is ready!"

POST /api/skills/refresh

GET /api/skills

code-review/
├── SKILL.md              # Required -- skill definition
├── scripts/
│   └── review.sh         # Optional -- executable helper
├── references/
│   └── review-checklist.md  # Optional -- loaded into context
└── assets/
    └── report-template.md   # Optional -- output template

---
name: code-review
description: Review pull requests for code quality, security issues, and best practices
required-bins: gh, git
required-env: GITHUB_TOKEN
user-invocable: true
primary-env: shell
command-dispatch: shell
command-tool: bash
metadata:
  category: development
  author: your-name
---

# Code Review Skill

Review a GitHub pull request for quality and security issues.

## Instructions

When asked to review a PR:

1. Fetch the PR diff using `gh pr diff <number>`
2. Analyze each changed file for:
   - Logic errors or bugs
   - Security vulnerabilities (injection, auth bypass, secrets exposure)
   - Performance issues (N+1 queries, unnecessary allocations)
   - Style violations (naming, formatting, dead code)
3. Load the review checklist from `references/review-checklist.md`
4. Generate a report using the template in `assets/report-template.md`
5. Post the review as a PR comment using `gh pr review <number>`

## Examples

User: "Review PR #42"
Agent: Fetches diff, analyzes changes, posts review comment

User: "Review the latest PR on elizaOS/eliza"
Agent: Finds latest PR, reviews it

## Listing Files

```bash
ls -la           # All files, long format
ls -lh *.txt     # Text files with human-readable sizes
```

```bash
gh issue list --repo owner/repo --search "bug" --state open
```

---
name: docker-skill
description: "Manage Docker containers"
required-bins:
  - docker
  - docker-compose
required-os:
  - macos
  - linux
---

## Troubleshooting

### "Permission denied"
```bash
chmod +x script.sh

brew install my-tool  # macOS
apt install my-tool   # Linux

### Test Your Skills

1. Read your `SKILL.md` and follow the instructions manually
2. Verify all commands work as written
3. Check that the frontmatter parses correctly (restart the agent, then `GET /api/skills`)
4. If the skill has requirements, test on a clean environment

---

## API Reference Summary

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/skills` | GET | List all discovered skills with enabled state |
| `/api/skills/refresh` | POST | Re-scan skill directories and refresh the list |
| `/api/skills/:id/enable` | POST | Enable a skill (persisted per-agent, honors scan acknowledgments) |
| `/api/skills/:id/disable` | POST | Disable a skill (persisted per-agent) |
| `/api/skills/:id` | PUT | **Deprecated** — use `POST /api/skills/:id/enable` or `POST /api/skills/:id/disable` instead |
| `/api/skills/:id/scan` | GET | Get the security scan report for a skill |
| `/api/skills/catalog` | GET | Browse the full skill catalog |
| `/api/skills/catalog/search` | GET | Search the catalog |
| `/api/skills/catalog/:slug` | GET | Get a catalog skill by slug |
| `/api/skills/catalog/refresh` | POST | Force-refresh the catalog cache |
| `/api/skills/catalog/install` | POST | Install a skill from the catalog |
| `/api/skills/catalog/uninstall` | POST | Uninstall a catalog skill |
| `/api/skills/marketplace/search` | GET | Search the remote marketplace |
| `/api/skills/marketplace/installed` | GET | List marketplace-installed skills |
| `/api/skills/marketplace/install` | POST | Install from marketplace (git or slug) |
| `/api/skills/marketplace/uninstall` | POST | Uninstall a marketplace skill |
| `/api/skills/marketplace/config` | GET | Check marketplace API key status |
| `/api/skills/marketplace/config` | PUT | Set the marketplace API key |

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `ELIZA_SKILLS_CATALOG` | Override the catalog file path |
| `SKILLS_REGISTRY` | Marketplace registry URL (default: `https://clawhub.ai`) |
| `CLAWHUB_REGISTRY` | Alternative to `SKILLS_REGISTRY` |
| `SKILLS_MARKETPLACE_URL` | Alternative to `SKILLS_REGISTRY` |
| `SKILLSMP_API_KEY` | API key for the legacy SkillsMP marketplace |
| `ELIZA_STATE_DIR` | Override the base state directory (default: `~/.eliza`) |
| `BUNDLED_SKILLS_DIRS` | Set by runtime -- path to bundled skills |
| `WORKSPACE_SKILLS_DIR` | Set by runtime -- path to workspace skills |
| `EXTRA_SKILLS_DIRS` | Set by runtime -- comma-separated extra skill directories |
| `SKILLS_ALLOWLIST` | Set by runtime -- comma-separated allowed skill IDs |
| `SKILLS_DENYLIST` | Set by runtime -- comma-separated denied skill IDs |

---

## Skill Operations Runbook

### Setup Checklist

1. Verify the skills plugin is loaded: `GET /api/skills` should return a non-empty list.
2. For marketplace installs, confirm registry connectivity: `GET /api/skills/marketplace/config` should show `configured: true` or a reachable default registry.
3. For catalog browsing, confirm the catalog file exists at one of the expected paths (see [Catalog File Locations](#catalog-file-locations) above).
4. Ensure `~/.eliza/workspace/skills/` is writable for marketplace and workspace skill installs.
5. For legacy SkillsMP marketplace, set `SKILLSMP_API_KEY` in the environment.

### Failure Modes

**Catalog operations:**

- Catalog returns empty results:
  The catalog file may be missing or empty. Run `POST /api/skills/catalog/refresh` to force a reload from disk. If the file does not exist, check that the `@elizaos/plugin-agent-skills` package is installed (it ships the initial catalog).
- Catalog search returns no matches:
  Search uses fuzzy matching across slug, name, summary, and tags. Try broader search terms. Exact slug matches score highest.
- Catalog cache is stale:
  The in-memory cache expires after 10 minutes (`MEMORY_TTL_MS`). Force-refresh with `POST /api/skills/catalog/refresh` or restart the agent.

**Marketplace operations:**

- Marketplace search fails with network error:
  Confirm the registry URL is reachable. Check `SKILLS_REGISTRY`, `CLAWHUB_REGISTRY`, or `SKILLS_MARKETPLACE_URL` environment variables. The default is `https://clawhub.ai`.
- Git clone fails during marketplace install:
  The installer uses sparse checkout to fetch only the skill directory. Confirm the repository URL and path are valid. Check that `git` is available in `PATH` and network access to GitHub is not blocked.
- Security scan blocks install (`blocked` status):
  The scan detected binary files (`.exe`, `.dll`, `.so`, etc.), symlink escapes, or a missing `SKILL.md`. The skill directory is automatically deleted. Inspect the skill source repository to confirm it is safe before requesting the author fix the issue.
- Install fails with "already installed":
  A record for this skill ID already exists in `marketplace-installs.json`. Uninstall first with `POST /api/skills/marketplace/uninstall`, then retry.

**Skill loading:**

- Custom skill not appearing in `/api/skills`:
  Confirm the skill directory contains a valid `SKILL.md` with name/description frontmatter. Check that the directory is in a scanned location (bundled, managed, workspace, or marketplace). Run `POST /api/skills/refresh` to re-scan.
- Skill loads but is disabled:
  Check the enable/disable cascade: database preferences override config, `denyBundled` blocks unconditionally, `allowBundled` acts as a whitelist. Use `POST /api/skills/:id/enable` to force-enable.
- Required binary or env var missing:
  Skills with `required-bins` or `required-env` frontmatter are skipped if dependencies are absent. Install the required CLI tool or set the environment variable.

### Recovery Procedures

1. **Corrupted marketplace install:** Delete `~/.eliza/workspace/skills/.marketplace/<skill-id>/` and remove its entry from `~/.eliza/workspace/skills/.cache/marketplace-installs.json`, then re-install.
2. **Catalog file missing:** Re-install or update `@elizaos/plugin-agent-skills` to restore the bundled catalog. Alternatively, copy a known-good `catalog.json` to `~/.eliza/skills/catalog.json`.
3. **Skill override conflict:** If a workspace skill unexpectedly overrides a bundled skill, rename the workspace skill directory or move it to a different location. Higher-precedence sources always win.

### Verification Commands

```bash
# Skill catalog and marketplace unit tests
bunx vitest run src/services/skill-marketplace.test.ts src/services/skill-catalog-client.test.ts

# Skill marketplace e2e lifecycle
bunx vitest run --config test/vitest/e2e.config.ts test/skills-marketplace-api.e2e.test.ts test/skills-marketplace-services.e2e.test.ts

bun run typecheck