How to Use Agent Skills
🔧 Tools · 📋 Prompt
Skills are markdown documents that teach the agent how to handle specific tasks. You write a skill, drop it in a directory (or save it as a tag-note in the platform), and the agent discovers it automatically. No Python, no deployment for tag-note skills.
How Skills Work
At startup, the agent loads only each skill's name and description (~100 tokens each). When a user request matches a skill, the agent calls use_skill to load the full instructions and follows them for that task.
Three progressive levels:
- Catalog - skill name + description (always loaded at startup)
- Instructions - full step-by-step guidance (loaded on demand via
use_skill) - Resources - companion files like templates or examples (loaded on demand via
read_skill_resource)
List and Enable Sources
za agents capabilities skills-sources list
za agents capabilities skills-sources configure <source-name>
Configure Provider Settings
za agents capabilities skills-sources settings
| Setting | Type | Default | Description |
|---|---|---|---|
injection_mode | "prompt" | "tools" | "both" | "both" | How skills surface to the agent. prompt = catalog in system prompt, tools = use_skill tool only, both = both channels |
prompt_format | "text" | "xml" | "text" | Formatting of skill catalog. xml recommended for Anthropic/Claude models |
include_location_in_prompt | bool | false | Include file paths in the prompt (useful for debugging) |
writable_source | str or null | null | Which source receives skills created via create_skill at runtime |
Skill Sources
| Source | CLI name | Default | Description |
|---|---|---|---|
| Disk Skills | disk | disabled | Markdown skill files on the file system |
| In-Memory Skills | in-memory-skills | disabled | Skills defined inline in JSON configuration |
| Platform Docs Skills | platform-docs-skills | disabled | Built-in skills covering Zeta Alpha platform features |
| Tag Notes | tag-notes | disabled | Skills stored as tag-notes in the platform UI |
| Skill Notes | skill-notes | disabled | Platform-managed skill notes with scope filtering |
| Skill Creation Skills | skill-creation-skills | disabled | Meta-skills that teach the agent how to author new skills |
| Image Search Skills | image-search-skills | disabled | Skills for image-based search workflows |
Disk Skills
Loads skill files from directories on the file system. Each skill lives in its own subdirectory with a SKILL.md file and optional companion resources.
za agents capabilities skills-sources configure disk
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
skills_directories | list[str] | [] | Directories to scan for skill subdirectories |
Directory Structure
<agents project>/
├── agent_setups.json
└── skills/
├── summarize-document/
│ └── SKILL.md
└── compare-papers/
├── SKILL.md
└── comparison-template.md ← companion resource
Companion files in the skill directory are accessible to the agent via read_skill_resource.
In-Memory Skills
Skills defined entirely in JSON configuration — no files needed. Useful for simple skills or skills managed through tenant configuration.
za agents capabilities skills-sources configure in-memory-skills
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
skills | list[{name, description, body}] | [] | List of skill definitions |
{
"in_memory_skills_source_configuration": {
"enabled": true,
"skills": [
{
"name": "executive-summary",
"description": "Write an executive summary. Use when asked for 'executive summary' or 'brief for leadership'.",
"body": "## Steps\n\n1. Identify the key findings\n2. Write a 3-paragraph summary\n3. Keep under 300 words"
}
]
}
}
In-memory skills do not support companion resources (read_skill_resource returns an error). For skills that need templates, use disk skills.
Platform Docs Skills
Curated skills covering the Zeta Alpha platform features — search, tags, documents, chat, data analysis, chemistry tools, memory, and notes.
za agents capabilities skills-sources configure platform-docs-skills
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
skill_overrides | dict[str, str] or null | null | Override individual skill bodies by name |
Registers 8 built-in skills:
| Skill | Coverage |
|---|---|
platform-search | Keyword search, filters, search tabs, QA widget, federated web search |
platform-tags | Create, organize, share document collections |
platform-documents | Upload, manage, read, and chat with private documents |
platform-chat | Conversational AI, agents, context, deep research, scheduled agents |
platform-data-analysis | Spreadsheets, CSV/Excel, SQL, statistics, charting |
platform-chemistry | Molecular tools, SMILES, PubChem, drug-likeness |
platform-skills-and-memory | Persistent memory, custom skill authoring |
platform-notes | Create, manage, and find notes and annotations |
Tag Notes
Skills stored as tag-notes in the platform UI — no file system access or deployment needed. Anyone with access to a tag can author and share skills.
za agents capabilities skills-sources configure tag-notes
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
tag_ids | list[str] | [] | Tags to load skills from |
include_favorites | bool | false | Also load skills from the user's favorites tag |
Skill Notes
Platform-managed skill notes with scope-based access control.
za agents capabilities skills-sources configure skill-notes
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
include_scopes | list[str] | ["own"] | Which scopes to read from (e.g. ["own"], ["own", "shared"]) |
allowed_skill_note_ids | list[str] or null | null | Restrict to specific skill note IDs; null loads all |
Skill Creation Skills
Meta-skills that teach the agent how to author new skills through conversation. When a user asks the agent to remember a workflow or encode a process, the agent follows these meta-skills to write proper SKILL.md files with frontmatter, trigger phrases, and step-by-step instructions.
za agents capabilities skills-sources configure skill-creation-skills
No additional configuration beyond enabled.
Image Search Skills
Skills for image-based search workflows.
za agents capabilities skills-sources configure image-search-skills
No additional configuration beyond enabled.
Writing a Skill
Create a SKILL.md file:
---
name: summarize-document
description: 'Summarize a document. Use when asked to "summarize", "give me a summary", or "what is this paper about".'
allowed_tools:
- read_document
- retrieve_metadata
---
## Steps
1. Use the document context to get the document ID, or ask the user which document to summarize
2. Call `retrieve_metadata` to get the title, source, and abstract
3. Call `read_document` to fetch the full content
4. Produce a structured summary:
- **Key findings** - the main claims or results
- **Methodology** - how the work was done
- **Conclusions** - implications and takeaways
5. Cite specific sections using the document URL
The description field is the discovery surface — write it with trigger phrases so the agent knows when to activate the skill. The allowed_tools field tells the agent which tools it's expected to use.
Managing Skills via the CLI
Add a Skill
za agents skill add [NAME] [-d "description"] [--no-generate]
By default, this runs the agent headlessly to generate the skill content using its built-in create_skill capability. The agent writes a complete Skill.md with proper frontmatter and step-by-step instructions based on your description.
Use --no-generate to create an empty template instead:
za agents skill add "summarize-document" -d "Summarize a document" --no-generate
This creates:
skills/
summarize-document/
Skill.md
If you omit the name or description, the CLI prompts for them interactively.
List Skills
za agents skill list
Remove a Skill
za agents skill remove [NAME]
For more on the Agent Skills protocol, see agentskills.io.