Skills

Teach the agent domain know-how with skills — from simple checklists to full professional procedures, loaded on demand.

What are skills

Skills are reusable packages of instructions and resources (a folder + a SKILL.md) that teach the agent to perform specific tasks — anything from a simple checklist to a full professional procedure with supporting files (scripts, templates). Typical uses: deployment procedures, code review checklists, API integration guides.

When a session starts, the app adds discovered skill names and descriptions to the agent's instructions; when your request matches a skill (or you name it explicitly), the agent loads the skill's full content before acting.

Built-in & custom skills

The app ships with basic built-in skills (such as web search); "More → Skills" in the sidebar lists what's currently available.

Custom skills are discovered from fixed locations:

• Global skills: ~/.agents/skills/<name>/SKILL.md (available in all sessions);
• Project skills: .agents/skills/<name>/SKILL.md inside the project (current project only);
• Legacy locations: .goose/skills/ and similar are still recognized (technical identifiers kept by convention).

Creating a skill

A SKILL.md needs YAML frontmatter (name and description), followed by the skill body:

---
name: code-review
description: Code review checklist for pull requests
---

# Code review checklist

When reviewing code, check each of these areas:

## Functionality
- [ ] Implementation matches the requirement
- [ ] Edge cases are handled
- [ ] Error handling is appropriate

## Security
- [ ] No hardcoded credentials
- [ ] User input is validated

The description decides when the agent matches the skill — spell out "what it does and when to use it" for the best results.

Skills vs. hint files vs. workflows

• Hint files (.cyhints / .goosehints / AGENTS.md): project conventions, applied automatically every session;
• Skills: domain knowledge and methods, loaded on demand;
• Workflows: executable, shareable task configurations, one click to run.

They compose well: hint files declare the rules, skills hold the know-how, workflows fix the steps.

This page is adapted from upstream open-source documentation (Apache-2.0) with modifications; see /legal/provenance for sources and changes.