mdcompose 0.2.0__tar.gz → 0.2.1__tar.gz

{mdcompose-0.2.0 → mdcompose-0.2.1}/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to mdcompose are recorded here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.2.1 (2026-09-14)
+
+### Added
+
+- add mdcompose skill command group
+
 ## v0.2.0 (2026-09-14)
 
 ### Added

{mdcompose-0.2.0 → mdcompose-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdcompose
-Version: 0.2.0
+Version: 0.2.1
 Summary: Keep CLAUDE.md and AGENTS.md in sync and composed from a personal snippet library, without hand-editing every project
 Project-URL: Homepage, https://github.com/Rovetown/mdcompose
 Project-URL: Repository, https://github.com/Rovetown/mdcompose
@@ -58,8 +58,7 @@ mdcompose keeps those as small snippets in one place and builds each project's `
 - **A committed lockfile.** `mdcompose.lock` embeds each snippet's content, so a clone or fork reproduces the same files with an empty library.
 - **Correct paths on Windows, WSL, and Linux**, including a warning when a managed file sits inside a OneDrive-synced folder.
 - **No install required.** `uvx mdcompose doctor` or `pipx run mdcompose doctor` run the real thing in a throwaway environment -- try it, or use it in a one-off script, without adding anything to your machine.
-- **Skills cost tokens too, and that's next (planned).** Every skill an agent does not need loaded for a project is context spent before it has done any work.
-  A skill file -- frontmatter, a body, sometimes a script -- is already snippet-shaped, so curating which skills a project loads, the same way AGENTS.md and CLAUDE.md are curated today, is the natural next composition target: real token savings, not just tidiness.
+- **Skills cost tokens too, so they're composed the same way.** A second, independent library curates which Claude Code Skills a project loads into `.claude/skills/`, so an agent stops paying context for skills a given project never needed.
   See [docs/concepts.md](https://github.com/Rovetown/mdcompose/blob/main/docs/concepts.md).
 
 It makes no network requests and collects no telemetry.
@@ -146,6 +145,10 @@ mdcompose snippet list         the snippets in your library
 mdcompose snippet edit <id>    open one in your editor
 mdcompose snippet remove <id>  delete one
 mdcompose snippet adopt        save a project's embedded snippets to your library
+mdcompose skill list           the skills in your skill library
+mdcompose skill edit <id>      open one in your editor
+mdcompose skill remove <id>    delete one
+mdcompose skill adopt          save a project's embedded skills to your skill library
 mdcompose import <file>        pull sections out of an existing CLAUDE.md or AGENTS.md
 mdcompose convert <src> <dst>  move content between this project's AGENTS.md and CLAUDE.md
 mdcompose eject                stop managing a directory: remove markers, delete the lock
@@ -217,7 +220,7 @@ A few projects cover the same idea of a personal snippet library composed per pr
 What mdcompose does that they do not: import-versus-copy tied to Claude Code's real `@import`; drift detection by hashing one owned block; a committed lock with embedded content so a fork works without the author's library; and real Windows, WSL, and mounted-drive path correctness.
 It deliberately does no format translation: a target receives Markdown, not Cursor rules or Copilot instructions.
 
-**None of them go past agent instructions -- mdcompose plans to.** A skill file is markdown plus optional scripts, same as a snippet; composing a curated skill selection per project the way AGENTS.md and CLAUDE.md are composed today means an agent stops paying context for skills a given project never needed loaded in the first place.
+**None of them go past agent instructions -- mdcompose does.** A skill file is markdown plus frontmatter, same as a snippet; a curated skill selection is composed per project into `.claude/skills/` the same way AGENTS.md and CLAUDE.md are, so an agent stops paying context for skills a given project never needed loaded in the first place.
 
 See [docs/concepts.md](https://github.com/Rovetown/mdcompose/blob/main/docs/concepts.md) for the fuller case for each point.
 

{mdcompose-0.2.0 → mdcompose-0.2.1}/README.md

@@ -28,8 +28,7 @@ mdcompose keeps those as small snippets in one place and builds each project's `
 - **A committed lockfile.** `mdcompose.lock` embeds each snippet's content, so a clone or fork reproduces the same files with an empty library.
 - **Correct paths on Windows, WSL, and Linux**, including a warning when a managed file sits inside a OneDrive-synced folder.
 - **No install required.** `uvx mdcompose doctor` or `pipx run mdcompose doctor` run the real thing in a throwaway environment -- try it, or use it in a one-off script, without adding anything to your machine.
-- **Skills cost tokens too, and that's next (planned).** Every skill an agent does not need loaded for a project is context spent before it has done any work.
-  A skill file -- frontmatter, a body, sometimes a script -- is already snippet-shaped, so curating which skills a project loads, the same way AGENTS.md and CLAUDE.md are curated today, is the natural next composition target: real token savings, not just tidiness.
+- **Skills cost tokens too, so they're composed the same way.** A second, independent library curates which Claude Code Skills a project loads into `.claude/skills/`, so an agent stops paying context for skills a given project never needed.
   See [docs/concepts.md](https://github.com/Rovetown/mdcompose/blob/main/docs/concepts.md).
 
 It makes no network requests and collects no telemetry.
@@ -116,6 +115,10 @@ mdcompose snippet list         the snippets in your library
 mdcompose snippet edit <id>    open one in your editor
 mdcompose snippet remove <id>  delete one
 mdcompose snippet adopt        save a project's embedded snippets to your library
+mdcompose skill list           the skills in your skill library
+mdcompose skill edit <id>      open one in your editor
+mdcompose skill remove <id>    delete one
+mdcompose skill adopt          save a project's embedded skills to your skill library
 mdcompose import <file>        pull sections out of an existing CLAUDE.md or AGENTS.md
 mdcompose convert <src> <dst>  move content between this project's AGENTS.md and CLAUDE.md
 mdcompose eject                stop managing a directory: remove markers, delete the lock
@@ -187,7 +190,7 @@ A few projects cover the same idea of a personal snippet library composed per pr
 What mdcompose does that they do not: import-versus-copy tied to Claude Code's real `@import`; drift detection by hashing one owned block; a committed lock with embedded content so a fork works without the author's library; and real Windows, WSL, and mounted-drive path correctness.
 It deliberately does no format translation: a target receives Markdown, not Cursor rules or Copilot instructions.
 
-**None of them go past agent instructions -- mdcompose plans to.** A skill file is markdown plus optional scripts, same as a snippet; composing a curated skill selection per project the way AGENTS.md and CLAUDE.md are composed today means an agent stops paying context for skills a given project never needed loaded in the first place.
+**None of them go past agent instructions -- mdcompose does.** A skill file is markdown plus frontmatter, same as a snippet; a curated skill selection is composed per project into `.claude/skills/` the same way AGENTS.md and CLAUDE.md are, so an agent stops paying context for skills a given project never needed loaded in the first place.
 
 See [docs/concepts.md](https://github.com/Rovetown/mdcompose/blob/main/docs/concepts.md) for the fuller case for each point.
 

{mdcompose-0.2.0 → mdcompose-0.2.1}/TODO.md

@@ -353,28 +353,23 @@ and parser fuzzing. `platform.py` and the interactive questionary pickers in
 `init` and `import` are the accepted remaining coverage gap; their flag paths
 are fully covered.
 
-### Agent skill composition (Claude Code Skills and equivalents)
-
-Not scoped. Raised during the README rewrite as a marketing point worth
-having a real backing plan for, not yet an OpenSpec change.
-
-- [ ] Explore composing a project's agent-skill files the same way AGENTS.md
-  and CLAUDE.md are composed today: a personal library of reusable skills,
-  picked per project instead of an agent loading every skill unconditionally.
-  A skill (a `SKILL.md`-shaped file: frontmatter plus a body, occasionally a
-  script alongside it) is already close enough to a snippet in shape that the
-  existing managed-block-and-manifest machinery may extend to it directly
-  rather than needing a second mechanism.
-- [ ] The actual argument for doing this, not just the organizational one:
-  every skill an agent does not need loaded for a given project is context it
-  never has to spend, so a curated per-project skill selection is a
-  token-efficiency win. That is the pitch in the README and
-  [`docs/concepts.md`](docs/concepts.md); it has to survive contact with a real design before it
-  becomes more than a pitch.
-- [ ] Revisit once v1 (AGENTS.md/CLAUDE.md composition) is stable. A second
-  composed-file family is exactly the kind of expansion that has to prove it
-  reuses the existing core rather than forking it, the standing bar for
-  everything in this Roadmap section.
+### Agent skill composition follow-ups (base feature and command group shipped)
+
+Composing a project's skill library into `.claude/skills/<id>/SKILL.md` the
+same way AGENTS.md/CLAUDE.md are composed is done (OpenSpec change
+`agent-skill-composition`), and so is managing the skill library itself:
+`skill list`, `skill edit`, `skill remove`, `skill adopt` (OpenSpec change
+`skill-commands`), mirroring `mdcompose snippet` command-for-command. Both
+reused the managed-block-and-manifest core rather than forking it, per the
+standing bar for this Roadmap section. One piece was deliberately cut from
+the base change and is the real remaining backlog:
+
+- [ ] A skill bundled with an accompanying script. The skill library and
+  `mdcompose.lock` model shipped is single-file-per-item throughout, the same
+  as the snippet library; a script-bearing skill needs a directory-shaped
+  library entry, which is a real extension of the "library holds nothing but
+  `.md` files" invariant and deserves its own proposal rather than folding
+  into the base change.
 
 ### Third-party integrations
 

{mdcompose-0.2.0 → mdcompose-0.2.1}/docs/concepts.md

@@ -61,6 +61,8 @@ The frontmatter is regenerated from the library on every run, even when only the
 Deselecting a skill deletes its file outright, and its now-empty `.claude/skills/<id>/` directory with it, rather than leaving an empty block the way AGENTS.md would: an empty `SKILL.md` means nothing to a skill-loading agent.
 An empty or unconfigured skill library never blocks `init`, and the reverse holds too -- an empty snippet library does not stop skills from composing.
 
+The skill library is managed the same way the snippet library is, not only by hand-editing files: `skill list`, `skill edit`, `skill remove`, and `skill adopt` mirror `snippet list`/`snippet edit`/`snippet remove`/`snippet adopt` command-for-command, including `skill adopt` pulling the skills embedded in a cloned project's manifest into your local skill library, with the same explicit, never-automatic collision handling.
+
 ## Drift detection: normalization and hashing
 
 A managed block's hash has to mean the same thing on Windows, under WSL, and on Linux, or a committed lock file could never be trusted across a team.

{mdcompose-0.2.0 → mdcompose-0.2.1}/docs/core-contract.md

@@ -935,6 +935,11 @@ No skill is shipped, generated, or seeded.
 An empty skill library, or one that was never configured, never blocks `init`: AGENTS.md and CLAUDE.md compose exactly as they would without this feature.
 The reverse holds too: an empty snippet library does not stop skills from composing.
 
+### 22.4 The skill commands
+
+`skill list`, `skill edit`, `skill remove`, and `skill adopt` mirror the snippet commands (section 13) exactly, over the skill library instead: same filtering, same editor and non-interactive editing path, same confirm-before-delete, same adopt-from-manifest collision handling with the same keep/overwrite choice and the same normalization-aware identical-content check.
+Adoption reads the manifest's `skills` list (see 9.2, 9.3) the same way `snippet adopt` reads `snippets`, and is exactly as explicit: no other operation ever writes into the skill library, and a manifest with an empty `skills` list is reported as embedding nothing rather than treated as an error or as "no manifest."
+
 ## 23. Skill composition
 
 Each skill selected in a target directory is composed into its own file at `.claude/skills/<id>/SKILL.md`, never blended into a shared block the way snippet bodies are.
@@ -971,4 +976,4 @@ Composing a skill from a manifest this machine did not write (a fresh clone) fol
 ## Not yet specified
 
 Nothing.
-Every planned behavior for v1 is implemented and described above: `doctor`, `init` and `init --global`, `snippet list`, `snippet edit`, `snippet remove`, `snippet adopt`, `import`, `convert`, `config show`, `config set`, `config unset`, `config edit`, `eject` and `eject --global`, `target add`, `target list`, `target remove`, and skill composition as part of `init` (sections 22-23).
+Every planned behavior for v1 is implemented and described above: `doctor`, `init` and `init --global`, `snippet list`, `snippet edit`, `snippet remove`, `snippet adopt`, `skill list`, `skill edit`, `skill remove`, `skill adopt`, `import`, `convert`, `config show`, `config set`, `config unset`, `config edit`, `eject` and `eject --global`, `target add`, `target list`, `target remove`, and skill composition as part of `init` (sections 22-23).

{mdcompose-0.2.0 → mdcompose-0.2.1}/mdcompose/cli.py

@@ -24,6 +24,7 @@ from mdcompose.commands import (
     eject_cmd,
     import_cmd,
     init_cmd,
+    skill_cmd,
     snippet_cmd,
     target_cmd,
 )
@@ -84,6 +85,7 @@ def main(
 
 
 app.add_typer(snippet_cmd.app, name="snippet")
+app.add_typer(skill_cmd.app, name="skill")
 app.add_typer(config_cmd.app, name="config")
 app.add_typer(target_cmd.app, name="target")
 init_cmd.register(app)

mdcompose-0.2.1/mdcompose/commands/skill_cmd.py

@@ -0,0 +1,313 @@
+"""The skill command group: list, edit, remove, adopt.
+
+Mirrors ``snippet_cmd.py`` command-for-command, over the skill library instead
+of the snippet library. A thin adapter, same as its sibling: each command
+parses arguments, resolves the skill library, calls into core, and formats
+the result.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mdcompose.core import config as config_module
+from mdcompose.core import files, skill_library_ops
+from mdcompose.core import manifest as manifest_module
+from mdcompose.core import platform as platform_module
+from mdcompose.core import skills as skills_module
+from mdcompose.core.exit_codes import AttentionError
+from mdcompose.core.output import OutputContext
+from mdcompose.prompts import confirm, output_for, prompt_choice
+
+app = typer.Typer(
+    name="skill",
+    help="Manage the personal skill library.",
+    rich_markup_mode=None,
+    no_args_is_help=True,
+)
+
+QuietOption = Annotated[
+    bool, typer.Option("--quiet", "-q", help="Suppress informational output.")
+]
+JsonOption = Annotated[
+    bool, typer.Option("--json", help="Emit one JSON document on stdout and nothing else.")
+]
+NoColourOption = Annotated[bool, typer.Option("--no-color", help="Never colourize output.")]
+TagOption = Annotated[str | None, typer.Option("--tag", help="Only skills carrying this tag.")]
+CategoryOption = Annotated[
+    str | None, typer.Option("--category", help="Only skills in this category.")
+]
+ContentOption = Annotated[
+    str | None,
+    typer.Option(
+        "--content", help="Replacement file contents. Supplying this skips the editor."
+    ),
+]
+YesOption = Annotated[bool, typer.Option("--yes", "-y", help="Answer yes to every confirmation.")]
+OnCollisionOption = Annotated[
+    str | None,
+    typer.Option(
+        "--on-collision",
+        help="Resolve every collision without asking: keep or overwrite.",
+    ),
+]
+IdsArgument = Annotated[
+    list[str] | None,
+    typer.Argument(help="Skill ids to adopt. Defaults to every embedded skill."),
+]
+
+
+def resolve_library() -> skills_module.LibraryView:
+    """Read the configured skill library once."""
+    directory = platform_module.config_dir()
+    configuration = config_module.load_config(config_module.config_path(directory))
+    return skills_module.view(config_module.skill_library_dir(configuration, directory))
+
+
+@app.command("list")
+def list_skills(
+    context: typer.Context,
+    tag: TagOption = None,
+    category: CategoryOption = None,
+    quiet: QuietOption = False,
+    json_output: JsonOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """List the skills in the skill library.
+
+    Filters narrow rather than widen: supplying both a tag and a category
+    lists only skills matching both. An empty skill library is reported, not
+    an error.
+    """
+    output = output_for(context, quiet=quiet, json_output=json_output, no_colour=no_colour)
+    library = resolve_library()
+    matched = skills_module.filter_skills(library.skills, tag=tag, category=category)
+
+    if output.json_mode:
+        output.emit(_as_json(library, matched))
+        return
+
+    if library.is_empty:
+        output.info(
+            f"the skill library at {library.directory.as_posix()} is empty. "
+            "Add one by writing a markdown file there, or 'mdcompose skill adopt'."
+        )
+        return
+    if not matched:
+        output.info("no skill matches that filter")
+        return
+
+    id_width = max(len(skill.id) for skill in matched)
+    name_width = max(len(skill.display_name) for skill in matched)
+    id_width = max(id_width, len("id"))
+    name_width = max(name_width, len("name"))
+    output.info(f"  {'id'.ljust(id_width)}  {'name'.ljust(name_width)}  description")
+    for skill in matched:
+        row_id = skill.id.ljust(id_width)
+        row_name = skill.display_name.ljust(name_width)
+        description = "" if skill.description is None else skill.description
+        output.info(f"  {row_id}  {row_name}  {description}")
+
+
+def _as_json(
+    library: skills_module.LibraryView, matched: tuple[skills_module.Skill, ...]
+) -> str:
+    return json.dumps(
+        {
+            "library": library.directory.as_posix(),
+            "skills": [
+                {
+                    "id": skill.id,
+                    "title": skill.title,
+                    "description": skill.description,
+                    "tags": list(skill.tags),
+                    "stack_signals": list(skill.stack_signals),
+                    "category": skill.category,
+                }
+                for skill in matched
+            ],
+        },
+        indent=2,
+        ensure_ascii=True,
+    )
+
+
+@app.command("edit")
+def edit_skill(
+    context: typer.Context,
+    skill_id: Annotated[str, typer.Argument(help="The skill to edit.")],
+    content: ContentOption = None,
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Open a skill in the configured editor, or replace its contents directly.
+
+    The result is validated before it is installed, so a broken edit leaves
+    the existing skill exactly as it was.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    library = resolve_library()
+    skill = library.require(skill_id)
+
+    if content is not None:
+        skill_library_ops.replace_body(library, skill_id, content)
+        output.info(f"wrote {skill_id}")
+        return
+
+    if skill.path is None:
+        raise AttentionError(f"skill '{skill_id}' has no file on disk to edit")
+    edited = _edit_in_editor(skill.path)
+    if edited is None:
+        output.info(f"{skill_id} unchanged")
+        return
+    skill_library_ops.replace_body(library, skill_id, edited)
+    output.info(f"wrote {skill_id}")
+
+
+def _edit_in_editor(path: Path) -> str | None:
+    """Open a copy in the editor and return the result, or None if unchanged.
+
+    A copy rather than the file itself, so an edit that fails validation
+    cannot leave the library holding it.
+    """
+    editor = os.environ.get("VISUAL") or os.environ.get("EDITOR")
+    if not editor:
+        raise AttentionError(
+            "no editor configured. Set VISUAL or EDITOR, or pass --content to "
+            "supply the new contents directly."
+        )
+    original = files.read_text(path)
+    with tempfile.TemporaryDirectory() as scratch:
+        draft = Path(scratch) / path.name
+        files.write_text(draft, original)
+        completed = subprocess.run([*shlex.split(editor), str(draft)], check=False)
+        if completed.returncode != 0:
+            raise AttentionError(f"editor exited with status {completed.returncode}")
+        edited = files.read_text(draft)
+    return None if files.content_equal(edited, original) else edited
+
+
+@app.command("remove")
+def remove_skill(
+    context: typer.Context,
+    skill_id: Annotated[str, typer.Argument(help="The skill to delete.")],
+    yes: YesOption = False,
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Delete a skill from the skill library.
+
+    Confirms first. Never touches a project that already composed it:
+    composition copies content, so a composed file keeps working without its
+    source skill.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    library = resolve_library()
+    library.require(skill_id)
+
+    if not confirm(output, f"delete skill '{skill_id}' from the skill library?", assume_yes=yes):
+        output.info(f"kept {skill_id}")
+        return
+    skill_library_ops.remove_skill(library, skill_id)
+    output.info(f"removed {skill_id}")
+
+
+@app.command("adopt")
+def adopt_skills(
+    context: typer.Context,
+    ids: IdsArgument = None,
+    on_collision: OnCollisionOption = None,
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Save the skills embedded in this project's manifest into the skill library.
+
+    Always explicit, never a side effect of composing, because pulling
+    someone else's skills into a personal library should be a deliberate act.
+    Touches no project file and no manifest.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    project_root = Path.cwd()
+    manifest = manifest_module.load_manifest(manifest_module.manifest_path(project_root))
+    if manifest is None:
+        raise AttentionError(
+            f"{project_root.as_posix()} has no {manifest_module.MANIFEST_FILENAME}, "
+            "so there is nothing to adopt"
+        )
+
+    library = resolve_library()
+    plan = skill_library_ops.plan_adopt(manifest, library, only=tuple(ids or ()))
+    if plan.is_empty:
+        output.info("the manifest embeds no skills")
+        return
+
+    resolutions = _resolve_collisions(output, plan, on_collision)
+    result = skill_library_ops.apply_adopt(plan, library.directory, resolutions=resolutions)
+    _report_adoption(output, result)
+
+
+def _resolve_collisions(
+    output: OutputContext,
+    plan: skill_library_ops.AdoptPlan,
+    on_collision: str | None,
+) -> dict[str, skill_library_ops.Resolution]:
+    """Decide what to do about each collision, by flag or by asking."""
+    if not plan.collisions:
+        return {}
+    if on_collision is not None:
+        decision = _validated_resolution(on_collision)
+        return {collision.skill_id: decision for collision in plan.collisions}
+
+    resolutions: dict[str, skill_library_ops.Resolution] = {}
+    for collision in plan.collisions:
+        output.warn(
+            f"skill '{collision.skill_id}' already exists in the skill library with "
+            "different content"
+        )
+        _show_difference(output, collision)
+        answer = prompt_choice(
+            output,
+            f"skill '{collision.skill_id}'",
+            options=skill_library_ops.RESOLUTIONS,
+            default=skill_library_ops.KEEP,
+            flag="--on-collision",
+        )
+        resolutions[collision.skill_id] = answer  # type: ignore[assignment]
+    return resolutions
+
+
+def _validated_resolution(candidate: str) -> skill_library_ops.Resolution:
+    if candidate not in skill_library_ops.RESOLUTIONS:
+        raise AttentionError(
+            f"--on-collision must be one of {', '.join(skill_library_ops.RESOLUTIONS)}, "
+            f"found '{candidate}'"
+        )
+    return candidate
+
+
+def _show_difference(output: OutputContext, collision: skill_library_ops.Collision) -> None:
+    """Show both versions, so the choice is made with the content in view."""
+    output.info(f"  skill library copy of '{collision.skill_id}':")
+    output.content_indented(collision.local)
+    output.info(f"  embedded copy of '{collision.skill_id}':")
+    output.content_indented(collision.embedded)
+
+
+def _report_adoption(output: OutputContext, result: skill_library_ops.AdoptResult) -> None:
+    for outcome, phrasing in (
+        ("written", "adopted"),
+        ("overwritten", "overwrote"),
+        ("already-present", "already present"),
+        ("kept", "kept the skill library copy of"),
+    ):
+        named = result.ids_with(outcome)  # type: ignore[arg-type]
+        if named:
+            output.info(f"  {phrasing}: {', '.join(named)}")