Skip to content

ADR: pack skills — share and co-maintain agent commands through charter packs

Status: Accepted

Date: 2026-09-27 (accepted 2026-10-04, mission pack-skills-kind-01M43419)

Deciders: Stijn Dejongh (owner). Design produced by a profile-loaded research and architecture squad: researcher-robbie (prior art), architect-alphonso (design), doctrine-daphne (doctrine integrity), paula-patterns (second-opinion adjudication).

Technical Story: #5193 (implementation tracking, under epic #2466).


Context and Problem Statement

Spec Kitty’s vision is governed, shared, consistent AI usage. Doctrine already delivers that for rules and techniques: directives, tactics, procedures, and profiles live in pack tiers (packs/built-in/ for consumers, org packs such as packs/internal/ for a team, and the project’s .kittify/doctrine/), are merged by merge_three_layers (src/charter/offering/drg/merge.py), and are switched on per project through spec-kitty charter activate.

There is no equivalent for the entry points people actually type. The shorthands a team relies on (for this repository: landing a contributor PR, driving a mission from an issue, triaging the tracker, curating memory) live as private, per-user agent skills. The research pass found:

  • No pack can ship a skill or command today. SkillRegistry reads one package root (src/specify_cli/skills/registry.py:66-93); the command-skill set is a closed tuple with a parity assert (src/specify_cli/skills/command_installer.py:81-106); every rendered command is forced to spec-kitty.<cmd> (src/specify_cli/skills/command_renderer.py:468).
  • No doctrine concept exists for a skill, command, alias, or shorthand, and no ADR, spec, or plan discusses shareable entry points.
  • The private copies duplicate doctrine and drift. The landing shorthand restates the internal procedure landing-contributor-prs (packs/internal/procedures/landing-contributor-prs.procedure.yaml) and already cites a doc path that does not exist (docs/development/pr-landing.md; the page is docs/development/how-to/pr-landing.md). Memory curation restates memory-curation-and-escalation; triage restates the built-in tracker-organisation-workflow and issue-triage-state-machine procedures.
  • They hard-code people and places (an operator handle, the repository slug, check names) and squat on the built-in spk- namespace (src/charter/offering/skills/README.md, “Naming Convention”).

A second, drifting, unreviewed copy of doctrine per person is exactly what the charter’s single canonical authority principle forbids. Sharing a shorthand today means pasting it into someone else’s account.

Decision Drivers

  • Single canonical authority (DIRECTIVE_044): the substance stays in procedures; the entry point must reference it, not restate it.
  • Relationships are DRG edges, not fields. ADR 2026-07-26-1 treats inline references: as pre-DRG residue (pinned by tests/architectural/test_reference_enum_ratchet.py); C-009 says the same for profile lineage.
  • One activation authority. The only non-kind activatable token today, mission-type, is recorded as debt awaiting promotion (ADR 2026-08-05-1). A second outlier would be a parallel authority.
  • Pack-tier boundary (ADR 2026-08-16-3): in-house shorthands must never ship in the wheel.
  • Terminology canon: do not add an eighth sense of “command” or a fifth of “alias”.
  • Every configured tool, not one harness: 13 slash-command tools plus 4 Agent Skills tools.
  • Trust: a shared prompt runs with the tool’s repository permissions.

Considered Options

  1. New doctrine kind command (“Pack Command”; forms full | alias), DRG-wired and charter-activatable (architect’s draft).
  2. No new kind: “pack skills” on the existing skill surface, installed whenever their bound procedure is active, with the binding in SKILL.md frontmatter (doctrine-integrity lens).
  3. New doctrine kind skill (URN skill:<id>, prose “pack skill”; forms prompt | wrapper), DRG-wired, charter-activatable, projected by the managed doctrine-skill installer (adjudicated synthesis of 1 and 2).
  4. Make procedures directly invocable (invocable: true on procedure).
  5. Tool-native plugin marketplaces (for example Claude Code plugins).
  6. An alias layer inside the command-skill pipeline (shortcodes.yaml per pack, resolved in command_renderer.render()), as sketched in #2470.

Decision Outcome

Chosen option: 3, a charter-activatable skill doctrine kind. It keeps option 1’s structure (a real ArtifactKind/NodeKind, DRG edges, charter activation) because option 2 has nowhere to put the skill → procedure binding except an inline reference block, which ADR 2026-07-26-1 forbids, and any independent activation would add a second mission-type style outlier. It takes option 2’s naming (“skill” is already the glossary term: packs/built-in/glossary_packs/spec-kitty-core.glossary-pack.yaml:545) and its sequencing (derive the lockstep kind lists first; augment procedures before thinning skills).

The skills README’s rule that skills are “not the source of team workflow” (src/charter/offering/skills/README.md:7-24) constrains substance. A pack skill is a thin, parameterised entry point that requires the procedure carrying the substance, so it complies with that rule rather than breaking it.

Shape of the artifact

# packs/internal/skills/land-pr.skill.yaml (org tier; never in the wheel)
schema_version: "1.0"
id: land-pr # URN skill:land-pr
title: Land a contributor PR
description: Maintainer landing pass on a PR — triage, rebase, classify reds, squad, hand off.
triggers: ["land this PR", "landing pass"]
form: prompt # prompt | wrapper
body_path: land-pr.skill.md # prompt form only; copied into SKILL.md unchanged (no per-tool placeholder rewrite)
parameters:
- {name: pr, required: true, description: "PR number or URL"}
- {name: steer, required: false, description: "free-text steer"}
invocation:
user_invocable: true
model_invocable: false # forced false when side_effects is non-empty
side_effects: [git-push, gh-write]
tools: ["*"] # accepted and stored; deferred: not used to filter projection
version: 1.0.0
maintainers: ["@spec-kitty/core"]
# a wrapper-form skill: a thin shorthand over an existing command
id: ship
form: wrapper
expands_to: {target: "builtin:spec-kitty.merge", args: "--strategy squash $ARGUMENTS"}

Relationships live only in the pack’s DRG fragment:

edges:
- {source: "skill:land-pr", target: "procedure:landing-contributor-prs", relation: requires}
- {source: "skill:land-pr", target: "directive:NO_FULL_HEAVY_SUITES_IN_MISSION", relation: requires}
- {source: "skill:land-pr", target: "agent_profile:reviewer-renata", relation: suggests}

Dangling endpoints fail closed with unresolved_edge_endpoint (src/charter/offering/drg/merge.py). The rendered skill carries a generated preamble that fetches each requires target at run time with spec-kitty charter context --include <urn>, so the substance is never copied into the skill.

Tiers, merge, and activation

TierLocationShips?Example content
built-inpacks/built-in/skills/ (a generated skill.graph.yaml shard is deferred)yesconsumer-safe shorthands (empty at MVP)
org<pack>/skills/, declared in drg/fragment.yaml, required_skills: in org-charter.yamlnever for packs/internalland-pr, mission-from-issue, issue-triage, curate-memory
project.kittify/doctrine/skills/repo-localrepository-specific shorthands
  • The built-in tier is empty at the MVP, so no skill.graph.yaml shard exists. The extractor helper that emits built-in skill nodes (_emit_skill_nodes) is in place for when the tier gains content.
  • Activation: spec-kitty charter activate skill land-pr --cascade procedure,directive through plan_activation / commit_plan; config key activated_skills. Cascade pulls in what the skill requires; deactivation keeps anything another active artifact still references (C-005).
  • Default in force when the key is absent: required_skills of registered org packs plus built-in defaults, not every available skill, supplied through the existing effective_ids seam and one kind attribute rather than per-kind branching. Registering a pack must not silently add N commands to every tool.
  • overrides: skill:<id> replaces a skill. At the MVP, overriding a built-in skill is refused; built-in replacement through replaceable-builtins.yaml is deferred to slice 3. enhances may change parameter defaults, triggers, tool targeting, or narrow invocation, but never the body or expansion. Same id in two sibling org packs is a hard conflict.
  • Co-maintenance: the pack’s pack_version, the skill’s version, maintainers, and review through the pack repository’s PRs. A locally edited rendered copy is reported as drift pointing back at the pack source, so tweaks become upstream PRs rather than forks.

Rendering and installation

charter (pure) specify_cli (adapter)
merged DRG + activated_skills
└─ prepare_project_skill_activations() ─► resolve_project_skill_catalog(project_root)
(id, rendered name, body, expansion, ├─ render_pack_skill(): builds its own SKILL.md
provenance, source_hash) │ (frontmatter, context preamble, parameters,
│ instructions); no command_renderer, no
│ User-Input block rewrite
├─ stage under .kittify/runtime/pack-skills/
├─ project skill roots only, never global
└─ .kittify/skills-manifest.json ownership
  • The managed doctrine-skill installer (src/specify_cli/skills/installer.py) is the owner. command_installer.py and its spec-kitty.* contract stay closed.
  • One catalog-composition seam used by every caller that today builds SkillRegistry.from_package() and installs with retire=True (init, upgrade migrations, the verifier, the managed-skills tool-surface provider). Injecting pack skills into a single call site would let the others prune them on the next upgrade.
  • Charter emits unresolved builtin: expansion targets; the specify_cli adapter validates them against its command set, keeping the enforced kernel <- charter <- … <- specify_cli direction. cli: targets are limited to spec-kitty argv.
  • Project scope only. Activation is per repository, so rendered skills go to project skill roots (.claude/skills/, .agents/skills/, and the other roots in AGENT_SKILL_CONFIG), never to user-global directories.
  • Coverage at MVP: the 16 tools with a project skill root, and only the primary (first-listed) root of each (.agents/skills/ for the shared-root tools). Amazon Q is wrapper-only: the installer skips wrapper-class tools silently and raises no finding for it. A research-gap finding for that tool, and project-local command files for non-skill tools, are deferred to slice 3.
  • Deactivation re-runs projection and retires manifest-owned entries only.
  • Rendered copies are gitignored in this repository, so doctor / upgrade compare the freshly prepared source_hash (a sha256: digest of the skill record, its DRG requires, its rendered name and its body) against the source_hash in the skills-manifest provenance (staleness, not only tampering of the rendered copy, which is reported separately as drift against the manifest content_hash). A manifest entry the current catalog no longer provides (for example after a namespace change) is reported as orphaned.

Namespaces and trust

  • spk-, spec-kitty-, and spec-kitty. are reserved for built-in. Org and project packs declare a skill_namespace; skills render as <namespace>-<id>. Two activated skills that render to the same name fail before any write; an unowned existing directory with that name is preserved and reported (an empty directory with that name is projected into).
  • A pack acts only after a maintainer registers it in charter_packs.org.packs (built at the MVP). Deferred to slice 3: remote packs pinning an immutable ref, and verifying content hashes at preparation.
  • Deferred to slice 3: activation printing a trust summary over the skill’s whole requires/suggests closure, assets included (assets already ship executables), and requiring --accept for side effects or remote packs. Built at the MVP: the validator refuses a scripts/ directory and permission-widening frontmatter (such as allowed-tools) for org and project skills.
  • Bindings (repository, operator) resolve at run time from project config, never baked into rendered files; public packs carry no personal identifiers.

Ownership proof

The charter’s “User Customization Preservation” rule requires any flow that mutates user-visible skill directories to document its proof. This flow acts only on what it can prove it owns.

  • Ownership record. .kittify/skills-manifest.json lists every file the installer wrote, with the content_hash it wrote. Retire (on deactivate, a namespace change, or a skill removed from the pack) and overwrite (on a changed pack source) act only on paths in that manifest. The installer retires an entry only when the current catalog no longer expects its path.
  • Validated paths. Before any write the installer checks every manifest entry: the skill name must be one path segment, the source path must be relative with no .., and the installed path must equal <primary skill root>/<name>/<source>. An entry that fails the check stops the projection with “Skills manifest contains an invalid ownership path”. Removal is per file; a directory is removed afterwards only when every entry in it was deleted.
  • A same-name directory the tool does not own (no manifest entry) is preserved and reported, even when it has no SKILL.md. An empty directory with that name holds nothing to preserve, so the installer projects into it.
  • A locally edited copy is kept. When an owned file no longer matches its recorded content_hash, the installer neither overwrites nor deletes it. charter activate and charter deactivate list it as “Skill file preserved”, and doctor skills reports it as drift. Replacing an owned, unmodified file keeps a backup of the old copy.
  • Names and ids are validated before they reach a path. A skill_namespace must be lowercase ASCII: it starts with a letter, its [a-z0-9] segments are joined by single -, and it is at most 32 characters. A skill id follows the same grammar and is at most 64 characters. The validator never normalises a value. An invalid namespace is refused before the staging directory or any skill root is touched; an invalid id makes the repository skip that skill file with a warning, which doctor doctrine reports. A skill that is already in force and then stops loading is refused instead of dropped, and the projection deletes nothing. Names that start with a reserved prefix, collide with a built-in skill name, or are not a single safe path segment are refused the same way.

Amendment 2026-10-06 (mission skill-surface-upgrade-integrity-01M482Z3)

  • New finding kind missing. doctor skills now reports a pack skill that is in force for a configured tool that accepts skill files but is not installed, whether it was never projected or its installed copy was deleted. Before, the health check could pass while the skill was absent. The drift, stale, orphaned and unresolvable kinds are unchanged.
  • doctor skills --fix projects missing skills. It calls the same project_pack_skills installer as charter activate and upgrade. The projected paths appear in the additive repaired_paths list; repaired_agents keeps agent keys only. --fix still never repairs drift.
  • no_tool_folder. When none of the configured agents’ tool folders exists, doctor skills fails and lists the finding under tool_folders.
  • Upgrade pre-check. spec-kitty upgrade uses the same findings function, so it also warns pack_skill_missing.
  • Rationale. Issue #5801: the projection and the health check disagreed about what “installed” means. Deferred: the installer verifier and the assessment surface still do not read missing.

Consequences

Positive

  • A team shorthand has one reviewed, versioned source that reaches every configured tool.
  • Procedures stay the single home of substance; entry points cannot silently drift from it.
  • Private skills get a promotion path into a project or org pack.
  • The kind is the convergence target for the built-in spk-* product skills later.

Negative

  • A new kind is real work: a row in each of the four per-kind tables in artifact_kinds.py (_PLURALS, _HAS_BUILT_IN_CONTENT_DIR, _PATTERNS, PROJECT_KIND_DIRS), three new enum facts (org_requirable, selection_overlayable, effective_when_absent), NodeKind, a doctor health dimension, an extractor helper, the delivery table (slot=None with a reason), and roughly a dozen exact-set tests (precedent: the glossary_pack kind). A generated skill.graph.yaml shard is deferred while the built-in tier is empty.
  • It expands the visible slash surface per project, which the skills README otherwise avoids; that is deliberate and scoped to activated skills only.
  • packs/built-in/skills/ coexists with src/charter/offering/skills/ until convergence.

Neutral

  • Invocation costs one extra charter context --include call per required artifact.

Confirmation

  • ATDD: activate a pack skill → it appears in .claude/skills/ and .agents/skills/; run upgrade → still present; deactivate → removed; nothing else touched.
  • Packaging safety: no packs/internal/skills/** path in the wheel.
  • Deferred to slice 2: the four internal shorthands run from the pack with no private copy, and the landing procedure carries the content that only the private skill held before. Slice 1 ships no packs/internal/skills/ entry.

Delivery slices

  1. Campsite (precondition): derive _BUILTIN_ARTIFACT_KINDS (src/charter/activation/pack_context.py), _ALLOWED_KINDS (src/charter/activation/activations.py), _ORG_DRG_KIND_ALIASES (src/charter/offering/drg/org_pack_loader.py), and REQUIRED_KIND_FIELDS from ArtifactKind, so this and every later kind adds no lockstep copies.
  2. MVP: kind and node registration, schema and validator for both forms, activation and cascade with the default-in-force rule, prepare_project_skill_activations, the catalog seam, project-root projection, namespaces, drift and staleness findings, retire on deactivate.
  3. Migration: augment landing-contributor-prs and the other procedures with the content only the private skills hold, then add the four thin packs/internal/skills/* entries and retire the private copies.
  4. Later: trust --accept gate and remote pinning, command-file projection for non-skill tools, a charter skill promote <dir> scaffolder, an Op-opening preamble, and converging the built-in spk-* skills onto the kind.

Pros and Cons of the Options

Option 1: new kind command

  • Good: correct structure (kind, edges, activation, managed installer, project scope).
  • Bad: “command” already has six or more senses (Slash Command, Command Template, Command Envelope, CLI command, CANONICAL_COMMANDS, command-skill tools) and form: alias adds a fifth sense of “alias”. Blocks later convergence of the product skills.

Option 2: pack skills without a kind

  • Good: cheapest doctrine-side change; reuses the glossary term.
  • Bad: the skill → procedure link would live in frontmatter, a second relationship authority; no own activation (breaks for wrapper skills, many skills over one procedure, and projects that want the procedure but not the entry point); no cascade, --include, or doctor health. The installer work, the dominant cost, is the same as option 3.

Option 3: new kind skill (chosen)

  • Good: one relationship authority, one activation authority, canonical term, convergence path.
  • Bad: kind-registration cost (reduced by slice 0).

Option 4: invocable procedures

  • Bad: procedures have no parameters, bindings, or tool targeting; every procedure edit would become a surface change.

Option 5: tool-native plugin marketplaces

  • Bad: tied to one tool; loses the single cross-tool source. It can stay a later projection target.

Option 6: alias layer in the command-skill pipeline (#2470)

  • Good: small, reuses the existing renderer and manifest.
  • Bad: widens the closed spec-kitty.* command-skill owner and its CONSUMER_SKILLS parity invariant; aliases only, so no home for full prompt skills; no DRG edge to the procedure it shortcuts, and no charter activation. If this ADR is accepted, #2470 is superseded by #5193.

Resolved questions

Resolved when the MVP landed (mission pack-skills-kind-01M43419):

  • /name exposure. src/specify_cli/tool_surface/profiles/capability_matrix.py records only native named-agent primitives (it does not say which tools surface a project skill as a /name command), so it cannot answer this. The in-repo record is the command-surface table in AGENTS.md: Codex invokes $<name>, Pi /skill:<name>, Vibe /<name>, and Letta routes Agent Skills through the model. Decision: a pack skill is an Agent Skill in the project skill roots and promises no /name form; how each tool surfaces it is the tool’s own rule. Per-tool exposure is not asserted by Spec Kitty.
  • Project-tier namespace. A required config key, charter_packs.project.skill_namespace; it is never derived from the repository name. A project-tier skill without it is refused with the remedy. The org-tier skill_namespace in org-charter.yaml is likewise required.
  • Run-time binding placeholders. Deferred to slice 2 with the first migrated shorthand. Slice 1 renders no binding placeholders, so no syntax can collide with $ARGUMENTS or TOML {{args}} yet.
  • #2470 supersession. Remains the owner’s call; this ADR does not close or relabel it.
  • CLAUDE.md names the org-pack key doctrine.org.packs; the code reads charter_packs.org.packs and treats the old key as a legacy fallback (src/charter/offering/drg/org_pack_config.py).