代理技能¶

技能是一个模块化、可移植的指令、脚本和上下文包，它使代理能够执行特定的、可重复的任务。您可以引用存储在命名暂存区或 Git 存储库中的技能，Cortex Agents 会自动发现它们以用于编排。

技能的工作原理¶

当代理收到用户查询时，它会评估每个已配置技能的名称和描述。如果代理判断某个技能是相关的，它会从 SKILL.md 文件中检索完整的指令和任何支持的脚本，并执行该技能。技能遵循发现与执行模型。代理不会持久保存技能文件的副本，它仅在原始位置引用技能文件，并在编排期间按需读取它们。

SKILL.md 文件结构¶

每个技能由一个 SKILL.md 文件定义，该文件包含以下内容：

技能名称
技能描述
给代理的指令
可选的脚本引用

每个技能文件夹的根目录下必须包含一个 SKILL.md 文件。该文件定义了技能的身份、指令以及任何相关联的脚本。以下示例展示了技能文件夹的结构：

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

SKILL.md 文件包含以下字段：


字段	必填	描述
name	是	技能的唯一标识符
描述	是	代理在编排期间用于判断相关性的简短摘要
响应指令	是	代理在执行技能时所遵循的详细指令

技能发现¶

Cortex Agents 引用每个技能文件夹根目录下的 SKILL.md 文件。代理扫描暂存区内容以查找 SKILL.md 文件，并返回技能名称、描述和文件位置。

技能编排¶

在代理调用期间，代理编排器使用代理中引用的每个技能的名称和描述来判断哪些技能与用户的查询相关。如果某个技能被选中，代理会从源位置检索完整的 SKILL.md 内容，包括详细指令和脚本路径。

技能来源¶

您可以将技能存储在以下两种类型的位置之一：

命名暂存区
Git 存储库

命名暂存区¶

以下示例展示了如何在 Snowflake 命名暂存区中存储技能文件夹。

登录 Snowsight。
导航到您想要创建暂存区的数据库和模式。
创建一个名为 skill_stage 的暂存区。
将技能文件上传到暂存区，并将它们放置在 skills/forecaster/ 路径下。

为技能创建一个暂存区。
```
CREATE STAGE IF NOT EXISTS db1.schema1.skill_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 存储库¶

以下示例展示了如何引用位于 Snowflake Git 存储库中的技能。为了稳定性，您可以指向特定的提交哈希；为了自动更新，您可以指向标签：

登录 Snowsight。
导航到存储技能的 Git 存储库集成。
使用特定的提交哈希引用来保持稳定性，或者使用标签以便在 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

备注

当您引用 Git 标签时，在账户管理员对存储库运行 FETCH 后，技能会自动更新。提交哈希引用是不可变的。

管理技能¶

列出可用技能¶

列出命名暂存区或 Git 存储库中所有可用的技能：

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

输出显示每个技能的名称、描述和文件位置：


名称	大小	校验和	上次修改时间
skill_stage/forecaster/SKILL.md	1008	1232131231231	2026 年 3 月 10 日，星期二 02:45 GMT
skill_stage/planner/SKILL.md	2001	1231231231231	2026 年 3 月 10 日，星期二 02:45 GMT

列出代理上的技能¶

查看特定代理上配置的所有技能：

DESCRIBE AGENT db1.schema1.my_agent;

输出返回一个 JSON 结构，包含每个技能的名称和源 URL。

向代理添加技能¶

通过更新代理规范向 Cortex Agent 添加技能。您可以使用 Snowsight UI、SQL 或 REST API。描述字段是可选的。如果省略，Snowflake 会从技能的 SKILL.md 文件中读取描述。

登录 Snowsight。
导航到 Skills 选项卡。
选择 Add Skill，然后选择 Stage 或 Git 作为源。
对于暂存区源，请提供暂存区名称和技能文件夹路径。
对于 Git 源，请提供指向该技能的存储库路径。
选择 Add Skill。

要从 Snowflake 命名暂存区添加技能，请执行以下操作：

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"
          }
        }
      ]
    }
  $$;

要从 Git 存储库添加技能，请执行以下操作：

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"
          }
        }
      ]
    }
  $$;

要从 Snowflake 命名暂存区添加技能，请执行以下操作：

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"
                }
            }
        ]
    }
}

要从 Git 存储库添加技能，请执行以下操作：

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"
                }
            }
        ]
    }
}

更新技能¶

要更新技能的内容，请修改源位置处的 SKILL.md 文件和任何相关联的脚本。所有引用该技能的代理将在下次调用时自动使用更新后的版本。

要更新代理规范中技能的元数据（例如描述），请使用相同的 PUT 端点并提供更新后的值。

从代理中移除技能¶

使用 Snowsight UI、SQL 或 REST API 从代理中移除技能。其余的技能将继续正常工作。

登录 Snowsight。
导航到 Skills 选项卡。
选择您要移除的技能并删除它。
选择 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": [
        ]
    }
}

更新代理规范，并从技能数组中省略该技能：

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": [
        ]
    }
}

将现有技能添加到另一个代理¶

您可以通过在每个代理的规范中引用相同的源路径，将相同的技能添加到多个代理中。由于技能是被引用而不是被复制，因此对技能文件的更新将适用于所有使用该技能的代理。

带代码的技能¶

如果您的技能需要执行代码，您必须在代理上启用代码执行工具。技能引用的所有脚本必须与 SKILL.md 文件位于同一文件夹中。

在 Snowflake Intelligence 中使用技能¶

在代理上配置的技能会在 Snowflake Intelligence 中自动可用。您也可以通过选择 + 按钮，然后从列表中选择一个技能来显式选中要使用的技能。

访问控制¶

下表描述了技能操作所需的权限：


权限	对象	适用场景
USAGE	暂存区	从命名暂存区读取技能文件
USAGE	Git 集成	从 Git 存储库读取技能文件
MODIFY	代理	在代理中添加、更新或移除技能
OWNERSHIP	代理	对代理配置的完全控制
USAGE	代理	调用代理及其技能

监控¶

在 Snowflake Intelligence 交互期间，技能调用会出现在思考步骤中。监控仪表板会显示技能调用详细信息以及其他编排信息，包括选择了哪个技能、提供的输入以及返回的结果。

限制¶

以下限制适用于 Cortex Agent 技能：

SKILL.md 位置： SKILL.md 文件必须位于技能文件夹的根目录。Snowflake 不搜索子目录。
支持文件： 所有脚本和支持文件必须与 SKILL.md 文件位于同一文件夹中。
Git 提取要求： 通过 Git 标签引用的技能不会自动更新。账户管理员必须对存储库运行 FETCH，才能使更改生效。