mdcompose 0.2.1__tar.gz → 0.3.0__tar.gz

{mdcompose-0.2.1 → 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.1 → mdcompose-0.3.0}/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.3.0 (2026-09-18)
+
+### Added
+
+- support script-bearing skills as directory entries (#17)
+
 ## v0.2.1 (2026-09-14)
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdcompose
-Version: 0.2.1
+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

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

@@ -353,7 +353,7 @@ 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 follow-ups (base feature and command group shipped)
+### 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
@@ -361,15 +361,21 @@ same way AGENTS.md/CLAUDE.md are composed is done (OpenSpec change
 `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.
+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.1 → 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
@@ -943,6 +954,7 @@ Adoption reads the manifest's `skills` list (see 9.2, 9.3) the same way `snippet
 ## 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
 
@@ -962,16 +974,18 @@ 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
 

{mdcompose-0.2.1 → 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(

{mdcompose-0.2.1 → mdcompose-0.3.0}/mdcompose/commands/skill_cmd.py

@@ -51,6 +51,13 @@ ContentOption = Annotated[
         "--content", help="Replacement file contents. Supplying this skips the editor."
     ),
 ]
+FileOption = Annotated[
+    str | None,
+    typer.Option(
+        "--file",
+        help="Which file to edit, relative to the skill's own directory. Defaults to SKILL.md.",
+    ),
+]
 YesOption = Annotated[bool, typer.Option("--yes", "-y", help="Answer yes to every confirmation.")]
 OnCollisionOption = Annotated[
     str | None,
@@ -114,7 +121,8 @@ def list_skills(
         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}")
+        marker = " [bundle]" if skill.is_bundle else ""
+        output.info(f"  {row_id}  {row_name}  {description}{marker}")
 
 
 def _as_json(
@@ -131,6 +139,7 @@ def _as_json(
                     "tags": list(skill.tags),
                     "stack_signals": list(skill.stack_signals),
                     "category": skill.category,
+                    "is_bundle": skill.is_bundle,
                 }
                 for skill in matched
             ],
@@ -145,38 +154,56 @@ def edit_skill(
     context: typer.Context,
     skill_id: Annotated[str, typer.Argument(help="The skill to edit.")],
     content: ContentOption = None,
+    file: FileOption = 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.
+    the existing skill exactly as it was. ``--file`` targets an accompanying
+    file of a directory-shaped skill instead of ``SKILL.md``; naming one
+    against a skill with no accompanying files is refused up front.
     """
     output = output_for(context, quiet=quiet, no_colour=no_colour)
     library = resolve_library()
     skill = library.require(skill_id)
+    if file is not None and file != skills_module.SKILL_MD_FILENAME and not skill.is_bundle:
+        raise AttentionError(f"skill '{skill_id}' has no accompanying files")
 
     if content is not None:
-        skill_library_ops.replace_body(library, skill_id, content)
+        skill_library_ops.replace_body(library, skill_id, content, relative=file)
         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)
+    edited = _edit_in_editor(_edit_target_path(skill, file))
     if edited is None:
         output.info(f"{skill_id} unchanged")
         return
-    skill_library_ops.replace_body(library, skill_id, edited)
+    skill_library_ops.replace_body(library, skill_id, edited, relative=file)
     output.info(f"wrote {skill_id}")
 
 
+def _edit_target_path(skill: skills_module.Skill, file: str | None) -> Path:
+    """Where to read the current content from for an interactive edit.
+
+    A new accompanying file named by ``--file`` has no path yet; that is left
+    to ``_edit_in_editor``, which treats a nonexistent path as empty content.
+    """
+    if file is None or file == skills_module.SKILL_MD_FILENAME:
+        if skill.path is None:
+            raise AttentionError(f"skill '{skill.id}' has no file on disk to edit")
+        return skill.path
+    assert skill.path is not None  # guaranteed by the is_bundle check in edit_skill
+    return skill.path.parent / file
+
+
 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.
+    cannot leave the library holding it. A path that does not exist yet (a
+    new accompanying file) starts from empty content rather than refusing.
     """
     editor = os.environ.get("VISUAL") or os.environ.get("EDITOR")
     if not editor:
@@ -184,7 +211,7 @@ def _edit_in_editor(path: Path) -> str | None:
             "no editor configured. Set VISUAL or EDITOR, or pass --content to "
             "supply the new contents directly."
         )
-    original = files.read_text(path)
+    original = files.read_text(path) if files.path_exists(path) else ""
     with tempfile.TemporaryDirectory() as scratch:
         draft = Path(scratch) / path.name
         files.write_text(draft, original)
@@ -294,11 +321,17 @@ def _validated_resolution(candidate: str) -> skill_library_ops.Resolution:
 
 
 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)
+    """Show both versions of every differing file, so the choice is made with
+    the content in view. A bundle skill's collision names each differing
+    accompanying file; a plain skill's names none, since there is only ever
+    the one file to show.
+    """
+    for path in collision.differing_paths:
+        label = "" if path == skills_module.SKILL_MD_FILENAME else f" ({path})"
+        output.info(f"  skill library copy of '{collision.skill_id}'{label}:")
+        output.content_indented(collision.local.get(path, ""))
+        output.info(f"  embedded copy of '{collision.skill_id}'{label}:")
+        output.content_indented(collision.embedded.get(path, ""))
 
 
 def _report_adoption(output: OutputContext, result: skill_library_ops.AdoptResult) -> None:

{mdcompose-0.2.1 → mdcompose-0.3.0}/mdcompose/core/init_ops.py

@@ -55,13 +55,21 @@ class FileTarget:
 
     ``frontmatter`` is ``None`` for AGENTS.md/CLAUDE.md, where nothing sits
     outside the managed block that mdcompose itself generates. It is set for
-    a skill target, whose ``name``/``description`` frontmatter must precede
-    the block and is regenerated on every write; see ``skill_composition.py``.
+    a skill's ``SKILL.md`` target, whose ``name``/``description`` frontmatter
+    must precede the block and is regenerated on every write; see
+    ``skill_composition.py``.
+
+    ``block_id`` is ``None`` for a directory-shaped skill's accompanying file,
+    which has no managed block at all: the whole file is mdcompose's, written
+    and drift-checked as a unit (see ``skill_composition.apply_accompanying_file``
+    and ``manifest.py``'s drift handling for an entry with no block id). Such a
+    target also carries no frontmatter, which together with a ``None``
+    ``block_id`` is what distinguishes it from every other target.
     """
 
     key: str
     path: Path
-    block_id: str
+    block_id: str | None
     content: str
     relative_path: str
     frontmatter: str | None = None
@@ -233,10 +241,17 @@ def skills_from_manifest(manifest: manifest_module.Manifest) -> tuple[Skill, ...
     """Build a skill selection from a manifest's embedded content.
 
     Used on the clone path, where the local skill library may be empty or
-    may not have this skill at all.
+    may not have this skill at all. A skill entry carrying embedded
+    accompanying files reconstructs as a directory-shaped skill.
     """
     return tuple(
-        Skill(id=entry.id, body=entry.content) for entry in manifest.skills_in_order()
+        Skill(
+            id=entry.id,
+            body=entry.content,
+            is_bundle=bool(entry.files),
+            files=dict(entry.files),
+        )
+        for entry in manifest.skills_in_order()
     )
 
 
@@ -361,9 +376,7 @@ def plan(
         from_embedded=from_embedded,
         skill_selection=skill_selection,
         skill_selection_source=skill_source,
-        stale_skill_paths=_stale_skill_paths(
-            root, manifest, tuple(skill.id for skill in skill_selection)
-        ),
+        stale_skill_paths=_stale_skill_paths(root, manifest, skill_selection),
     )
 
 
@@ -394,25 +407,37 @@ def _detect(
 
 
 def _stale_skill_paths(
-    root: Path, manifest: manifest_module.Manifest | None, current_skill_ids: tuple[str, ...]
+    root: Path, manifest: manifest_module.Manifest | None, selection: Sequence[Skill]
 ) -> tuple[Path, ...]:
-    """Manifest-recorded skill files not in the current selection, by full path.
+    """Manifest-recorded skill files no longer part of the selection, by full path.
 
     Anything in ``manifest.files`` keyed by something other than the two
-    well-known AGENTS.md/CLAUDE.md keys is a skill entry, since this is the
-    only feature that ever writes a third kind of key.
+    well-known AGENTS.md/CLAUDE.md keys is a skill entry: either a skill's own
+    id (its ``SKILL.md``), or ``<skill id>:<relative path>`` (one of its
+    accompanying files; see ``manifest.py``'s schema). A file is stale when its
+    owning skill is no longer selected at all, or, for an accompanying file,
+    when that skill is still selected but no longer carries that particular
+    file.
     """
     if manifest is None:
         return ()
-    current = set(current_skill_ids)
+    current_files = {skill.id: set(skill.files) for skill in selection}
     return tuple(
         root / entry.path
         for key, entry in manifest.files.items()
         if key not in {manifest_module.AGENTS_MD_KEY, manifest_module.CLAUDE_MD_KEY}
-        and key not in current
+        and _is_stale_skill_key(key, current_files)
     )
 
 
+def _is_stale_skill_key(key: str, current_files: Mapping[str, set[str]]) -> bool:
+    """Whether a skill-keyed manifest entry no longer belongs to the selection."""
+    skill_id, _, relative = key.partition(":")
+    if skill_id not in current_files:
+        return True
+    return bool(relative) and relative not in current_files[skill_id]
+
+
 def _recorded_mode(manifest: manifest_module.Manifest | None) -> Mode | None:
     if manifest is None:
         return None
@@ -480,16 +505,40 @@ def _targets(
 
 
 def _skill_targets(root: Path, selection: Sequence[Skill]) -> tuple[FileTarget, ...]:
+    targets: list[FileTarget] = []
+    for skill in selection:
+        targets.append(
+            FileTarget(
+                key=skill.id,
+                path=skill_composition.skill_path(root, skill.id),
+                block_id=managed_block.SKILL_MANAGED_BLOCK,
+                content=_skill_body(skill),
+                relative_path=skill_composition.skill_path(Path(), skill.id).as_posix(),
+                frontmatter=skill_composition.render_frontmatter(skill),
+            )
+        )
+        targets.extend(_accompanying_targets(root, skill))
+    return tuple(targets)
+
+
+def _accompanying_targets(root: Path, skill: Skill) -> tuple[FileTarget, ...]:
+    """One target per accompanying file of a directory-shaped skill.
+
+    ``block_id`` is ``None`` and ``frontmatter`` is left at its default,
+    which together mark this as neither a ``SKILL.md`` target nor an
+    AGENTS.md/CLAUDE.md target: see ``FileTarget``.
+    """
+    skill_dir = skill_composition.skill_path(root, skill.id).parent
+    relative_skill_dir = skill_composition.skill_path(Path(), skill.id).parent
     return tuple(
         FileTarget(
-            key=skill.id,
-            path=skill_composition.skill_path(root, skill.id),
-            block_id=managed_block.SKILL_MANAGED_BLOCK,
-            content=_skill_body(skill),
-            relative_path=skill_composition.skill_path(Path(), skill.id).as_posix(),
-            frontmatter=skill_composition.render_frontmatter(skill),
+            key=f"{skill.id}:{relative}",
+            path=skill_dir / relative,
+            block_id=None,
+            content=content,
+            relative_path=(relative_skill_dir / relative).as_posix(),
         )
-        for skill in selection
+        for relative, content in sorted(skill.files.items())
     )
 
 
@@ -529,9 +578,12 @@ def apply(
             entries[target.key] = _entry_for_existing(target, plan_to_apply)
             continue
         if target.frontmatter is not None:
+            assert target.block_id is not None  # a SKILL.md target always has one
             changed = skill_composition.apply_to_file(
                 target.path, target.block_id, target.content, target.frontmatter
             )
+        elif target.block_id is None:
+            changed = skill_composition.apply_accompanying_file(target.path, target.content)
         else:
             changed = composition.apply_to_file(target.path, target.block_id, target.content)
         if changed:
@@ -563,25 +615,42 @@ def apply(
 
 
 def _delete_stale_skill_files(paths: Sequence[Path]) -> tuple[str, ...]:
-    """Delete a manifest-recorded skill file no longer in the selection.
-
-    Removes the skill's directory afterward only if it is now empty, never a
-    directory the user has put something else into.
+    """Delete manifest-recorded skill files no longer part of the selection.
+
+    Removes empty directories left behind afterward, walking upward from each
+    deleted file's parent. The walk stops at, and never removes, the shared
+    `.claude/skills` directory itself, never a directory the user has put
+    something else into, and it revisits a directory left empty by an earlier
+    deletion in the same batch (a bundle skill's own directory can become
+    empty only after its last accompanying file is gone).
     """
     deleted: list[str] = []
     for path in paths:
         if files.path_exists(path) and path.is_file():
             path.unlink()
             deleted.append(path.as_posix())
-        parent = path.parent
-        if files.path_exists(parent) and parent.is_dir() and not any(parent.iterdir()):
-            parent.rmdir()
+        _remove_empty_ancestors(path.parent)
     return tuple(deleted)
 
 
+def _remove_empty_ancestors(directory: Path) -> None:
+    current = directory
+    while (
+        files.path_exists(current)
+        and current.is_dir()
+        and current.name != skill_composition.SKILLS_DIR_NAME
+        and not any(current.iterdir())
+    ):
+        parent = current.parent
+        current.rmdir()
+        current = parent
+
+
 def _entry_mode(target: FileTarget, plan_to_apply: InitPlan) -> Mode:
     """A skill target has no import/copy distinction; it is always materialized."""
-    return composition.COPY if target.frontmatter is not None else plan_to_apply.mode
+    if target.frontmatter is not None or target.block_id is None:
+        return composition.COPY
+    return plan_to_apply.mode
 
 
 def _entry_for(target: FileTarget, plan_to_apply: InitPlan) -> manifest_module.FileEntry:
@@ -602,11 +671,15 @@ def _entry_for_existing(
     Recording what is actually there, rather than what mdcompose would have
     written, is what stops the same drift being reported on every later run. It
     also means a clone reproduces the kept version rather than the one the user
-    deliberately replaced.
+    deliberately replaced. An accompanying file has no managed block to read
+    the kept content from: the whole file is what was kept.
     """
-    result = managed_block.read_blocks(target.path)
-    block = result.find(target.block_id)
-    content = target.content if block is None else block.content
+    if target.block_id is None:
+        content = files.read_text(target.path)
+    else:
+        result = managed_block.read_blocks(target.path)
+        block = result.find(target.block_id)
+        content = target.content if block is None else block.content
     return manifest_module.FileEntry(
         path=target.relative_path,
         mode=_entry_mode(target, plan_to_apply),
@@ -630,6 +703,8 @@ def _snippet_entries(selection: Sequence[Snippet]) -> tuple[manifest_module.Snip
 
 def _skill_entries(selection: Sequence[Skill]) -> tuple[manifest_module.SkillEntry, ...]:
     return tuple(
-        manifest_module.SkillEntry(id=skill.id, position=index, content=skill.body)
+        manifest_module.SkillEntry(
+            id=skill.id, position=index, content=skill.body, files=dict(skill.files)
+        )
         for index, skill in enumerate(selection)
     )