mdcompose 0.2.0__tar.gz → 0.3.0__tar.gz

{mdcompose-0.2.0 → mdcompose-0.3.0}/.pre-commit-config.yaml

@@ -37,13 +37,13 @@ repos:
       - id: check-merge-conflict
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.16.6
+    rev: v0.16.7
     hooks:
       - id: ruff-check
         args: [--fix]
 
   - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.30.1
+    rev: v8.30.0
     hooks:
       - id: gitleaks
 
@@ -63,7 +63,7 @@ repos:
       - id: check-github-workflows
 
   - repo: https://github.com/commitizen-tools/commitizen
-    rev: v4.18.0
+    rev: v4.18.1
     hooks:
       - id: commitizen
         stages: [commit-msg]

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

@@ -3,6 +3,18 @@
 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.3.0 (2026-09-18)
+
+### Added
+
+- support script-bearing skills as directory entries (#17)
+
+## 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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdcompose
-Version: 0.2.0
+Version: 0.3.0
 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.3.0}/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.3.0}/TODO.md

@@ -353,28 +353,29 @@ 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 (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.
+
+A skill bundled with an accompanying script is also done (OpenSpec change
+`skill-script-bundle`). The skill library entry is now either the original
+single `.md` file or a directory (`<id>/SKILL.md` plus accompanying files at
+other relative paths), sharing one id namespace; `mdcompose.lock` schema
+version 3 embeds a directory-shaped skill's accompanying files under the
+entry's `files` field; composition writes and drift-tracks each accompanying
+file by a whole-file hash, since a script has no managed-block-safe comment
+syntax; `skill list/edit/remove/adopt` all handle a directory-shaped entry,
+with `--file` on `skill edit` targeting one accompanying file. See the
+change's design.md for the full decision log (file-or-directory-never-both,
+UTF-8-text-only accompanying files, no binary support).
+
+Nothing open in this area.
 
 ### Third-party integrations
 

{mdcompose-0.2.0 → mdcompose-0.3.0}/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.3.0}/docs/core-contract.md

@@ -421,7 +421,7 @@ An implementation does not add the manifest to any ignore file, and does not tre
 
 | Field | Meaning |
 | ----- | ------- |
-| schema version | the format this file was written in (2 as of skill composition) |
+| schema version | the format this file was written in (3 as of the skill script bundle) |
 | generated by | the version string of the mdcompose that wrote it |
 | generated at | when it was written |
 | detected stack | the signal files found when it was composed |
@@ -429,12 +429,16 @@ An implementation does not add the manifest to any ignore file, and does not tre
 | skills | the composed skills, in order, with content embedded (see 22) |
 | files | one entry per managed file, keyed by which file it is |
 
-`files` is keyed `agents_md` and `claude_md` for the composed pair, and by a skill's own id for each composed skill file (see 22.2).
-Each file entry carries a project-relative path, a mode of `import` or `copy` (a skill entry always carries `copy`, since a skill is always materialized), the recorded hash of that file's managed block, and which block id that hash refers to.
+`files` is keyed `agents_md` and `claude_md` for the composed pair, by a skill's own id for that skill's composed `SKILL.md`, and by `<skill id>:<relative path>` for each of a directory-shaped skill's composed accompanying files (see 22.2, 23.4).
+Each file entry carries a project-relative path, a mode of `import` or `copy` (a skill entry always carries `copy`, since a skill is always materialized), and a recorded hash.
+For an `agents_md`, `claude_md`, or `SKILL.md` entry that hash covers the entry's managed block, alongside which block id it refers to; for an accompanying-file entry it covers the whole file instead, and the entry carries no block id at all (see 10).
 An import-mode entry also records what it imports.
 
+Each skill entry may carry a `files` field: a mapping from an accompanying file's path, relative to the skill's own directory, to its embedded content. It is present only for a directory-shaped skill and is empty or absent for the common, file-shaped one, so a schema-2 manifest (which never wrote it) still reads unchanged.
+
 A schema-1 manifest carries no `skills` list and no per-entry block id.
 It still reads: no skills are recorded, and `agents_md`/`claude_md` fall back to their well-known block ids.
+A schema-2 manifest carries no `files` field on a skill entry; it still reads, with every skill resolving as file-shaped.
 
 Unrecognized fields are preserved on read.
 A schema version higher than the implementation understands is refused, naming the file and both versions, rather than read with the wrong field meanings.
@@ -474,6 +478,9 @@ Restoring a deleted file is not the same operation as reconciling an edited bloc
 Because the hash covers only the block, an edit outside the block is clean.
 And because content is normalized before hashing, a fresh clone is clean regardless of the line ending convention the checkout used.
 
+A file entry with no block id at all, which is what a skill's accompanying file always records (see 9.2), is compared by a hash of its whole normalized content instead of a block's: clean or drifted only, since there is no block to remove or markers to malform.
+A directory recorded where a file is expected reads as missing, the same as a genuinely absent path.
+
 Detection reads only.
 Neither the managed files nor the manifest is modified by determining their state.
 
@@ -915,9 +922,13 @@ The registrations themselves are kept: a later global write restores the project
 
 ## 22. The skill library
 
-A second library, entirely independent of the snippet library: a flat directory of markdown files, one skill per file, YAML frontmatter then body, filename minus `.md` as the id.
+A second library, entirely independent of the snippet library: a flat directory of skills, one entry per skill.
 Configured and defaulted the same way as the snippet library (a `skills` sibling directory, or an explicit `skill_library_path`), and just as readable and editable without mdcompose installed.
 
+A skill entry is one of two shapes. Usually it is a single markdown file, YAML frontmatter then body, filename minus `.md` as the id. It may instead be a directory, named by the id, holding `SKILL.md` (parsed the same way as the file shape) plus zero or more accompanying files (a script, a config) at other relative paths inside that directory. A directory with no `SKILL.md` is not a skill and is left alone, the same as any other unrecognized entry. Both shapes share one id namespace: a bare `<id>.md` file and an `<id>/` directory both present for the same id is refused rather than one silently winning.
+
+An accompanying file's identity within its skill is its path relative to the skill's directory. It is read and written as UTF-8 text under the same size limit, byte order mark handling, and line-ending preservation as every other file mdcompose handles; a file past the limit, or not valid UTF-8, is refused by name. No binary asset support.
+
 ### 22.1 Frontmatter
 
 A skill's frontmatter supports `title`, `description`, `tags`, `stack_signals`, and `category`.
@@ -926,7 +937,7 @@ An unrecognized field is ignored; a wrong-typed known field is refused, naming t
 
 ### 22.2 mdcompose writes only skill files into the skill library
 
-Nothing but a skill `.md` file is written into the skill library directory: no index, no cache, no bookkeeping.
+Nothing but a skill's own files is written into the skill library directory: no index, no cache, no bookkeeping. For a directory-shaped skill that means `SKILL.md` plus its accompanying files, at their recorded relative paths, inside the skill's own directory and nowhere else; a file the user placed in that directory by hand is left untouched and never composed.
 A skill id of exactly `agents_md` or `claude_md` is refused, since either would collide with the manifest's two well-known `files` keys.
 
 ### 22.3 The skill library starts empty and is independently optional
@@ -935,9 +946,15 @@ 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.
+A directory-shaped skill additionally composes every accompanying file at the same relative path under `.claude/skills/<id>/` that it occupies in the skill library.
 
 ### 23.1 Managed block and frontmatter
 
@@ -957,18 +974,20 @@ Re-running `init` reopens the skill picker with the manifest's recorded selectio
 
 ### 23.3 Deselecting deletes
 
-Unlike a deselected snippet, which leaves its managed block empty, a deselected skill has its `SKILL.md` file deleted outright, and its `.claude/skills/<id>/` directory removed if that leaves it empty.
-A directory the user has put another file into is left in place; only the `SKILL.md` file is removed.
-An empty file has no meaning to a skill-loading agent, where an empty block still leaves a valid, if empty, AGENTS.md.
+Unlike a deselected snippet, which leaves its managed block empty, a deselected skill has every file mdcompose composed for it deleted outright: `SKILL.md`, and, for a directory-shaped skill, every accompanying file the manifest recorded. Its `.claude/skills/<id>/` directory, and any now-empty subdirectory an accompanying file's relative path created, are removed afterward if that leaves them empty.
+A directory (or subdirectory) the user has put another file into is left in place; only the files mdcompose composed are removed.
+An empty `SKILL.md` has no meaning to a skill-loading agent, where an empty block still leaves a valid, if empty, AGENTS.md.
+
+A skill can also stay selected while one of its accompanying files is dropped from the library between runs: that file alone is deleted, by the same rule, without touching `SKILL.md` or the skill's other files.
 
 ### 23.4 Manifest and drift
 
-A composed skill gets a `files` entry keyed by its own id (see 9.2) and an entry in the manifest's `skills` list, embedding its full content the same way a snippet's is embedded.
-Drift detection is the same shared operation used for every managed file; it needs nothing skill-specific, since a `files` entry already names its own block id.
+A composed skill gets a `files` entry keyed by its own id for `SKILL.md` (see 9.2), one further `files` entry per accompanying file keyed `<skill id>:<relative path>`, and an entry in the manifest's `skills` list embedding `SKILL.md`'s content the same way a snippet's is embedded, plus its accompanying files' content under the entry's own `files` field.
+`SKILL.md`'s drift is the same shared managed-block operation used for every managed file; an accompanying file's drift is the same operation's whole-file-hash path (see 10), since its `files` entry carries no block id.
 
-Composing a skill from a manifest this machine did not write (a fresh clone) follows the same confirmation flow as AGENTS.md and CLAUDE.md: the content is shown before anything is written, and a flag supplies the confirmation non-interactively.
+Composing a skill from a manifest this machine did not write (a fresh clone) follows the same confirmation flow as AGENTS.md and CLAUDE.md: the content is shown before anything is written, and a flag supplies the confirmation non-interactively. For a directory-shaped skill this covers every accompanying file as well as `SKILL.md`.
 
 ## 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.3.0}/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.0 → mdcompose-0.3.0}/mdcompose/commands/init_cmd.py

@@ -482,14 +482,24 @@ def _show_drift(output: OutputContext, target: init_ops.FileTarget | None) -> No
     """Show what is there against what would replace it."""
     if target is None:
         return
-    result = managed_block.read_blocks(target.path)
-    block = result.find(target.block_id)
     output.info("  currently:")
-    output.content_indented("" if block is None else block.content, empty="    (empty)")
+    output.content_indented(_current_content(target), empty="    (empty)")
     output.info("  would become:")
     output.content_indented(target.content, empty="    (empty)")
 
 
+def _current_content(target: init_ops.FileTarget) -> str:
+    """What is on disk now, at the granularity drift for this target compares.
+
+    An accompanying file has no managed block: the whole file is what is
+    being compared, so the whole file is what is shown.
+    """
+    if target.block_id is None:
+        return files.read_text(target.path)
+    block = managed_block.read_blocks(target.path).find(target.block_id)
+    return "" if block is None else block.content
+
+
 def _validated_drift_choice(candidate: str) -> init_ops.DriftChoice:
     if candidate not in init_ops.DRIFT_CHOICES:
         raise AttentionError(