zeph 0.22.4

Lightweight AI agent with hybrid inference, skills-first architecture, and multi-channel I/O
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

# Skills

Skills give Zeph specialized knowledge for specific tasks. Each skill is a markdown file (`SKILL.md`) containing instructions and examples that are injected into the LLM prompt when relevant.

Instead of loading all skills into every prompt, Zeph selects only the top-K most relevant (default: 5) using a combination of BM25 keyword matching and embedding cosine similarity fused via Reciprocal Rank Fusion. This keeps prompt size constant regardless of how many skills are installed.

## How Matching Works

1. You send a message — for example, "check disk usage on this server"
2. Zeph embeds your query using the configured embedding model
3. The top 5 most relevant skills are selected by cosine similarity
4. Selected skills are injected into the system prompt
5. Zeph responds using the matched skills

This happens automatically on every message. You never activate skills manually.

## Bundled Skills

| Skill | Description |
|-------|-------------|
| `api-request` | HTTP API requests using curl |
| `docker` | Docker container operations |
| `file-ops` | File system operations — list, search, read, analyze |
| `git` | Git version control — status, log, diff, commit, branch |
| `mcp-generate` | Generate MCP-to-skill bridges |
| `setup-guide` | Configuration reference |
| `skill-audit` | Spec compliance and security review |
| `skill-creator` | Create new skills |
| `system-info` | System diagnostics — OS, disk, memory, processes |
| `web-scrape` | Extract data from web pages |
| `web-search` | Search the internet |

Use `/skills` in chat to see active skills and their usage statistics.

## Key Properties

- **Progressive loading**: only metadata (~100 tokens per skill) is loaded at startup. Full body is loaded on first activation and cached
- **Hot-reload**: edit a `SKILL.md` file, changes apply without restart
- **Two matching backends**: in-memory (default) or Qdrant (faster startup with many skills, delta sync via BLAKE3 hash). Both support BM25+cosine hybrid search via Reciprocal Rank Fusion (enabled by default, disable with `hybrid_search = false`)
- **Secret gating**: skills that declare `x-requires-secrets` in their frontmatter are excluded from the prompt if the required secrets are not present in the vault. This prevents the agent from attempting to use a skill that would fail due to missing credentials
- **Compact prompt mode**: when context budget is tight, `skills.prompt_mode = "auto"` (default) switches to a condensed XML format that includes only name, description, and triggers — ~80% smaller than full bodies. Force with `"compact"` or disable with `"full"`. See [Context Engineering — Skill Prompt Modes](../advanced/context.md#skill-prompt-modes)
- **Channel allowlist**: skills can declare which I/O channels they are permitted to run on via `x-channels` in YAML frontmatter. When set, the skill is excluded from matching on channels not in the list. Omit to allow all channels.
- **Description cap**: skill descriptions are capped at 2048 characters to prevent oversized prompt injection from user-created skills
- **Injection sanitization**: skill bodies and `/skill create` inputs are sanitized against prompt injection. URL domains in skill bodies are checked against a configurable allowlist. Untrusted skill content has structural XML tags escaped before prompt injection

## Natural Language Skill Generation

Use `/skill create` to generate a new skill from a natural language description:

```
/skill create "A skill that formats JSON files using jq"
```

Zeph generates a complete `SKILL.md` with frontmatter, instructions, and examples via LLM reflection. Skills can also be mined from GitHub repositories — Zeph analyzes repo structure and README to extract actionable skill definitions.

Duplicate detection prevents creating skills that overlap with existing ones by checking semantic similarity against the skill registry.

## Semantic Confusability Mitigation

When multiple skills have overlapping descriptions, the matcher can confuse them. Zeph mitigates this with:

- **Category grouping**: skills are grouped by functional category, and matching considers category affinity alongside raw similarity
- **Two-stage matching**: an initial broad match is followed by a disambiguation stage that compares top candidates within the same category
- Use `/skill confusability` to generate a report showing which skills are at risk of being confused

## Skill Mining

Skill mining automates discovery and generation of new skills by searching GitHub for relevant repositories and extracting SKILL.md descriptions from their READMEs and documentation. Configure via `[skills.mining]`:

```toml
[skills.mining]
queries             = ["topic:cli-tool language:rust stars:>100"]
max_repos_per_query = 20      # capped at 100 by the GitHub API
dedup_threshold     = 0.85    # cosine similarity threshold against existing skills
output_dir          = ""      # target directory; defaults to managed skills dir
generation_provider = ""      # provider for skill generation; falls back to primary
embedding_provider  = ""      # provider for embedding dedup; falls back to primary
rate_limit_rpm      = 25      # max GitHub search requests per minute
```

Mining searches GitHub using the configured `queries`, fetches each repo's documentation, calls the `generation_provider` to produce a SKILL.md, then deduplicates against existing skills using embedding similarity. Skills with similarity above `dedup_threshold` to an existing skill are skipped. The GitHub API caps `max_repos_per_query` at 100.

## External Skill Management

Zeph includes a `SkillManager` that installs, removes, and verifies external skills. Skills can be installed from git URLs or local paths into the managed directory (`~/.config/zeph/skills/`), which is automatically appended to `skills.paths`.

Installed skills start at the `quarantined` trust level. Use `zeph skill verify` to check BLAKE3 integrity, then promote with `zeph skill trust <name> verified` or `zeph skill trust <name> trusted`.

See [CLI Reference — `zeph skill`](../reference/cli.md#zeph-skill) for the full subcommand list, or use the in-session `/skill install` and `/skill remove` commands for hot-reloaded management without restart.

## Skill & Plugin Registry Discovery

Zeph supports opt-in discovery and installation of skills and plugins from external registries (like [skills.sh](https://www.skills.sh)) without needing to know the exact git URL or file path beforehand.

**Key points:**

- **Opt-in only** — Registry lookups are disabled by default. No network calls are made unless you explicitly enable `[skills.registry] enabled = true` in `config.toml`.
- **Two-step workflow** — Use `zeph skill search <query>` to find skills by keyword, then install one by its registry ID with `zeph skill get <registry-id>`. The same flow works for plugins: `zeph plugin search` and `zeph plugin get`.
- **Same security gates** — Fetched packages route through the existing frontmatter validation and injection-pattern scan before install, so no new content-safety bypass is introduced.
- **Distinct from `install`** — The existing `zeph skill install <url|path>` and `zeph plugin add <path>` commands remain unchanged. Registry-based install uses the separate `get` commands (`zeph skill get`, `zeph plugin get`) to avoid ambiguity.

### Setting up registry access

Edit `config.toml` or run `zeph init` / `zeph --migrate-config` to add:

```toml
[skills.registry]
enabled = true
backend_kind = "skills-sh"              # public skills.sh registry
# auth_vault_key = "ZEPH_SKILL_REGISTRY_TOKEN"  # optional: vault key for auth token if registry requires it
```

### Using registry search and install

```bash
# Search for skills by keyword
zeph skill search "json"

# Install a skill by registry ID (as printed by search)
zeph skill get skills-sh/json-formatter

# Same flow for plugins
zeph plugin search "github"
zeph plugin get skills-sh/github-integration
```

If the registry is not enabled, these commands print an actionable message explaining how to opt in.

## Next Steps

- [Add Custom Skills](../guides/custom-skills.md) — create your own skills
- [Context Budgets](context-budgets.md) — how BATS budget hints affect skill prompt modes
- [Self-Learning Skills](../advanced/self-learning.md) — how skills evolve through failure detection
- [SkillOrchestra](../advanced/skill-orchestra.md) — RL-based adaptive skill routing
- [NL Skill Generation](../advanced/nl-skill-generation.md) — generate skills from descriptions or GitHub repos
- [Skill Trust Levels](../advanced/skill-trust.md) — security model for imported skills