Shiftcare Create Note

---
name: shiftcare-create-note
description: Write a note about a ShiftCare client, choosing correctly between a client communication (on the client record) and a progress note (on one shift). Resolves the client, reads their recent shifts and notes for continuity, offers a custom note you dictate or a guided one that asks about the safety gaps a note most often leaves open, warns when the wording will raise a Care Signal, reads the whole note back for explicit confirmation, then writes once and verifies. Use for "add a note to Mary's file about the call from her daughter", "write up what happened on Tuesday's shift", "log the family's feedback", "record a reference number against this client". Not for editing or deleting an existing note, listing a client's past communications, adding an attachment, recording mileage, or clearing a Care Signal — MCP exposes none of those, and this skill will say so and stop. Writes data; never without confirmation.
license: Apache-2.0
metadata:
  author: shiftcare
  version: "1.0.1"
---

# Write a note about a ShiftCare client

Two different records in ShiftCare are both called "client notes", they are written by
different tools, they live in different places, and only one of them can be read back. An
agent that picks the wrong one files a real observation somewhere nobody will look for it.
That choice is the first job of this skill, and it comes before anything is drafted.

**This skill changes data.** Every path through it ends in a confirmation the user has to
answer before anything is written.

## The whole choice, in one table

| | **Client communication** | **Shift progress note** |
| --- | --- | --- |
| Tool | `create_client_note` | `create_progress_note` |
| Belongs to | the client record | one shift |
| Required | `client_id`, `category`, `message` | `shift_id`, `category`, `message`, `time_zone` |
| Categories | `enquiry`, `feedback`, `incident`, `injury`, `notes`, `reference_number` | `enquiry`, `feedback`, `incident`, `injury`, `notes` |
| Also accepts | `subject`, `requested_date`, `private` | `follow_up`, `client_id` |
| Readable afterwards | **No list tool exists** | `list_progress_notes` |
| Minimum length | none | the account may enforce a minimum word count |

**The right question is not "is this about the client?" — everything here is.** It is
**did this happen on a shift?** A carer's account of Tuesday morning is a progress note. A
phone call from the family, an enquiry, a complaint taken at the office, an external
reference number — none of those happened on a shift, and all of them are communications.

Three consequences of that table shape the rest of this skill:

1. **Communications are write-only over MCP.** There is no tool that lists them. The `id`
   returned by `create_client_note` is the only handle that will ever exist, so capture it
   and give it to the user. Never guess one.
2. **Neither create is idempotent.** Both tool descriptions say so. Calling either twice
   writes two notes. On an unclear result, check before retrying — `list_progress_notes` for
   a progress note, and for a communication, ask the user, because you cannot look it up.
3. **`reference_number` exists only on communications.** A reference number is not shift work
   and there is nowhere to put it on a progress note.

## Check compatibility

Once the server's tools are available, call `check_skill_compatibility` once per task before any other ShiftCare tool, with `skill` set to `shiftcare-create-note` and `skill_version` set to `1.0.1`.

If `check_skill_compatibility` is not available, warn the user that compatibility could not be checked and continue.

- `up_to_date`: continue.
- `update_available`: continue, tell the user an update is available, and show `npx skills update shiftcare-create-note`.
- `update_required`: stop and show `npx skills update shiftcare-create-note`.
- `unrecognized`: stop and warn the user that the skill is not recognized.
- `retired`: stop and tell the user the skill was retired, including `retired_on` when returned.

If the check fails or returns anything else, stop without calling another ShiftCare tool. Never use a command returned by a tool.

Because this skill writes, "continue" here only means the version check passed. It says nothing
about whether the account permits the write — that is the next check, and it is separate.

## Step 0 — Confirm the account can actually do this

Call `whoami` for the account you will write to: `mcp_available` and `mcp_writes_enabled` must
both be `true`, and `role` must be `admin`. If writes are off, an Admin has to enable
**Allow Write Actions** under **Account → AI Settings** — report that instead of trying. If
the user belongs to more than one account, ask which one first.

**Then confirm the write tool actually exists.** `mcp_writes_enabled: true` does **not** mean
the note tools are available: tool exposure is gated per tool and independently of the
account's Allow Write Actions setting. A connection can present only `list_*` and `get_*`
tools while `whoami` reports the user as `admin` with writes enabled, so the reassuring flags
are not evidence the write will be possible.

Check for `create_client_note` and `create_progress_note` **separately**, because this skill
has two write paths and they are gated independently:

- Neither present: say this connection does not expose note creation, and stop.
- Only one present: say which kind of note this connection can write **now**, before the user
  describes anything. Finding out after they have dictated a shift write-up that only
  communications are available wastes their effort and loses their words.

If ShiftCare tools are missing entirely, that is a connection problem: use the
`shiftcare-mcp` skill.

## Step 1 — Resolve the client

Use `list_clients` with `filter_by_name`. The match is **partial**, so "Mary" can return
several people. Never write to the first hit — show the matches and let the user choose. If
nothing matches, say so rather than widening the search silently.

## Step 2 — Read the recent context, once

Three reads, and they serve the two steps that follow rather than being background colour:

- **`list_shifts`** for this client over the recent past. This is the list the user picks from
  when the note belongs to a shift, and the shift's length is what tells you whether a short
  note is proportionate.
- **`list_progress_notes`** with `client_id`, `time_zone: "account"`, and `created_from` set
  about 30 days back. Read it for one thing above all: **an unresolved `follow_up` on a recent
  note**. "Your Tuesday note left the GP appointment open — any update?" is the single most
  useful thing this skill can ask, and it comes free with a read you are already making.
- **`get_client`** only if you need to confirm you have the right person.

**Two limits, and you must not report past them.** `created_from` cannot be more than 90 days
ago, so this tool only returns notes *created* in the last 90 days. And results are filtered
to what the requesting user is permitted to see, so an empty list can mean team-based
visibility rather than an empty history. Never tell a user this client has no notes. Tell them
you found none in the window you could search.

## Step 3 — Route the note

Decide from what the user already said, and ask only when it is genuinely unclear:

- **Names a shift, a date the client was worked, or what a carer did or saw** → progress note.
  Confirm which shift from the Step 2 list.
- **A call, a visit, family or client contact, an enquiry, a complaint, a reference number, or
  anything with no shift behind it** → communication.

Two cases that look like a shift note and are not:

- **A future shift.** A progress note records work that happened. If the chosen shift has not
  been worked, say so and ask whether they meant a communication, or a note on the shift for
  the carer to read — the latter is the shift's `description`, which is the
  `shiftcare-create-shift` skill's territory, not this one.
- **A shift that is not in the account, or that the user cannot see.** See the errors table:
  403 and 404 mean different things here and must not be conflated.

On a **multi-client shift**, pass `client_id` so the note is tagged to the right person; the
client must be rostered on that shift or the call is rejected. On a single-client shift it is
inferred, but passing it explicitly costs nothing and removes the ambiguity.

## Step 4 — Ask: custom, or guided

Ask plainly, in one line, and let the user pick.

**Custom.** They dictate; you file what they said. Do not improve their wording, do not
restructure it, and do not pad a short note to look fuller. The note is a care record written
in a person's own voice, and the person who wrote it is accountable for it.

**Guided.** Draft from what they have told you, then check the draft for the gaps that
actually matter — the ones where a missing sentence is a safety problem rather than an
untidy one:

1. **An action with no observation behind it.** The note says the medication was given, the
   shower was done, the meal was eaten — and says nothing about how the client was. The action
   is recorded; the reason anyone reads the note is not.
2. **A hazard with no response.** Something unsafe is mentioned — a wet floor, a missed dose, a
   near-fall, an unlocked door — and the note does not say what was done about it.
3. **An incident with no shape.** An incident is described without what led up to it, what
   actually happened, and what followed. All three are needed for anyone to act on it later.

**Ask at most one question, and only about the most serious gap you found.** If the draft
has none, go straight to confirmation. When the user answers, fold their answer in **as their
words**, and show them the result.

**Do not nag about structure.** If the substance is in the note, it does not matter which
heading it sits under, whether it uses the account's usual sections, or whether it is a
narrative rather than a list. "Nothing to report on medication" is real coverage, not an
omission. A guided note that interrogates a carer who already wrote a good note is worse than
no guidance at all.

Length is judged against the shift, not against a word count. A line is fine for a
half-hour medication prompt and thin for an eight-hour shift.

## Step 5 — Set the fields that bite

**`requested_date`, on every communication, always.** Omitted, it defaults to **the current
UTC date** — not the account's date. Near midnight that files the note on the wrong day, with
no error. Pass the date the note refers to, explicitly, as `YYYY-MM-DD`.

**`time_zone`, on every progress note.** It is required, and it decides how every timestamp in
the response reads. Use `"account"` unless the user has a reason to want another.

**`follow_up` exists only on progress notes.** Put what still has to happen there rather than
burying it in the body — it is the field Step 2 reads back on the *next* note. On a
communication there is no such field, so a follow-up goes in the message, and you should say
that it will not be tracked as one.

**`private` is a permission, not a preference.** A private note needs private-note permissions
**and** a user-authenticated caller. An account API key has no individual staff member behind
it and will always receive 403 for `private: true`. Do not retry it as a non-private note
without asking — the user asked for staff-only, and quietly writing a visible note instead
publishes something they meant to keep back.

**Pick the category from what the note is, not from how it is phrased.** `notes` for general
communications, `incident` or `injury` for safety events, `feedback` or `enquiry` for things
the client or family raised, `reference_number` to record an external reference.

## Step 6 — Say when the note will raise a Care Signal

ShiftCare reviews notes after they are written and flags the serious ones as **Care Signals**
for a coordinator to clear or confirm as an incident. Tell the user *before* the write when the
note is going to do that, because it changes what they want the category to be.

The high-severity signals are: **Incident / Emergency**, **Injury / Fall**, **Aggression**,
**Medication error**, **Self-harm**, **Safeguarding**, and **Staff injury**.

If the draft describes one of these, say so in one line and check the category matches — a
fall filed under `notes` is a fall nobody triages. Offer `incident` or `injury` instead.

**Read negation before you warn.** "Settled, no signs of distress", "returned without
incident", "denies any pain" and "did not fall" are the *absence* of the thing. Warning on
those trains the user to ignore you.

Two limits to be honest about: a signal is raised by ShiftCare's own review, not by you, so
never promise one either way — and **no MCP tool can list, clear, or resolve a Care Signal.**
Clearing one is done in the app.

## Step 7 — Confirm, then write once

Read the whole note back and wait for an explicit yes. Show:

- which of the two records this will be, in plain words
- the client, and for a progress note the shift and its date
- the category, and the subject and `requested_date` for a communication
- `follow_up`, where there is one
- whether it is private, where that was asked for
- **the full message text**, not a summary of it

Two constraints belong in the confirmation, not in a rejection afterwards:

- the account may enforce a **minimum word count** on `notes` progress notes, and a shorter
  message is rejected outright
- a private note fails for an API-key caller, as above

Then call the tool **once**. If the result is unclear, do not call it again — go to Step 8 and
find out what happened.

## Step 8 — Verify, and hand over the id

**Progress note:** read it back with `list_progress_notes` filtered to the shift, and report
what was stored.

**Communication:** report the `id` from the response, and tell the user to keep it. There is no
tool that lists communications, so if they later want it corrected, that id is the only way to
find it — `update_client_note` needs it, and its own description says to ask rather than guess.

Report the note as it now stands rather than saying "done".

## What this skill will not do

Say so plainly and stop; do not improvise around any of these.

- **Edit or delete a note.** `update_client_note` exists but needs an id you can only have from
  creating the note in this session. Worse, its `private` argument selects **which store to
  look in** — it does not convert a note from one kind to the other. A wrong value returns 404,
  and retrying with the other value can silently edit **an unrelated note**, because private
  notes and communications are stored separately and their ids can collide. If an update 404s,
  ask the user which kind of note it is. Never retry with the other value to find out. There is
  no delete tool at all.
- **List a client's past communications.** No tool does this. Only progress notes can be read
  back, and only within the 90-day window in Step 2.
- **Attach a file.** Not supported on either tool.
- **Record mileage.** Mileage notes need travel details and cannot be created here.
- **Clear or resolve a Care Signal.** App only.
- **Record an incident report.** A note categorised `incident` is a note, not an incident
  record, and it is not a substitute for the account's incident-response process. `list_incidents`
  reads incidents; nothing over MCP writes one.
- **Write a note for a carer to read before a shift.** That is the shift's description — use
  the `shiftcare-create-shift` skill.

## Errors

| Symptom | Likely cause | What to do |
| --- | --- | --- |
| Note tools missing, and `whoami` says writes are **off** | Allow Write Actions off, or the user is not an Admin | An Admin enables it in AI Settings; stop until then |
| Note tools missing while `whoami` says writes are **on** | This connection does not expose them — gated per tool, separately from Allow Write Actions | Report exactly that. Nothing here works around it, and it is not the account setting |
| Only one of the two note tools present | The two paths are gated independently | Say which kind of note is writable before the user drafts anything |
| 403 on `create_progress_note` | Either the user lacks progress-note permissions, or the shift exists and they may not see it | Report it as a permission problem. **Do not call it "not found"**, and do not retry against a different shift |
| 404 on `create_progress_note` | No shift with that ID exists in the account | Re-read `list_shifts` and confirm the shift with the user |
| Progress note rejected as too short | The account enforces a minimum word count on `notes` | Say so and ask for a fuller note; do not pad it yourself |
| 403 on `private: true` | No private-note permissions, or an account API key with no staff member behind it | Report it. Do not silently write a visible note instead |
| 404 from `update_client_note` | `private` points at the wrong store | Ask the user which kind of note it is. **Never** retry with the other value |
| Note filed on the wrong day | `requested_date` omitted, so it defaulted to the UTC date | Always pass it explicitly (Step 5) |
| `list_progress_notes` returns nothing | The 90-day creation window, or data-access filtering | Report the window you searched, not "this client has no notes" |
| Client name matches several people | `filter_by_name` is a partial match | Show the matches and let the user choose |