Installed Skills¶

Install named skills from external repositories. Skills are fetched dynamically at generate time and included in your outputs — no local copy needed.

Overview¶

Installed skills let you pull specialized AI instructions from any git repository or local path. Unlike includes (which import .ai-rulez/ content), installed skills expect a simpler structure: a skills/<name>/SKILL.md file at the repository root.

Use installed skills to:

• Add library-specific instructions (e.g., how to use a framework or SDK)
• Share team skills across projects without full includes
• Distribute AI guidance alongside your library

Quick Start¶

# Install a skill
ai-rulez skill install kreuzberg --source https://github.com/kreuzberg-dev/kreuzberg

# List installed skills
ai-rulez skill list

# Generate — the skill is fetched and included automatically
ai-rulez generate

# Remove when no longer needed
ai-rulez skill remove kreuzberg

Configuration¶

Installed skills are defined in .ai-rulez/config.toml:

[[installed_skills]]
name = "kreuzberg"
source = "https://github.com/kreuzberg-dev/kreuzberg"

[[installed_skills]]
name = "ai-rulez"
source = "https://github.com/Goldziher/ai-rulez"
ref = "main"

[[installed_skills]]
name = "custom-skill"
source = "https://github.com/org/repo"
path = "custom/skill/path"    # defaults to skills/<name>

Fields¶

CLI Commands¶

ai-rulez skill install <name> --source <url> [flags]¶

Install a named skill.

Flags:

• --source <url> (required): Git URL or local path
• --path <dir> (optional): Path within repo to skill directory
• --ref <ref> (optional): Git ref (branch, tag, commit)
• --local (optional): Record the skill in your gitignored config.local.* overlay instead of config.toml, so it applies on this machine only. See Local Configuration

Examples:

# From a git repo (skill at skills/kreuzberg/)
ai-rulez skill install kreuzberg --source https://github.com/kreuzberg-dev/kreuzberg

# With explicit path and ref
ai-rulez skill install my-lib --source https://github.com/org/repo --path libs/my-lib --ref v2.0

# From a local path
ai-rulez skill install local-skill --source ../my-other-repo

ai-rulez skill remove <name> [flags]¶

Remove an installed skill from the configuration.

Flags:

• --force (optional): Skip confirmation prompt
• --local (optional): Remove through the overlay. A skill defined in the shared config is hidden on this machine by writing remove = true to the overlay; the shared config is not changed

ai-rulez skill list [flags]¶

List all installed skills.

Flags:

• --json (optional): Output as JSON

How It Works¶

1. During ai-rulez generate, each installed skill is fetched from its source
2. The skill directory (SKILL.md + optional references/) is read
3. Reference files are concatenated into the skill content
4. The skill is added to the root-level content tree
5. If a local skill has the same name, the local skill wins (installed skill is skipped with a warning)

Skill Directory Structure¶

Installed skills expect this layout in the source repository:

repo-root/
  skills/
    my-skill/
      SKILL.md              # Required: main skill content
      references/            # Optional: additional reference docs
        api-reference.md
        configuration.md

SKILL.md Format¶

---
name: my-library
description: >-
  Brief description of what this skill covers.
license: MIT
metadata:
  author: your-org
  version: "1.0"
  repository: https://github.com/your-org/your-repo
---
# My Library

Instructions for AI assistants working with your library...

A missing description produces a warning rather than an error; the skill name is used as a fallback. Set it anyway — the description is how the assistant decides when to load the skill.

References¶

Files in references/ are read alphabetically and appended to the skill content under ## Reference: <filename> headings. This lets you separate detailed API docs, configuration guides, etc. from the main skill instructions.

Local Override¶

For development workflows, use local_override to point to a local checkout instead of fetching from git:

[[installed_skills]]
name = "my-lib"
source = "https://github.com/org/my-lib"
local_override = "../my-lib"

If the local path exists and contains the skill, it's used. If it doesn't exist, the skill is skipped (not fetched from git).

MCP Tools¶

The MCP server exposes three tools for managing installed skills:

• install_skill — Install a skill (params: name, source, path, ref, local)
• uninstall_skill — Remove a skill (params: name, local)
• list_installed_skills — List all installed skills (shared layer only; takes no local)

local: true writes to the config.local.* overlay instead of the shared config.

Creating Distributable Skills¶

To make your project's skill installable by others:

1. Create skills/<project-name>/SKILL.md at your repository root
2. Add YAML frontmatter with name, description, and optional metadata
3. Write comprehensive instructions in the skill body
4. Optionally add references/*.md for detailed reference documentation
5. Users install with: ai-rulez skill install <name> --source <your-repo-url>

Comparison with Includes¶