Otto skills

Skills are structured workflows Otto loads on demand, following the open Agent Skills format. A skill is a folder containing a SKILL.md file with YAML frontmatter and Markdown instructions, plus any scripts or supporting files the workflow needs. Skills encode domain knowledge for a specific task such as authoring a Dag, diagnosing a failure, or upgrading Airflow.

Otto’s bundled skills come from two sources:

• Open-source skills in the astronomer/agents repository cover Airflow operations, Dag authoring and testing, dbt and Cosmos, lineage and metadata, data discovery, and Airflow extensions.
• Proprietary skills are available only through Otto. They cover production failure investigation, Airflow upgrades, and migrations from legacy orchestration systems, and they rely on Astronomer’s proprietary compatibility knowledge base.

You can also author your own skills for team-specific workflows. To browse what’s loaded in your current session, run /skills in an interactive Otto session.

Author a skill

Ask Otto to write a skill

The most effective skills are extracted from real work. Complete a task in an Otto session, providing context and corrections as you go, then describe the workflow you want codified:

> Write a skill called deploy-to-staging that verifies the current branch is main, runs astro deploy against the staging Deployment, and confirms the deploy succeeded in the Astro UI. Use it whenever I ask to deploy, push, or test against staging.

Otto generates a SKILL.md under .astro/otto/skills/<skill-name>/ and shows you the draft for review. Edit the file in your editor or ask Otto to revise it before you commit.

Skill anatomy

Each skill is a folder with a SKILL.md file. The frontmatter declares the skill’s name and trigger description, and the body holds the workflow Otto follows when the skill fires.

1
---
2
name: deploy-to-staging
3
description: Deploy the current project to the staging Deployment. Use when the user asks to deploy to staging, push to staging, or test against staging.
4
---
5
6
# Deploy to staging
7
8
Follow this workflow to deploy the project:
9
10
1. Verify the current branch is `main`.
11
2. Run `astro deploy --deployment-id <staging-deployment-id>`.
12
3. Confirm the deploy succeeded in the Astro UI.

The description field is the most important part: it determines when Otto loads the skill. Include one sentence on what the skill does and the phrasing that should trigger it, prefixed with “Use when…”.

Skills can also include scripts, templates, or reference docs alongside SKILL.md. For example, the analyzing-data skill ships scripts that run a full Jupyter kernel for data exploration.

Commit .astro/otto/skills/ to your repository so every engineer on the team picks up the same skills.

Test and iterate

Run a prompt that should fire the skill and confirm Otto loads it. If the skill doesn’t fire, refine the description. If it fires for the wrong prompts, narrow the trigger phrasing. Ask Otto to update the skill the same way you’d refine a prompt: describe what’s off, and Otto edits the file for you.

Where skills live

Otto loads skills from your project repository and your home directory:

• Project skills (.astro/otto/skills/): Skills committed alongside your Astro project so the whole team picks them up. Otto walks up from the current folder to the git repository root, so skills in any ancestor directory also load.
• User skills (~/.astro/otto/skills/): Your personal skills, available across every project on this computer. These live in your home directory and stay out of your project repository.
• Cross-harness skills (.agents/skills/ and ~/.agents/skills/): Skills following the standard Agent Skills layout, available to Otto and any other Agent Skills-compatible tool. Use these when you want the same skills to load across multiple agents.

Otto also recognizes top-level .md files in the .astro/otto/skills/ paths as single-file skills. The .agents/skills/ paths require a directory with a SKILL.md file.

To point Otto at skills from other agent harnesses, such as ~/.claude/skills or ~/.codex/skills, list the paths in the skills array in ~/.astro/otto/settings.json. See Otto settings.

How Otto loads skills

When a prompt matches a skill’s description, Otto loads the skill’s SKILL.md content and follows the workflow.

You can also invoke a skill directly. Type / and start typing the skill name to filter the autocomplete, or run /skills to browse the full list.