Blitz Report Excel Add-in Skills / Getting Started

Blitz Report Skill Author

br-skill-author

Write a new Blitz Report Excel skill or extend one of the shipped br-* skills: interview the user for the business question, discover the exact report names, parameters and list values live from the connected Oracle EBS instance, write a complete SKILL.md in the shipped format into a worksheet, and give the steps to install it in Copilot in Excel or Claude in Excel.

When to use

Use when the user asks for their own skill, wants to turn a prompt they repeat into a skill, wants other thresholds, their own reports or another output in an existing skill, or says 'make a skill for', 'customise the holds analysis', 'add our report to the skill'. Writes nothing to Oracle EBS.

Install

Download br-skill-author.zip

Claude in Excel: upload the zip under Customize > Skills > Create skill. Microsoft 365 Copilot in Excel: copy the skill folder into Documents/Copilot/Microsoft Excel/Skills in your OneDrive. Or install blitz-report-excel-addin-ai-skills in Claude Code and run /blitz-report-excel-addin-ai-skills:excel-skills-setup.

Requires Blitz Report and the Blitz Report Excel add-in, connected to your Oracle EBS instance.

View source on GitHub

Skill contents

SKILL.mdreferences/install-and-extend.mdreferences/skill-template.md

# Blitz Report Skill Author (br-skill-author)

> 🚨 **Blitz data = Excel worksheet UDFs, not MCP tools/connectors.** Extract data only by writing `=br_...()` into a cell (via `execute_office_js`) and reading the spill — **never** `tool_search` for `br_*`, **never** `refresh_mcp_connectors`, and never conclude "no Oracle EBS / Blitz connector is set up" (the Blitz Report add-in is an Excel add-in, not an MCP connector, so it never appears in the connector list — its absence there is expected). Load the extraction mechanism first: `read_skill("br-run-reports")`.

A skill is a folder named exactly as the `name` in its SKILL.md frontmatter; the frontmatter holds
the `name` and a `description`, the body holds the instructions. Copilot in Excel reads the folder
from the user's OneDrive skills folder, Claude in Excel from a zip of it uploaded to the user's
Claude account. The assistant picks a skill by its description, so the description decides whether
the skill fires at all. You cannot write files: you write the file text into a worksheet and the
user saves it.

**Requires:** br-run-reports (discovery mechanics). Read `references/skill-template.md` before
writing and `references/install-and-extend.md` before the hand-over.

## Step 1 — Interview (one message, only what is missing)
1. The question the skill answers, in the user's words, with two or three example prompts (they go
   into the description).
2. Module and responsibility; the inputs every run needs (organization, operating unit, ledger,
   period, date window) and which may default.
3. What comes back: a ranked list, a red/amber/green scorecard, a dashboard, a count; and the
   decision the user takes with it.
4. Thresholds and rules (days overdue, amount floors, categories to exclude). A value the user does
   not know becomes a labelled placeholder in CONFIG, never a silent guess.
5. Whether the skill should also change Oracle EBS data (release, update, create). If yes it is an
   action skill: it delegates every write to br-run-uploads and asks for confirmation twice.
Do not write anything before the answers are in.

## Step 2 — New skill, or extension of a shipped one
- A shipped br-* skill already covers the question (holds, close readiness, collections, stock
  levels, BOM, WIP, payments, duplicates) and the user wants other thresholds, their own reports,
  another output or a narrower scope: extend it. Ask the user to paste that skill's SKILL.md into a
  sheet named `skill_source` (column A, one line per row; Copilot users open it from the OneDrive
  skills folder, Claude users from the downloaded zip), or to describe the change. Keep the shipped
  structure and change only what was asked.
- Anything else: a new skill from the template.
- Names: lower-case words joined by hyphens, with the customer's own prefix instead of `br-`
  (`acme-ap-holds-3-months`). An extension gets a new name too: a folder named `br-*` is replaced
  when the shipped skills are updated, so edits inside it are lost. Folder name = frontmatter name.

## Step 3 — Discover the reports live (helper sheet `blitz_`; never activate it; delete it at the end)
Every report name, parameter name and fixed list value in the skill comes from the instance, never
from memory. The user's own reports sit in the same library and are found the same way.
- `=br_report_list_external("<words>")` lists candidates (`Type = U` rows are uploads, used only by
  the action section). Nothing found: match the full library as br-report-finder does.
- `=br_report_params_external("<Report Name>")` gives the exact parameter spellings, `Must Set?`,
  `Multiple` and `Has LOV`; the skill passes parameters with these spellings only.
- `=br_param_values_external("<Report Name>","<Parameter>")` gives the exact spelling of any value
  the skill hard-codes (a status, a period type, a hold type): write the `Value` column as shown.
- `=br_report_templates_external("<Report Name>")` when the skill needs a particular column set.
- `#BLITZ_NOT_CONNECTED`: ask the user to connect through the Blitz Report ribbon. `#SPILL!`: clear
  space and retry.
Do not run a report while authoring. Column names come from a short run only when the user asks
for it, with the narrowest parameters that still return rows.

## Step 4 — Write the SKILL.md
Fill `references/skill-template.md`. The generated text keeps these rules:
- Frontmatter `name` = folder name; `description` = what it does, the user's own trigger phrases,
  and `WRITES to Oracle EBS` only for an action skill.
- The data banner and the delegation sentences (extraction by br-run-reports, writes by
  br-run-uploads) verbatim from the template. The generated skill never calls the worksheet
  functions itself except through those two skills.
- A `Reports used` table with exact names and the parameters passed; the fallback search only on
  `#BLITZ_REPORT_NOT_FOUND`.
- CONFIG with every threshold and its status (confirmed by the user, or placeholder until confirmed);
  the summary sheet the skill writes shows the assumptions.
- A numbered pipeline, one workbook operation per step; analytics as Excel formulas (Copilot runs no
  scripts); named output sheets in tab order; a Validation section with the tie-out; a 'Talk in the
  user's language' section.
- An analysis skill never writes to Oracle EBS. An action skill: proposal, confirmation 1, fill and
  validate, confirmation 2, submit; never a write without both.
- No double quote character anywhere in the text (Excel wraps such a cell in quotes when it is
  copied, and the quotes land in the file): single quotes or backticks instead. No tab characters.
- SKILL.md under about 10 KB; longer detail goes to `references/<topic>.md`, named in the SKILL.md.

## Step 5 — Hand over
Add a sheet named after the skill and write the file text into column A from A1, one line of the
file per row, the column formatted as text, nothing else on the sheet. A second file (such as
`references/thresholds.md`) goes on its own sheet named `<skill-name> references thresholds`. Then
give the user the install steps from `references/install-and-extend.md` for their assistant, in
their words, and the first prompt to try. Copilot in Excel may show a Save skill card for the text once
it is complete: tell the user to save it there, which writes the folder into their skills folder and
lists the skill under Custom skills at once. Delete `blitz_`.

## Validation (before the hand-over)
- Every report, parameter and list value in the text appeared in a discovery spill of this session.
- Folder name equals the frontmatter name; the description contains the user's trigger phrases.
- No double quote characters, no tabs, no worksheet function names outside the fixed banner.
- No data from the instance in the text (the skill travels with the user's OneDrive): names of
  reports, parameters and settings only, never values from report rows.

## Talk in the user's language
'I will write the skill as a text sheet that you save as SKILL.md', 'the skill runs the AP Invoice
on Hold report and ranks the holds'. Never mention `blitz_`, the worksheet functions or the spill.

# Installing, testing and extending a skill

Give the user the part for their assistant, in their words.

## From the worksheet to a file
1. On the sheet named after the skill, select column A (click the column header), copy, paste into
   Notepad or VS Code, and check the first and last lines: a line starting or ending with a stray
   quote character means a double quote slipped into the text; remove it in the editor.
2. Save as `SKILL.md` with UTF-8 encoding inside a new folder named exactly like the skill
   (`acme-ap-holds-3-months`). A second file from a sheet named `<skill-name> references <topic>`
   is saved as `references/<topic>.md` inside that folder.

## Copilot in Excel
When the Copilot pane shows a Save skill card after the text is written, Save skill writes the folder
into the skills folder and the skill appears under Custom skills at once; the steps below are the manual
route.
1. Copilot pane > Settings (the three dots) > Manage plugins & skills > Custom skills > Open skills
   folder. This is `Documents/Copilot/Microsoft Excel/skills` in the OneDrive of the account that
   licenses Office.
2. Move the skill folder there and wait until OneDrive shows it synced.
3. Select Refresh in the Custom skills dialog. The skill appears under its name; switch it on, or
   name it in the prompt with `@<skill-name>`, which runs it even while it shows as off.
4. Where the Copilot pane offers the `@skill-builder` skill, the text can also be handed to it with
   'save this as a skill named <skill-name>' instead of steps 1 to 3.

## Claude in Excel
Claude in Excel uses the skills of the user's Claude account; the upload is done in Claude on the web,
not in the Excel pane.
1. Right-click the skill folder > Compress to ZIP file. The zip holds the folder itself at the top
   level (`<skill-name>/SKILL.md`), not the loose files.
2. claude.ai > Customize > Skills > + > Create skill > Upload a skill, and choose the zip. Check that
   its switch is on. `br-analytics-standards` and `br-run-reports` must be uploaded too, once.
3. Skills need code execution: Settings > Capabilities > Code execution and file creation; on a Team
   or Enterprise plan the owner turns it on for the organization.
4. In the Claude pane in Excel, type / to see the skill, or ask the first example prompt.

## First run and what to fix
Open a new workbook, connect the Blitz Report add-in to the environment with the responsibility the
skill needs, and ask the first example prompt from the description.
- The skill did not fire: name it (`@<skill-name> ...` in Copilot, `/` in the Claude pane), then
  sharpen the description with the words the user actually used.
- A report was not found: the name in the `Reports used` table differs from the library; copy the
  exact name from the add-in's report list.
- A parameter was rejected: its spelling differs from the run screen; copy it from the parameter
  list of the report.
- Zero rows: the responsibility has no access to the organization, operating unit or ledger, or a
  date parameter defaulted to today; set the input explicitly or switch responsibility.
- The summary does not tie: a column header in a formula is not the header on the raw sheet.
Every fix is an edit of SKILL.md followed by Refresh (Copilot), or for Claude by deleting the skill
under Customize > Skills (the ... menu next to its switch) and uploading the new zip.

## Extending a shipped br-* skill
1. Copy the shipped folder to a new name with the customer's prefix and change `name` in the
   frontmatter to match; the shipped folder stays as delivered and is replaced by later updates.
2. Safe to change: `description` (add the user's phrases), the `Reports used` table (the customer's
   own report in place of the shipped one, keeping the columns the pipeline reads, or named in the
   pipeline where they differ), every value under `CONFIG`, output sheet names and order, the
   narrative, the scope (a date window, an organization, a category).
3. Keep as they are: the data banner, the division of responsibility, the delegation to
   br-run-reports, and for action skills the two confirmations and the single column the skill
   writes.
4. The user's own report must carry the parameters the pipeline passes and the columns it reads;
   check both with the report's parameter list and a short run before changing the table.

## Sharing with colleagues
Copilot reads each user's own OneDrive skills folder: copy the folder to each colleague's skills
folder, or distribute it as the Microsoft 365 administrator does for the organization. For Claude
in Excel each user uploads the zip once, or the owner of a Team or Enterprise plan provisions it
for everyone: Organization settings > Plugins & skills > Add > Upload a skill. Keep one copy of the
folder as the master and send the whole folder, never a SKILL.md alone, when it has a `references`
folder.

# Template for a generated skill

Copy this file text, replace every `<...>`, delete the lines that do not apply (marked *optional*
or *action skills only*). Keep the fixed sentences unchanged: they are what makes the skill run the
same way on Claude in Excel and Copilot in Excel. Use single quotes or backticks, never a double
quote character, in the generated text.

```
---
name: <skill-name>
description: >
  <What it does, in Oracle EBS terms, one sentence>. Use when the user asks '<prompt 1>',
  '<prompt 2>', or <trigger phrases in their words>. <Writes nothing to Oracle EBS. |
  WRITES to Oracle EBS after two confirmations.>
---

# <Title> (<skill-name>)

> 🚨 **Blitz data = Excel worksheet UDFs, not MCP tools/connectors.** Extract data only by writing `=br_...()` into a cell (via `execute_office_js`) and reading the spill — **never** `tool_search` for `br_*`, **never** `refresh_mcp_connectors`, and never conclude 'no Oracle EBS / Blitz connector is set up' (the Blitz Report add-in is an Excel add-in, not an MCP connector, so it never appears in the connector list — its absence there is expected). Load the extraction mechanism first: `read_skill('br-run-reports')`.

> **Performance:** read `br-analytics-standards` at the start of every run. Every pipeline step
> follows those rules: one workbook operation per step, no mid-pipeline verification reads.

<One paragraph: what the skill produces and the decision it supports. Who does what: you own
scoring and the verdict; br-run-reports does extraction<; br-data-dashboard the build>.>

**Requires:** br-run-reports<, br-data-dashboard><, br-run-uploads>.

## Division of responsibility — READ FIRST
**You do NOT run Blitz reports yourself.** All extraction is done by **br-run-reports** (it owns
connection, responsibility, the run and the completion check). Never call `br_*` functions, and
never read or rename the result sheet until the extraction is confirmed complete.
<This skill is read-and-recommend only: it never changes Oracle EBS data. | This skill changes
Oracle EBS data only through **br-run-uploads**, only on the confirmed rows, and only after the
two confirmations below.>

## When to use
'<prompt 1>', '<prompt 2>', <trigger phrases>. For <a neighbouring need> use <other skill> instead.

## Inputs
- **<Input>** (required) — ask if not supplied.
- **<Input>** — default <value>; say so and let the user change it.
- *Optional:* <input>, <input>.

## Reports used (authoritative names — do NOT broad-search for them)
Pass the documented name directly; search only on `#BLITZ_REPORT_NOT_FOUND`.

| Report (exact name) | Run with | Notes |
|---|---|---|
| `<Report Name>` | `<Parameter>=<value>; <Parameter>=<value>` | <its role: the driver, the evidence, the cross-check> |
| `<Report Name>` *(optional)* | `<Parameter>=<value>` | <when to run it> |

Dates are passed as `YYYY-MM-DD`; a parameter whose desired value is the default is omitted (a
comma in a value splits it into several values).

## CONFIG
### Classes
| Condition (report, column) | Class | Recommendation |
|---|---|---|
| <condition> | **<Class>** | <what the user does about it> |

### Defaults (edit to the customer)
- <threshold> = <value> (<confirmed by the user | placeholder until the customer confirms>).
- <threshold> = <value> (...).
The summary sheet shows these values under 'Assumptions'.

### Output sheets & tab order (left to right)
`<Summary>` (first), `<Detail>`, [`<Optional>`], raw report sheets last.

## Pipeline
1. **Extract — DELEGATE.** br-run-reports runs `<Report Name>` with <parameters> → sheet
   `<name>`; then `<Report Name>` → `<name>`. Wait for each completion; do nothing mid-run.
2. **Anchor.** Record <row count and the total of <amount column>> from the raw sheet.
3. **Classify *(single workbook operation)*.** <The formulas or logic, by column header name, never
   by column position>. Write `<Detail>` in one write: <columns>.
4. **Summary *(single workbook operation)*.** On a new sheet at position 0: <banner with the
   verdict>, <KPI block>, <ranked list>, 'Assumptions' block from CONFIG. Charts in a second
   operation at most.
5. **Narrative.** At most five bullets: overall call, biggest item, recommended next action.
6. **Validation read.** The one permitted re-read: the summary's count and total equal the anchor.

## Validation
- `<Summary>` count and total tie to `<Detail>` and to the anchor.
- <Class> only when <condition>; <verdict colour> only when <condition>.

## Degradation rules
- `<Report Name>` returns no rows → <say so and stop | fall back to `<Report Name>` and say so>.
- A required input is missing → ask; never guess an organization, ledger or period.
- The user declines an optional stage → the sheets so far are the deliverable; never nag.

## Talk in the user's language
Say '<the business action>' and name reports by their names; never name worksheet functions, the
helper sheet or trigger cells.

## Action step (action skills only)
7. **Propose → confirmation 1.** List the rows to change with count, amounts and <key field>;
   ask 'Fill the <Upload Name> grid for these <n> rows (<amount>)?'. Nothing is written yet.
8. **Fill and validate.** br-run-uploads downloads `<Upload Name>` for <scope>, writes only
   `<column>` on the confirmed rows, validates, and shows the validation results.
9. **Confirmation 2 → submit.** Ask 'Submit <n> validated rows (<amount>) to Oracle EBS now?'.
   Only 'yes' to this question submits. Report the per-row results afterwards.
Untouched rows are inert. Never mix two uploads in one confirmation.
```

## Filling guidance
- The description is the trigger: put the user's own words in it. 'Use when the user asks' followed
  by two or three prompts beats a generic sentence.
- One report per role: a driver (the rows to judge), evidence (why), a cross-check (ties the
  total). More reports make the run slower, not better.
- A CONFIG value the user gave is 'confirmed by the user'; one you chose is a placeholder, named
  as such in the skill and on the summary sheet.
- Formulas, not code: Copilot in Excel runs no scripts, so classification is FILTER, SORTBY,
  SUMIFS, XLOOKUP and LET over the raw sheet, written by column header name.
- A sheet layout where cells sharing a format sit next to each other, one write per block.