Develop a Skill

A Skill is a set of instructions that teaches an Agent how to perform specific work. It can include references, templates, assets, and Python scripts. Skills are suitable for capturing workflows, not for storing passwords, and they do not bypass user permissions.

Create your first Workspace Skill

Create the following structure at the project root:

.agents/
└── skills/
    └── release-review/
        └── SKILL.md

SKILL.md must use this exact capitalization. Minimal example:

---
name: release-review
description: Review the changes, tests, and known risks in a release candidate. Use when the user requests a release review.
---

# Release review

1. Read the changes and test results for this release.
2. Distinguish verified facts from items that still need confirmation.
3. Report blockers, risks, and recommendations.

Use lowercase, hyphen-separated directory names and name values. The description should explain both “what it does” and “when to use it,” because the Agent uses this information to decide whether to activate the Skill.

Add resources

A Skill can contain:

release-review/
├── SKILL.md
├── references/     # Detailed instructions read as needed
├── assets/         # Images or other resources
├── templates/      # Reusable templates
└── scripts/        # Python scripts

Keep mandatory steps in SKILL.md, and place longer background material in referenced files. Use relative links and ensure that their capitalization matches the actual files. Do not include Tokens, private keys, personal data, or absolute local paths.

Test a Skill

Prepare at least three types of test requests:

1. Should trigger: The user explicitly needs the workflow.
2. Boundary case: Information is incomplete, input is large, or approval is required.
3. Should not trigger: The topic is similar, but the Skill is not needed.

Test in a new task. Confirm that the Agent selects the correct Skill, follows its critical steps, and does not trigger it incorrectly because the instructions are too broad. Test again after modifying a Skill, because a Run that has already started continues to use the version frozen when it began.

Scripts and permissions

Skill Scripts currently support only scripts/*.py and depend on Python 3 being available on the computer outside the workspace. Script execution is not an operating-system sandbox: it requires full read, write, and command permissions, and every run requests explicit approval. If dependencies are missing, Captain Who reports the problem but does not install packages automatically.

Therefore, do not add a script when instructions or a template are sufficient. When adding a script, use structured parameters, bound its input and output, document side effects, and avoid reading unauthorized locations.

Install and manage Skills

• Workspace Skills live in .agents/skills/ in the current project and do not automatically become global Skills.
• “Settings → Skills” shows built-in and installed Skills and lets you enable, update, or uninstall manageable entries.
• Third-party installation currently supports GitHub sources and local directories authorized by the user. The application shows the inspection results before requesting installation approval.
• Installed packages are managed by the application and should not be edited directly. To modify one, first create a Workspace copy in a project, then test and install the new version.

Current limitations

• The number and content of Skills activated in one Run are subject to safety budgets; very large directories may be truncated and accompanied by diagnostics.
• Other online Skill Registries are not yet available as general installation sources.
• Skill activation applies only to the current Run; it is not permanent across conversations.
• A Skill's source or “installed” status does not grant additional Tool permissions.