Agent skills¶

A skill is a modular, portable package of instructions, scripts, and context that gives agents the capability to perform specific, repeatable tasks. You can reference skills stored in a named stage or a Git repository and Cortex Agents discover them automatically for use in orchestration.

How skills work¶

When an agent receives a user query, it evaluates the name and description of each configured skill. If the agent identifies a skill as relevant, it retrieves the full instructions and any supporting scripts from the SKILL.md file and executes the skill. Skills follow a discovery-and-execution model. The agent doesn’t persist a copy of the skill files, it only references the skill files in their original location and reads them on demand during orchestration.

SKILL.md file structure¶

Each skill is defined by a SKILL.md file that contains the following:

A skill name
A description of the skill
Instructions for the agent
Optional script references

Each skill folder must contain a SKILL.md file at its root. The file defines the skill’s identity, instructions, and any associated scripts. The following example shows the structure of the skill folder:

skills/
  forecaster/
    SKILL.md
    forecaster.py
  planner/
    SKILL.md
    planner.py

The SKILL.md file includes the following fields:


Field	Required	Description
name	Yes	Unique identifier for the skill
description	Yes	Brief summary used by the agent during orchestration to determine relevance
instructions	Yes	Detailed instructions the agent follows when executing the skill

Skill discovery¶

Cortex Agents reference the SKILL.md files at the root of each skill folder. The agent scans the stage contents for SKILL.md files and returns the skill name, description, and file location.

Skill orchestration¶

During agent invocation, the agent orchestrator uses the name and description of every skill referenced in the agent to decide which skills are relevant to the user’s query. If a skill is selected, the agent retrieves the full SKILL.md content, including detailed instructions and script paths, from the source location.

Skill sources¶

You can store skills in one of the two following types of locations:

Named stages
Git repositories

Named stages¶

The following example shows how to store skill folders in a Snowflake named stage.

Sign in to Snowsight.
Navigate to the database and schema where you want to create the stage.
Create a stage named skill_stage.
Upload the skill files to the stage, placing them in the skills/forecaster/ path.

Create a stage for skills.
```
CREATE STAGE IF NOT EXISTS db1.schema1.skill_stage;
```

Upload skill files to the stage.

PUT file:///path/to/forecaster/SKILL.md @db1.schema1.skill_stage/skills/forecaster/;
PUT file:///path/to/forecaster/forecaster.py @db1.schema1.skill_stage/skills/forecaster/;

Git repositories¶

The following example shows how to reference skills located in a Snowflake Git repository. You can point to a specific commit hash for stability or a tag for automatic updates:

Sign in to Snowsight.
Navigate to the Git repository integration where your skills are stored.
Reference the skill at a specific commit hash for stability, or use a tag for automatic updates after a FETCH.

-- Reference a skill at a specific commit
@my_db.my_schema.skills_repo/commits/abc123def/skills/forecaster

-- Reference a skill at a tag (updates automatically on fetch)
@my_db.my_schema.skills_repo/tags/latest/skills/forecaster

Note

When you reference a Git tag, the skill updates automatically after the account admin runs a FETCH on the repository. Commit hash references are immutable.

Manage skills¶

List available skills¶

List all skills available in a named stage or git repository:

LS @db1.schema1.stage1/ PATTERN='.*SKILL\.md';

The output shows each skill’s name, description, and file location:


Name	Size	Checksum	Last Modified
skill_stage/forecaster/SKILL.md	1008	1232131231231	Tue March 10 2026 02:45 GMT
skill_stage/planner/SKILL.md	2001	1231231231231	Tue March 10 2026 02:45 GMT

List skills on an agent¶

View all skills configured on a specific agent:

DESCRIBE AGENT db1.schema1.my_agent;

The output returns a JSON structure with each skill’s name and source URL.

Add a skill to an agent¶

Add a skill to a Cortex Agent by updating the agent specification. You can use the Snowsight UI, SQL, or the REST API. The description field is optional. If omitted, Snowflake reads the description from the skill’s SKILL.md file.

Sign in to Snowsight.
Navigate to the Skills tab.
Select Add Skill and choose Stage or Git as the source.
For a stage source, provide the name of the stage and the skill folder path.
For a Git source, provide the repository path to the skill.
Select Add Skill.

To add a skill from a Snowflake named stage:

ALTER AGENT db1.schema1.my_agent
  MODIFY LIVE VERSION
   SET SPECIFICATION = $$
    {
     //Please include all existing non-changed fields as well
      "skills": [
        {
          "name": "forecaster",
          "source": {
            "type": "STAGE",
            "path": "@db1.schema1.stage1/skills/forecaster"
          }
        }
      ]
    }
  $$;

To add a skill from a Git repository:

ALTER AGENT db1.schema1.my_agent
  MODIFY LIVE VERSION
   SET SPECIFICATION = $$
    {
     //Please include all existing non-changed fields as well
      "skills": [
        {
          "name": "forecaster",
          "source": {
            "type": "GIT",
            "path": "@my_db.my_schema.skills_repo/tags/latest/skills/forecaster"
          }
        }
      ]
    }
  $$;

To add a skill from a Snowflake named stage:

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
{
    "name": "my_agent",
    "comment": "Agent with skill capabilities",
    "spec": {
        "models": {
            "orchestration": "claude-4-sonnet"
        },
        "instructions": {
            "system": "You are an assistant with forecasting and analysis capabilities."
        },
        "skills": [
            {
                "name": "forecaster",
                "source": {
                    "type": "STAGE",
                    "path": "@db1.schema1.stage1/skills/forecaster"
                }
            }
        ]
    }
}

To add a skill from a Git repository:

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
{
    "name": "my_agent",
    "comment": "Agent with skill capabilities",
    "spec": {
        "models": {
            "orchestration": "claude-4-sonnet"
        },
        "instructions": {
            "system": "You are an assistant with forecasting and analysis capabilities."
        },
        "skills": [
            {
                "name": "forecaster",
                "source": {
                    "type": "GIT_INTEGRATION",
                    "path": "@my_db.my_schema.skills_repo/tags/latest/skills/forecaster"
                }
            }
        ]
    }
}

Update a skill¶

To update a skill’s content, modify the SKILL.md file and any associated scripts at the source location. All agents that reference the skill automatically use the updated version on their next invocation.

To update a skill’s metadata in the agent specification (for example, the description), use the same PUT endpoint with the updated values.

Remove a skill from an agent¶

Remove a skill from an agent using the Snowsight UI, SQL, or the REST API. The remaining skills continue to function.

Sign in to Snowsight.
Navigate to the Skills tab.
Select the skill you want to remove and delete it.
Select Save.

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
{
    "name": "my_agent",
    "comment": "Agent with skill capabilities",
    "spec": {
        "models": {
            "orchestration": "claude-4-sonnet"
        },
        "instructions": {
            "system": "You are an assistant with forecasting and analysis capabilities."
        },
        "skills": [
        ]
    }
}

Update the agent specification and omit the skill from the skills array:

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
{
    "name": "my_agent",
    "comment": "Agent with skill capabilities",
    "spec": {
        "models": {
            "orchestration": "claude-4-sonnet"
        },
        "instructions": {
            "system": "You are an assistant with forecasting and analysis capabilities."
        },
        "skills": [
        ]
    }
}

Add an existing skill to another agent¶

You can add the same skill to multiple agents by referencing the same source path in each agent’s specification. Because skills are referenced and not copied, updates to the skill files apply to all agents that use the skill.

Skills with code¶

If your skills need to execute code, you must enable the code execution tool on the agent. All scripts referenced by a skill must be located in the same folder as the SKILL.md file.

Use skills in Snowflake Intelligence¶

The skills configured on an agent are automatically available in Snowflake Intelligence. You can also explicitly select a skill for use by selecting the + button and then choosing the skill from the list.

Access control¶

The following table describes the privileges required for skill operations:


Privilege	Object	Required for
USAGE	Stage	Reading skill files from a named stage
USAGE	Git Integration	Reading skill files from a Git repository
MODIFY	Agent	Adding, updating, or removing skills in an agent
OWNERSHIP	Agent	Full control over the agent configuration
USAGE	Agent	Invoking the agent and its skills

Monitoring¶

Skill invocations are surfaced in the thinking steps during Snowflake Intelligence interactions. The monitoring dashboard displays skill invocation details alongside other orchestration information, including which skill was selected, the input provided, and the result returned.

Limitations¶

The following limitations apply to Cortex Agent skills:

SKILL.md location: The SKILL.md file must be at the root of the skill folder. Snowflake doesn’t search subdirectories.
Supporting files: All scripts and supporting files must reside in the same folder as the SKILL.md file.
Git fetch requirement: Skills referenced by Git tag don’t update automatically. The account admin must run a FETCH on the repository for changes to take effect.