Skip to main content

​
Overview

Skills package reusable instructions, scripts, and resources that agents can use for specialized tasks. Use a skill when you want an agent to follow a repeatable workflow, apply team-specific conventions, or use supporting files without repeating the same guidance in every prompt. Poolside supports the Agent Skills format. Each skill is a folder with a SKILL.md file that describes when to use the skill and how the agent should apply it. A skill can also include supporting files, such as scripts, references, and templates.

​
When to use a skill

Use a skill when you want agents to:
  • Follow a repeatable workflow, such as reviewing code against team conventions
  • Apply specialized domain guidance for a task
  • Use supporting files such as templates, reference docs, or helper scripts
  • Reuse the same procedure across agents, projects, or team members
Do not use a skill for:
  • Broad agent behavior that should apply to every task (use agent instructions instead)
  • Project-specific coding rules that should live with the project (use AGENTS.md instead)
  • Read-only reference collections that agents need to search rather than apply as instructions (use a repository instead)
  • External tools or services that agents need to invoke (use an MCP server instead)

​
How skills work

Skills can apply automatically when the description in SKILL.md matches your request. You can also explicitly select a skill from the skills menu for the current prompt. The description in SKILL.md determines when the agent applies the skill. When the agent uses a skill, it reads the skill instructions and any supporting files. The agent can only use skills that are available to it and that you have permission to use.

​
Skill sources

Skills come from two sources: local directories on your machine or in your project, and organization-managed repositories. The skills menu groups available skills by source.
SourceWhat it’s for
Project SkillsSkills stored with the current project
Global SkillsPersonal skills available across projects
Remote SkillsSkills from organization-managed repositories
Project Skills and Global Skills are available automatically from local directories. Remote Skills come from repositories configured in the Poolside Console and must be enabled in agent configuration before agents can use them. For setup instructions, see Remote skills below. Poolside scans the following local directories for skills:
  • ~/.config/poolside/skills/
  • .poolside/skills/
  • .agents/skills/
Poolside also scans directories used by other tools that use the Agent Skills format, so skills you’ve already created for those tools appear in the skills menu automatically.

​
Skill format

A skill must be a directory with a SKILL.md file. The directory name must match the name field in the SKILL.md frontmatter. The SKILL.md file must include YAML frontmatter with a name and description, followed by Markdown instructions. 
my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

---
name: code-review
description: Review code changes against team review guidelines. Use when reviewing pull requests, diffs, or local code changes.
---

# Code review

Use this skill to review code changes against the team's review checklist.

## Review process

1. Read the diff.
2. Check the changed code against the review checklist in `references/review-checklist.md`.
3. Report only actionable issues.
The description helps the agent decide when to use the skill. Write it so it describes both what the skill does and when the agent should use it. Do not rely on the Agent Skills allowed-tools or compatibility fields to restrict tools or where a skill can run. Poolside does not enforce those fields. For the full skill format, see the Agent Skills specification.

​
Remote skills

Remote skills give your team a shared set of skills without requiring local setup. They come from repositories that administrators configure in the Poolside Console, and a repository can contain one or more skills. You can use a remote skill when your agent configuration enables it and you have permission to access the source repository. In the agent creation and edit flow, remote skills appear in the Skills section, grouped by repository name. You access skills at the repository level. If you can access the repository, the agent can use any enabled skill from it. To add remote skills to your organization, create a repository in the Poolside Console. Then create or edit a managed agent, open the Skills section, and enable the discovered skills from that repository.

​
Access and security

Remote skills follow repository-level access controls. Local skills are files on your machine or in your project and have no per-skill access controls. If your organization needs to restrict the runtime environment, use sandboxes instead.

​
Skills and sandboxes

If you use local sandboxes, prefer project-level skills in .poolside/skills/ when a skill must be available inside the sandbox. User-level skills in ~/.config/poolside/skills/ are not mounted in local sandboxes. Only workspace directories and user-configured extra mounts are available inside the container.

​
Use a skill

Use the skills menu when you want to see available skills or explicitly apply one to your current prompt. Prerequisites
  • You have an active Poolside Assistant or pool code session.
  • The skill is available from a local skill directory or a remote repository.
Steps
  1. In Poolside Assistant or pool code, type /skills.
  2. Review the available skills in the menu. The menu groups skills by source, such as Project Skills, Global Skills, and Remote Skills.
  3. Select the skill you want to use.
  4. Finish your prompt and send it.
The selected skill applies to the current prompt. Skills can also apply automatically when the skill description matches your request.

​
Create a local skill

Add a local skill when you want to test a skill in a project before sharing it with a team or assigning it to an agent. Prerequisites
  • You have write access to the project where you want to add the skill.
Steps
  1. In your project, create a skill directory under .poolside/skills/: 
    mkdir -p .poolside/skills/code-review
  2. Add a SKILL.md file: 
    touch .poolside/skills/code-review/SKILL.md
  3. Add the required frontmatter and instructions: 
    ---
name: code-review
description: Review code changes against team review guidelines. Use when reviewing pull requests, diffs, or local code changes.
---

# Code review

Review code changes against the team's review checklist.
  4. Start a Poolside Assistant or pool code session in the project.
  5. Ask for a task that matches the skill description, such as Review my current changes against the code review skill.
If Poolside skips a skill because SKILL.md does not match the expected format, open the repository from Repositories in the Poolside Console and check whether a Skipped Skills section appears. For local skills, verify your SKILL.md frontmatter and directory name directly.

​
Review skill usage

Use the Trajectory Viewer to inspect which skills the agent used during a session. Skill usage appears in the trajectory alongside the other context and tool activity for the run. If a skill did not run when you expected, check the following:
  • The skill is available to the agent you used.
  • You have permission to use the repository, if you expected a remote skill to run.
  • The skill’s description matches the task you asked the agent to complete.
  • The SKILL.md frontmatter is valid and the name matches the skill directory.