Skills

A skill is a self-contained capability package — a folder containing instructions and optional supporting files — that Ziva loads automatically when the current task matches. Unlike slash commands, which you invoke manually, skills are picked up by the agent on their own when the conversation calls for them.

Locations

Ziva loads skills from these directories (highest priority first):

1. Project-level:
   • <project>/.ziva/skills/
   • <project>/.agents/skills/
2. User-level:
   • ~/.ziva/skills/
   • ~/.agents/skills/

A skill in a higher-priority location replaces one with the same name found lower down.

Security note: Skills can instruct the agent to perform any action and may include executable code. Review skill content before use.

How skills work

1. Ziva scans skill locations and extracts names and descriptions at startup
2. The agent can see available skill descriptions as it reasons about your task
3. When a task matches, the agent loads the full SKILL.md file using relative paths to reference scripts and assets

This is progressive disclosure: skill descriptions are always available, but full instructions load only when the agent determines they’re relevant.

Skill commands

Skills register as /skill:name commands that you can invoke manually:

/skill:state-machine           # Load and execute the skill
/skill:state-machine refactor  # Load skill with arguments

Arguments after the command are appended to the skill content as User: <args>, allowing you to provide additional context or parameters directly.

Skill structure

A skill is a directory containing at minimum a SKILL.md file. Everything else is freeform.

state-machine/
├── SKILL.md              # Required: frontmatter + instructions
├── examples/             # Reference files
│   └── limboai-enemy.tscn
└── templates/            # Templates or helper files
    └── base-state.gd

SKILL.md format

The SKILL.md file combines frontmatter with instructions:

---
name: state-machine
description: Use when building or refactoring a state machine in Godot 4. Covers AnimationTree, LimboAI, and manual Node-per-state setups.
---
 
# State Machine Setup
 
When the user asks to build or debug a state machine:
 
1. Ask which approach: AnimationTree, LimboAI, or manual Node subclasses.
2. For LimboAI, default to bt_state.tres resources unless told otherwise.
3. Always add a debug print on state-enter unless explicitly told not to.
 
See examples/limboai-enemy.tscn for a known-good template.
See templates/base-state.gd for boilerplate code.

Files can be referenced using relative paths; the agent will read them as needed.

Frontmatter fields

Name rules

• 1-64 characters
• Lowercase letters, numbers, hyphens only
• No leading/trailing hyphens
• No consecutive hyphens

Valid: state-machine, pdf-tools, godot-editor Invalid: StateMachine, -state, state--machine

Description best practices

The description is crucial — it determines when the agent loads the skill. Be specific.

Good: “Refactor or debug state machines in Godot 4, including AnimationTree, LimboAI, and manual Node-per-state approaches.”

Poor: “Helps with state machines.”

Creating a skill

1. Create a directory in ~/.ziva/skills/ or <project>/.ziva/skills/
2. Add a SKILL.md file with name, description, and your instructions
3. Add supporting files (examples, templates, scripts) alongside it

Example:

~/.ziva/skills/
└── state-machine/
    ├── SKILL.md
    └── examples/
        └── limboai-enemy.tscn

SKILL.md:

---
name: state-machine
description: Use when building or refactoring a state machine in Godot 4. Covers AnimationTree, LimboAI, and manual Node-per-state setups.
---
 
When the user asks to build or debug a state machine:
 
1. Ask which approach: AnimationTree, LimboAI, or manual Node subclasses.
2. For LimboAI, default to bt_state.tres resources unless told otherwise.
3. Always add a debug print on state-enter unless explicitly told not to.
 
See examples/limboai-enemy.tscn for a known-good template.

Skills vs slash commands

See also

• Slash commands — /-style prompts you invoke manually
• AGENTS.md — project-wide instructions that always apply