Repository navigation
feat: invoke a Bot's Skills from / in a Human DM #4252
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
DoodleBears
wants to merge
12
commits into
main
Choose a base branch
from
claude/bot-skill-trigger-e16a1f
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+2,496
−46
Open
Changes from all commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
cbf27b7
feat: invoke a Bot's Skills from / in a Human DM
DoodleBears 8499460
Merge origin/main into S1
DoodleBears a741544
fix(skills): compare Memory paths after resolving symlinks
DoodleBears f5ce5d6
fix(skills): use the Orchestrator agent-preset scope
DoodleBears be4baef
chore(skills): meet source policy, ADR numbering and Host cast checks
DoodleBears d519bf1
fix(skills): keep restored Skill offsets and chips out of command par…
DoodleBears b7c592b
docs(skills): imported Project Skills activate without a separate review
DoodleBears 8d9216d
fix(skills): preserve selected invocations and refuse oversized skills
DoodleBears e5e36a2
test(skills): type the shortcut choice id
DoodleBears 03d35f9
Merge remote-tracking branch 'origin/main' into claude/bot-skill-trig…
DoodleBears e90efa9
docs(skills): renumber the Skill ADRs to 0345 and 0346 after main too…
DoodleBears d0d376f
fix(skills): enforce readable owners and shift expanded tokens
DoodleBears File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
32 changes: 32 additions & 0 deletions
32
.agents/skills/verify-deepseekbot/features/skill-invocation.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| # Skill Invocation in a Bot DM | ||
|
|
||
| A Human types `/` in a PersonaBot DM, picks a Skill, and sends it. The Host stores the Skill's text with the message and the Bot reads it as a `<skill_invocation>` block ([ADR-0346](../../../../docs/adr/0346-skill-invocation-is-snapshotted-text-that-addresses-no-one.md)). | ||
|
|
||
| ## Sub-features | ||
|
|
||
| - `menu` lists composer commands first, then Skills: Host Skills and the Project Skills under the Bot's Memory Repository `.agents/skills` or `.dsh/skills`. Each row shows its owner (Bot avatar or Skill icon), `/name` and a one-line description. | ||
| - `rank` orders Skills by name prefix, then name subsequence, then description text. | ||
| - `chip` inserts the picked Skill as one token; Backspace removes it whole; the draft keeps it across reloads. | ||
| - `snapshot` stores `{name, owner, path, content}` with the message; editing or deleting the `SKILL.md` later does not change the sent message. | ||
| - `deliver` gives the Bot the message with `[/name]` and the `<skill_invocation>` block, so DSH does not load the Skill a second time. | ||
| - `cli` `deepseekbot skills-list --bot <slug> [--query]` and `send <slug> --body "/name …" --skill <owner>/<name>`. | ||
|
|
||
| ## How to get to it (user POV) | ||
|
|
||
| - Enter Bot mode, open a Bot DM, type `/` and a few letters in the composer, choose a Skill with the arrow keys and Enter (or click it), write the rest of the message, press Enter. | ||
|
|
||
| ## Driving it with verify-app | ||
|
|
||
| Preconditions: `launch` reported a model credential and `doctor` passes. | ||
|
|
||
| 1. **Seed a Project Skill.** Get the Bot's Memory Repository from `rpc botharness/list` and the Host profile layout, then write `<memory>/.agents/skills/qa-echo/SKILL.md` with frontmatter `name: qa-echo`, `description: Reply with a fixed QA word` and a body such as `Reply with exactly SKILL_QA_7731 and nothing else.` | ||
| 2. **Menu.** `shot skill-menu --bot-mode --fill "Message <Bot>=/qa"` and read `skill-menu.aria.txt`: a `/qa-echo · <Bot>` menu item appears after any matching command. | ||
| 3. **Send.** `shot skill-send --bot-mode --fill "Message <Bot>=/qa" --press Enter --press Enter --wait-text SKILL_QA_7731`. The first Enter picks the Skill, the second sends. | ||
| 4. **Canonical state.** `rpc botharness/channelTimeline '{"channelId":"<dm id>"}'`: the Human entry has `skillInvocations[0]` with `owner {kind: bot}`, the `path` of the seeded file and its body; the Bot entry replies `SKILL_QA_7731`. | ||
| 5. **CLI.** `deepseekbot skills-list --bot <slug> --query qa` lists `qa-echo`; `deepseekbot send <slug> --body "/qa-echo" --skill bot:<slug>/qa-echo` returns a committed reply. | ||
|
|
||
| ## Gotchas | ||
|
|
||
| - The `/` menu reads the catalog when the DM opens. A Skill written while the DM is open appears after reopening the DM until S3 (live refresh) lands. | ||
| - DSH discovers `<memory>/.agents/skills` because the Orchestrator's cwd is the Memory Repository; a Skill placed in `.botharness/` is not found. | ||
| - Recalling an older message with ArrowUp, or restoring a failed send, keeps `/name` as plain text without the chip. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| section: Added | ||
| --- | ||
|
|
||
| ## en | ||
|
|
||
| - Type `/` in a PersonaBot DM to pick a Skill: commands come first, then Host Skills and the Skills in the Bot's Memory Repository `.agents/skills`, each with its owner and a one-line description. The picked Skill becomes a chip, its text is saved with the message, and the Bot reads that text with your message; `deepseekbot skills-list` and `send --skill` do the same from the CLI ([#4232](https://github.com/BotHarness/DeepSeekBot/issues/4232)). | ||
|
|
||
| ## zh | ||
|
|
||
| - 在 PersonaBot 私聊中输入 `/` 即可选择 Skill:先列命令,再列 Host Skill 和该 Bot Memory Repository `.agents/skills` 下的 Skill,每行显示归属和单行描述。选中的 Skill 显示为 chip,其文本随消息保存,Bot 会连同你的消息一起读到;CLI 中可用 `deepseekbot skills-list` 和 `send --skill` 完成同样的操作([#4232](https://github.com/BotHarness/DeepSeekBot/issues/4232))。 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| section: Fixed | ||
| --- | ||
|
|
||
| ## en | ||
|
|
||
| - Fixed repeated Skill selection in the CLI, selected Skill and mention rendering in Bot prompts, oversized Skill sends being silently truncated, private or archived Bot Skills being accepted in Group sends, and Skill offsets after All Bots expansion ([#4232](https://github.com/BotHarness/BotHarness/issues/4232)). | ||
|
|
||
| ## zh | ||
|
|
||
| - 修复 CLI 重复选择同名 Skill、Bot 提示词中已选 Skill 与提及的渲染,超长 Skill 发送时被静默截断、群聊接受无权读取或已归档 Bot 的 Skill,以及所有 Bot 提及展开后的 Skill 位置错误([#4232](https://github.com/BotHarness/BotHarness/issues/4232))。 |
20 changes: 20 additions & 0 deletions
20
docs/adr/0345-project-skills-travel-with-their-directory.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| --- | ||
| Status: Proposed | ||
| Date: 2026-11-15 | ||
| --- | ||
|
|
||
| # Project Skills travel with their directory | ||
|
|
||
| A PersonaBot's Skills are the **Project Skills** of its Memory Repository: `SKILL.md` folders under `<Memory Repository>/.agents/skills/`. They are not a separate kind of Skill and have no store of their own. The Orchestrator Session's cwd is already the Memory Repository, so DSH's file-skill discovery finds them, and in that PersonaBot's own Sessions they override a **Host Skill** of the same name, without BotHarness registration code. A folder covered by a Workspace Grant contributes Project Skills the same way. BotHarness scans only the granted root itself (`.agents/skills` and `.dsh/skills`) and does not walk up to an enclosing Git root, so visibility never exceeds the Grant. | ||
|
|
||
| Installing a Skill is a file write. A PersonaBot decides where a Skill belongs. If it is the bot's own capability, it goes in the Memory Repository, which the bot may write freely. If it is a project convention, it goes in a Workspace folder, under the existing write authority. Memory's Git history is the record of these writes, so no separate activity entry is created. A Human removes a Project Skill by deleting its files; there is no disabled state. | ||
|
|
||
| Because Project Skills are ordinary text files in the Memory Repository, they travel with every existing way of sharing a PersonaBot: the Memory Git repository, a Bot Zip and a Profile Backup. This differs from ADR-0044. That ADR rejects embedding or auto-installing Skills as **Host** runtime dependencies. A Project Skill is part of the PersonaBot's own content, not a Host dependency. On a target Host, the Project Skills arrive with the rest of the PersonaBot's Memory and are discoverable as soon as the PersonaBot is installed or imported. They get no separate Skill review: they carry the same trust as the Memory content they live in. The marketplace detail page and the PersonaBot profile show a Skills section listing the Memory Repository's Project Skills. Workspace Skills belong to the project and are not listed there. | ||
|
|
||
| ## Considered Options | ||
|
|
||
| - **A `.botharness/skills/` folder with a BotHarness skill provider** — rejected: DSH does not scan it. BotHarness would need a per-bot provider, but DSH registrations are scoped only to an agent preset. It would also diverge from the `.agents/skills` layout that Humans and cross-agent tooling already use. | ||
| - **A separate "Bot Skill" concept** — rejected: it has the same mechanism as any Project Skill. A second name would suggest storage or rules that do not exist. | ||
| - **Walk up to the enclosing Git root like DSH** — rejected for BotHarness listings: a Grant on a monorepo subfolder would expose Skills outside the granted folder. | ||
| - **Export only Desired Dependency References and leave the Skill files behind** — rejected: Skills are a defining part of what a PersonaBot can do, and they are plain text that already lives in its Memory. | ||
| - **Hold imported Skills in a pending folder until a Human reviews them** — rejected: the rest of the Memory Repository, which also shapes the PersonaBot's behavior, is not held back. A Skill-only gate would add a second copy of each Skill, a move on acceptance, and conflicts with the Memory Git repository shared between Hosts, without closing a gap the Memory itself leaves open. |
22 changes: 22 additions & 0 deletions
22
docs/adr/0346-skill-invocation-is-snapshotted-text-that-addresses-no-one.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| --- | ||
| Status: Proposed | ||
| Date: 2026-11-15 | ||
| --- | ||
|
|
||
| # Skill Invocation is snapshotted text that addresses no one | ||
|
|
||
| Typing `/` in a Channel or DM composer lists commands first, then Skills. The Skills come from the Host Skills plus the Project Skills of every PersonaBot in the conversation: each bot's Memory Repository and its Workspace Grants. A DM counts only that one PersonaBot. Each row shows its owner (a PersonaBot avatar, a folder for a Workspace, or a Host mark), its name and a one-line description. Picking a row inserts a chip, as `@` does. | ||
|
|
||
| A **Skill Invocation** addresses no one. It inserts the Skill's text into the message. Which PersonaBot reads and acts on the message follows its mentions and normal routing, never the Skill's owner. Picking Alice's Skill and mentioning Bob gives Bob that text. Ownership affects only automatic discovery: a bot's model catalog contains Host Skills and its own Memory Repository's Project Skills, and nothing else. | ||
|
|
||
| The Host resolves the Skill when the message is sent and stores a snapshot in a typed `ChannelMessage` part: the name, the owner (`host`, `bot:<slug>` or `workspace:<name>`), the `SKILL.md` path and the content. Every recipient therefore gets identical text, even one whose Sessions cannot discover that Skill. History stays reproducible after the Skill changes or is deleted. Bot Inbox delivery renders the snapshot as a `<skill_invocation>` block carrying its owner and path. A recipient without read authority for that path receives the text but not the files: ADR-0067's path guard still applies. External IM mirrors fall back to the plain text `/name`. | ||
|
|
||
| When a command and a Skill share a name, the command keeps the bare name. | ||
|
|
||
| Delivery is staged under #4231. The first slice covers Human DMs with Host Skills and the PersonaBot's Memory Repository Skills, so `SkillOwner` has only the `host` and `bot` kinds. Group Channels and Workspace Grant Skills, with the `workspace:<name>` owner, arrive in later slices. | ||
|
|
||
| ## Considered Options | ||
|
|
||
| - **A Skill Invocation implicitly mentions the Skill's owner** — rejected: it adds hidden rules ("whose Skill is it?") to what Humans already understand as inserted text plus explicit mentions. | ||
| - **Expand at delivery time, per recipient** — rejected: recipients could see different text, history would not reproduce, and a recipient that cannot discover the Skill would fail. | ||
| - **Plain `/name` text expanded by DSH's user-message scanner** — rejected: Channel messages reach bots as Bot Inbox text, not DSH user messages. The scanner also matches `/word` anywhere and cannot say which owner's Skill was meant. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.