ciao-upkeep
Skill11 starsChanged 10 days agoApache-2.0View on GitHub
Keep Ciaobot current between releases — check every dependency and pin we install (Python, npm, the gws CLI, GitHub Actions, the Node floor, Playwright), keep the stock skill catalog, ciao-capabilities and the marketing site in sync with the code, sweep doc rot, and maintain the watchlist in docs/UPKEEP.md. Trigger on "keep ciao up to date", "check dependencies", "any updates", "check the site", "watchlist", "upkeep", or after a feature ships that adds a user-facing capability.
In this repository63 other files it gives its agents.
- AGENTS.mdAGENTS.md
- ciao-dev-installSkill
- ciao-release-notesSkill
- ciao-releaseSkill
- gws-sharedSkill
- gws-workflow-email-to-taskSkill
- gws-workflow-file-announceSkill
- gws-workflow-meeting-prepSkill
- gws-workflowSkill
- gws-workflow-standup-reportSkill
- gws-workflow-weekly-digestSkill
- persona-content-creatorSkill
- persona-customer-supportSkill
- persona-event-coordinatorSkill
- persona-exec-assistantSkill
- persona-hr-coordinatorSkill
- persona-it-adminSkill
- persona-project-managerSkill
- persona-researcherSkill
- persona-sales-opsSkill
- persona-team-leadSkill
- prSkill
- recipe-backup-sheet-as-csvSkill
- recipe-batch-invite-to-eventSkill
- recipe-block-focus-timeSkill
- recipe-bulk-download-folderSkill
- recipe-collect-form-responsesSkill
- recipe-compare-sheet-tabsSkill
- recipe-copy-sheet-for-new-monthSkill
- recipe-create-classroom-courseSkill
- recipe-create-doc-from-templateSkill
- recipe-create-events-from-sheetSkill
- recipe-create-expense-trackerSkill
- recipe-create-feedback-formSkill
- recipe-create-gmail-filterSkill
- recipe-create-meet-spaceSkill
- recipe-create-presentationSkill
- recipe-create-shared-driveSkill
- recipe-create-task-listSkill
- recipe-create-vacation-responderSkill
- recipe-draft-email-from-docSkill
- recipe-email-drive-linkSkill
- recipe-find-free-timeSkill
- recipe-find-large-filesSkill
- recipe-forward-labeled-emailsSkill
- recipe-generate-report-from-sheetSkill
- recipe-label-and-archive-emailsSkill
- recipe-log-deal-updateSkill
- recipe-organize-drive-folderSkill
- recipe-plan-weekly-scheduleSkill
- recipe-post-mortem-setupSkill
- recipe-reschedule-meetingSkill
- recipe-review-meet-participantsSkill
- recipe-review-overdue-tasksSkill
- recipe-save-email-attachmentsSkill
- recipe-save-email-to-docSkill
- recipe-schedule-recurring-eventSkill
- recipe-send-team-announcementSkill
- recipe-share-doc-and-notifySkill
- recipe-share-event-materialsSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 31
Read it before starting. Then pick the section below, run the check, and update the Last checked column for what you actually looked at.
- Distinctive: line 259
Every check ends the same way: what you looked at, what changed, and what you filed — with the issue number.
- Very specific: line 269
check_available_updatesfails open: Every network call is wrapped in except Exception: pass, and release.py prints "Dependency update …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ciaobot upkeep
Contributor/project skill — lives in the repo's workspace
skills/folder, notciao/stock/skills/. It is for people working on Ciaobot and is deliberately not packaged or shipped to end-user installs.ciao sync-skillsmirrors it into the runtime-discovered.claude/skills/catalog. Don't move it intociao/stock/.
The standing checks that keep the repo honest between releases. The release
skill (/ciao-release) deliberately does none of this — it cuts, it verifies,
it ships, and it does not fix. Anything upkeep finds becomes a commit on
develop, reviewed on its own PR.
Two things to keep straight:
- Check — compare, report, file. Cheap, safe, repeatable.
- Adopt — change a pin, fix a doc, edit the site. A normal PR against
develop, with the gates. Never bundled into a release.
Everything here runs in the main checkout on a branch. No worktree.
0. The watchlist first
docs/UPKEEP.md is the working document: topics we keep an eye on over time,
with the last-checked date and the decision. It is edited during ordinary
work, not swept periodically — the moment you notice a topic worth watching,
add a row. AGENTS.md points at it so any agent working in this repo knows it
exists.
Read it before starting. Then pick the section below, run the check, and update
the Last checked column for what you actually looked at. A stale date on a
row you did not check is worse than no date.
1. Dependencies — everything we install
ciao/dependency_updates.py::check_available_updates reports updates for
two files only: pyproject.toml and web/package.json. It is correct for
what it covers, and it covers less than we install. AUTO_UPDATE_KEYS is
("claude-agent-sdk",), so --apply during a release bumps exactly one
package; everything else is report-only. Treat its output as one section of
this one.
env -u PYTHONPATH .venv/bin/python -c "
import pathlib
from ciao.dependency_updates import check_available_updates
for u in check_available_updates(pathlib.Path('$(pwd)')):
flags = ('auto' if u.auto else 'manual', 'safe' if u.is_safe else 'major')
print(f'{u.key:28} {u.ecosystem:7} {u.current:12} -> {u.latest:12} {\" \".join(flags)}')"The full inventory — what is pinned where, and what the checker misses:
| Thing | Pinned in | Covered? |
Python deps (incl. firecrawl-anydoc>=0.2.4,<0.3.0) | pyproject.toml | yes — reported only |
| Frontend deps | web/package.json | yes — reported only |
gws CLI | generated, not pinned by hand — see below | drift reported, updates manual |
| AnyDoc | rides the pyproject.toml pin | yes |
| GitHub Actions | .github/workflows/*.yml | no |
| Node floor | .nvmrc and web/scripts/check-node.mjs | no |
| Playwright | web/ | no |
The unchecked ones need their own check:
# gws: nothing to bump by hand — see the note below
npm view @googleworkspace/cli version 2>/dev/null || echo "check github.com/googleworkspace/cli"
gws --version
grep -m1 'version:' ciao/stock/skills/gws-shared/SKILL.md
# Actions
grep -rhoE 'uses: [^ ]+@v[0-9]+' .github/workflows | sort -uThe Node floor is a paired edit and the failure is silent. .nvmrc and
SUPPORTED_RANGE in web/scripts/check-node.mjs must move together. Below the
range, every jsdom-environment vitest file fails to start its worker — and
vitest still prints Test Files N passed for the files that did run. A green
suite that skipped a third of itself. When raising the floor, change both in
one commit and re-run cd web && npm test on the new version.
Adopting an update is a normal PR, not a release step. Bump it on a branch,
run the gates (mypy ciao, pytest -n auto tests/, npm test, npm run
build), and let the release carry it later. Never blanket-upgrade majors.
gws: never hand-edit the version
The gws-* skills are generated, and so is the version. gws
generate-skills writes metadata: version: into gws-shared/SKILL.md itself,
and gws-shared is one of the shipped skills, so regenerating advances the pin
automatically. Upgrading the local gws CLI is the only input; there is
nothing to hand-maintain.
So the procedure is: upgrade the CLI, then regenerate. Do not edit
metadata.version by hand — a hand-bumped pin is either overwritten by the
next regeneration or, worse, records a version the skills were never generated
from, which is the exact drift the pin exists to prevent.
# 1. the input: upgrade the CLI, then confirm it
gws --version
# 2. dry run — reports which skills would change, writes nothing
env -u PYTHONPATH .venv/bin/python -c "
from pathlib import Path
from ciao.gws_skills import regenerate_stock_gws_skills
r = regenerate_stock_gws_skills(Path('$(pwd)/ciao/stock/skills'), write=False)
print('would update:', r.updated)
print('missing:', r.missing)"
# 3. then write
env -u PYTHONPATH .venv/bin/python -c "
from pathlib import Path
from ciao.gws_skills import regenerate_stock_gws_skills
r = regenerate_stock_gws_skills(Path('$(pwd)/ciao/stock/skills'), write=True)
print('updated:', r.updated)
print('missing:', r.missing)"missing is the output that matters: a skill the CLI no longer generates is
reported and left untouched, so the repo keeps shipping a skill for a
command that may no longer exist. That is a decision, not a warning to wave
through — either drop the skill in the same PR or record why it stays.
The invariant, and the check after regenerating:
env -u PYTHONPATH .venv/bin/python -c "
from pathlib import Path
from ciao.gws_skills import installed_gws_version, pinned_gws_version
d = Path('$(pwd)/ciao/stock/skills')
i, p = installed_gws_version(), pinned_gws_version(d)
print('installed', i, 'pinned', p, 'OK' if i == p else 'DRIFT')"This also happens at release time. ciao/release.py:600
(_refresh_stock_gws_skills) regenerates unconditionally during --apply and
stages whatever changed, so a gws upgrade that lands before a cut is picked up
and gated by the release instead. That is a legitimate path, and the safer one,
because the full check suite runs over it. Do it as its own PR anyway when you
want a small reviewable diff rather than a regeneration folded into a release
commit.
ciao release reports the drift as Stock gws skills: gws CLI X != pinned Y
and treats a missing CLI as a skip, not a failure.
2. Stock skills ↔ capabilities ↔ the marketing site
Three places describe the same product to three different audiences, and
nothing enforces that they agree. The sync tests cover ciao/ modules
(test_architecture_doc.py), CIAO_* env vars
(test_env_vars_documented.py) and API routes (test_pwa_api_docs.py). They
cover none of these three surfaces.
Stock skills — ciao/stock/skills/. A new bundled skill that nobody adds
to the catalog is invisible to the two audiences that matter:
ls ciao/stock/skills/ | grep -v '^gws-'For each one, check it appears in:
ciao/stock/skills/ciao-capabilities/— the feature goes in the matching file underreferences/(the area table inSKILL.mdsays which: workspaces and chats, memory, automations, files, models and extensions, tasks, install and settings), and a new area gets a row in that table. Keep theSKILL.mdindex under 10 KB and its frontmatterdescriptionunder 1,024 characters (tests/test_stock_frontmatter.pyenforces both); add trigger keywords only for questions about the feature, not for actions another skill performs. A feature that is described but not triggerable does not get found.site/builtin.html— the stock table, with a link to itsSKILL.md. Verify the links resolve rather than assuming:
And the reverse: a stock skill nobody links from the site.git grep -oh "stock/skills/[a-z0-9-]*/SKILL.md" -- site/ \ | sed 's|stock/skills/||; s|/SKILL.md||' | sort -u \ | while read -r s; do [ -f "ciao/stock/skills/$s/SKILL.md" ] && echo "OK $s" || echo "DEAD $s" doneciao/stock/skills/ciao-cli/commands.jsonmust map to theOPERATIONStable inciao/mcp_server.pyand agree withdocs/AGENT_CLI.md. Run bothtest_every_documented_command_parsesandtest_every_agent_command_is_in_the_telemetry_tableintests/test_agent_surface.py; together they check command/parser and parser/catalog consistency.
Capabilities — for a user-facing feature, ciao-capabilities is the answer
to "can you…?". After any feature that adds one: add the entry to the right
references/ file, add the trigger words to the SKILL.md description, and skim the changelog since the last tag for features that
shipped without one.
3. The marketing site
site/ contains hand-written HTML pages, published by
.github/workflows/pages.yml on any push to main that touches site/**. So a
wrong claim goes live the moment it merges, and workflow_dispatch means a fix
does not need a release.
It has no tests. Nothing compares it to the code it describes. That is the whole argument for checking it.
For each release's removals and renames, sweep it:
git diff <last-tag>..develop --stat
# for each removed route, env var, page, setting, subagent or skill:
git grep -n -iE "<identifier>" -- site/This range is the worked example. It removed GET /api/automation, the
/api/menubar-notifications feed, the push_all_devices and trusted_url
settings, the Settings → Notifications and → Automations tabs, three stock
subagents and three stock skills. site/features.html still has a full
Automations section with a screenshot. It happens to be correct —
/automations survives as a redirect to /schedules (web/src/router.ts) —
but nothing but a human checking knew that, and the same section is one rename
away from being wrong. Sweep, then confirm rather than assume.
Also worth a look each pass: site/builtin.html's skill and subagent copy
against what ciao/stock/skills/ actually ships, and the feature descriptions
against the current Settings tabs. Screenshots in site/assets/img/ are the slow rot —
an image of a UI that no longer exists, with the alt text still describing it.
4. Doc rot
The sync tests prove structure, not truth — a paragraph describing a removed
engine, a renamed env var or a deleted page passes them. v0.8.0 shipped both:
PWA_API.md still documented a cloud transcription engine four releases after
its removal, and INTEGRATIONS.md still claimed a policy two releases after it
was dropped.
env -u PYTHONPATH .venv/bin/python -m pytest \
tests/test_architecture_doc.py tests/test_env_vars_documented.py tests/test_pwa_api_docs.pyThen, for identifiers the range removed, sweep by hand across README.md,
INTEGRATIONS.md, PWA_API.md, docs/, DESIGN.md and site/.
5. Advisories and triage
pip-audit, npm audit and npm run lint are || true in ci.yml — advisory
by design, so a release is not held hostage by a transitive CVE. But advisory
means someone reads them, and today nobody does. Run them, and file an issue
for anything high/critical that has a fix.
Triage, on the same pass: gh issue list --state open and
gh pr list --state open. Close what is fixed or dead, label what is not
([Bug] → bug, [Feature] → enhancement, per ciao-support), and surface
the rest. A stale open-issue list is how a two-year-old report gets rediscovered
as new.
Reporting
Every check ends the same way: what you looked at, what changed, and what you
filed — with the issue number. Update docs/UPKEEP.md's Last checked column
in the same commit as whatever else you changed, so the document never claims
coverage it does not have.
Traps
- A green
npm testproves nothing about the Node floor. Below^20.19 || ^22.13 || >=24, vitest printsTest Files N passedfor the files that ran. Checknode --versionand read the count. check_available_updatesfails open. Every network call is wrapped inexcept Exception: pass, andrelease.pyprints "Dependency update check skipped" on any exception. A network failure reads exactly like "no updates available". Confirm you got a real report, not a skipped one.- The
gwsversion is generated, never hand-edited.gws generate-skillsemitsmetadata: version:intogws-shared/SKILL.md, andgws-sharedis one of the shipped skills, so regeneration advances the pin. Hand-bumping it is the failure this pin prevents: it either gets overwritten, or it records a version the skills were never generated from. Upgrade the CLI, regenerate, and let the pin follow. - Never
git add -Ain this checkout. Another session may be editing it. Stage explicit paths and readgit diff --cachedbefore committing. - Use
rtk proxy git …for anything you are about to commit on. The RTK hook filters git output, and it has reported a clean tree over seven modified files. - Editing
site/publishes on merge tomain. It is not a draft. Check the claim against the code before you commit it, not after.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

