Skip to main content

Skills

Skills are Agent's packaged expert workflows. Each skill defines a complete execution strategy — which tools to use, in what order, and what output to produce — so the AI can handle specific classes of tasks reliably instead of improvising every time.

How Skills Work​

When Agent starts, it loads all available skills and injects each skill's name and description into the system prompt. When you make a request, the AI uses semantic matching to decide whether a skill should be activated, then loads the full instructions through tool calls and follows them.

The whole process is automatic. You do not need to memorize commands or manually choose a mode — just describe what you want to do naturally.

User: "Help me commit these changes"
  → AI recognizes that the `commit` skill is relevant
  → Loads the full instructions (`read_skill`)
  → Follows the workflow to inspect changes, generate a commit message, and run `git commit`

Built-in Skills​

Agent includes three core built-in skills for engineering workflows:

commit — Smart Commit Assistant​

Runs git commit safely, automatically scanning for large files and binary artifacts before committing.

Workflow:

  1. Check the Git repository state and current branch
  2. Scan all new untracked files for size (>1MB warning, >10MB blocked) and risky types (build outputs, dependency directories, media files, and similar artifacts)
  3. If problems are found, stop immediately, report them, and suggest appropriate .gitignore rules
  4. If checks pass, show a change summary and generate a Conventional Commits-style message
  5. Run git add and git commit

Typical triggers: "Commit the code", "Help me commit", "Prepare a commit"

code-reviewer — Code Review Assistant​

Analyzes code quality, security issues, and best practices in two modes:

  • Local review: review a git diff, a specific commit, or branch differences
  • Remote review: review a GitLab merge request directly

Typical triggers: "Review these changes", "Check the code quality", "Review this MR"

serena — LSP Coding Assistant​

Provides symbol-level code analysis and precise editing through the Language Server Protocol (LSP), making it ideal for large codebases.

Core capabilities:

  • Find functions, classes, and variables quickly through symbol indexing
  • Replace symbol definitions precisely without reading whole files
  • Find references, jump to definitions, and rename symbols
  • Support major languages such as Go, TypeScript, Python, and Rust

Typical triggers: "Analyze this module", "Refactor this class", "Find every call site of this function"

Skill Loading Rules​

Skills are loaded from two locations, and user skills take precedence over built-in skills with the same name:

1. <executable-directory>/builtin-skills/   ← Built-in skills distributed with the app
2. ~/.aiagent/skills/                      ← User-defined skills (can override built-ins)

Each skill is a standalone directory with SKILL.md as the main instruction file:

~/.aiagent/skills/
  my-skill/
    SKILL.md          ← Required, main skill instructions
    reference.md      ← Optional supporting file (AI can read on demand)
    examples/
      sample.json     ← Optional, any nested file structure is supported

The AI can inspect all supporting files in a skill directory with list_skill_files and read specific ones with read_skill_file. This makes it easy to keep large references, example data, and the core instructions separate.

Typical Skill Use Cases​

Skills are especially useful in these scenarios:

ScenarioBenefit
Team-standard workflowsEveryone follows the same process, producing predictable results
Repetitive task automationCode review, commits, documentation generation — no need to rewrite prompts
Encapsulating domain knowledgeTurn best practices into reusable operational instructions
Multi-step flow controlInvoke tools in the right order and handle exception branches correctly

Team Collaboration Pattern​

It is a good practice to version-control skill files inside your repository:

# Keep team skills inside the project repository
project-repo/
  .aiagent-skills/
    release-checklist/
      SKILL.md
    pr-review/
      SKILL.md
      review-standards.md

This lets skills evolve together with the codebase and be reviewed through normal code review, turning AI behavior into a maintainable engineering asset.

Next​