Cortask

Using Skills

Skills extend what Cortask agents can do. Each skill is a self-contained plugin that teaches an agent new capabilities -- from calling external APIs to controlling desktop apps. Skills are defined by a SKILL.md file with metadata and instructions that the agent follows at runtime.

How Skills Work

When a workspace has skills enabled, the agent receives the skill's instructions as part of its context. The skill's description field determines when the agent activates it -- descriptions include trigger phrases and negative triggers to avoid overlaps with other skills.

Skills can provide three types of capabilities:

  • Instructions: Markdown text teaching the agent to use existing tools (like bash or web fetch) in specific ways.
  • HTTP tools: API endpoints declared in YAML that become callable tools for the agent, with automatic credential injection.
  • Code tools: Custom JavaScript handlers (index.js) that register new tools with full programmatic control.

Enabling and Disabling Skills

Skills are enabled or disabled per workspace. In the workspace settings, you can toggle individual skills on or off. Only enabled skills are included in the agent's context for that workspace.

Skills from three sources are available:

  • Bundled: Ship with Cortask in the skills/ directory. Not editable.
  • User: Installed to your user data directory (via Git or manual creation). Editable.
  • Config directory: Loaded from additional directories specified in configuration. Editable.

Skill Eligibility

A skill can be present but ineligible if its requirements are not met. The system checks:

  1. OS compatibility: The skill's compatibility.os field lists supported platforms (darwin, linux, win32). If the current OS is not listed, the skill is ineligible.
  2. Environment variables: The requires.env field lists environment variables that must be set.
  3. Binaries: The requires.bins field lists CLI tools that must be on PATH (checked via which / where).
  4. Credentials: If the skill defines a credentials.json schema, all required credential fields must be filled.

Skills with always: true bypass all eligibility checks and are always available.

Ineligible skills appear in the UI with the reason they cannot be used, and they are excluded from the agent's context.

Configuring Skill Credentials

Many skills require API keys or other secrets. These are defined in a credentials.json file alongside the skill's SKILL.md. Cortask stores credentials in an encrypted store (AES-256-GCM), never in plain config files.

Supported credential types:

TypeDescription
api-keySingle API key or token
basic-authUsername and password pair
bearer-tokenBearer token for Authorization headers
oauth2OAuth 2.0 flow (see below)
customArbitrary fields defined by the skill

Credential fields support validation constraints: pattern (regex), minLength, maxLength, and required (defaults to true). Some credentials support multiple instances (e.g., multiple email accounts), stored as named entries in the credential store.

To configure credentials, go to the skill's settings in the UI or use the CLI:

cortask skill set-credential <skill-name>

OAuth2 Setup

Skills that use OAuth2 define an oauth block in their credential schema with:

  • authorizationUrl -- Where to redirect the user for consent.
  • tokenUrl -- Where to exchange the authorization code for tokens.
  • scopes -- Requested permission scopes.
  • pkce -- Whether PKCE is used (optional).
  • refreshable -- Whether offline/refresh tokens are requested.

The OAuth2 flow in Cortask:

  1. The UI builds an authorization URL with the configured client ID and redirect URI.
  2. You authenticate with the provider and grant consent.
  3. The callback returns an authorization code to Cortask.
  4. Cortask exchanges the code for access and refresh tokens, storing them encrypted.
  5. HTTP template tools reference tokens via {{oauth2:accessToken}} placeholders.

Token revocation removes all stored OAuth2 tokens for the skill from the credential store.