Skills

Skills are reusable instruction packages that give the AI agent domain-specific knowledge during story execution. A skill can contain coding standards, framework guidelines, testing patterns, architectural constraints, or any other structured guidance that should apply across multiple stories.

When a task runs with skills attached, the agent receives the skill content as part of its context and can reference the instructions throughout its work. Skills are managed at the account level and can be applied to individual tasks or propagated automatically through workflows.

Authoring a Skill

A skill is a collection of files packaged as a .zip archive. Every skill must include a SKILL.md file at the root of the archive.

SKILL.md Format

The SKILL.md file uses YAML frontmatter to declare the skill's metadata, followed by Markdown content with the skill's instructions.

---
name: react-patterns
display_name: React Patterns
description: Component patterns, hook conventions, and testing standards for React projects
version: 1.0.0
---

## Component Structure

- Use functional components with hooks
- Co-locate tests with components using `.test.tsx` suffix
- Keep components under 200 lines; extract logic into custom hooks

## State Management

- Prefer local state with useState for component-scoped data
- Use context for shared state across a subtree
- Avoid prop drilling beyond two levels

Frontmatter Fields

Field	Required	Description
name	Yes	Unique identifier for the skill. Must be lowercase alphanumeric with hyphens, starting with a letter or digit (e.g., my-skill-1). Regex: ^[a-z0-9][a-z0-9-]*$
display_name	No	Human-readable name shown in the UI. Defaults to name if omitted
description	Yes	Brief summary of what the skill teaches the agent
version	No	Semver string for tracking revisions. Defaults to 1.0.0

Supporting Files

Beyond SKILL.md, you can include additional files in the archive — templates, configuration examples, reference documents, or any other text content the agent should have access to. Nested directories are supported (e.g., templates/component.md).

Validation Constraints

Uploads are validated against these rules:

Constraint	Limit
Total archive size	2 MB
Maximum files	25
Required file	SKILL.md with valid frontmatter
Name format	Lowercase alphanumeric + hyphens, starts with letter or digit
File paths	No path traversal (../) or absolute paths. Allowed characters: a-zA-Z0-9_-./

tip

Keep skills focused on a single concern. A skill for "React testing patterns" is more reusable than one that combines React patterns, CI configuration, and deployment conventions. Compose multiple focused skills on a task rather than bundling unrelated guidance into one.

Managing Skills

Skills are managed from Settings > Integrations > Skills. This section is available to admin users.

Uploading a Skill

1. Navigate to Settings > Integrations > Skills
2. Click the upload area or drag and drop a .zip file
3. The system validates the archive, extracts SKILL.md frontmatter, and stores the skill
4. The new skill appears in the list with its name, description, version, and file count

If validation fails — for example, a missing SKILL.md, an invalid name, or an oversized archive — an error message explains what to fix.

Viewing Skill Contents

Expand any skill card to browse its files. Select a file from the dropdown to view its content. This lets you verify the instructions the agent will receive without downloading the original archive.

Editing Metadata

Click the edit button on a skill card to update its display name, description, or version. These changes apply immediately to all future task executions that use the skill.

note

Editing metadata does not change the skill's files. To update the actual instructions, upload a new version of the skill with the same name in the SKILL.md frontmatter.

Deleting a Skill

Delete a skill from its card menu. Deleted skills use a soft-delete mechanism — any tasks already in flight continue to have access to the skill's content until they complete. New tasks will no longer see the deleted skill as an option.

Applying Skills to Tasks

Skills can be attached to tasks at three points in the UI. Once attached, the selected skills are stored in the task's execution configuration and persist across workflow runs.

When Creating a Task

The Add Task modal on the Board includes a skills selector. If your account has uploaded skills, a multi-select dropdown appears where you can choose one or more skills to apply. The selected skills take effect immediately when the task begins execution.

When Running a Task

The Run Task action (available from a card's action menu) also includes a skills selector. This lets you attach or change skills at the point of execution, without modifying the task's default configuration.

From the Card Detail Panel

Open any story card and look for the skills selector in the execution configuration section. Changes here update the task's stored skills immediately. The next workflow run for this task will use the updated skill set.

tip

If your team frequently uses the same skills across tasks, set them once via the card detail panel. They persist across re-runs and workflow triggers without needing to re-select each time.

Skills in Workflows

Skills integrate with the workflow engine so that tasks triggered by automation receive the correct skill context without manual selection.

Automatic Propagation

When a workflow triggers a task execution, the engine resolves skills using a fallback chain:

1. Entity data — skills attached directly to the entity (task) being processed
2. Trigger data — skills included in the workflow trigger payload
3. Execution configuration — skills stored in the task's execution config in the database

The first source that provides skill IDs wins. This means skills set on a task via the Board UI automatically flow into any workflow run for that task — no additional workflow configuration needed.

Per-Step Skill Assignment

In the workflow builder, individual steps that trigger AI agent execution can specify which skills to apply. This allows different steps in the same workflow to use different skill sets — for example, an analysis step might use a "security-review" skill while an implementation step uses "react-patterns."

How Skills Reach the Agent

During execution, the selected skills are provisioned into the agent's environment at ~/.claude/skills/<skill-name>/. Each skill's files are written to disk so the agent can discover and reference them. The agent also receives a summary of available skills in its prompt context, describing each skill's name and purpose.

Skills vs. Memory

Both skills and memory provide context to the AI agent, but they serve different purposes:

	Skills	Memory
Scope	Explicit — selected per task or workflow step	Automatic — applied to all executions for a repository or account
Content	Authored by you, versioned, packaged as files	Accumulated by the agent from past executions, editable by you
Use case	Prescriptive instructions: "follow these patterns"	Descriptive knowledge: "this is how the codebase works"
Lifecycle	Upload once, attach where needed	Grows over time, consolidated automatically

Use skills for explicit standards and guidelines you want enforced. Use memory for organic knowledge about a codebase that the agent discovers and maintains.