feat(skills): install the agent skills into any repository

The stewardship skills were written by exactly one code path: `init`, which
only runs on a new repository. Adopting an existing one starts from the
repository-adoption skill, and nothing could put that skill there -- so the
entry point to the procedure depended on the operator already having it
from somewhere else. Services/Monitoring carries three domain skills of its
own and no stewardship skill; `adopt` lists `.claude/skills` among its
collision paths and installs nothing.

    repoctl skills install --repo .    # travels with the repository
    repoctl skills install --global    # follows the operator everywhere
    repoctl skills status --repo .

Scope is stated, never guessed: the two answers differ in who ends up with
the skills, and neither is the obvious default.

No plan and no approval hash. That discipline protects a repository's own
content; this writes only tool-owned files, in a fixed subdirectory, whose
content is fully determined by the installed version. The house rule it
does keep is that a write never destroys what it did not author: a skill
whose content differs is reported as SKILLS_MODIFIED and left alone until
`--force` says otherwise, and the check covers every skill before the first
byte is written, so a refusal leaves nothing half-updated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Alexander Baranov
2026-08-26 14:35:38 +03:00
co-authored by Claude Opus 5
parent c21ffceef3
commit c80d39cc73
6 changed files with 352 additions and 3 deletions
+132
View File
@@ -0,0 +1,132 @@
"""`repoctl skills`: put the stewardship agent skills where an agent looks for them.
The skills were distributed by exactly one path: `init`, which only ever runs on
a *new* repository. Adopting an existing repository needs the adoption skill,
and nothing could install it there -- so the entry point to the whole procedure
depended on the operator already having the skill from somewhere else.
This command is deliberately not plan-then-approve. That discipline exists to
protect a repository's own content, and nothing here touches it: the targets are
a fixed set of tool-owned files under a fixed subdirectory, with content
determined entirely by the installed version of repoctl. What it does keep is
the house rule that a write never destroys something it did not author -- a
skill whose content differs is reported, not overwritten.
"""
from __future__ import annotations
from pathlib import Path
from typing import Any
from . import io
from .paths import PathViolation, confined_path
from .skills_content import (
REPO_HANDOFF_SKILL,
REPOSITORY_ADOPTION_SKILL,
REPOSITORY_BOOTSTRAP_SKILL,
)
SKILLS_SUBPATH = ".claude/skills"
SKILLS: dict[str, str] = {
"repo-handoff": REPO_HANDOFF_SKILL,
"repository-adoption": REPOSITORY_ADOPTION_SKILL,
"repository-bootstrap": REPOSITORY_BOOTSTRAP_SKILL,
}
class SkillsError(ValueError):
"""`repoctl skills` refused to proceed, carrying a stable finding code."""
def __init__(self, code: str, message: str) -> None:
super().__init__(f"{code}: {message}")
self.code = code
def target_base(repo: Path | None, *, global_scope: bool) -> Path:
"""The directory the skills tree hangs under: a repository, or the user's home.
A repository-local install travels with the repository and is what a
teammate cloning it gets; a global install follows the operator across every
repository, including ones not adopted yet. Both are legitimate, and which
one is wanted cannot be guessed, so one of them must be stated.
"""
if global_scope and repo is not None:
raise SkillsError("SKILLS_SCOPE_AMBIGUOUS", "Use either --repo or --global, not both")
if global_scope:
return Path.home()
if repo is None:
raise SkillsError(
"SKILLS_SCOPE_MISSING",
"Say where the skills go: --repo PATH for one repository, or --global for every one",
)
base = repo.expanduser()
if not base.is_dir():
raise SkillsError("SKILLS_TARGET_MISSING", f"No such directory: {base}")
return base.resolve()
def skills_dir(base: Path) -> Path:
"""Where the skills live under ``base``."""
return base / SKILLS_SUBPATH
def _skill_path(base: Path, name: str) -> Path:
# Confined against the base rather than the skills directory: the latter
# routinely does not exist yet, and confinement needs a real root to
# resolve against.
try:
return confined_path(base, f"{SKILLS_SUBPATH}/{name}/SKILL.md")
except PathViolation as exc: # pragma: no cover - names are module constants
raise SkillsError("SKILLS_PATH_OUTSIDE_TARGET", f"{name}: {exc}") from exc
def status(base: Path) -> list[dict[str, str]]:
"""Report each skill as ``missing``, ``current`` or ``modified``.
``modified`` deliberately does not distinguish "the operator edited it" from
"repoctl moved on": both mean the file on disk is not the one this version
ships, and neither is safe to overwrite without being asked.
"""
report: list[dict[str, str]] = []
for name, content in SKILLS.items():
path = _skill_path(base, name)
if not path.exists():
state = "missing"
else:
on_disk = path.read_text(encoding="utf-8", errors="replace")
state = "current" if on_disk.strip() == content.strip() else "modified"
report.append({"skill": name, "state": state, "path": path.as_posix()})
return report
def install(base: Path, *, force: bool = False) -> dict[str, Any]:
"""Write every missing skill; refuse to replace one whose content differs.
Nothing is written until every target has been checked, so a refusal leaves
the directory exactly as it was rather than half-updated.
"""
current = status(base)
modified = [item["skill"] for item in current if item["state"] == "modified"]
if modified and not force:
raise SkillsError(
"SKILLS_MODIFIED",
"Already present with different content: "
+ ", ".join(sorted(modified))
+ ". Re-run with --force to replace them.",
)
written: list[str] = []
for item in current:
if item["state"] == "current":
continue
name = item["skill"]
io.write_text_atomic(_skill_path(base, name), SKILLS[name])
written.append(name)
return {
"target": skills_dir(base).as_posix(),
"installed": sorted(written),
"unchanged": sorted(i["skill"] for i in current if i["state"] == "current"),
"skills": status(base),
}