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 skill-sources list
za agents capabilities skill-sources configure <source-name>
Configure Provider Settings
za agents capabilities skill-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 skill-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 skill-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 skill-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 skill-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 skill-sources configure skill-notes
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
include_scopes | list[str] | ["own"] | Which scopes to read from: "own" (the user's skills) and "shared_with_me" (skills others shared with the user) |
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 skill-sources configure skill-creation-skills
No additional configuration beyond enabled.
Image Search Skills
Skills for image-based search workflows.
za agents capabilities skill-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]
Capture Expert Knowledge with an Interview
The knowledge-interview skill has the agent interview a subject-matter expert. It saves each topic as a skill, with the steps, the decision rules and the facts a colleague may ask about, and the expert shares it with the team.
It runs on the Zeta Alpha platform only; the agents SDK does not ship knowledge_interview_skills_source_configuration. It runs as its own agent, so the main agent is unchanged. Add it to the tenant's bot_configurations:
{
"bot_identifier": "knowledge_interviewer",
"display_name": "Knowledge Interviewer",
"bot_type": "custom_agent",
"bot_params": {
"knowledge_interview_skills_source_configuration": { "enabled": true },
"skill_note_skills_source_configuration": { "enabled": true },
"memory_note_memory_store_configuration": { "enabled": true }
}
}
The custom_agent setup must have the note tools enabled: the agent checks the notes colleagues shared with search_notes before asking.
A colleague's agent only uses skills shared with them when its skill notes include that scope. To let the tenant's main agent use shared interview skills, set this in bot_configurations.main_agent.bot_params:
{
"skill_note_skills_source_configuration": {
"enabled": true,
"include_scopes": ["own", "shared_with_me"]
}
}
Every skill any colleague shares with the user then reaches that agent.
- Start. Ask "Interview me about how we release a QC batch", or attach a document that lists the topics. The agent posts an agenda, searches the documents and notes for what is already captured, and asks about the rest one question at a time: the decision the knowledge supports, its criteria and rules, real cases, and the edges newcomers trip over, such as mistakes, owners, exceptions and what happens afterwards.
- Confirm. At the end of each topic the agent reads back a draft skill: the steps, the criteria and rules with their limits, each marked as policy or your own rule of thumb, the cases, the pitfalls and exceptions, and facts such as who decides and where things are kept. It asks what it made sound more rigid than it is, and saves the skill, private, only after you confirm.
- Curate. Edit or delete skills on the Skills page, or ask the agent to change them in chat.
- Share. Use the share button on the skill's card. Colleagues' agents use a shared skill from their next conversation. The agent never shares anything itself.
For more on the Agent Skills protocol, see agentskills.io.