Skip to main content

​
Overview

Skills are prompt packages that live as directories in your repo. Each skill has a SKILL.md file with frontmatter defining its name and description. The CLI discovers these directories and pushes them to the Runlayer API, keeping remote state in sync with your repo. This is designed to run in CI. Commit a skill, merge to main, and it’s live.

​
Skill directory structure

skills/
  ticket-triage/
    SKILL.md          # required — must have `name` in frontmatter
    instructions.md
    examples.txt
  code-review/
    SKILL.md
    checklist.md

​
SKILL.md frontmatter

---
name: Ticket Triage
description: Classify and route incoming support tickets
---

Your skill instructions go here...
  • name (required) — human-readable label shown in the UI
  • description (optional) — short summary, max 1024 characters
The directory path (e.g. skills/ticket-triage) is the stable sync key. Renaming the directory creates a new skill; changing name in frontmatter updates the display name. Supported file types: .md, .txt, .sh, .py, .js, .ts.

​
CLI usage

runlayer skills push [PATH] --namespace <namespace> [OPTIONS]
FlagDescription
--namespace, -NRequired. Groups skills by repo (e.g. myorg/my-repo)
--host, -HRunlayer host URL. Also reads RUNLAYER_HOST env var
--secret, -sAPI key. Also reads RUNLAYER_API_KEY env var
--dry-run, -nShow what would change without making API calls
--pruneDelete remote skills whose directories no longer exist locally
PATHRoot directory to scan. Defaults to .

​
Examples

# Preview changes
runlayer skills push --namespace myorg/repo -n

# Push skills
runlayer skills push --namespace myorg/repo

# Push and remove deleted skills
runlayer skills push --namespace myorg/repo --prune

# Delete all skills in a namespace (run from empty dir)
cd $(mktemp -d) && runlayer skills push --namespace myorg/repo --prune

​
GitHub Actions

name: Push Skills
on:
  push:
    branches: [main]
    paths:
      - 'skills/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: astral-sh/setup-uv@v4

      - run: uvx runlayer skills push --namespace ${{ github.repository }} --prune
        env:
          RUNLAYER_HOST: ${{ secrets.RUNLAYER_HOST }}
          RUNLAYER_API_KEY: ${{ secrets.RUNLAYER_API_KEY }}
Set RUNLAYER_HOST and RUNLAYER_API_KEY as repository secrets. The paths filter ensures the workflow only runs when files under skills/ change. The --prune flag removes skills from Runlayer when their directory is deleted from the repo.

​
How push works

  1. CLI walks the directory tree looking for SKILL.md files
  2. Each SKILL.md must have name in its YAML frontmatter (directories without it are skipped)
  3. The directory path relative to root becomes the skill’s path — this is the stable key used to match local and remote skills
  4. For each discovered skill:
    • New path — creates the skill and uploads all files
    • Existing path — compares name, description, and file contents; updates only what changed
    • Remote-only path (with --prune) — deletes the skill from Runlayer