shiftcare-create-note

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