Add Custom Skills

Create your own skills to teach Zeph new capabilities. A skill is a single SKILL.md file inside a named directory.

Skill Structure

skills/
└── my-skill/
    └── SKILL.md

SKILL.md Format

Two parts: a YAML header and a markdown body.

---
name: my-skill
description: Short description of what this skill does.
---
# My Skill

Instructions and examples go here. This content is injected verbatim
into the LLM context when the skill is matched.

Header Fields

Field	Required	Description
`name`	Yes	Unique identifier (1-64 chars, lowercase, hyphens allowed)
`description`	Yes	Used for embedding-based matching against user queries
`compatibility`	No	Runtime requirements (e.g., “requires curl”)
`allowed-tools`	No	Space-separated tool names this skill can use
`x-requires-secrets`	No	Comma-separated secret names the skill needs (see below)

Secret-Gated Skills

If a skill requires API credentials or tokens, declare them with x-requires-secrets:

---
name: github-api
description: GitHub API integration — search repos, create issues, review PRs.
x-requires-secrets: github-token, github-org
---

Secret names use lowercase with hyphens. They map to vault keys with the ZEPH_SECRET_ prefix:

`x-requires-secrets` name	Vault key	Env var injected
`github-token`	`ZEPH_SECRET_GITHUB_TOKEN`	`GITHUB_TOKEN`
`github-org`	`ZEPH_SECRET_GITHUB_ORG`	`GITHUB_ORG`

Activation gate: if any declared secret is missing from the vault, the skill is excluded from the prompt. It will not be matched or suggested until the secret is provided.

Scoped injection: when the skill is active, its secrets are injected as environment variables into shell commands the skill executes. Only the secrets declared by the active skill are exposed — not all vault secrets.

Store secrets with the vault CLI:

zeph vault set ZEPH_SECRET_GITHUB_TOKEN ghp_yourtokenhere
zeph vault set ZEPH_SECRET_GITHUB_ORG my-org

See Vault — Custom Secrets for full details.

Name Rules

Lowercase letters, numbers, and hyphens only. No leading, trailing, or consecutive hyphens. Must match the directory name.

Skill Resources

Add reference files alongside SKILL.md:

skills/
└── system-info/
    ├── SKILL.md
    └── references/
        ├── linux.md
        ├── macos.md
        └── windows.md

Resources in scripts/, references/, and assets/ are loaded lazily on first skill activation (not at startup). OS-specific files (linux.md, macos.md, windows.md) are filtered by platform automatically.

Local file references in the skill body (e.g., [see config](references/config.md)) are validated at load time. Broken links and path traversal attempts (../../../etc/passwd) are rejected.

Configuration

[skills]
paths = ["./skills", "/home/user/my-skills"]
max_active_skills = 5

Skills from multiple paths are scanned. If a skill with the same name appears in multiple paths, the first one found takes priority.

Testing Your Skill

Place the skill directory under ./skills/
Start Zeph — the skill is loaded automatically
Send a message that should match your skill’s description
Run /skills to verify it was selected

Changes to SKILL.md are hot-reloaded without restart (500ms debounce).

Installing External Skills

Use zeph skill install to add skills from git repositories or local paths:

# From a git URL — clones the repo into ~/.config/zeph/skills/
zeph skill install https://github.com/user/zeph-skill-example.git

# From a local path — copies the skill directory
zeph skill install /path/to/my-skill

Installed skills are placed in ~/.config/zeph/skills/ and automatically discovered at startup. They start at the quarantined trust level (restricted tool access). To grant full access:

zeph skill verify my-skill        # check BLAKE3 integrity
zeph skill trust my-skill trusted  # promote trust level

In an active session, use /skill install <url|path> and /skill remove <name> — changes are hot-reloaded without restart.

See Skill Trust Levels for the full security model.

Deep Dives

Skills — how embedding-based matching works
Self-Learning Skills — automatic skill evolution
Skill Trust Levels — security model for imported skills

Keyboard shortcuts

Zeph Documentation