Skills

Overview

Skills are reusable prompt packages that live as directories — each containing a SKILL.md file with frontmatter and supporting files. Publish a skill once and your team can install the same vetted, version-controlled instructions into Claude Code, Cursor, and other clients. There are two workflows:

Author & publish — write skills in your repo, push them to Runlayer with skills push (typically in CI)
Consume & install — add published skills to your project or global config with skills add

Authoring skills

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...

Field	Required	Notes
`name`	Yes	Human-readable label shown in the UI
`description`	No	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 UTF-8 text file types: .css, .csv, .html, .js, .json, .md, .markdown, .py, .sh, .svg, .ts, .txt, .xml, .yaml, .yml. CSV files have table previews; isolated HTML/SVG previews require a low-risk security scan. Binary files such as PNGs and PDFs are not supported.

Publishing

Push skills from a local directory to the Runlayer API.

uvx runlayer skills push [PATH] --namespace <namespace> [OPTIONS]

Flag	Description
`--namespace, -N`	Required. Groups skills by repo (e.g. `myorg/my-repo`)
`--public`	Publish pushed skills as public
`--host, -H`	Runlayer host URL. Also reads `RUNLAYER_HOST` env var
`--secret, -s`	API key override (optional; prefer `uvx runlayer login`). Also reads `RUNLAYER_API_KEY`
`--dry-run, -n`	Show what would change without making API calls
`--prune`	Delete remote skills whose directories no longer exist locally
`PATH`	Root directory to scan. Defaults to `.`

Examples

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

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

# Push skills and make them public
uvx runlayer skills push --namespace myorg/repo --public

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

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

How push works

CLI walks the directory tree looking for SKILL.md files
Each SKILL.md must have name in its YAML frontmatter (directories without it are skipped)
The directory path relative to root becomes the skill’s path — this is the stable key used to match local and remote skills
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

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.

Creating from the web UI

From the Skills page, click Add skill. You can:

Import from GitHub — paste a public GitHub repo URL (e.g. github.com/owner/repo or github.com/owner/repo/tree/branch/path). Runlayer discovers skill directories (each with a SKILL.md) and lets you choose which to import. Imported skills are linked to their source URL and can be re-synced when the upstream changes.
Upload files — drag a .zip/.skill archive (must contain a SKILL.md at the top or inside a single root folder), a single .md/.markdown file (treated as SKILL.md), or a folder.
Use a template — start from a pre-built skill template.

After upload or import, Runlayer parses the frontmatter, runs a security scan, and shows the results before the skill is created.

Using skills in AI clients

Open a skill and click Add to Client. If the skill is included in Runlayer Plugin, Runlayer recommends that shared connection first. Click Connect to use Runlayer Plugin, or continue with the client-specific instructions to install the skill directly. To work with several skills at once:

Open Skills and select the skill cards.
Click Add to Client in the selection bar.
Use Runlayer Plugin, add the skills to an editable Plugin, or create a new Plugin.

See Plugins for the complete flow.

Security scanning

When you upload or update skill files — via the CLI (skills push), web import from GitHub, the API, or the web UI — Runlayer automatically scans each file with ToolGuard. The scan runs before the file is accepted, and the results (per-file risk scores and an overall skill classification) are shown in the skill detail page. After upload, the skill detail page displays the overall security score and per-file risk indicators. Click the score badge to open a dialog showing per-file findings — grouped by concern level — so you can review exactly which lines triggered each score. If a skill was created before security scanning was enabled, or if you want to re-evaluate after updating files, skill owners and admins can trigger a manual rescan from the skill detail page using the Scan security button. The platform enforces a configurable skill risk policy based on the scan result. By default, high-risk skills are blocked and medium-risk skills show a warning. Admins can adjust these actions in Settings → Security Scanners. See ToolGuard Models — Skill Risk Policy for details.

Why a skill gets blocked

The scan combines ToolGuard’s ML threat classification with additional deterministic checks. Each finding appears in the findings dialog with a severity, the matched content, and a line reference, and is tagged with a risk category from the ToolGuard threat taxonomy (for example Data Exfiltration, Privilege Escalation, Context Poisoning, Destructive Action, or Guardrail Bypass) — so reviewers see what was flagged and why, not just a score. Per-file results map to the same risk tiers used across ToolGuard. A serious finding raises the file to High risk — rejected by the default policy — while lower-severity findings surface as a Medium-risk warning and import with a warning by default. Typical High-risk triggers include hidden-character obfuscation, piping downloads into a shell, and referencing credential material; typical warnings include network access, destructive commands, dynamic code execution, and encoded payloads. When an admin accepts a medium-risk warning, the acceptance is recorded in the Audit Log.

Scanning from the CLI

You can also scan one skill, or a folder containing many skills, on-demand before publishing:

uvx runlayer skills scan <path-to-skill-dir-or-SKILL.md>

Flag	Description
`--name`	Override skill name sent to the security scan API for single-skill scans only
`--fail-on`	Exit non-zero on `warn` or `block` result (useful in CI)
`--secret, -s`	API key override. Also reads `RUNLAYER_API_KEY`
`--host, -H`	Runlayer host URL. Also reads `RUNLAYER_HOST`

This calls the same ToolGuard security scan API used by skills push, but without uploading. Single-skill scans return one scan object; multi-skill scans return a JSON object with a skills array. Use --fail-on block in CI pipelines to gate merges on security scan results.

CI gate example

Run the scan as a required check on pull requests so a risky skill never reaches main:

name: Scan Skills
on:
  pull_request:
    paths:
      - 'skills/**'

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

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

      - run: uvx runlayer skills scan skills/ --fail-on block
        env:
          RUNLAYER_HOST: ${{ secrets.RUNLAYER_HOST }}
          RUNLAYER_API_KEY: ${{ secrets.RUNLAYER_API_KEY }}

--fail-on block exits non-zero when any skill classifies as block-level risk, failing the check; use --fail-on warn to also fail on medium-risk warnings. The scan only evaluates files — it does not upload or publish — so pair it with the push workflow above (scan on pull_request, publish on push to main).

Installing

Add published skills from the Runlayer API to your local project or global config.

uvx runlayer skills add [SOURCE] [OPTIONS]

Flag	Description
`source`	Optional when `--all` is used. Skill UUID or namespace (e.g. `Org/Repo`)
`--all`	Install all accessible skills across namespaces
`--skill`	Filter by skill name within a namespace
`--client, -c`	Target editor client: `claude_code` (default), `cursor`, `goose`, `opencode`, `vscode`
`--global, -g`	Install globally instead of project-level
`--dry-run, -n`	Show what would be installed without writing files
`--secret, -s`	API key override (optional; prefer `uvx runlayer login`). Also reads `RUNLAYER_API_KEY`
`--host, -H`	Runlayer host URL. Also reads `RUNLAYER_HOST` env var

Examples

# Install all skills from a namespace
uvx runlayer skills add myorg/my-repo

# Install all accessible skills across namespaces
uvx runlayer skills add --all

# Install a single skill by name
uvx runlayer skills add myorg/my-repo --skill ticket-triage

# Install globally
uvx runlayer skills add myorg/my-repo --global

# Install for Cursor instead of Claude Code
uvx runlayer skills add myorg/my-repo --client cursor

If --all sees the same skill name in multiple namespaces, install fails with an explicit error. Re-run with a namespace SOURCE (or UUID) to disambiguate. Typical output:

Done: 12 installed, 3 skipped

Validation errors:

Pass either SOURCE or --all, not both.
Missing argument 'SOURCE'. Use SOURCE or --all.

File layout

Skills are written to a canonical directory and, for some clients, an editor-specific directory via symlink:

Scope	Canonical	Claude Code	Codex	Cursor	Goose / VS Code / OpenCode
Project	`.agents/skills/`	`.claude/skills/`	`.codex/skills/`	`.cursor/skills/`	`.agents/skills/` (direct)
Global	`~/.agents/skills/`	`~/.claude/skills/`	`~/.codex/skills/`	`~/.cursor/skills/`	`~/.agents/skills/` (direct)

Goose, VS Code, and OpenCode read from the canonical directory directly — no symlinks are created for these clients. A lockfile at .runlayer/skill-lock.yml (or ~/.runlayer/skill-lock.yml for global) tracks installed skills and versions per client.

Symlink behavior

Skill files are stored in the canonical directory (.agents/skills/ or ~/.agents/skills/).
Claude Code, Codex, and Cursor directories contain symlinks to the canonical location. Goose, VS Code, and OpenCode use the canonical directory directly.

Example (project install for Claude Code):

.agents/skills/ticket-triage/          # real files
.claude/skills/ticket-triage -> ../../.agents/skills/ticket-triage

Client-scoped lifecycle:

uvx runlayer skills remove --client <client> removes only that client’s symlink + lockfile entry.
Canonical files are kept while any other client still references the same skill.
Canonical files are deleted only when the last client reference is removed.

If symlink creation is blocked by filesystem policy or permissions, install fails for clients that require symlinks. Run in a writable path that supports symlinks.

Interactive find

Browse and install skills interactively from the terminal.

uvx runlayer skills find

The command loads all available skills, presents a searchable multi-select list, then prompts you to choose target clients and install scope (project or global). No flags are required — the wizard walks you through each step.

Flag	Description
`--secret, -s`	API key override. Also reads `RUNLAYER_API_KEY`
`--host, -H`	Runlayer host URL. Also reads `RUNLAYER_HOST`

Managing installed skills

List

uvx runlayer skills list [OPTIONS]

Flag	Description
`--client, -c`	Target editor client: `claude_code` (default), `cursor`, `goose`, `opencode`, `vscode`
`--global, -g`	List global skills

list, update, and remove are scoped to the selected --client.

Update

Pull the latest versions of installed skills from the API.

uvx runlayer skills update [OPTIONS]

Flag	Description
`--skill`	Update a specific skill only
`--client, -c`	Target editor client (default: `claude_code`)
`--global, -g`	Update global skills
`--dry-run, -n`	Show what would change without writing files
`--secret, -s`	API key override (optional; prefer `uvx runlayer login`). Also reads `RUNLAYER_API_KEY`
`--host, -H`	Runlayer host URL. Also reads `RUNLAYER_HOST` env var

Do installed skills auto-update? No. Files written by skills add are pinned in the lockfile (.runlayer/skill-lock.yml) and do not change until you run skills update (or re-run runlayer setup sync, which your MDM can schedule). If you connect the org-wide Runlayer Plugin instead of installing files, the skills a user can access are resolved on each request, so published changes are reflected automatically with no reinstall.

Remove

uvx runlayer skills remove [SKILL_NAME] [OPTIONS]

Flag	Description
`name`	Optional when `--all` is used. Skill name to remove
`--all`	Remove all installed skills in the selected scope
`--yes`	Skip confirmation prompt for `--all`
`--client, -c`	Target editor client (default: `claude_code`)
`--global, -g`	Remove from global skills

Remove examples

# Remove one skill
uvx runlayer skills remove ticket-triage

# Remove all project skills (prompts for confirmation)
uvx runlayer skills remove --all

# Remove all global skills without prompt
uvx runlayer skills remove --all --global --yes

Typical output (examples):

Remove 5 skill(s) from project install? [y/N]:
Aborted.

Done: 5 removed

From repo to Claude and Cursor

How a skill authored in a repo ends up in a teammate’s Claude Code or Cursor session, end to end:

Author & publish — write skills under skills/ in your repo and push them with uvx runlayer skills push --namespace <org/repo>, typically from CI (see GitHub Actions above). Every upload is security scanned before it is accepted.
(Optional) Bundle into a plugin — select skills on the Skills page and click Add to Client, create a Plugin from the Plugins page, or use uvx runlayer plugins push. See Plugins.
Install on dev machines — each developer runs skills add or plugins add, which writes files into the client-specific directories (.claude/skills/, .cursor/skills/, etc. — see File layout) so the client picks them up.
Or roll out org-wide — admins enable Auto Sync on connectors or plugins in the dashboard; developers (or your MDM) run uvx runlayer setup sync, which auto-detects installed clients (Claude Desktop, Claude Code, Cursor, VS Code, and more) and writes the config. See Auto-Sync to Clients.
Or use Runlayer Plugin — instead of installing skills file-by-file, connect the org-wide Runlayer Plugin MCP entrypoint, which exposes every skill the user can access through search tools.

Plugins

Bundle skills and connectors into a single reusable toolset

Agents

Attach skills to agents to extend what they can do

ToolGuard

How skill files are scanned for security risks

Connectors

Add and manage MCP servers your skills can use

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Overview

Authoring skills

Directory structure

SKILL.md frontmatter

Publishing

Examples

How push works

GitHub Actions

Creating from the web UI

Using skills in AI clients

Security scanning

Why a skill gets blocked

Scanning from the CLI

CI gate example

Installing

Examples

File layout

Symlink behavior

Interactive find

Managing installed skills

List

Update

Remove

Remove examples

From repo to Claude and Cursor

Plugins

Agents

ToolGuard

Connectors

​Overview

​Authoring skills

​Directory structure

​SKILL.md frontmatter

​Publishing

​Examples

​How push works

​GitHub Actions

​Creating from the web UI

​Using skills in AI clients

​Security scanning

​Why a skill gets blocked

​Scanning from the CLI

​CI gate example

​Installing

​Examples

​File layout

​Symlink behavior

​Interactive find

​Managing installed skills

​List

​Update

​Remove

​Remove examples

​From repo to Claude and Cursor

​Related Resources

Plugins

Agents

ToolGuard

Connectors

Overview

Authoring skills

Directory structure

SKILL.md frontmatter

Publishing

Examples

How push works

GitHub Actions

Creating from the web UI

Using skills in AI clients

Security scanning

Why a skill gets blocked

Scanning from the CLI

CI gate example

Installing

Examples

File layout

Symlink behavior

Interactive find

Managing installed skills

List

Update

Remove

Remove examples

From repo to Claude and Cursor

Related Resources