officedev/office-js-docs-pr/excel

Create a Copilot skill for Excel that uses the Office JavaScript Library (preview)

In this tutorial, you create a Copilot skill for Excel that uses the APIs of the Office JavaScript Library (Office.js). The skill finds the first table on the first worksheet that has at least 12 columns and contains only numeric body data, then finds rows in that table whose data embodies an accelerating growth trend. For each matching row, it adds a chart of the rows data to the worksheet.

[!NOTE]

- This tutorial assumes that you're familiar with Overview of Copilot skills for Excel (preview) and Build plugins for Copilot Cowork. Although the latter article is in the context of Cowork, the general packaging, manifest, icon, installation, and publishing guidance in that article also applies to Excel skills. This tutorial focuses on the Excel-specific pieces and uses the same plugin package model described in that article.

- Custom skills for Excel are in preview and require version 2608 (Build 20305.20002) or later. They are available in only the Beta and Current Channel (Preview) channels, through the Microsoft 365 Insider Program. Don't use them in a production Copilot extension.

What you'll build

You'll build a Microsoft 365 app package with one skill.

my-copilot-plugin-skills/
|-- manifest.json
|-- color.png
|-- outline.png
|-- skills/
    |-- accelerating-growth-trend-finder/
        |-- SKILL.md
        |-- resources/
        |   |-- workbook-data-guardrails.md
        |   |-- excel-vs-agent-execution.md
        |-- scripts/
            |-- find-accelerating-growth-trend-rows.js

The Office.js script implements the workbook analysis and editing. The SKILL.md file tells Copilot when to use the script and how to explain the result to the user.

Accelerating growth trend definition

For this skill, a row embodies an accelerating growth trend when both of the following are true.

• Each cell value, beginning with the second column, is higher than the value immediately to its left.
• Each increase, beginning with the increase from the second cell to the third cell, is larger than the preceding increase.

For example, the following row qualifies.

2, 4, 8, 15, 27, 46, 78, 130, 215, 351, 570, 921

The values are strictly increasing, and the size of the increases also strictly grow:

+2, +4, +7, +12, +19, +32, +52, +85, +136, +219, +351

Prerequisites

Before you start, make sure you have the Microsoft 365 Agents Toolkit CLI as described in "Step 7: Test" of Build plugins for Copilot Cowork.

Task 1: Create the plugin folders

Create the following folders.

my-copilot-plugin-skills/
| -- skills/
   | -- accelerating-growth-trend-finder/
       | -- resources/
       | -- scripts/

Task 2: Create SKILL.md

1. In the skills/accelerating-growth-trend-finder/ folder, create a file called SKILL.md.
2. Add the following YAML frontmatter (including the two --- lines) to the very top of the file. Note that the metadata.tags value includes excel, which helps identify the skill as Excel-oriented for purposes of skill discovery.

```yaml

name: accelerating-growth-trend-finder description: | Use this skill in Excel when the user asks to find rows in a workbook table that show an accelerating growth, increasingly larger increases, or numeric values that rise faster from left to right. metadata: category: Excel analysis version: 1.0.0 tags: excel, office-js, tables, trends, analysis

```

> [!IMPORTANT] > The value of the name property must exactly match the name of the of the child folder directly under the skills folder.

1. Below the frontmatter, add the following Markdown to focus Copilot to the purpose and resources of the skill. You create the two resource files in a latter step.

```md # Accelerating growth trend finder

Find rows in the first qualifying Excel table whose numeric values increase from left to right with increasingly larger increases.

## Reference resources

Before running the script, consult:

• resources/workbook-data-guardrails.md
• resources/excel-vs-agent-execution.md

Use these resources to confirm that the current workbook is the right source of truth, that the skill is running inside Excel, and that the user is asking for workbook analysis rather than general advice. ```

1. Below the resources, add the following workflow section. You create the JavaScript file that calls Office.js in a later step.

```md ## Workflow

1. Confirm that the current context is Excel.
2. Run scripts/find-accelerating-growth-trend-rows.js when the user asks to identify rows with an accelerating growth trend.

1. Below the workflow, add the following sections that give instructions about the output. Note that Copilot recognizes when the JavaScript has ended in an error state and it can compose and report its own error message, such as "No qualifying table was found." But in scenarios where you need Copilot to report the exact error message returned by the code, you can instruct it do so. The Copilot chat output section illustrates both strategies.

```md ## Workbook output

Let scripts/find-accelerating-growth-trend-rows.js create charts, but do not create new worksheets or formulas.

## Copilot chat output

1. For each chart that is created, report the table name and row that is the chart's source.
2. If there are no rows with an accelerating growth trend, report the problem. Use the exact error message that is returned by scripts/find-accelerating-growth-trend-rows.js. Do not reword it.
3. If there are any other problems, such as no qualifying tables, report the problem.

```

1. Below the output instructions, add the following guidance to Copilot.

```md ## Common pitfalls to avoid

• Do not inspect tables outside the first worksheet.
• Do not analyze a table unless it has at least 12 columns.
• Do not treat the header row as numeric data.
• Do not infer, coerce, or fill missing values.
• Do not run the Office.js script outside Excel.

```

Task 3: Add workbook data guardrails

1. In the skills/accelerating-growth-trend-finder/resources folder create a Markdown file named workbook-data-guardrails.md. The resource file keeps scenario-specific workbook assumptions out of SKILL.md, while still giving Copilot guardrails for when it invokes the script.
2. Give the file the following content.

```md # Workbook data guardrails

Use this reference before running the accelerating growth trend script.

## Data requirements

• Use only the first worksheet in the current workbook.
• Use the first table on that worksheet that has at least 12 columns.
• Ignore the table header row when checking whether the data is numeric.
• Require every table body cell to contain a finite number.
• Stop at the first table that satisfies the column-count and numeric-data requirements.

## Search rules

• Do not search other worksheets.
• Do not search loose ranges outside Excel tables.
• Do not rename sheets, tables, or headers.
• Do not create helper columns or formulas before running the script.

## Quality checks

• If no table qualifies, report that no qualifying table was found.
• If a table qualifies but no rows match, report that no rows in the qualifying table embody the trend.
• Treat blank cells, text, errors, booleans, and dates that aren't returned as numbers as nonnumeric data.
• If the user requests exponential trend data, report to the user that you will look for accelerating growth trend data, and that while all exponential trends are accelerating growth trends, the converse is not the case, so some of the trends you find may not be exponential.

```

Task 4: Add Excel execution guidance

1. In the skills/accelerating-growth-trend-finder/resources folder, create a Markdown file named excel-vs-agent-execution.md. The rules in this file are needed because the skill may be accessible in Copilot outside the context of Excel, in which case the Office.js APIs can't run. If the skill runs outside Excel, Copilot shouldn't pretend that it analyzed the workbook.
2. Give it the following content.

```md # Excel vs non-Excel execution guidance

## When the skill runs inside Excel

• Use the workbook as the source of truth.
• Follow the instructions in the Workflow, Workbook output, and Copilot chat output sections of the SKILL.md file.

## When the skill runs outside Excel

• Do not claim that workbook rows were analyzed.
• Explain that the skill can only be used in Copilot in Excel.
• Ask the user to open the workbook in Excel and invoke the skill there.

## When to use the scripts folder

• Run scripts/find-accelerating-growth-trend-rows.js only when the user asks to find table rows with accelerating, or increasingly larger left-to-right growth.
• Do not run the script for general explanations of accelerating growth growth.
• Do not run the script when the current environment cannot execute Excel Office.js APIs.

```

Task 5: Add the script that calls Office.js

1. In the skills/accelerating-growth-trend-finder/scripts folder, create a JavaScript file named find-accelerating-growth-trend-rows.js.
2. Give the file the following content. Note the following about this code.

• The script consists of the declaration of a single function and there isn't code that calls the function. Copilot understands that when the skill is invoked, it should call the function.
• The script doesn't call Office.onReady or define Office.initialize. Copilot creates the runtime, initializes Office.js, and executes skill scripts.
• The script is designed to search only the first worksheet. This is to ensure that the skill processes quickly.
• The script is designed to inspect only tables that meet certain conditions. This is to provide multiple error paths to illustrate different ways of handling errors.
• The script calls helper methods that you create in later steps: findFirstQualifyingTable, hasAcceleratingGrowthTrend, and createAndPositionChart.
• If the call of findFirstQualifyingTable returns null, then the script ends with a simple return; statement. Copilot will recognize the problem and compose its own error message.
• If no rows with accelerating growth are found, and so no charts are created, the script returns an explicit error message. The SKILL.md file instructs Copilot to use exactly this error message.
• The function is parameterless because the workbook itself supplies all input.

> [!NOTE] > The preview of Office.js-based skills doesn't support passing parameters to the functions that call Office.js. We're working hard to provide this support in the future.

```javascript await Excel.run(async (context) => { const firstWorksheet = context.workbook.worksheets.getFirst();

const tables = firstWorksheet.tables; tables.load("items"); await context.sync();

const tableInfo = await findFirstQualifyingTable(tables.items);

if (!tableInfo) { return; }

const { table: matchingTable, tableRange: matchingTableRange, dataRange: matchingDataRange } = tableInfo;

let createdCharts = [];