Agent Skills¶

Skills are reusable prompt templates that extend agent capabilities.

Skill Format¶

Skills are markdown files named SKILL.md:

---
name: cost-review
description: "Review SQL queries for cost optimization"
---

Analyze the SQL query for cost optimization opportunities:

1. Check for full table scans
2. Evaluate partition pruning
3. Suggest clustering keys
4. Estimate credit impact
5. Recommend cheaper alternatives

Focus on the query: $ARGUMENTS

Frontmatter Fields¶

Field	Required	Description
`name`	Yes	Skill name
`description`	Yes	Short description shown in the agent's `<available_skills>` listing
`alwaysApply`	No	When `true`, the skill's full body is inlined into the system prompt at session start — the agent does not need to invoke the `Skill` tool to see it. See Auto-loading skills.
`applyPaths`	No	A glob (string) or list of globs. When at least one file under the worktree matches, the skill's full body is inlined into the system prompt at session start. Useful for project-aware skills (e.g. `dbt_project.yml` for dbt projects).

Auto-loading skills¶

By default, skills are lazy-loaded: only the name and description appear in the system prompt, and the full body is fetched only when the model invokes the Skill tool. This keeps the prompt small but relies on the model choosing to load the skill at the right moment.

For skills that should always be in context for a given kind of project (e.g. "every dbt session should see the dbt-development pitfalls"), declare one of:

---
name: dbt-develop
applyPaths:
  - "dbt_project.yml"        # matches if any dbt_project.yml exists in the worktree
  - "**/dbt_project.yml"
description: "..."
---

or, for unconditional loading:

---
name: house-rules
alwaysApply: true
description: "..."
---

At session start, every matched skill body is prepended to the system prompt (BEFORE the standard <available_skills> listing — placement matters: putting the auto-loaded block first frames the bodies as binding "rules of the road" rather than background reference) under:

<auto_loaded_skill name="<skill-name>">
... full skill body ...
</auto_loaded_skill>

The agent is told it does not need to invoke the Skill tool again to access these — they are binding guidance for the session.

When to use¶

Pattern	Mode
Project-type-specific guidance (dbt project, Snowflake project, BigQuery project)	`applyPaths` with the project marker file
Team conventions that apply to every session in a repo	`alwaysApply: true` in a project-level `.opencode/skills/<skill>/SKILL.md`
Skill that's only relevant when the user asks for it explicitly (e.g. test generation, cost review)	Leave both fields unset — keep lazy loading

Context-size implications¶

When a skill auto-loads, its full body lands in the system prompt. A 250-line skill (~5K tokens) bumps the system prompt by roughly 25%. Two mitigators:

Prompt caching amortizes the cost — the system prompt is the most-cached part of the request. Across a long agent loop (~26 steps per task is typical) the auto-loaded body is read from cache, not re-billed as fresh input.
Match the glob narrowly — applyPaths: "dbt_project.yml" only fires inside dbt projects; non-dbt sessions are unaffected. The mechanism is opt-in per skill and per worktree.

If you find auto-loaded bodies are crowding out task-specific context, prefer applyPaths over alwaysApply so the skill only loads when the project markers indicate it's relevant.

Discovery Paths¶

Skills are loaded from these locations (in priority order):

Project directories (project-scoped, highest priority):
- .opencode/skills/
- .altimate-code/skill/
- .altimate-code/skills/
Global user directories:
- ~/.altimate-code/skills/

Custom paths (from config):

{
  "skills": {
    "paths": ["./my-skills", "~/shared-skills"]
  }
}

External directories & remote URLs (if not disabled):
- ~/.claude/skills/
- ~/.agents/skills/
- .claude/skills/ (project, searched up tree)
- .agents/skills/ (project, searched up tree)
```
{
  "skills": {
    "urls": ["https://example.com/skills-registry.json"]
  }
}
```

Built-in Data Engineering Skills¶

altimate ships with built-in skills for common data engineering tasks. Type / in the TUI to browse what's available and get autocomplete on skill names.

Skill	Description
`/sql-review`	SQL quality gate that lints 26 anti-patterns, validates syntax, and checks safety
`/sql-translate`	Cross-dialect SQL translation
`/schema-migration`	Schema migration planning and execution
`/pii-audit`	PII detection and compliance audits
`/cost-report`	Snowflake FinOps analysis
`/lineage-diff`	Column-level lineage comparison
`/query-optimize`	Query optimization suggestions
`/data-viz`	Interactive data visualization and dashboards
`/dbt-develop`	dbt model development and scaffolding
`/dbt-test`	dbt schema test generation
`/dbt-unit-tests`	Automated dbt unit test generation (v1.8+)
`/dbt-docs`	dbt documentation generation
`/dbt-analyze`	dbt project analysis
`/dbt-troubleshoot`	dbt issue diagnosis
`/teach`	Teach patterns from example files
`/train`	Learn standards from documents/style guides
`/training-status`	Dashboard of all learned knowledge

CLI Commands¶

Manage skills from the command line:

# Browse skills
altimate-code skill list                    # table view
altimate-code skill list --json             # JSON (for scripting)
altimate-code skill show dbt-develop        # view full skill content

# Create
altimate-code skill create my-tool                    # scaffold skill + bash tool
altimate-code skill create my-tool --language python   # python tool stub
altimate-code skill create my-tool --language node     # node tool stub
altimate-code skill create my-tool --skill-only        # skill only, no CLI tool

# Validate
altimate-code skill test my-tool            # check frontmatter + tool --help

# Install from GitHub
altimate-code skill install owner/repo              # GitHub shorthand
altimate-code skill install https://github.com/...  # full URL (web URLs work too)
altimate-code skill install ./local-path            # local directory
altimate-code skill install owner/repo --global     # install globally

# Remove
altimate-code skill remove my-tool          # remove skill + paired tool

# Publish to the linked workspace
altimate-code skill publish my-tool         # upload every file in the skill directory; re-run to update

skill publish sends the whole skill directory, not just SKILL.md, so keep secrets out of it. A built-in filter skips known file and directory names — .env*, .git, id_rsa, *.pem, *.key, *.p12, .npmrc/.netrc, credentials.json, secrets.*, .ssh/.aws, editor swap files — but it matches names only and never scans file contents, so a token inside config.yaml or a key named server.crt would still be uploaded. Built-in skills, global skills and skills the workspace itself sent you cannot be published — including the copies the VS Code / Cursor extension delivers into .claude/skills/ and .agents/skills/, which carry an .altimate-managed.json marker.

TUI¶

Open the skill browser by typing /skills in the prompt (or <leader>k):

Keyboard shortcuts:

Key	Action
Enter	Use — inserts `/<skill-name>` into the prompt
`ctrl+a`	Actions — show, edit, test, remove, or publish the selected skill to the linked workspace (the publish row is unavailable when `ALTIMATE_DISABLE_WORKSPACE=1` is set)
`ctrl+o`	New — scaffold a new skill + CLI tool (`ctrl+n` moves down the list and `ctrl+e` is line-end in the filter box, as in every dialog)
`ctrl+g`	Install a skill from a GitHub repo, URL, or local path (`ctrl+i` is Tab in most terminals, so it cannot be the chord)
Tab / Shift+Tab	Move between the Actions · New · Install buttons in the footer, then Enter — the same three without a chord
Esc	Back — returns to previous screen

Create skill (ctrl+o, or the New footer button):

Install skill (ctrl+g, or the Install footer button):

Adding Custom Skills¶

The fastest way to create a custom skill is with the scaffolder:

altimate-code skill create freshness-check

This creates two files:

.opencode/skills/freshness-check/SKILL.md — teaches the agent when and how to use your tool
.opencode/tools/freshness-check — executable CLI tool stub

Pairing Skills with CLI Tools¶

Skills become powerful when paired with CLI tools. Drop any executable into .opencode/tools/ and it's automatically available on the agent's PATH:

.opencode/tools/           # Project-level tools (auto-discovered)
~/.config/altimate-code/tools/  # Global tools (shared across projects)

A skill references its paired CLI tool through bash code blocks:

---
name: freshness-check
description: "Check data freshness across tables"
---

# Freshness Check

## CLI Reference
\`\`\`bash
freshness-check --table users --threshold 24h
freshness-check --all --report
\`\`\`

## Workflow
1. Ask the user which tables to check
2. Run `freshness-check` with appropriate flags
3. Interpret the output and suggest fixes

The tool can be written in any language (bash, Python, Node.js, etc.) — as long as it's executable.

Skill-Only (No CLI Tool)¶

You can also create skills as plain prompt templates:

---
name: cost-review
description: "Review SQL queries for cost optimization"
---

Analyze the SQL query for cost optimization opportunities.
Focus on: $ARGUMENTS

$ARGUMENTS is replaced with whatever the user types after the skill name (e.g., /cost-review SELECT * FROM orders passes SELECT * FROM orders).

Skill Paths¶

Skills are loaded from these paths (highest priority first):

.opencode/skills/ and .altimate-code/skill/ (project)
~/.altimate-code/skills/ (global)
Custom paths via config:

{
  "skills": {
    "paths": ["./my-skills", "~/shared-skills"]
  }
}

Remote Skills¶

Host skills at a URL and load them at startup:

{
  "skills": {
    "urls": ["https://example.com/skills-registry.json"]
  }
}

Disabling External Skills¶

export ALTIMATE_CLI_DISABLE_EXTERNAL_SKILLS=true

This disables skill discovery from ~/.claude/skills/ and ~/.agents/skills/ but keeps .altimate-code/skill/ discovery active.

Duplicate Handling¶

If multiple skills share the same name, project-level skills override global skills. A warning is logged when duplicates are found.

Which Skill the Agent Picks¶

The skill list the agent sees marks each skill with where it was found:

Source	Where
`workspace`	Synced from the Altimate workspace this project is linked to
`project`	Inside the project, such as `.claude/skills/`, `.agents/skills/` or `.altimate-code/skills/`
`built-in`	Ships with altimate-code
`personal`	Your own folders under your home directory, such as `~/.claude/skills/`
`other`	Anywhere else, such as a `skills.paths` entry outside the project and your home directory

When more than one skill fits a task, the agent is told to load the one from the highest source in that order, and to fall back to a lower source only when nothing higher covers the task. So a skill your team added to the workspace is preferred over a similar skill another team left in the repository. The label comes from the skill's location, not from anything written in the skill.

One exception: a project skill with exactly the same name as a workspace skill replaces it, and is listed as project. That keeps a skill you are editing in the repository, and may later publish, from being shadowed by the workspace's older copy.

Copies for Claude Code¶

In a linked project that has a .claude directory, each workspace sync can also write the workspace skills into .claude/skills/ so Claude Code finds them. Copies are written only when ALTIMATE_CLAUDE_SKILL_SYNC=1 is set; the Altimate Code plugin for Claude Code sets it when it refreshes the workspace. The copies are marked as owned by Altimate Code and git-ignored, and they are withdrawn when you unlink the project or sign out (withdrawal runs whether or not the variable is set).