Skip to main content

Create a skill

A maintainable skill lets another person answer five questions from the instructions alone: when should it run, what inputs are required, what is the workflow, how is completion verified, and when must it stop?

Choose the scope​

Personal skill​

Use this for a workflow you reuse across projects. Open Plugins → Skills → Open folder, then create one folder for the skill in the directory Ghast opens.

Ghast also discovers these user-level directories:

  • ~/.claude/skills
  • ~/.codex/skills
  • ~/.agents/skills
  • ~/.pi/agent/skills
  • ${XDG_CONFIG_HOME:-~/.config}/opencode/skills
  • ${HERMES_HOME:-~/.hermes}/skills

Open folder points to the Workspace Skill directory isolated to the current Ghast profile. Global directories owned by other agents should be managed in those agents. When a name appears more than once, check the source and actual path in Details.

Project skill​

Use this for directories, commands, release steps, or domain rules that apply to only one project. The recommended location is <project>/.agents/skills/<skill>/SKILL.md. Ghast also scans .claude/skills, .codex/skills, .pi/skills, .opencode/skills, and .hermes/skills inside a project. Add the project to Ghast, then refresh the library.

Do not put customer credentials, temporary release URLs, or one-off requirements into a global skill.

Minimal layout​

release-review/
└── SKILL.md

Add support files only when the workflow needs them:

release-review/
├── SKILL.md
├── references/
│   └── checklist.md
├── scripts/
│   └── verify.sh
└── templates/
    └── report.md

Keep triggers and the main workflow in SKILL.md. Move long references, scripts, and templates into separate files, and state when to read or run them. Do not scaffold directories for speculative needs.

Required YAML front matter​

The file must begin with YAML front matter and include name and description:

---
name: release-review
description: Review a release candidate, verify scope and results, confirm rollback readiness, and report a release decision.
allowed-tools:
  - Glob
  - Grep
  - Read
  - Bash
---

# Release review

## When to use

Use when the user asks to review a local project or change set before release.

Common fields:

FieldRequiredPurpose
nameYesA short, stable skill name.
descriptionYesWhen the skill should be selected; include the task object and outcome.
licenseNoDistribution and reuse terms.
compatibilityNoPlatform, application, or runtime requirements.
allowed-toolsNoTool names the reusable workflow genuinely needs.
always-injectNoLoad for every task; reserve for rare, stable, universally applicable rules.

The description is a primary input to Auto matching. Avoid descriptions such as “helps with many tasks.” State the trigger and deliverable clearly.

Recommended body​

# Name

## When to use
State triggers and exclusions.

## Inputs
List required files, scope, accounts, or user decisions.

## Workflow
Give ordered actions and checkpoints before high-risk steps.

## Verification
Define the evidence that counts as complete.

## Stop conditions
Say when the agent must not guess or expand scope.

## Output
Define the final answer or artifact format.

Use imperative steps instead of a long product essay. Separate requirements from recommendations. Before any send, delete, publish, payment, or overwrite action, require appropriate authorization and a final-state check.

Declare tools​

List only tools the reusable procedure needs in allowed-tools. A read-only review should not request Edit or Write. When the skill is loaded explicitly, these names can be added to the current run's tool set. They do not grant permission or guarantee that every model or mode provides them.

always-inject: true keeps an enabled, trusted, unarchived skill eligible even when ordinary Skill selection is empty. It does not add an on/off control to the composer. Image generation clears every skill. The model still reads the complete instructions through the Skill Tool, and allowed-tools remains bounded by the current mode and permissions. Reserve this field for stable guidance that truly needs to affect every ordinary task.

MCP tool names can change with server versions. Never embed account credentials in a skill; connect the service through a plugin or MCP configuration.

Include scripts safely​

Executable scripts should:

  • define their inputs and outputs;
  • avoid modifying or deleting user data by default;
  • return a non-zero status with a readable error on failure;
  • never print secrets, cookies, or entire environments;
  • state the working directory, runtime condition, and verification in SKILL.md;
  • document platform limits in compatibility or the body.

Review scripts in third-party skills before enabling them. Marketplace presence or successful discovery is not a trust guarantee.

Make Ghast discover the skill​

  1. Put SKILL.md inside its own directory.
  2. Return to Plugins → Skills.
  3. Choose Refresh.
  4. Search for name and open the result.
  5. Check source, path, full content, and compatibility.
  6. Turn on Enable in Ghast.
  7. Choose Try now, add a small task, and send it.

If parsing fails, first check the opening and closing ---, YAML indentation, and that name and description are non-empty strings.

Accept a new skill​

Test at least three cases:

  1. Should trigger: an exact match loads the skill and follows its output format.
  2. Should not trigger: a neighboring but different task does not cause Auto to over-select it.
  3. Missing input: the skill stops and names the missing material instead of inventing it.

Also inspect tool minimization, visible errors, sensitive-data handling, and stop conditions. Keep it enabled only after these checks. Use always-inject only when every task genuinely needs the guidance.

Update and version​

Refresh the library after every edit and repeat the smallest acceptance check. When triggers, tools, scripts, or the output contract change, document the change. Version plugin-distributed skills with the plugin; do not edit an installed copy in place.