Skills extend the agent’s capabilities through structured SKILL.md directories. They follow the Agent Skills specification and can be loaded explicitly or selected by the model.

Skill Format

A skill is a directory with a SKILL.md (YAML frontmatter + instructions) plus optional scripts/, references/, and assets/ directories.

---
name: refund-policy
description: Handle customer refund requests using the policy handbook.
---

# Refund Policy

Instructions and context for the LLM when this skill is active.

Explicit Sources

cliver-core discovers nothing implicitly. The application supplies skill sources — a directory of skill directories, or a single skill directory. Later sources override earlier ones by name.

from cliver_core import AgentCore, SkillManager

skills = SkillManager(sources=["./skills", "./team-skills"])
agent = AgentCore(bindings, builtin_tools=[...], skill_manager=skills)

list_skills() returns routing metadata only (name + description) — progressive disclosure keeps skill bodies out of context until activation.

Running a Skill Explicitly

run_skill(name, user_input, conversation=...) appends an activation header (skill name and location, so bundled scripts are runnable) and the skill body to the single system message, then runs the normal Re-Act loop.

result = await agent.run_skill("refund-policy", "Customer 12345 wants a refund", conversation=history)

A declared allowed-tools frontmatter narrows the advertised tools for that run. A non-empty allowlist that matches zero available tools fails fast; an absent or empty list leaves tools unchanged. run_skill() deliberately adds none of the model-driven skill tools below — the skill is already pinned.

Model-Driven Selection

With a SkillManager configured, chat() and stream():

• put a short catalogue (name + description) in the system prompt (skill_summary_limit=10 by default),
• advertise FindSkills(query, limit) to search the full catalogue,
• advertise ActivateSkill(name) to load a skill’s body as a tool result for the rest of the run.

Activation is one skill at a time. An activated skill that bundles files also gets ReadSkillFile(path) — confined to that skill’s directory (path escapes refused, UTF-8 text, 256 KiB cap). Workspace files stay on Read.

Applications can tune selection without touching the core: skill_selector ranks the prompt catalogue, skill_search replaces lexical search, and candidate_selector / tool_selector narrow the candidate pools for a query.

Skills in the CLI Application

The cliver application supplies eight skill sources: builtin skills, {config_dir}/skills, ~/.agents/skills, and project-local .cliver, .agent, .claude, .gemini, and .qwen directories. It also ships four builtin skills — brainstorm, write-plan, execute-plan, and wbs-planner.