FM-924 — Official `fleet` skill as a built-in global skill

[Andreas-Froyland]

Epic: #120 · Depends on: FM-922

Context

bootstrap/fleet-bootstrap documents the legacy agents-registry. PLAN M7 calls for Fleet-provided skills that drive fleetctl --output json.

Goal

A skills/fleet/SKILL.md teaching agents to use this controller through fleetctl --output json (status, machines, projects/ready, Lab lease lifecycle, operations). It ships with the controller as a built-in catalog entry versioned with the release and is globally assigned by default (removable).

Architecture reference

docs/PLAN.md (agent access, M7 Fleet-provided skills).

Dependencies

FM-922

Research required

Current fleetctl command surface.

Acceptance criteria

• Every command in the skill is covered by a CLI snapshot test so the docs cannot rot
• bootstrap/fleet-bootstrap removed or replaced with a pointer

Non-goals

• MCP server

Tests

CLI snapshot coverage check for commands referenced in the skill.

[Andreas-Froyland]

Implementation scoping findings (from a research pass; see the thread for context):

The issue is larger than writing skills/fleet/SKILL.md — three of its four moving parts have no existing mechanism:

1. Built-in catalog seeding does not exist. There is no code path that seeds a built-in catalog entry anywhere (no include_str! of skill content, no startup seeding, no migration). SkillCatalogPort (create/get/list/update/publish/get_version/list_versions, crates/fleet-application/src/skill_catalog.rs:69) is purely caller-driven today. "Versioned with the release" needs a design decision: seed-on-startup (idempotent upsert keyed by content digest) vs. a migration, and what happens when an operator edits or unpublishes the built-in entry (re-seed would resurrect it — is the built-in immutable?).

2. "Globally assigned by default (removable)" has no persistence to attach to. SkillAssignmentScope::All and compose_skill_assignments exist (crates/fleet-application/src/composition.rs:129,186) and FM-923 landed assignments in the Git desired-state layer (schemas/src/kinds.rs SkillPreset with scope defaulting to All, PR Implement scoped Fleet skill assignments #175) — but there is no controller-side assignment storage or seeding, so "globally assigned by default" currently means a preset in Fleet Git, not a built-in. Shipping the default as a Git preset is a different mechanism than seeding it controller-side, and the issue doesn't say which is intended. Also unresolved: if the built-in assignment is "removable", what stops the next release/startup from re-adding it?

3. No doc-coverage test mechanism exists. The acceptance criterion "every command in the skill is covered by a CLI snapshot test" needs a new test that parses fleetctl invocations out of skills/fleet/SKILL.md and cross-checks each against the CLI surface/tests (crates/fleetctl/tests/cli.rs has no golden-file/snapshot framework — the closest patterns are the real-router e2e tests like fleetctl_talks_to_a_real_controller). Doable, but it is a new test harness, not a fill-in.

4. Removal of bootstrap/fleet-bootstrap is trivial (nothing references it in code) — no concern.

Design decisions needed before implementation (ADR-adjacent per the AGENTS.md rule about documented boundaries):

• Where built-in seeding lives (startup upsert vs migration) and whether the built-in entry is operator-immutable or re-seeded when missing.
• Whether the default global assignment is seeded controller-side or shipped as a SkillPreset in Fleet Git, and how "removable" survives re-seeding.

Re-labeling to agent:claude so the agent with the skills-catalog context picks it up; the GLM queue is otherwise empty.

[Andreas-Froyland]

Design decisions (maintainer, 2026-09-27)

Answering the scoping questions above:

1. Seeding: an idempotent upsert at startup, into a reserved entry. On controller start, the built-in fleet skill (skills/fleet/SKILL.md, embedded with include_str!) is upserted under a reserved catalog id. A new immutable version is published only when the release's content digest changes. The API refuses edits to the reserved entry, so re-seeding never overwrites operator work.
2. Default assignment: implicit, with an opt-out in Fleet Git. Desired-state composition adds an implicit global assignment of the built-in skill unless Fleet Git opts out. Removal is expressed in Git, which the controller never writes, so a new release cannot silently re-add a removed assignment.

Both change documented boundaries (the skills catalog and desired-state composition), so the implementation will update docs/architecture/skills-catalog.md and docs/architecture/desired-state.md and propose an ADR.