officedev/office-js-snippets/create-script-lab-snippet

Create a Script Lab snippet

Create complete sample coverage for the Office.js API identified by the user. The input is one API name, preferably in canonical form such as Excel.Range.values, Word.Paragraph.insertText, PowerPoint.Shape, or Office.MessageCompose.subject, or a direct Microsoft Learn Office.js API reference URL.

Do not assume that every API needs a new YAML file. First determine whether the clearest, smallest coverage is a new sample or an expansion of an existing sample.

Required outcome

Complete all applicable parts of the change:

• Add or expand a public snippet under samples/<host>/<group>/.
• Give the sample deterministic data in a workbook, document, presentation, or Outlook item when the host permits it; otherwise state exact item prerequisites.
• Add rows to the host file in snippet-extractor-metadata/ that map the demonstrated API members to named snippet functions, subject to the cross-repository coverage decision in section 2.
• Make the Office.js object model and types clear inside every mapped function.
• Regenerate repository outputs with the existing build.
• Validate the snippet with the repository's existing tests.

Do not finish with only a proposed sample or a coverage recommendation when new or improved coverage is needed. If an existing example already provides the best coverage, explain the comparison and preserve it rather than creating a redundant sample or mapping.

1. Resolve the API

Normalize the input into:

• package or namespace, such as Excel, Word, PowerPoint, or Office;
• Office host, including Outlook when an API is exposed through the Office namespace;
• class, interface, enum, or type name;
• member name, when one was supplied;
• overload number or top-level category (class, interface, enum, or type);
• API requirement set and whether the API is stable or preview.

Use the Office JavaScript API reference on Microsoft Learn as the canonical documentation. The reference is generated from these script inputs:

• `office.d.ts` for released APIs.
• `office_preview.d.ts` for the preview API surface.

Consult these source definitions to confirm exact Office.js declarations, overloads, and option types. Treat an API found in office.d.ts as released, even if it also appears in office_preview.d.ts. Treat an API found only in office_preview.d.ts as preview. Continue to use Microsoft Learn to verify requirement sets, host and client support, and documented limitations.

When the user provides a Microsoft Learn URL, use that page to identify the API and ensure it belongs to the Office JavaScript API reference under /javascript/api/. Do not substitute a similarly named VBA, Microsoft Graph, Office Scripts, or other API. If the user gives an unqualified name, resolve it from the repository and these authoritative sources. Ask only when multiple valid Office.js APIs remain genuinely indistinguishable.

Use the stable Office.js library unless the requested API is preview-only. Verify availability in the Learn reference and the applicable Office Add-in requirement-set documentation, then set api_set to the highest requirement set used anywhere in the sample.

For Outlook, also resolve the required activation context:

• Message Read
• Message Compose
• Appointment Attendee
• Appointment Organizer
• a supported combination of those modes

Confirm any client, Exchange account, mailbox, permission, or feature-specific limitation documented for the API.

2. Audit existing coverage

Search all of these surfaces before editing:

1. The appropriate CSV:

• snippet-extractor-metadata/excel.csv
• snippet-extractor-metadata/word.csv
• snippet-extractor-metadata/powerpoint.csv
• snippet-extractor-metadata/outlook.csv

1. All YAML files under samples/ for the API namespace, class, member, related object-model access path, and nearby feature terminology.

1. The reference repository's API Coverage Report.csv. This report includes both mapped examples from this repository and examples maintained in the reference repository. Parse it as CSV, including quoted fields. Match Package, fully qualified Class, Field, and Type; inspect Has Example?. A top-level API uses Field = N/A, while a method field includes its signature. Resolve overloads against the declarations from section 1 instead of assuming that a method name or report row position identifies an overload.

1. The appropriate host YAML under the reference repository's `docs/code-snippets/`, such as excel-snippets.yaml, word-snippets.yaml, powerpoint-snippets.yaml, or outlook-snippets.yaml. For Outlook APIs, check office-snippets.yaml too when applicable. Inspect the actual code under the exact API UID, such as Word.Font:class, Word.Font#color:member, or Excel.Range#insert:member(1).

The report is a combined coverage index, not a source attribution or quality assessment. Has Example? = true does not establish that an example is reference-owned; trace it to the local CSV and mapped function, the reference YAML, or both. Confirm apparent gaps against those sources, since the report can lag source changes. If a source cannot be retrieved or an overload cannot be resolved, state the uncertainty rather than treating the API as uncovered.

Compare reference-owned and Script Lab examples

For every API being considered for a new mapping, including adjacent APIs discovered in section 5, check whether a reference-owned example exists. If it does, read it and compare it with the proposed Script Lab function as it will be extracted, not just with the full interactive sample.

Choose the better reference example using these criteria:

• Correctness against the current declarations, requirement set, host or Outlook activation mode, and documented limitations.
• Direct demonstration of the exact API target and overload, rather than incidental usage or a related API.
• Clarity and focus: explicit object-model access and types, minimal unrelated code, and understandable setup or prerequisites.
• Completeness: appropriate asynchronous handling, visible load and synchronization where required, and a useful result.
• Practical value: deterministic, repeatable behavior and a scenario that helps the reader use the API.

Generally favor the office-js-snippets example because it provides a runnable Script Lab sample and maintained extraction. Prefer it when quality is comparable, or improve its focused function so it is at least as clear as the reference example. Retain a reference-owned example when it is more targeted or otherwise better for that API page; interactivity alone does not outweigh a clearer extracted example. The report's Description Rating rates documentation descriptions, not example quality.

Record the exact API UID, existing source link and local function when applicable, chosen source, and a brief reason in the handoff or PR description. Do not add a tracking file just for this comparison.

• Reference-owned example wins: Do not add a local CSV mapping for that UID. Add or expand a Script Lab sample only when it provides distinct gallery value or serves other APIs. If a local mapping already duplicates the winning reference example, remove that mapping and regenerate its extract without deleting a useful gallery sample.
• Script Lab example wins: Add or retain the local mapping only with a coordinated removal or replacement of the reference-owned entry in OfficeDev/office-js-docs-reference. Identify the exact YAML file and UID that must change. Do not silently create duplicate reference examples or assume that changing this repository updates the reference repository. If the companion change is outside the authorized scope, ask for approval before adding a competing mapping; the gallery sample can still proceed without that mapping.
• No reference-owned example exists: Follow the local coverage decisions below and add a mapping when appropriate.

Apply the cross-repository decision first, then treat these local cases separately:

• A CSV row exists and its mapped function clearly demonstrates the API: improve it only if it fails the requirements in this skill.
• A relevant snippet uses the API but has no suitable CSV mapping: expand or clarify that snippet and add the mapping.
• A related snippet can accept one focused action without mixing unrelated scenarios: expand it.
• No coherent sample exists, or expansion would make an existing sample broad or confusing: create a new snippet.

Prefer expansion when the requested API uses the same setup data, object model, requirement set, and user scenario as an existing sample. Prefer a new snippet when it needs substantially different setup, belongs to another gallery group, changes stable versus preview placement, or would make the existing sample difficult to understand.

Do not duplicate an existing scenario merely to create a one-API file.

3. Design the sample

Each sample must be understandable and repeatable. Document-host samples must not rely on the user's current file. Outlook samples must clearly define the mailbox item and activation context they require.

Setup requirements

For Excel, Word, and PowerPoint, add a visible Set up action that creates deterministic data and named artifacts for subsequent actions.

• Excel: Create or replace a dedicated worksheet, normally named Sample. Add the ranges, tables, charts, or other objects needed by the API, format them when useful, activate the sheet, and call context.sync().
• Word: Create a known sample document state with the paragraphs, ranges, tables, content controls, shapes, or other objects needed by the API. Do not depend on arbitrary existing content or selection unless selection is the API being demonstrated.
• PowerPoint: Create known slides and shapes, text, images, or other objects needed by the API. Do not depend on arbitrary existing slides or selection unless selection is the API being demonstrated.

Make setup safe to run repeatedly. Reuse or replace clearly named sample artifacts instead of accumulating ambiguous duplicate content.

Keep setup separate from the focused API actions unless the API itself creates the sample object. Do not map generic setup plumbing to an API merely to increase coverage.

Outlook context and setup

Outlook does not provide a general equivalent of creating a sample workbook, document, or presentation. Follow the established Outlook pattern instead: