Claude Skill

install-ability

在本机 Astravia 中安装能力——插件(plugin)、Skill/场景(scene)与 MCP 服务器。用户说「装一个插件 / install plugin / 从能力市场安装 / 加一个 MCP server / 配置 MCP / 装个 skill」,或插件装完没生效、需要 reload、pending 版本没应用时使用。不用于安装 npm 依赖、IDE 插件、浏览器扩展,也不用于开发插件(那是 plugin-workbench)或创作 Skill(那是 create-skill)。

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download maomaochong-ai-open-astravia-packages_skill-presets_install-ability-a22aa03.zip · 5 KB

Install

skills CLI npx skills add https://github.com/maomaochong-ai/open-astravia/tree/main/packages/skill-presets/install-ability
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install maomaochong-ai-open-astravia@llmmart
Git git clone https://github.com/maomaochong-ai/open-astravia.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole maomaochong-ai/open-astravia collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

在 Astravia 中安装能力

Astravia 的能力分三种,安装路径互不相同。先分类,再动手。

用户给的东西 类型 安装路径
npm 包名、.zip、http(s) zip 链接、本地插件工程目录 插件 astravia-plugin-cli add → 按需 reload(§2)
能力市场里的插件条目 插件 引导用户在能力市场页安装(§2.6)
能力市场里的 skill(有 slug) Skill skills.manage install-from-market(§3)
用户自己写的 / 仓库里的 SKILL.md Skill 交给 create-skill skill(§3.2)
command + args,或一个 MCP 的 http url MCP mcp.manage upsert(§4)

分不清时先问用户,不要凭包名猜类型:npm 上的 @modelcontextprotocol/server-* 是 MCP,不是 Astravia 插件。

1. 通用前置

  • 只在用户明确要求安装时执行。当前任务缺某个工具,不构成自行安装能力的理由。
  • 所有写操作都会弹宿主审批。用户拒绝就停下并如实报告,不要改走别的路子达成同一效果。
  • 禁止直接改注册表:~/.astravia/plugins/、~/.astravia/plugins-manifest.json、~/.astravia/skills-manifest.json(市场安装的部分)、~/.astravia/agent/mcp.json 都由宿主维护,手写会与宿主状态错位。
  • 安装源来自用户。第三方 zip / http 链接在安装前把来源念给用户确认一次。

2. 插件

2.1 命令入口

npx @astravia-org/plugin-cli add <npm-package|./local.zip|https://…/x.zip|.>
npx @astravia-org/plugin-cli reload <plugin-id>

. 表示「当前插件工程」(会先 pack)。加 --json 便于解析结果。

npx 不可用或离线时,用系统插件「制作插件」内置的同一份 CLI:先 plugins.query → {"operation":"get","id":"plugin-workbench"} 取 rootPath,再

node "{workbenchRoot}/agent/cli/astravia-plugin-cli.js" add <source> --json

CLI 不直接写插件目录,它把请求交给正在运行的宿主校验、审批、安装。npm 包会以关闭生命周期脚本的方式下载,只解出 package.json#astravia.archive 声明的那个归档。

2.2 安装后必须重载(本 skill 的核心)

  • 首次安装:宿主直接启用,输出 Installed <id>@<version>. —— 到此结束。

  • 覆盖升级已装插件:宿主把新版本挂成 pending,输出

    Installed <id>@<old>. Update <new> is pending reload. Run `astravia-plugin-cli reload <id>` to apply it.
    

    此刻插件仍在跑旧代码。安装动作没有完成,必须立刻重载:

    npx @astravia-org/plugin-cli reload <plugin-id>
    

--json 下的判据(不要靠读人类文案):

字段 含义 动作
result.plugin.pendingVersion 非空 新版本待应用 必须 reload
reload 返回 plugin.activeVersion 当前生效版本 应等于刚装的版本,否则报告异常

reload 走与 UI 相同的宿主审批流,用户确认后新版本才生效。

2.3 热更新是例外

改已安装插件、或对方是开发中的工程时,先 plugins.query → get <id>:

  • 返回项含 devWatch → 热更新已开启,源码构建成功后自动重载。不要 reload、不要重装。
  • 无 devWatch → 走 §2.1 / §2.2 常规流程。

开发迭代(不是安装)可以直接开热更新:在插件工程目录 npx @astravia-org/plugin-cli watch,--stop 关闭。

2.4 没有 CLI 时的等价调用

plugins.manage {"operation":"install-from-url","url":"https://…/x.zip"}
plugins.manage {"operation":"reload","id":"<plugin-id>"}

本地路径安装用 install-from-path(zip 绝对路径 + "enable": true)。若目标是「制作插件」工作台里的工程,改为引导用户点面板的「应用到 Astravia」,那条路径不弹确认。

2.5 退出码

0 成功 · 2 参数错 · 3 连不上宿主(Astravia 没运行,或 ASTRAVIA_CONFIG_DIR/ASTRAVIA_HOME 指到了别的环境)· 4 宿主拒绝(权限、id 冲突、系统插件不可覆盖)· 5 其它失败。遇到 3 先让用户确认 Astravia 桌面端在前台运行,不要反复重试。

2.6 能力市场里的插件

市场插件没有 Agent 侧的按 slug 安装动作。用 navigation.open 打开能力市场页,让用户点安装;装完再按 §2.7 校验即可。

2.7 校验

plugins.query → {"operation":"get","id":"<id>"},确认 enabled === true、activeVersion 是目标版本、pendingVersion 不存在。

3. Skill

3.1 从能力市场装

skills.manage {"operation":"install-from-market","type":"skill","slug":"<slug>"}

type 为 "skill"。slug 不确定就别猜:用 navigation.open 打开能力市场让用户挑,拿到准确 slug 再装。

Skill 不需要 reload,装完即进入能力页。校验:skills.query {"operation":"manifest"},确认目标 name 在清单里且 enabled: true。

3.2 本地 / 自己写的 Skill

不要在这里手搓目录和清单——按 create-skill skill 的流程做(全局 ~/.astravia/skills/<name>/、项目 <root>/.astravia/skills/<name>/、插件 agent/skills/<name>/ 各有各的注册方式)。

3.3 启停与卸载

skills.manage {"operation":"set-enabled","name":"<name>","enabled":false}
skills.manage {"operation":"uninstall","name":"<name>"}

卸载前先 skills.query manifest 核对真实 type,类型对不上宿主会直接拒绝。

4. MCP 服务器

mcp.manage {"operation":"upsert","name":"filesystem",
  "data":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/abs/dir"]}}

mcp.manage {"operation":"upsert","name":"remote",
  "data":{"type":"http","url":"https://example.com/mcp","headers":{"Authorization":"Bearer …"}}}
  • 缺省是 stdio;http 必须显式写 "type":"http"。可选字段:env、cwd、disabled、autoApprove、startupTimeout、debug。
  • 密钥只从用户处取,放进 env / headers,不要写进仓库文件、不要回显到聊天里。
  • upsert 同名即覆盖,用它做「更新配置」,不要先 remove 再加。
  • 校验:mcp.query {"operation":"get","name":"<name>"}(密钥字段会脱敏)。起不来时,先把 command args 在终端手跑一次看报错,再改配置——不要靠反复 upsert 试。
  • 停用 / 删除:mcp.manage set-enabled / remove。
  • 新装 MCP 的工具在当前会话里可能要等宿主重连才出现。这不是安装失败,别为了让工具出现而重装。

5. 报告

安装结束后向用户说明:装了什么类型、id/name 与版本、是否执行了 reload 及重载后的 activeVersion、校验结果,以及任何被用户拒绝或未能执行的步骤。不要把「已提交安装请求」说成「已安装成功」。

Files (open-astravia)
  • ability.json 2.7 KB
    Loading…
  • SKILL.md 7.4 KB
    ---
    name: install-ability
    description: 在本机 Astravia 中安装能力——插件(plugin)、Skill 与 MCP 服务器。用户说「装一个插件 / install plugin / 从能力市场安装 / 加一个 MCP server / 配置 MCP / 装个 skill」,或插件装完没生效、需要 reload、pending 版本没应用时使用。不用于安装 npm 依赖、IDE 插件、浏览器扩展,也不用于开发插件(那是 plugin-workbench)或创作 Skill(那是 create-skill)。
    metadata:
      version: 1.0.0
      author: Astravia
      category: 开发
    ---
    
    # 在 Astravia 中安装能力
    
    Astravia 的能力分三种,安装路径互不相同。**先分类,再动手**。
    
    | 用户给的东西 | 类型 | 安装路径 |
    | --- | --- | --- |
    | npm 包名、`.zip`、http(s) zip 链接、本地插件工程目录 | 插件 | `astravia-plugin-cli add` → 按需 `reload`(§2) |
    | 能力市场里的插件条目 | 插件 | 引导用户在能力市场页安装(§2.6) |
    | 能力市场里的 skill(有 slug) | Skill | `skills.manage install-from-market`(§3) |
    | 用户自己写的 / 仓库里的 SKILL.md | Skill | 交给 `create-skill` skill(§3.2) |
    | `command` + `args`,或一个 MCP 的 http url | MCP | `mcp.manage upsert`(§4) |
    
    分不清时**先问用户**,不要凭包名猜类型:npm 上的 `@modelcontextprotocol/server-*` 是 MCP,不是 Astravia 插件。
    
    ## 1. 通用前置
    
    - **只在用户明确要求安装时执行**。当前任务缺某个工具,不构成自行安装能力的理由。
    - 所有写操作都会弹宿主审批。用户拒绝就**停下并如实报告**,不要改走别的路子达成同一效果。
    - **禁止直接改注册表**:`~/.astravia/plugins/`、`~/.astravia/plugins-manifest.json`、`~/.astravia/skills-manifest.json`(市场安装的部分)、`~/.astravia/agent/mcp.json` 都由宿主维护,手写会与宿主状态错位。
    - 安装源来自用户。第三方 zip / http 链接在安装前把来源念给用户确认一次。
    
    ## 2. 插件
    
    ### 2.1 命令入口
    
    ```bash
    npx @astravia-org/plugin-cli add <npm-package|./local.zip|https://…/x.zip|.>
    npx @astravia-org/plugin-cli reload <plugin-id>
    ```
    
    `.` 表示「当前插件工程」(会先 pack)。加 `--json` 便于解析结果。
    
    npx 不可用或离线时,用系统插件「制作插件」内置的同一份 CLI:先 `plugins.query` → `{"operation":"get","id":"plugin-workbench"}` 取 `rootPath`,再
    
    ```bash
    node "{workbenchRoot}/agent/cli/astravia-plugin-cli.js" add <source> --json
    ```
    
    CLI 不直接写插件目录,它把请求交给正在运行的宿主校验、审批、安装。npm 包会以关闭生命周期脚本的方式下载,只解出 `package.json#astravia.archive` 声明的那个归档。
    
    ### 2.2 安装后必须重载(本 skill 的核心)
    
    - **首次安装**:宿主直接启用,输出 `Installed <id>@<version>.` —— 到此结束。
    - **覆盖升级已装插件**:宿主把新版本挂成 **pending**,输出
    
      ```
      Installed <id>@<old>. Update <new> is pending reload. Run `astravia-plugin-cli reload <id>` to apply it.
      ```
    
      此刻插件**仍在跑旧代码**。安装动作没有完成,必须立刻重载:
    
      ```bash
      npx @astravia-org/plugin-cli reload <plugin-id>
      ```
    
    `--json` 下的判据(不要靠读人类文案):
    
    | 字段 | 含义 | 动作 |
    | --- | --- | --- |
    | `result.plugin.pendingVersion` 非空 | 新版本待应用 | **必须** `reload` |
    | `reload` 返回 `plugin.activeVersion` | 当前生效版本 | 应等于刚装的版本,否则报告异常 |
    
    reload 走与 UI 相同的宿主审批流,用户确认后新版本才生效。
    
    ### 2.3 热更新是例外
    
    改**已安装插件**、或对方是开发中的工程时,先 `plugins.query` → `get <id>`:
    
    - 返回项含 `devWatch` → 热更新已开启,源码构建成功后自动重载。**不要** reload、不要重装。
    - 无 `devWatch` → 走 §2.1 / §2.2 常规流程。
    
    开发迭代(不是安装)可以直接开热更新:在插件工程目录 `npx @astravia-org/plugin-cli watch`,`--stop` 关闭。
    
    ### 2.4 没有 CLI 时的等价调用
    
    ```json
    plugins.manage {"operation":"install-from-url","url":"https://…/x.zip"}
    plugins.manage {"operation":"reload","id":"<plugin-id>"}
    ```
    
    本地路径安装用 `install-from-path`(zip 绝对路径 + `"enable": true`)。若目标是「制作插件」工作台里的工程,改为引导用户点面板的「应用到 Astravia」,那条路径不弹确认。
    
    ### 2.5 退出码
    
    `0` 成功 · `2` 参数错 · `3` 连不上宿主(Astravia 没运行,或 `ASTRAVIA_CONFIG_DIR`/`ASTRAVIA_HOME` 指到了别的环境)· `4` 宿主拒绝(权限、id 冲突、系统插件不可覆盖)· `5` 其它失败。遇到 `3` 先让用户确认 Astravia 桌面端在前台运行,不要反复重试。
    
    ### 2.6 能力市场里的插件
    
    市场插件没有 Agent 侧的按 slug 安装动作。用 `navigation.open` 打开能力市场页,让用户点安装;装完再按 §2.7 校验即可。
    
    ### 2.7 校验
    
    `plugins.query` → `{"operation":"get","id":"<id>"}`,确认 `enabled === true`、`activeVersion` 是目标版本、`pendingVersion` 不存在。
    
    ## 3. Skill
    
    ### 3.1 从能力市场装
    
    ```json
    skills.manage {"operation":"install-from-market","type":"skill","slug":"<slug>"}
    ```
    
    `type` 为 `"skill"`。**slug 不确定就别猜**:用 `navigation.open` 打开能力市场让用户挑,拿到准确 slug 再装。
    
    Skill 不需要 reload,装完即进入能力页。校验:`skills.query {"operation":"manifest"}`,确认目标 name 在清单里且 `enabled: true`。
    
    ### 3.2 本地 / 自己写的 Skill
    
    不要在这里手搓目录和清单——按 `create-skill` skill 的流程做(全局 `~/.astravia/skills/<name>/`、项目 `<root>/.astravia/skills/<name>/`、插件 `agent/skills/<name>/` 各有各的注册方式)。
    
    ### 3.3 启停与卸载
    
    ```json
    skills.manage {"operation":"set-enabled","name":"<name>","enabled":false}
    skills.manage {"operation":"uninstall","name":"<name>"}
    ```
    
    卸载前先 `skills.query manifest` 核对真实 `type`,类型对不上宿主会直接拒绝。
    
    ## 4. MCP 服务器
    
    ```json
    mcp.manage {"operation":"upsert","name":"filesystem",
      "data":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/abs/dir"]}}
    
    mcp.manage {"operation":"upsert","name":"remote",
      "data":{"type":"http","url":"https://example.com/mcp","headers":{"Authorization":"Bearer …"}}}
    ```
    
    - 缺省是 stdio;http 必须显式写 `"type":"http"`。可选字段:`env`、`cwd`、`disabled`、`autoApprove`、`startupTimeout`、`debug`。
    - **密钥只从用户处取**,放进 `env` / `headers`,不要写进仓库文件、不要回显到聊天里。
    - `upsert` 同名即覆盖,用它做「更新配置」,不要先 remove 再加。
    - 校验:`mcp.query {"operation":"get","name":"<name>"}`(密钥字段会脱敏)。起不来时,先把 `command args` 在终端手跑一次看报错,再改配置——不要靠反复 upsert 试。
    - 停用 / 删除:`mcp.manage set-enabled` / `remove`。
    - 新装 MCP 的工具在**当前会话**里可能要等宿主重连才出现。这不是安装失败,别为了让工具出现而重装。
    
    ## 5. 报告
    
    安装结束后向用户说明:装了什么类型、id/name 与版本、**是否执行了 reload 及重载后的 activeVersion**、校验结果,以及任何被用户拒绝或未能执行的步骤。不要把「已提交安装请求」说成「已安装成功」。
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.