Skip to content

docs(skill): cut SKILL.md to an 8 KB core with references - #377

Merged
leemour merged 3 commits into
mainfrom
docs/skill-cut
Nov 16, 2026
Merged

leemour merged 3 commits into
mainfrom
docs/skill-cut

Conversation

@leemour

@leemour leemour commented Nov 16, 2026

Copy link
Copy Markdown
Member

Task

Cut the agent skill so an agent that loads it pays about 2,000 tokens by default, with no rule lost.

Why

An agent carries SKILL.md in every turn of its session. A timed agent test (2026-11-16) showed a large skill adds thousands of input tokens per turn and pushes sessions past their time budget. zm's skill was 19,877 bytes (about 5,000 tokens). Same pattern as whatsapp-cli#406.

What

  • skills/zoom-cli/SKILL.md: 19,877 → 7,866 bytes. Frontmatter (description sharpened for questions stored meetings can answer), discovery, the profile rule, answering from meetings and recordings, writes that need the owner, output, and an index (when to read each file; relative link, zm skill show <part>, GitHub fallback).
  • skills/zoom-cli/references/: search, people-and-projects, prepare, archive, zoom-live, setup (20,692 bytes in all). Text moved verbatim or tightened.
  • Corrected stale text from before 0.77.0: meetings link --event-id (was meetings update --event-id), meetings create|update|cancel|invitation (was remote-meetings), the series id comes from meetings scheduled, and --dry-run shows the command and permission rather than the request. Added from 0.77.0: meetings show/meetings list ask Zoom by default (--offline reads the store only), --start-time for create, --occurrence-id for cancel, the remote-meetings permission key, the meeting:read:past_meeting scope.
  • scripts/check-agent-docs.ts (pnpm check:agent-docs, run in CI after the build): validates the core and every reference's links and command paths with validateSkill, checks the core links each reference, caps the core at 8,500 bytes.
  • scripts/package-check.ts: the package ships skills/zoom-cli/.
  • Backlog ZM-30 (P1): do not release before building on the cli-base that installs references/ (0.106.0 or later) and the cli-core that serves them over MCP (skillResources; cli-core 0.678.0 on npm still serves only SKILL.md). Checked: with cli-base 0.102.1 zm skill install --for agents into a temporary HOME writes only SKILL.md, and zm skill show search fails.

Testing

  • Every rule, trap, boundary and recipe of the old file (165 items) was listed and ticked against its new place. A fresh reviewer compared old and new and checked commands against --help; its findings were fixed (the --offline trap, --dry-run wording, cancel occurrences, create start time, search filters moved to search, "same over MCP" back on projects scan, overlap note beside passages, sharper index triggers).
  • pnpm check:agent-docs (also shown failing on a planted bad link and command), pnpm docs:check, pnpm lint, scripts typecheck, pnpm package:check, npm pack --dry-run lists all reference files, the skill tests in src/cli-execution.test.ts.

🤖 Generated with Claude Code

leemour and others added 3 commits November 16, 2026 17:11
An agent carries SKILL.md in every turn of its session; the 20 KB skill cost about
5,000 input tokens per turn. The core keeps discovery, the profile rule, answering
from stored meetings, the limits on writes and the output shape, and links six
references (search, people and projects, prepare, archive, zoom-live, setup) with
the rest, moved verbatim or tightened.

Names removed in 0.77.0 are corrected: meetings link --event-id, and
meetings create|update|cancel|invitation instead of remote-meetings.

scripts/check-agent-docs.ts validates every reference's links and command paths,
checks the core links each one and caps the core at 8,500 bytes; CI runs it. The
package ships skills/zoom-cli/. ZM-30: do not release before the cli-base and
cli-core that deliver references.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…l occurrences, filters in search

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour merged commit 79694c3 into main Nov 16, 2026
11 checks passed
@leemour
leemour deleted the docs/skill-cut branch November 16, 2026 16:20
leemour added a commit that referenced this pull request Nov 16, 2026
#378)

Moves zm to `@wirecat/cli-core` 0.681.0 and `@wirecat/cli-base` 0.106.0
and prepares 0.78.0, so the skill cut from #377 reaches npm with its
`references/`. Release approved by the owner on 2026-11-16.

cli-core 0.681.0 makes `skill install` write `references/*.md` beside
`SKILL.md` and lets `skill show <name>` print one. Before, only
`SKILL.md` was installed and its links to `references/` led nowhere.

## What changed

- `package.json`, `src/version.ts`: 0.78.0. `CHANGELOG.md`: `changes/`
fragments collected into `## 0.78.0 — 16.11.2026`.
- `docs/commands.md` regenerated: `skill show [name]`; meetings have one
more field (cli-core's optional `call`).
- `contracts/help.snap`: "Works with" names notion.
- `contracts/upgrade.json`: store schema 67 (was 66).
- `lint/baseline/unknown-verb.json`: dropped the stale `meetings
invitation` entry the lint asked to remove.
- `src/command-boundaries.test.ts`: `events list` under a meetings tool
now marks title, description and location untrusted.

zm's `SHELL_OVERRIDES.skill` still matches the shared command: no
`contract.unacknowledged-override` at start.

## Conformance

- Local, on this branch: `standards:check`, `lint`, `typecheck`,
`test:coverage` (755 passed), `test:matrix` (344 tested, 0 missing),
`contracts:check`, `contracts:upgrade`, `docs:check`, `generate:check`,
`version:check`, `lint:commands`, `security:no-leak`, `package:check`,
`smoke:node`, `smoke:bun`, `check:agent-docs` — all green.
- Built bin in a temp HOME with the keyring unreachable: `zm skill
install` wrote `SKILL.md` and all 6 `references/*.md` into both
`.claude/skills/zoom-cli/` and `.agents/skills/zoom-cli/`; `zm skill
show search` printed `references/search.md` byte for byte.
- No live check against Zoom: the change is the dependency bump and the
skill text; no Zoom request path changed in this repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant