Product features: how to write workspace skills

A skill is instructions for an agent to repeat a class of work step by step, not background knowledge (that belongs in a knowledge base). Quality decides whether chat recalls it and does it right.

In Skills Center you can Describe to create (natural-language draft, may include scripts and reference docs), create a blank skill, or pick templates such as API call. You can also tell the help agent or a work agent in Messages “help me generate a skill”. Below: basic writing requirements and templates you can rewrite.

When generating or updating a skill, first follow What belongs in a skill (allow-list): keep only allow-list content; drop everything else (including thinking blocks, writing process, retired paths, and raw chat dumped into the skill).

---

0. Allowed vs forbidden (summary)

Allowed

Forbidden (wipe on generate/update)

• Any <think> / thinking block, writing plan, chat-process narrative
• Duplicate section titles, old and new conflicting rules together
• Real secrets, invented URLs/numbers, vague trigger sentences
• Retired scripts / half templates still in the pack
• Whole chat or tool dumps as the body

Full table and minimum viable pack: What belongs in a skill (allow-list).

---

1. What a complete skill at least contains

Id (slug): used when exporting a skill pack and interoperating with external tools; usually generated from the name; you can adjust it when editing SKILL.md.

Capability type: 2–8 character list-filter tag (e.g. “API call”, “Data export”); the system tries to infer on create/update; you can re-infer type on detail.

---

2. Before you write: a four-sentence task card

Before publish or freeze, self-check in four sentences:

1. Which class of work repeats — e.g. “recognize uploaded invoices then write them into a sheet”, not a vague “data analysis”.
2. How the user says it — e.g. “recognize invoice”, “export employee list”.
3. What must be delivered — what the user should see at the end (file, receipt, confirm copy).
4. When you must stop — missing file, missing name, facts unverified: ask the user first; do not invent.

If the four sentences are unclear, run the flow through in Messages first, then tell the help agent or work agent generate a skill, or start from a Skills Center template.

---

3. Trigger notes: when to use, when not

In the SKILL.md YAML header or Skills Center trigger notes, two lines:

• When to use: start with trigger phrases the user might say, then the scene.
• When not: scenes to exclude (chitchat, unrelated topics).

Important: if the user message hits wording in When not, the system will not inject this skill this round. Put easy-to-confuse scenes in When not, not only in the body.

Avoid vague sentences like “auto-generated from a conversation”, “helps improve efficiency” — almost useless for recall.

Examples

description: |
  When to use: recognize invoices, book them, upload receipt images and ask for a summary.
  When not: pure chitchat, Q&A unrelated to sheets or booking.

The Skills Center trigger-notes box can use the same two lines (no description: prefix):

When to use: export employee list, pull HR API data, query active staff.
When not: pure chitchat, Q&A unrelated to the HR API.

---

4. Required body sections

Whether hand-written or frozen from chat, the body at least needs:

Optional (write only when there is content):

When generating a skill from chat, the system tries this structure; in Skills Center you can complete against the writing checklist (beside Save on the editor).

---

5. Safety and facts (hard)

• Do not put real API keys, Bearer tokens, passwords in the skill body, trigger notes, or knowledge base.
• For auth, use a connection-credential placeholder: {{CredentialName}}, matching the name configured under workspace connection credentials (starts with a capital, e.g. CRM_READ, HR_EMPLOYEES).
• Do not invent URLs, fields, or return data that never appeared in the materials.
• Dates and ranges: write relative rules (“this month”, “last 7 days”), not frozen example days — see Agent operating rules.

---

6. Network and connection credentials

When the skill must call an external business API, besides the required sections above:

6.1 Prerequisites (three layers)

1. The platform has enabled agent network capability;
2. The workspace has Network requests enabled, and the target host is in the grant policy (Workspace collaboration → Assistant capability packs → Network requests);
3. The current member has a matching-named credential under Connection credentials (admin configures; members can see their credential names, not secret values).

Details: Member connection credentials.

6.2 How the body cites credentials

• Steps say to send with http_request.
• Header example: Authorization: Bearer {{CRM_READ}} (replace CRM_READ with the real credential name).
• URL is a full address; the host must be in Network requests authorized hosts.

6.3 Extra failure signals

For external APIs, ## Failure signals should include:

• Workspace has not enabled Network requests, or the target host is not on the grant list → say an admin must enable or add the host.
• Current member has no connection credential, or body {{Name}} does not match a configured name → say configure it under Connection credentials.
• Auth failure, missing required parameter, API error → explain and stop; do not invent data.
• User urges “skip verification” → still verify or mark uncertainty.

---

7. Full SKILL.md example (file / editor)

Conversation-derived skills in the Skills Center editor are logically the same as the following SKILL.md (YAML header + body).

YAML header and body (through APIs and calls):

---
name: export-employee-list
description: |
  When to use: export employee list, pull active staff, query the HR employee API.
  When not: pure chitchat, Q&A unrelated to the HR API.
permissions:
  tools: [http_request]
  secrets: [HR_EMPLOYEES]
---

# Export employee list

## How to use

- **Which class of work repeats**: pull an employee list from HR by the user’s conditions and present it.
- **Required inputs**: time range, department, employment status; ask first if missing; do not invent.
- **Steps**:
  1. Confirm the request and whether required parameters are complete.
  2. Call the API below with `http_request`; auth uses `{{HR_EMPLOYEES}}`, never a real secret.
  3. Only access **Network requests** authorized host `hr.example.com`.

## APIs and calls

HTTP example (after the section above):

GET https://hr.example.com/api/v1/employees?status=active
Authorization: Bearer {{HR_EMPLOYEES}}

Rest of the body:

- Query parameters and paging follow the business API docs; dates use relative rules (e.g. “this month”).

## Done when

- Return the list or table the user asked for, and explain the result in plain language.

## Failure signals

- **Workspace has not enabled Network requests**, or `hr.example.com` is not an authorized host: say an admin must configure **Network requests**.
- **Connection credential `HR_EMPLOYEES` not configured**: say add that name under **Connection credentials**.
- Auth failure, missing required parameter, API error: explain and stop.
- Even if the user urges skipping verification, still verify or mark uncertainty.

Note: the permissions block is optional for conversation-derived skills; if the body correctly writes http_request and {{Name}}, runtime still uses the same network and injection logic.

---

8. Templates you can rewrite

These match Skills Center create blank skill and API-call template starters; copy then replace parentheses or examples.

8.1 Generic blank skill (delete APIs and calls if no HTTP)

Trigger notes:

When to use: (trigger phrases the user might say, then which class of work this skill owns)
When not: (scenes to exclude, e.g. pure chitchat, Q&A unrelated to this work)

Body: How to use (repeat class, required inputs, steps) → Done when → Failure signals → optional APIs and calls with http_request and {{CredentialName}}. HTTP example: GET https://api.example.com/api/v1/example plus Authorization: Bearer {{CredentialName}}.

8.2 API-call skills

Trigger notes: When to use: export a list, query a business system, call an external API. When not: pure chitchat, unrelated to business APIs.

Body: see section 7; replace HR_EMPLOYEES, hr.example.com, and the path with your credential name and business host.

8.3 Data-export skills (HTTP optional)

Trigger notes: When to use: user wants to export a list, report, or sheet. When not: looking up a single detail, unrelated to export.

Body: required inputs (range, format such as CSV/Excel; ask if missing); steps (confirm range and format); Done when: user has a downloadable or usable export; Failure signals: no permission, empty data, unsupported format — explain and stop. If export depends on a business API, merge 8.2 APIs and calls with 6.3 failure signals.

8.4 Script skills (Describe to create can generate)

When the work is fixed logic, repeatable (clean CSV, batch rename rules, stats on a large file), put the deterministic part in the pack’s scripts/ and write ## Script execution in the body:

• Which script to run, inputs/outputs, how to report exceptions
• Common: data/CSV/chart scripts; do not write .xlsx/.docx/.pptx/.pdf with scripts — use office-document tools (office_document; PDF via build_pdf)
• Complex flows can mix script + API: script processes data; body ## APIs and calls submits
• Scripts must not contain real secrets; sensitive items use env vars or connection-credential placeholders

In Skills Center Describe to create, pick script-first or script + API; after generate, edit scripts/ and references/ in the left file tree.

Agents with script execution enabled can also use skill_script_read / skill_script_write in chat to read or update files under scripts/ (skill_update only changes the body, not .py); after change, run_script a trial; non-empty output_files counts as successful output.

Run prerequisites (admin; see Script execution and member grants):

1. Platform mindlink.json script-execution master switch on;
2. Workspace Assistant capability packs → Script execution enabled;
3. Current member is not Forbidden, and per-member grant skill slugs (if any) include this skill.

If not met, the assistant should explain the limit and suggest contacting an admin — do not pretend the script ran.

8.5 Skill dependencies (base + analysis)

When an analysis/chart/stats skill depends on a fetch/API skill:

1. Base skill (e.g. “Access HR employee data”): narrow trigger; only how to http_request the data.
2. Upper skill (e.g. “Employee profile charts”): wider trigger; body has ## Dependent skills with display name and id ` hr-employee-data `.
3. The upper skill must also carry ## API summary or references/hr-fetch-summary.md so a hit on the upper skill alone is not missing API material.
4. In Describe to create you can tick dependent existing skills and connection credentials (multi-select); generate writes matching {{Name}} placeholders into API steps.
5. Reference content is separate from the description: description is intent (one sentence); paste or upload API URLs, fields, sample requests into Reference content; generate writes them into references/ as facts so the assistant does not invent details.

At chat runtime: if an upper skill hits and the body has ## Dependent skills, the system tries to inject dependent-skill material too (still limited by count and length).

8.6 Query-type skills and predefined queries

When members query workspace data-connection business data in Messages, skills and predefined queries split differently; they must work together and cannot replace each other.

What a skill should write

• Chinese names, field meaning, enum notes for each business table (e.g. status=active means employed).
• Common user phrasings and which predefined query to pick (write query id and required parameters).
• Do not: put a full SELECT in the skill body and expect the agent to run it — the system does not allow improvised SQL; execution must go through table preview or a predefined query.

What a predefined query should write

• Configure in Workspace collaboration → Assistant capability packs → Data integration → Data connections.
• After saving a connection, Generate skill writes each query’s id, name, and parameter notes into the skill body so chat picks the right query.
• Not required: without predefined queries the agent can still see table structure and preview sample rows; for filters, stats, or a fixed metric, still configure queries.

Writing example (skill-body fragment): How to use — distinguish “recognize structure/see samples” vs “query by condition”; samples use table preview (default about 200 unfiltered rows, not a full business result); conditioned queries call e.g. staff_by_dept (dept_name) or orders_recent (start_date); only use connections and queries the member is granted. Table notes: employees.dept_name, status. Failure: if they want filter/stats/duplicate-check but no matching query — first query.list; if none, propose SELECT and query id, wait for confirm, then admin query.upsert and same conversation query.run; do not fake a full result from table preview. SQL placeholders must be ?, not @empName.

Config tips: queries by business scene, not one per table; names and descriptions clearer than piling SQL; Data resources / Who can use so roles see only related tables; several connections: dedicated query agents get Overview → Available data and skills; conversation-derived skills write to the workspace Skills Center and auto-join an agent that ticked Specify skills; skill = business meaning + which query; predefined query = how to query; missing query: propose read-only SELECT → user confirm → admin save → run immediately; do not conclude stats/duplicates from table preview; cross-workspace migrate: export pack tries to include used predefined-query definitions; on import an admin can write missing queries onto the target data connection.

Full notes: Data connections and predefined queries.

---

8.7 HTML interactive pages (ECharts / Leaflet / Mermaid)

When the delivery is previewable HTML needing charts, map pins, or org/process diagrams: templates only cite platform allow-listed scripts — no CDN. Simple PNG preview can use chart.

User-facing notes (read first): Interactive HTML report scripts.

Minimum viable packs you can rewrite in the repo:

Each has SKILL.md + one complete HTML under references/. After Skills Center Import skill pack (dist/*.zip), replace sample data with this run’s fetch.

Trigger-note examples: department-level charts / pie / bar / ECharts HTML (not “table only, no chart”, geo distribution, org tree); store map / site map / store pins / geo HTML (not “table only, no map”); org chart / department hierarchy / reporting-line / org-tree HTML (not “list table only”, changing HR master data).

Body highlights:

• ## Delivery shape: unique template path and allow-listed scripts; Leaflet needs css + js; mainland default Amap-style tiles (do not default OSM official tiles — often timeout on the mainland); Mermaid as a tree, not a plain table pretending to be an org chart.
• Steps: fetch → fill template placeholders / replace data arrays → file_write delivery; do not inline a whole library.
• Failure signals: no coordinates/nodes, external CDN, no permission — stop.

---

9. Pre-publish writing checklist

Before save or publish:

Trigger notes

• [ ] When to use starts with trigger phrases the user might say (e.g. “export a list”)
• [ ] When not has scenes to exclude
• [ ] No vague sentences (e.g. “auto-generated from a conversation”)

Body structure

• [ ] ## How to use (required inputs; ask if missing)
• [ ] ## Done when
• [ ] ## Failure signals
• [ ] HTTP: ## APIs and calls
• [ ] Query-type skills: table/field notes map to predefined query ids; no “executable full SELECT” in the body pretending to be a query

Safety and facts

• [ ] No real secrets or tokens
• [ ] HTTP auth uses {{Name}} matching Connection credentials
• [ ] No invented URLs or data that never appeared in the materials

The Skills Center editor shows similar check progress beside Save.

---

10. Three acceptance tests (self-test)

After a large change or new publish, try one round each in a test workspace:

1. Happy path — request and materials complete; can it finish steps and deliver.
2. Gap path — deliberately omit key info; does it ask instead of guessing.
3. Temptation path — “just give the conclusion”, “don’t verify”; does it still verify or mark uncertainty.

---

11. Common troubleshooting

---

12. Related entries

• Skills and agents — Skills Center entry and freeze path
• What belongs in a skill (allow-list) — allowed vs forbidden on generate/update
• Interactive HTML report scripts — ECharts / Mermaid / Leaflet
• Agent operating rules (AGENTS.md) — relative dates and query steps
• Member connection credentials — {{Name}} config and cite
• Script execution and member grants — Office files from skill scripts, member grants
• Data connections and predefined queries — queries; predefined queries vs skill table notes
• Detailed contract: repo skill composition spec (docs/core-mechanisms/技能组成规范.md)