Skill composition

Document version: 1.2 Status: Matches current backend (skillpkg, skillfromchat, conversation-deposit tables, GET /api/v1/skills) Voice: For product, operations, and integrators — what a skill is, what it is made of, how it enters conversation. Implementation names are in Implementation mapping at the end.

Related:

• 产品规格.md §3.5 (file-first Workspace), §3.6 (skill deposit and governance)
• 智能体调用知识文档的方式.md (skills vs knowledge base)
• 智能体对话编排.md (skills enter conversation as a catalog, then this round’s body)
• help/product-features/skills-and-agents.md (user-side entry notes)

---

1. Up front

A skill in Cadau is a professional operations handbook the agent can replay a class of actions from, step by step, in conversation — not an “API name” in an external business API, and not the agent’s long-term persona (that belongs to “My agents” and Soul).

A well-formed skill includes at least:

1. Name (user-visible title)
2. Trigger notes (description: when to use, when not to)
3. Operations body (steps, API highlights, troubleshooting, as Markdown)

As needed it may include references/ (long templates and notes), scripts/ (deterministic scripts), assets/ (static resources). Nothing outside the allowlist (thinking blocks, writing process, repealed paths, chat originals, and similar) — see user-side What belongs in a skill (allowlist) and §3.5 below.

Conversation-deposited skills are stored in the database as metadata columns + body; platform built-in and agent Workspace skills on disk may map to SKILL.md + optional extra directories (see §3). Regardless of storage shape, the logic contract is unified.

---

2. Boundary with knowledge documents and agents

On conflict: in conversation runtime material, skill notes beat generic memory; versus the agent knowledge base, explicit overrides in the agent knowledge base win (see 智能体调用知识文档的方式.md §5).

---

3. Logical composition (all sources unified)

3.1 Required: trigger notes + operations body

Trigger-notes example (user-visible copy, not necessarily YAML source):

Applicable: the user uploads invoice/receipt images and asks to recognize, book, or summarize.

Not applicable: plain-text small talk, Q&A unrelated to tables or booking.

Writing tips:

• The Applicable line starts with trigger phrases the user might say (e.g. “recognize invoice”, “export the list”), then the scene.
• Not applicable must name exclusion scenes that user messages can hit; at runtime, if the user message hits not applicable, that skill is not injected this round.
• Avoid empty sentences such as “auto-generated from conversation” or “helps raise efficiency” — they barely help recall.

#### 3.1.1 Task card (fill before writing a skill)

Regardless of source (conversation deposit, Skills center hand edit, platform built-in), walk a task card in your head or in a draft first:

If the four task-card sentences are unclear, it is not ready to publish as a skill; finish the conversation first or split a narrower scene.

3.2 Recommended body structure (operations body)

When conversation deposit is synthesized by the model, the body should prefer these sections (omit if there is nothing relevant):

3.3 Progressive disclosure (by stage)

Current implementation (v1): L0+L1; over-long bodies are truncated at runtime; the full version is viewed in the Skills center.

3.4 On-disk directory shape (platform / agent Workspace)

Aligned with Agent Skills convention, a file-type skill directory example (platform built-in: docs/agent-skills/workspace/workspace-ops/):

skills/{skill-id}/
  SKILL.md          # required: YAML header + body
  references/       # optional: long docs loaded on demand
  scripts/          # optional: deterministic scripts (must sandbox)
  assets/           # optional: templates, static resources

SKILL.md logical header fields:

---
name: invoice-ocr-to-sheet
description: |
  适用：用户上传发票/收据并要求识别、入账、汇总。
  不适用：纯文字闲聊或与入账无关的问答。
permissions:
  tools: [http_request]
  secrets: [LARK_APP_TOKEN]
---
# 发票识别入账
…

Conversation deposit is not required to land as a directory; after synthesis, YAML headers are parsed into DB columns, semantics match SKILL.md.

3.5 Allowlist and forbidden (hard rules on generate / update)

Allowed:

Must not write into a skill pack:

• Model thinking blocks (think / redacted_thinking and similar) and writing-process narrative
• Repeated ## headings; old and new conflicting rules coexisting
• Real secrets; URLs/fields/numbers that never appeared in the material
• Empty trigger sentences; stacking chat originals / tool_trace
• Deprecated-but-not-deleted scripts or half templates
• Changelog-style long text acting as current steps (history stays in the version table)

User-side full text: skill-content-rules.md. Synthesis and update must strip thinking blocks before writing (skillpkg.StripThinkLikeBlocks / ParseDocument).

---

4. Sources and storage

---

5. How it enters conversation

1. The user talks with My agents in workspace Messages.
2. The backend matches workspace skills against the current user message: name or “applicable” must share a consecutive 3 Chinese characters with the wording (short skill names may use 2), so “check errors” does not wrongly recall “checklist / data query”. Then a selector refines; if the selector clearly says “no skill this round”, keywords are not used to pad.
3. At most 3 hits; trigger notes + body (may truncate) are assembled into runtime material; after send, the front end hints “the model referred to these workspace skills this round”.
4. Users can view the full text and version history in the Skills center, and roll back the published version of conversation-deposited skills.

Create / update deposit (say it in Messages; do not call an external API):

• Create: “generate a skill / deposit a skill from the flow just now”
• Update: “update skill xxx” and include the name if possible

---

6. Synthesis and validation (conversation deposit)

When generating a skill from conversation, the model must output a full document with YAML frontmatter; after server skillpkg.ParseDocument:

• name → override the default inferred name (if valid)
• description → trigger notes (must include applicable / not applicable)
• After frontmatter → body_markdown

If the model is unavailable, fallback body is still saved, but trigger notes use a structured template sentence, and the user is encouraged to later view it in the Skills center and update the skill via conversation.

Function-type summarize: on create or update deposit, the server calls the model to produce a 2–8 character Chinese tag from name, trigger notes, and body (e.g. “weather query”, “API call”); if the model is unavailable or fails, a rule heuristic is used. Users can tap Re-summarize type on skill detail to refresh by hand (POST /api/v1/skills/conv/{id}/function-type/infer), without bumping the version.

Synthesized body must include: ## 使用说明, ## 完成标准, ## 失败信号; with HTTP also ## 接口与调用. The Applicable line of trigger notes must start with a user trigger phrase.

6.1 Post-publish acceptance (ops SOP)

After publishing or a large skill change, try one round each in a test workspace (may be recorded by hand; automation not required):

On recall anomalies: not recalled → prefer changing trigger notes (applicable); recalled but did it wrong → fix body steps and completion criteria / failure signals.

---

7. Skills center UI convention

---

8. Safety and governance

• Bodies must not contain real secrets; Authorization and similar must be placeholders.
• permissions declare tool and secret names; values go through environment variables or workspace secret management (later).
• Execution that includes scripts/ needs sandbox and approval (product spec §3.6.2).
• Version changes and rollbacks write audit events.

---

9. Implementation mapping

---

10. Change log