Skip to content

Agent Skills

Agent skills let AlphaBase discover reusable instructions from your repo or home directory. Skills are loaded on-demand via the native skill tool—agents see available skills and can load the full content when needed. Review repository and global skills before use. Skill instructions can direct an agent to read files, invoke tools, or contact external services; they do not grant privileges by themselves and do not replace runtime permissions.

Create and load a skill

On desktop, open Automation & Extensions → Skills Manager or Settings → Skills.

  1. Inspect the source, scope, readiness, required tools, and connections.
  2. Choose Create Workspace Skill for the open project or Create Global Skill for reuse across projects in that environment.
  3. Enter a name, description, and instructions, then create the skill.
  4. Load an available skill into the composer or choose its offered slash command. Describe the task and send it; loading instructions alone does not execute work.

Definitions use a folder containing SKILL.md, with a name and description in YAML frontmatter. Inspect the source shown in the manager rather than assuming skills from another app are installed or ready to run in AlphaBase.

Import and review

Choose Import From URL or Import From File and confirm the target scope. Supported imports are staged for review; a successful import does not establish approval or readiness.

Open Review queue when offered. Inspect the instructions, source, scope, scan, and evaluation before approving or rejecting. Missing packaged resources, failed checks, or quarantine can prevent approval. Resolve the stated problem before retrying.

Use Local Skills Lab

Local Skills Lab records reusable procedures from verified work when Learn is enabled. Expand it to inspect learned procedures, drafts, and the evidence behind them.

Under Settings & maintenance → Agent policy, review Use approved procedures, Propose from verified runs, and Auto-approve learned procedures. Turn off auto-approval and save the policy if validated learned procedures should wait for manual review. Learning and procedure use are separate controls.

Learned procedures retain their saved scope and matching-task requirements. They do not rewrite a model or bypass permissions. Optional shared discovery also depends on the configured connection and its consent controls.


Place files

Create one folder per skill name and put a SKILL.md inside it. AlphaBase searches these locations:

  • Project config: .alphabase/skills/<name>/SKILL.md
  • Global config: ~/.config/alphabase/skills/<name>/SKILL.md
  • Global desktop definitions: ~/.alphabase/skills/<name>/SKILL.md where home-directory discovery is enabled
  • Project Claude-compatible: .claude/skills/<name>/SKILL.md
  • Global Claude-compatible: ~/.claude/skills/<name>/SKILL.md
  • Project agent-compatible: .agents/skills/<name>/SKILL.md
  • Global agent-compatible: ~/.agents/skills/<name>/SKILL.md

Understand discovery

For project-local paths, AlphaBase walks up from your current working directory until it reaches the git worktree. It loads any matching skills/*/SKILL.md in .alphabase/ and any matching .claude/skills/*/SKILL.md or .agents/skills/*/SKILL.md along the way.

Global definitions are also loaded from ~/.config/alphabase/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md, and ~/.agents/skills/*/SKILL.md.


Write frontmatter

Each SKILL.md must start with YAML frontmatter. The basic definition fields include:

  • name (required)
  • description (required)
  • license (optional)
  • compatibility (optional)
  • metadata (optional, string-to-string map)

Additional capability metadata can affect readiness, such as required tools or connections. Inspect the discovered skill’s readiness before using it.


Validate names

name must:

  • Be 1–64 characters
  • Be lowercase alphanumeric with single hyphen separators
  • Not start or end with -
  • Not contain consecutive --
  • Match the directory name that contains SKILL.md

Equivalent regex:

^[a-z0-9]+(-[a-z0-9]+)*$

Follow length rules

description must be 1-1024 characters. Keep it specific enough for the agent to choose correctly.


Use an example

Create .alphabase/skills/git-release/SKILL.md like this:

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: alphabase
metadata:
audience: maintainers
workflow: github
---
## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command
## When to use me
Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

Recognize tool description

AlphaBase lists available skills in the skill tool description. Each entry includes the skill name and description:

<available_skills>
<skill>
<name>git-release</name>
<description>Create consistent releases and changelogs</description>
</skill>
</available_skills>

The agent loads a skill by calling the tool:

skill({ name: "git-release" })

Configure permissions

Control which skills agents can access using pattern-based permissions in alphabase.json:

{
"permission": {
"skill": {
"*": "allow",
"pr-review": "allow",
"internal-*": "deny",
"experimental-*": "ask"
}
}
}
PermissionBehavior
allowSkill loads immediately
denySkill hidden from agent, access rejected
askUser prompted for approval before loading

Patterns support wildcards: internal-* matches internal-docs, internal-tools, etc.


Override per agent

Give specific agents different permissions than the global defaults.

For custom agents (in agent frontmatter):

---
permission:
skill:
"documents-*": "allow"
---

For built-in agents (in alphabase.json):

{
"agent": {
"plan": {
"permission": {
"skill": {
"internal-*": "allow"
}
}
}
}
}

Disable the skill tool

Completely disable skills for agents that shouldn’t use them:

For custom agents:

---
permission:
skill: deny
---

For built-in agents:

{
"agent": {
"plan": {
"permission": {
"skill": "deny"
}
}
}
}

When disabled, the <available_skills> section is omitted entirely.


Troubleshoot loading

If a skill does not show up:

  1. Verify SKILL.md is spelled in all caps
  2. Check that frontmatter includes name and description
  3. Ensure skill names are unique across all locations
  4. Check permissions—skills with deny are hidden from agents