Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
# Partner skill contribution check needs the PR base commit for path diffs.
fetch-depth: 0

- uses: pnpm/action-setup@v6

Expand All @@ -29,6 +32,11 @@ jobs:

- run: pnpm install --frozen-lockfile

- name: Check partner skill contribution
env:
GITHUB_BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || '' }}
run: node tools/check-skill-contribution.mjs

- run: pnpm run sync:skill-assets

- run: pnpm -r --filter "./packages/*" build
Expand Down
14 changes: 14 additions & 0 deletions docs/agents/skill-change.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,28 @@
# Skill 文案 / 路由 / 安装约定

> **合作方投稿(非 `bailian-*`)**请看 [docs/skill-contribute/](../skill-contribute/)。本文只服务本团队维护的官方 `bailian-*` 家族。

## 触发条件

- 改 `skills/*/SKILL.md` 的 description、路由表、consent、安全闸、hand-off、references 落款
- 调整 `bailian-protocol` 与业务 skill 的关系,或业务 skill 之间的软 hand-off 约定
- 新增 / 拆分 / 合并 `bailian-*` 业务 skill,或改 `tools/generate-reference.ts` 的 `GROUP_OWNER_SKILL` 归属(与命令增删改交叉时两边都看)
- 给业务 skill 补安装说明、README,或统一「勿猜 flag → `reference/`」类约定
- 在总入口 `bailian-cli` 中提及某个已合入的合作方 skill(见下方「在总入口中提及合作方 skill」)

纯改生成物 `skills/*/reference/*.md`(由命令 metadata 驱动)→ 走 [command-add-remove.md](command-add-remove.md) / [command-flag-change.md](command-flag-change.md),**不要手改 reference**。

## 在总入口中提及合作方 skill

合作方投稿合入后,用户用 `bl skill add --name bailian-protocol,<name>` 即可安装;Agent 靠该 skill 自己的 `description` 触发,**不必**改总入口也能用。

有时希望用户先命中总入口 skill `bailian-cli`,再被指引到某个合作方 skill。这时:

- **只由本团队**另开一个 PR,在 `skills/bailian-cli/SKILL.md` 里加**一行**说明(例如「某类业务场景 → 读 `<partner-skill>`」)
- **不要**和合作方投稿 PR、或工程改动(`packages/**` / `tools/**`)混在同一 PR
- 加不加、怎么写由团队决定;不加这一行也不影响合作方 skill 安装后单独被触发
- 合作方投稿规范见 [docs/skill-contribute/](../skill-contribute/);对方 PR **不应**改 `bailian-cli`

## 统一口径(安装)

1. **Supported install:** `bl skill init`(装齐 registry 中全部 `bailian-*`,含 `bailian-protocol`)
Expand Down
79 changes: 79 additions & 0 deletions docs/skill-contribute/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# 向本仓库投稿 Skill

本文说明如何向 `modelstudioai/cli` 提交**场景类(最佳实践)** Skill。
官方总入口与命令面能力(名称以 `bailian-` 开头)由本团队维护;合作方请走本文路径,不要新增或修改 `bailian-*` Skill。

可复制的目录模板见:[templates/best-practice/](./templates/best-practice/)。

一作家族(`bailian-*`)的文案与路由约定见内部清单:[docs/agents/skill-change.md](../agents/skill-change.md)。

## 你能改什么

- **可以**:只改 `skills/<你的 skill 名>/`
- **CI 硬拦**:`packages/**`、`tools/**`、`.vite-hooks/**`、发布相关 workflow(以及手改 `skills/*/reference/`)
- **限制**:目录名不要以 `bailian-` 开头;不要改 `skills/bailian-*`(含总入口 `bailian-cli`)。`bailian-` 前缀为官方一作家族,合作方请用非此前缀的场景名。

合入后,用户用下面命令安装即可使用(**不必**改总入口 `bailian-cli`):

```sh
bl skill add --name bailian-protocol,<你的-skill-名>
```

Agent 会根据你在 `SKILL.md` 里写的 `description` 判断要不要用这个 Skill。
若希望用户从总入口 `bailian-cli` 也能被指引过来,由**本团队另开一个 PR** 在总入口里加一行说明;投稿 PR 里也尽量不要改 `bailian-cli`。加不加这一行都不影响你的 Skill 安装后单独被触发。

## 四条必须遵守的规则(CI 会检查)

1. **目录与命名**
目录名 = frontmatter 里的 `name`;使用安全目录名(不要空格、路径分隔符、`..` 等);不要与仓库里已有的 `skills/<目录>` 重名。

2. **目录结构**
根目录要有 `SKILL.md`(YAML frontmatter,至少包含非空的 `name`、`description`)。手写流程放在 `references/`。
**不要**新增或修改任何 `skills/*/reference/`(那是命令手册生成物,给官方 `bailian-*` 用的)。

3. **如何指向百炼能力**
需要跑 `bl`、鉴权或共享协议时,用**技能名**去找已安装的 Skill(先找 `bailian-protocol`;生图/精调等再找对应的 `bailian-*`)。已安装就 Read;没有就提示用户执行上面的 `bl skill add`,或让用户跑 `bl … --help`。
**不要**写成「必须存在 `../bailian-xxx/SKILL.md` 才能继续」。

4. **安全**
不要引导自动补 `--yes`;不要写入真实凭证、真实内部资源或未公开的内部文档链接。

## 建议(不做 CI 硬性检查)

- 目录名不要以 `bailian-` 开头;投稿 PR 不要改 `skills/bailian-*`(含 `bailian-cli`)。
- `description` 写清:做什么、什么时候用、什么时候不要用;尽量别和现有 `bailian-*` 抢同一类意图。
- 用户可见说明尽量中英双语。
- 示例命令对照真实 `bl <command> --help`,不要猜 flag。

## 关于 `metadata.version`

模板里会给一个占位版本(例如 `0.1.0`),由你自己维护。

- 它**不会**自动变成 registry 里的分发版本,也**不需要**和本仓库 `packages/cli` 的版本对齐。
- 改 version **不会**单独走旁路发版;合入 `main` 后仍走现有的 skills 发布对账流程。

官方 `bailian-*` 的 version 仍由本仓库工具与 CLI 版本同步;你的 Skill **不会**被那套同步改写。

## 推荐步骤

1. 复制模板到目标目录:

```sh
cp -R docs/skill-contribute/templates/best-practice skills/<你的-skill-名>
```

2. 把目录名、`SKILL.md` frontmatter 的 `name` / `description`、以及 `references/` 里的场景说明改成你的内容;保留「如何按技能名找到百炼 Skill」那段固定说明。
3. 本地确认只改了 `skills/<你的-skill-名>/`(若顺带改了投稿文档 `docs/skill-contribute/**` 也可以)。
4. 开 PR,描述里可粘贴下方自检清单。

## 投稿自检清单

提交前请确认:

- [ ] Skill 目录名:`skills/<name>/`;frontmatter 的 `name` 与目录名一致;`description` 非空
- [ ] 本 PR **只**改了 `skills/<name>/`(以及可选的 `docs/skill-contribute/**`);**没有**改 `packages/**`、`tools/**`、`.vite-hooks/**`
- [ ] **没有**改任何 `skills/*/reference/**`
- [ ] (软限制)目录名不以 `bailian-` 开头;未改 `skills/bailian-*`
- [ ] 正文用技能名指向 `bailian-protocol` / 相关 `bailian-*`,没有把相对路径写成执行前提
- [ ] 维护人联系方式(GitHub 用户名或团队)已写在 PR 描述里
- [ ] (可选)无真实凭证、无未公开内部链接;未引导自动补 `--yes`
17 changes: 17 additions & 0 deletions docs/skill-contribute/templates/best-practice/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# your-skill-name

Scene-oriented Bailian usage skill (best practice). Copy this folder to `skills/<name>/` and replace placeholders.

## Install

```sh
bl skill add --name bailian-protocol,your-skill-name
```

`bl skill init` installs official `bailian-*` skills only; this skill is installed on demand with the command above.

## Notes

- Keep `name` in `SKILL.md` identical to the directory name.
- `metadata.version` is yours to maintain; it is not locked to the CLI package version and is not the registry publish marker.
- Do not edit `skills/bailian-cli` in the same PR; if the hub should mention this skill, the Bailian team opens a separate PR.
60 changes: 60 additions & 0 deletions docs/skill-contribute/templates/best-practice/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
name: your-skill-name
metadata:
version: "0.1.0"
description: >-
Replace this with WHAT the skill does, WHEN to use it, and WHEN not to use it.
Avoid overlapping the same intents already owned by bailian-* family skills
(media → bailian-gen, fine-tune → bailian-finetune, agents.yaml → bailian-managed-agent,
sandbox → bailian-sandbox, knowledge → bailian-knowledge, web search routing → bailian-web-search,
hub resource commands → bailian-cli).
---

# Your skill title

Replace the placeholders below. Keep the "Bailian skills by name" section as an execution checklist.

## Bailian skills by name (keep this section)

Before running any `bl` command:

1. Look up the installed skill named `bailian-protocol` (shared consent, version preflight, auth, call attribution, error reporting). If it is installed, Read it and follow it. If it is missing, stop and tell the user to run:

```sh
bl skill add --name bailian-protocol,your-skill-name
```

Do not treat a relative path such as `../bailian-protocol/SKILL.md` as a hard requirement for continuing.

2. When the task needs a Bailian domain skill (for example image/video → `bailian-gen`, fine-tune → `bailian-finetune`), look it up **by skill name**. If installed, Read it; if missing, suggest `bl skill add --name <skill>` or fall back to `bl <command> --help`. Do not require `../bailian-*/SKILL.md` paths to exist.

3. Do not auto-append `--yes` for high-risk commands. Ask the user to confirm when the CLI requires confirmation.

**Install (supported for this skill):**

```sh
bl skill add --name bailian-protocol,your-skill-name
```

This skill does **not** need to be listed in the hub skill `bailian-cli` to work after install.

## When to use

- …

## When not to use

- Ordinary Q&A / coding / writing the host agent can do without Bailian → do not trigger
- …

## Workflow

See [references/workflow.md](references/workflow.md).

## Quick examples

Keep examples scoped to this skill. Prefer bare `bl …` in docs; wrap with call attribution only when actually executing (see `bailian-protocol` if installed).

```sh
bl <command> --help
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Workflow (edit for your scenario)

Describe the step-by-step Bailian usage for this business scenario.

1. Clarify the user goal and whether Bailian is required.
2. Ensure `bailian-protocol` (and this skill) are installed:

```sh
bl skill add --name bailian-protocol,your-skill-name
```

3. Follow protocol rules (consent, auth, call attribution) when running `bl`.
4. For domain work (media, fine-tune, …), hand off by **skill name** to the matching `bailian-*` skill if installed; otherwise use `bl … --help`.
5. Record outcomes the user cares about; do not invent flags—use `--help` or an installed skill's docs.
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
"prepare": "vp config",
"check": "vp check",
"sync:skill-assets": "pnpm --filter bailian-cli run generate:reference && pnpm --filter bailian-cli run sync:skill-version",
"check:skill-contribution": "node tools/check-skill-contribution.mjs",
"dev": "pnpm -F bailian-cli-core dev",
"bl": "pnpm -F bailian-cli dev",
"kscli": "pnpm -F knowledge-studio-cli dev",
Expand Down
Loading