Product features: what belongs in a skill (allow-list)

Purpose: when generating or updating a skill, keep only what execution needs; drop everything else.

Source help/en/product-features/skill-content-rules.md

Purpose: when generating or updating a skill, keep only what execution needs; drop everything else. Applies: chat “generate / update skill”, Skills Center “Describe to create / Improve”, hand edits, and import. How it lands: writing injection prefers this article; publish checks catch leaked thinking blocks, duplicate H2s, and contradictory delivery rules.

A skill is a step-by-step how-to for the agent plus optional executables — not a writing-process scratchpad, and not a chat-log archive.

1. Principles

Allow-list: only items under Allowed below may enter the skill pack; anything not listed stays out by default.
One thing, one use: every file and body section must answer “what does execution rely on this for”; if you cannot answer, delete it.
Single source of truth: each rule in one place; no “forbidden above, allowed below” soft conflicts.
Reproducible: body states steps and delivery; long templates, scripts, sample HTML go in attached files, cited by path — do not dump a whole debug trail into the body.

2. Allow-list: what a skill must / may have

2.1 Metadata (required)

Content	Why	Requirement
Name (display)	Skills Center list title; user recognizes “which capability”	Short, scene-recognizable, e.g. “Rilong department-level chart”
Id (slug)	Export-pack directory name, interop with external tools	Lowercase hyphenated; usually system-generated
Trigger notes	Whether chat recalls it	Must include When to use / When not; When to use starts with trigger phrases
Capability type	List filter tag	2–8 characters, e.g. “Data report”; system may infer

2.2 Skill body (required)

Editor Markdown / SKILL.md body after frontmatter.

Section	When required	Why
`# Display name` (optional one-line title)	Recommended	Matches the list name, easier to read
`## How to use`	Required	Which class of work repeats, prerequisites, required inputs, recommended call order; ask if input is missing
`## Done when`	Required	Visible delivery on success (file link, report, receipt copy)
`## Failure signals`	Required	Must stop and explain to the user
`## APIs and calls`	When there is HTTP	Method, URL, auth placeholder, parameter highlights
`## Procedure`	No HTTP, pure steps	How to do it step by step
`## Script execution`	When using `run_script`	Which script, I/O, relation to business steps
`## Chart spec` / delivery shape	Charts or a fixed HTML report	Chart types, field mapping; or the one delivery-template convention
`## Troubleshooting and iteration`	Known pitfalls	Symptom → handling; keep only still-valid items
`## Cautions`	Permission/secret boundaries	Do not hard-code secrets, credential names, host scope

The body may include classification tables, placeholder notes, forced paths (e.g. local ECharts), and relative-path cites of attached files.

2.3 Attached files (as needed; do not create empty directories)

Directory	Why	Put	Do not put
`references/`	Long material loaded on demand so the body stays short	API notes, query-definition JSON, complete reusable HTML/report templates, field maps	Chat excerpts, one-off run results, expired drafts
`scripts/`	Deterministic compute/assemble (sandbox)	Clean after fetch, aggregate, fill a template to generate HTML/Office	Retired scripts, empty `NotImplemented` shells, matplotlib-then-PNG scripts that contradict a body red line
`assets/`	Static assets, layout shells	Empty HTML, CSS, icons, sample structure (no business secrets)	One-run PNG screenshots as “gold answers”, files with real tokens

Conventions:

If the user-accepted “standard delivery” is a whole HTML, it should land in references/ (or assets/) as a complete template; the body only says “this file is authoritative + how to replace data” — not a half skeleton in the body.
If the body says “no Python plotting”, scripts/ must not keep plotting scripts; keep only assemble/fill-template scripts (if needed).
One-run headcounts (e.g. 93, 1745) may only be marked example, do not copy, or omitted; execution uses this run’s fetch.

2.4 Optional: permission declaration (frontmatter)

permissions:
  tools: [data_source_invoke, file_write]
  secrets: [CredentialName]

Declares which tools and connection-credential names this skill depends on (not secret values). Skip if there is no external dependency.

3. Forbidden list: never on generate / update

Do not write the following into the skill body, trigger notes, or attached files:

Forbidden	Why extra / harmful
`<think>` / `<thinking>` / `<redacted_thinking>` thinking blocks	Model writing draft, not execution steps; wastes context, misleads execution
“I plan to read the skill then change…” process narrative	Same — chat process, not a skill
Duplicate same-named `##` titles (delivery shape twice)	Patch misalignment, stacked rules
Retired path plus a current red line (“no PNG” then “PNG may be the default preview”)	The agent still takes the old path
Real API keys, Bearer tokens, passwords	Security risk
Invented URLs, fields, numbers that never appeared in the materials	Execution fails or fake data
Vague trigger sentences (“auto-generated from a conversation”, “helps improve efficiency”, “user message involves APIs this skill inferred”)	Recall useless
Changelog-style long text (“v1 used a script / v2 switched to HTML…” as steps)	Keep only current valid steps; history belongs in version records
Uncited retired scripts / empty template files	Raises mis-call chance
CDN external scripts (when local vendor is required)	Preview unavailable or against platform rules
Whole chat logs, tool_trace dumps in the body	Should be tidied into steps; raw excerpts are not a skill

4. Minimum viable pack (check)

Notes only (no scripts, no template files):

Metadata + body (How to use / Done when / Failure signals + optional sections)

Fetch + fixed HTML report (e.g. department-level stats):

Metadata + body (delivery red lines, classification rules, cite paths)
Body must include a parseable Markdown classification table (department rollup, level keywords) + placeholder list (if the template uses __TOTAL__ etc.)
One complete HTML template under references/ (may include __placeholders__, or a full layout skeleton with sample numbers)
Recommended: scripts/ with a build_report(...) aggregate/fill-template script (no plotting) — copied as-is when creating an app
Chat finished stats, skill has no script (body classification notes + HTML template only): creating an app, the model generates in-app build_report.py from “skill body + how this conversation produced the report”, freezing equivalent compute into the app
Still recommend classification table and placeholders in the body for model compile and human check
Do not: old plotting scripts, half table bodies, think, PNGs that contradict the red line; do not assume a platform-resident universal report calculator
Flow: produce the report with a skill in chat first → then say “generate an app”

Fetch + map / structure HTML (store pins, org tree):

Same “fixed HTML” requirements; template scripts use platform Leaflet or Mermaid (see /static/vendor/)
Repo skeletons: examples/html-vendor-skills/dept-level-charts/, store-locations-map/, org-structure-diagram/
Do not: Google/Baidu SDKs, CDN, unregistered charting libs; do not replace platform ECharts with matplotlib / homemade SVG for statistical charts

API-call type:

Metadata + body (including ## APIs and calls) + {{CredentialName}}
Long API notes may go in references/

5. Self-check after generate and update (must pass)

Does the body start with a title or ## How to use, with no think / planning fluff at the start?
Is there only one current delivery path, old paths wiped?
Is every attached file cited by the body? Uncited: delete.
Are example numbers marked “do not copy” or removed?
Do trigger notes include concrete trigger phrases + When not?
Any real secrets or CDN (when forbidden)?

If any item fails: fix until it passes before publish — do not bump a version with extras.

6. Related docs

Interactive HTML report scripts — when to use ECharts / Mermaid / Leaflet, sample skills
How to write workspace skills — writing, templates, checklist
Skills and agents — entry and freeze path
Repo contract: Skill composition spec