markdown-docx 0.1.0__tar.gz → 0.2.0__tar.gz

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/.github/workflows/ci.yml

@@ -60,6 +60,9 @@ jobs:
       - name: Run tests
         run: uv run pytest
 
+      - name: Smoke-test editable skill lifecycle
+        run: uv run python scripts/smoke_skill.py --expected-source local
+
   visual-smoke:
     runs-on: ubuntu-latest
     steps:
@@ -115,6 +118,7 @@ jobs:
           .wheel-smoke/bin/python -m pip install dist/*.whl
           .wheel-smoke/bin/markdown-docx --version
           .wheel-smoke/bin/markdown-docx --syntax --json
+          .wheel-smoke/bin/python scripts/smoke_skill.py
           echo '# Wheel smoke test' > smoke.md
           .wheel-smoke/bin/markdown-docx smoke.md smoke.docx
 

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/.github/workflows/publish-pypi.yml

@@ -42,6 +42,9 @@ jobs:
       - name: Run tests
         run: uv run pytest
 
+      - name: Smoke-test editable skill lifecycle
+        run: uv run python scripts/smoke_skill.py --expected-source local
+
       - name: Verify release tag matches package version
         if: github.event_name == 'release' && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
         shell: bash
@@ -83,6 +86,7 @@ jobs:
           .wheel-smoke/bin/python -m pip install dist/*.whl
           .wheel-smoke/bin/markdown-docx --version
           .wheel-smoke/bin/markdown-docx --inspect-template --json
+          .wheel-smoke/bin/python scripts/smoke_skill.py
 
       - name: Upload distributions
         uses: actions/upload-artifact@v7.0.1

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0
+
+- Synchronize existing pristine managed skills to the running CLI version during normal commands.
+- Store managed ownership, version, and normalized content hashes in `SKILL.md` front matter. Migrate legacy managed skills and recover invalid version metadata.
+- Add read-only skill status and force installation for managed edits. Preserve custom directory support, removal safety, and JSON output.
+- Skip automatic synchronization for local source and editable builds. Add atomic replacement, concurrent-change checks, and installed-wheel lifecycle smoke tests.
+
 ## 0.1.0
 
 - Add strict Markdown parsing with invisible YAML directives and line-aware diagnostics.

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: markdown-docx
-Version: 0.1.0
+Version: 0.2.0
 Summary: Convert constrained Markdown documents into editable Word files.
 Project-URL: Homepage, https://github.com/pseudosavant/markdown-docx
 Project-URL: Repository, https://github.com/pseudosavant/markdown-docx
@@ -24,6 +24,7 @@ Classifier: Topic :: Text Processing :: Markup
 Requires-Python: >=3.11
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: markdown-it-py<5,>=3.0
+Requires-Dist: packaging>=24.0
 Requires-Dist: pillow<13,>=10.0
 Requires-Dist: python-docx==1.2.0
 Requires-Dist: pyyaml<7,>=6.0
@@ -53,6 +54,39 @@ Then ask an agent to create both the Markdown source and the editable Word outpu
 
 The skill teaches the agent how to inspect the format, inspect blank Word templates, render safely, and handle structured results.
 
+## Manage the agent skill
+
+The standard location is `~/.agents/skills/markdown-docx/SKILL.md`. Normally installed CLI builds automatically synchronize an already-installed managed skill during ordinary commands, including help and version output. The running CLI version is the authority. A pristine older skill is replaced with the bundled skill. Equal and newer versions are left alone. Missing and unmanaged skills are never installed or overwritten automatically.
+
+Synchronization is local. It does not query a package index, refresh uv's cache, or update the CLI. The skill continues to instruct agents to use `uvx markdown-docx`. Updates affect future skill loading. Instructions already loaded by a running agent may stay unchanged until the agent reloads them.
+
+Inspect the skill without changing it:
+
+```powershell
+uvx markdown-docx skill status
+uvx markdown-docx skill status --json
+```
+
+Status reports the selected path, ownership, CLI and skill versions, version ordering, integrity, and automatic synchronization eligibility. Modified or unverifiable skills with valid version metadata are preserved. To replace a managed skill intentionally:
+
+```powershell
+uvx markdown-docx skill install --force
+```
+
+Install `--force` still refuses unmanaged content and never downgrades a newer skill. A normal install creates a missing skill, updates a pristine older skill, or leaves a current skill alone. Legacy managed skills and managed skills with missing or invalid version metadata receive a fresh replacement. This recovery does not require a valid hash.
+
+Custom directories require explicit updates. Automatic synchronization only checks the standard directory. Local source and editable development builds skip automatic synchronization, but explicit installation still works:
+
+```powershell
+uvx markdown-docx skill install --skills-dir PATH
+uvx markdown-docx skill status --skills-dir PATH
+uvx --from . markdown-docx skill install
+```
+
+Remove the skill with `uvx markdown-docx skill remove`. Removal refuses unmanaged content and extra files unless `--force` is supplied. All skill commands accept `--skills-dir` and `--json`. Skill commands never trigger automatic synchronization. Maintenance notices go to stderr and leave JSON stdout intact.
+
+See [skill lifecycle metadata and decisions](docs/skill-management.md) for the hash format and recovery rules.
+
 ## Use the CLI directly
 
 ```powershell
@@ -74,7 +108,7 @@ uvx markdown-docx --syntax --json
 
 ## Supported Markdown
 
-Version 0.1.0 supports:
+Version 0.2.0 supports:
 
 - ATX headings from `#` through `######`
 - Paragraphs and standard soft or hard line breaks
@@ -86,7 +120,7 @@ Version 0.1.0 supports:
 - Local and remote inline images
 - Standalone images with width and alignment metadata
 
-Links are rejected in 0.1.0. `python-docx` 1.2.0 can read hyperlinks but has no supported public API for creating them. The source alt text for images remains meaningful Markdown content, but the same library release has no public API for embedding it in a Word drawing. A rendered document containing images reports `image_alt_text_not_embedded` in its warning list.
+Links are rejected in 0.2.0. `python-docx` 1.2.0 can read hyperlinks but has no supported public API for creating them. The source alt text for images remains meaningful Markdown content, but the same library release has no public API for embedding it in a Word drawing. A rendered document containing images reports `image_alt_text_not_embedded` in its warning list.
 
 The following syntax is intentionally unsupported:
 

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/README.md

@@ -22,6 +22,39 @@ Then ask an agent to create both the Markdown source and the editable Word outpu
 
 The skill teaches the agent how to inspect the format, inspect blank Word templates, render safely, and handle structured results.
 
+## Manage the agent skill
+
+The standard location is `~/.agents/skills/markdown-docx/SKILL.md`. Normally installed CLI builds automatically synchronize an already-installed managed skill during ordinary commands, including help and version output. The running CLI version is the authority. A pristine older skill is replaced with the bundled skill. Equal and newer versions are left alone. Missing and unmanaged skills are never installed or overwritten automatically.
+
+Synchronization is local. It does not query a package index, refresh uv's cache, or update the CLI. The skill continues to instruct agents to use `uvx markdown-docx`. Updates affect future skill loading. Instructions already loaded by a running agent may stay unchanged until the agent reloads them.
+
+Inspect the skill without changing it:
+
+```powershell
+uvx markdown-docx skill status
+uvx markdown-docx skill status --json
+```
+
+Status reports the selected path, ownership, CLI and skill versions, version ordering, integrity, and automatic synchronization eligibility. Modified or unverifiable skills with valid version metadata are preserved. To replace a managed skill intentionally:
+
+```powershell
+uvx markdown-docx skill install --force
+```
+
+Install `--force` still refuses unmanaged content and never downgrades a newer skill. A normal install creates a missing skill, updates a pristine older skill, or leaves a current skill alone. Legacy managed skills and managed skills with missing or invalid version metadata receive a fresh replacement. This recovery does not require a valid hash.
+
+Custom directories require explicit updates. Automatic synchronization only checks the standard directory. Local source and editable development builds skip automatic synchronization, but explicit installation still works:
+
+```powershell
+uvx markdown-docx skill install --skills-dir PATH
+uvx markdown-docx skill status --skills-dir PATH
+uvx --from . markdown-docx skill install
+```
+
+Remove the skill with `uvx markdown-docx skill remove`. Removal refuses unmanaged content and extra files unless `--force` is supplied. All skill commands accept `--skills-dir` and `--json`. Skill commands never trigger automatic synchronization. Maintenance notices go to stderr and leave JSON stdout intact.
+
+See [skill lifecycle metadata and decisions](docs/skill-management.md) for the hash format and recovery rules.
+
 ## Use the CLI directly
 
 ```powershell
@@ -43,7 +76,7 @@ uvx markdown-docx --syntax --json
 
 ## Supported Markdown
 
-Version 0.1.0 supports:
+Version 0.2.0 supports:
 
 - ATX headings from `#` through `######`
 - Paragraphs and standard soft or hard line breaks
@@ -55,7 +88,7 @@ Version 0.1.0 supports:
 - Local and remote inline images
 - Standalone images with width and alignment metadata
 
-Links are rejected in 0.1.0. `python-docx` 1.2.0 can read hyperlinks but has no supported public API for creating them. The source alt text for images remains meaningful Markdown content, but the same library release has no public API for embedding it in a Word drawing. A rendered document containing images reports `image_alt_text_not_embedded` in its warning list.
+Links are rejected in 0.2.0. `python-docx` 1.2.0 can read hyperlinks but has no supported public API for creating them. The source alt text for images remains meaningful Markdown content, but the same library release has no public API for embedding it in a Word drawing. A rendered document containing images reports `image_alt_text_not_embedded` in its warning list.
 
 The following syntax is intentionally unsupported:
 

markdown_docx-0.2.0/docs/skill-management.md

@@ -0,0 +1,69 @@
+# Managed agent skill
+
+The distribution, CLI command, and skill are named `markdown-docx`. The Python import package is `markdown_docx`. `markdown_docx.__version__` supplies the version reported by the CLI and written by the canonical skill renderer in `src/markdown_docx/skill.py`.
+
+## Metadata
+
+New installations write lifecycle metadata inside the existing YAML front matter:
+
+```yaml
+---
+name: markdown-docx
+description: Existing skill description
+metadata:
+  managed-by: markdown-docx
+  managed-version: "0.2.0"
+  managed-content-sha256: "sha256:<64 lowercase hexadecimal characters>"
+---
+```
+
+The description and all instructions come from one bundled template. The version is always a quoted string with the exact running CLI version. There is no top-level version field or sidecar file. New files use UTF-8 without a BOM, LF line endings, and a trailing newline.
+
+To calculate the hash, render the complete file with `managed-content-sha256: ""`, normalize CRLF and CR to LF, then calculate SHA-256 over the UTF-8 bytes. Replace only the hash value with `sha256:` followed by the digest. Verification blanks that value using parsed YAML source positions. It preserves the rest of the original text rather than serializing YAML again. The hash covers the instructions, examples, front matter, and formatting. It detects edits and is not a signature or security boundary.
+
+Front matter ownership is authoritative. The old `<!-- managed-by: markdown-docx -->` marker still identifies legacy managed files when no conflicting `managed-by` field is present. New files omit that marker. Unrelated metadata in the bundled template remains part of the generated skill and its hash.
+
+## Automatic decisions
+
+All normal CLI invocations check `~/.agents/skills/markdown-docx/SKILL.md`, including rendering, inspection, help, version, about, and no-argument help. Skill commands do not run this check.
+
+| Installed state | Automatic action |
+| --- | --- |
+| Missing directory or file | Leave absent |
+| Unmanaged or owned by another tool | Leave untouched |
+| Legacy managed file without a version | Treat as version 0 and replace |
+| Managed file with missing or invalid version | Replace without hash verification |
+| Equal or newer valid version | Leave untouched |
+| Older version with matching stored hash | Replace with the running CLI's bundled skill |
+| Older version with missing, malformed, or mismatched hash | Preserve and recommend force installation |
+
+Versions use PEP 440 ordering through `packaging.version.Version`. An invalid running CLI version disables automatic synchronization. Verification compares the installed file against its own stored hash. It never compares an older file against the current bundled hash to decide whether the older file was edited.
+
+Replacements use a flushed and closed temporary file in the skill directory followed by an atomic replacement. The installed file is read again immediately before replacement. Any observed concurrent change cancels the replacement. There is no lock or long retry loop. An external writer can still race the final filesystem operation.
+
+Updates and preservation notices go to stderr. Failures are best effort and do not change the primary command's exit status or JSON stdout. No notice is emitted for absent, unmanaged, current, or newer skills, or skipped development builds.
+
+## Explicit commands
+
+```powershell
+uvx markdown-docx skill install
+uvx markdown-docx skill install --force
+uvx markdown-docx skill status --json
+uvx markdown-docx skill remove
+```
+
+A normal install creates a missing skill and updates a pristine older skill. It refuses altered or unverifiable managed files with valid versions, including edits to the current version. Use `uvx markdown-docx skill install --force` to restore such a file. Force installation still refuses unmanaged content and never replaces a newer version. Missing or invalid managed versions use the recovery rule in the table.
+
+Status is read-only. Plain and JSON results include the selected path, standard-location flag, installation and ownership state, exact CLI version, valid installed version, version relation, integrity state, runtime source, automatic synchronization eligibility and reason, and a force command when applicable. Missing or malformed managed versions are reported as null with a separate version state. Legacy status reports legacy integrity and compares its effective version 0 before migration.
+
+Install retains the existing `installed`, `created`, `updated`, `skill`, and `path` JSON fields. Removal retains its existing result fields and force semantics. It refuses unmanaged skills or extra directory entries unless removal `--force` is supplied. Legacy managed skills remain removable. Installation and synchronization only write `SKILL.md`. They preserve unrelated files. Existing directories without `SKILL.md` are refused by explicit install and removal.
+
+All three commands accept `--skills-dir PATH`. Custom directories participate only in explicit commands. Include the same directory when updating or forcing a custom installation.
+
+## Runtime source and loading
+
+Automatic synchronization uses installed-distribution records and PEP 610 `direct_url.json`. Local directories, local source archives, and editable installations are excluded. Source code that does not match the installed distribution's module path is also excluded. Unidentified or malformed provenance is handled conservatively. An installed wheel, including one installed from a local wheel file, remains eligible. No launcher detection is used.
+
+Explicit installation remains available from a checkout with `uvx --from . markdown-docx skill install`. Tests redirect the standard skills directory to temporary storage. The package smoke check verifies wheel provenance, runtime version, canonical content, and lifecycle behavior in an isolated temporary skill directory.
+
+This feature only synchronizes local skill content to the CLI that is already running. It never queries PyPI, updates the CLI, or refreshes uv's cache. Agent instructions continue to invoke `uvx markdown-docx`. Updates apply to future skill loading and may not affect instructions already loaded in an active agent session.

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "markdown-docx"
-version = "0.1.0"
+version = "0.2.0"
 description = "Convert constrained Markdown documents into editable Word files."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -28,6 +28,7 @@ classifiers = [
 dependencies = [
   "httpx>=0.27,<1",
   "markdown-it-py>=3.0,<5",
+  "packaging>=24.0",
   "Pillow>=10.0,<13",
   "PyYAML>=6.0,<7",
   "python-docx==1.2.0",

markdown_docx-0.2.0/scripts/smoke_skill.py

@@ -0,0 +1,77 @@
+"""Check packaged skill behavior without accessing the user's skills directory."""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import tempfile
+from importlib.metadata import version
+from pathlib import Path
+from unittest.mock import patch
+
+from markdown_docx import __version__, skill
+from markdown_docx.cli import main
+
+
+def invoke(args: list[str]) -> tuple[str, str]:
+    stdout, stderr = io.StringIO(), io.StringIO()
+    code = main(args, stdout=stdout, stderr=stderr)
+    assert code == 0, (code, stdout.getvalue(), stderr.getvalue())
+    return stdout.getvalue(), stderr.getvalue()
+
+
+def check(expected_source: str) -> None:
+    assert skill.runtime_source() == expected_source
+    assert version("markdown-docx") == __version__
+    with tempfile.TemporaryDirectory(prefix="markdown-docx-skill-smoke-") as directory:
+        root = Path(directory) / "skills"
+        with patch.object(skill, "default_skills_dir", return_value=root):
+            stdout, stderr = invoke(["--version"])
+            assert stdout == f"markdown-docx {__version__}\n" and not stderr
+            assert not root.exists()
+            stdout, stderr = invoke(["skill", "install", "--json"])
+            installed = json.loads(stdout)
+            assert installed["created"] and not stderr
+            path = Path(installed["path"])
+            canonical = path.read_bytes()
+            assert canonical == skill.render_skill().encode("utf-8")
+            assert b"Always invoke the tool as `uvx markdown-docx ...`" in canonical
+            assert list(path.parent.iterdir()) == [path]
+            stdout, stderr = invoke(["skill", "status", "--json"])
+            status = json.loads(stdout)
+            assert status["managed_version"] == __version__
+            assert status["integrity"] == "valid" and not stderr
+            assert status["local_development"] == (expected_source == "local")
+            older = skill.render_skill("0.0.0").encode("utf-8")
+            path.write_bytes(older)
+            stdout, stderr = invoke(["--syntax", "--json"])
+            assert json.loads(stdout)["ok"]
+            if expected_source == "installed":
+                assert "Updated managed skill" in stderr
+                assert path.read_bytes() == canonical
+            else:
+                assert not stderr
+                assert path.read_bytes() == older
+            altered = older + b"Local edits\n"
+            path.write_bytes(altered)
+            stdout, stderr = invoke(["--syntax", "--json"])
+            assert json.loads(stdout)["ok"]
+            assert path.read_bytes() == altered
+            if expected_source == "installed":
+                assert skill.FORCE_INSTALL_COMMAND in stderr
+            else:
+                assert not stderr
+            stdout, stderr = invoke(["skill", "install", "--force", "--json"])
+            assert json.loads(stdout)["updated"] and not stderr
+            assert path.read_bytes() == canonical
+            stdout, stderr = invoke(["skill", "remove", "--json"])
+            assert json.loads(stdout)["removed"] and not stderr
+            assert not path.exists()
+    print(f"Managed skill smoke passed for {expected_source} runtime {__version__}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--expected-source", choices=("installed", "local"), default="installed")
+    check(parser.parse_args().expected_source)

markdown_docx-0.2.0/src/markdown_docx/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/src/markdown_docx/assets/syntax.json

@@ -1,7 +1,7 @@
 {
   "format": "markdown-docx",
-  "version": "0.1.0",
-  "text": "markdown-docx 0.1.0 syntax\n\nSupported Markdown:\n  ATX headings, paragraphs, emphasis, strong text, inline code, hard line breaks, fenced code blocks, blockquotes, ordered and unordered lists, pipe tables, and images.\n\nMetadata comments:\n  document metadata must be first\n  section metadata starts a next-page section\n  <!-- markdown-docx: page-break --> inserts a page break\n  table metadata must immediately precede a pipe table\n  image metadata must immediately precede a standalone image\n\nLengths use in, cm, mm, or pt. Image widths may also use percentages.\n\nUnsupported in 0.1.0:\n  links, raw HTML, task lists, footnotes, horizontal rules, indented code blocks, multi-paragraph list items, DOTX, floating images, headers and footers from Markdown, page-number fields, and direct OOXML features.",
+  "version": "0.2.0",
+  "text": "markdown-docx 0.2.0 syntax\n\nSupported Markdown:\n  ATX headings, paragraphs, emphasis, strong text, inline code, hard line breaks, fenced code blocks, blockquotes, ordered and unordered lists, pipe tables, and images.\n\nMetadata comments:\n  document metadata must be first\n  section metadata starts a next-page section\n  <!-- markdown-docx: page-break --> inserts a page break\n  table metadata must immediately precede a pipe table\n  image metadata must immediately precede a standalone image\n\nLengths use in, cm, mm, or pt. Image widths may also use percentages.\n\nUnsupported in 0.2.0:\n  links, raw HTML, task lists, footnotes, horizontal rules, indented code blocks, multi-paragraph list items, DOTX, floating images, headers and footers from Markdown, page-number fields, and direct OOXML features.",
   "page_sizes": ["letter", "legal", "a4", "custom"],
   "orientations": ["portrait", "landscape"],
   "length_units": ["in", "cm", "mm", "pt"],

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/src/markdown_docx/cli.py

@@ -12,7 +12,7 @@ from markdown_docx.assets import load_syntax_payload
 from markdown_docx.errors import EXIT_INTERNAL, InputError, MarkdownDocxError, UsageError
 from markdown_docx.parser import parse_document
 from markdown_docx.renderer import render_docx
-from markdown_docx.skill import install_skill, remove_skill
+from markdown_docx.skill import install_skill, remove_skill, skill_status, synchronize_skill
 from markdown_docx.template import inspect_template
 
 PROGRAM_NAME = "markdown-docx"
@@ -77,8 +77,10 @@ Inspection:
   {PROGRAM_NAME} --list-table-styles [--template formatting.docx] [--json]
 
 Agent skill:
-  {PROGRAM_NAME} skill install [--skills-dir DIR] [--json]
+  {PROGRAM_NAME} skill install [--skills-dir DIR] [--force] [--json]
   {PROGRAM_NAME} skill remove [--skills-dir DIR] [--force] [--json]
+  {PROGRAM_NAME} skill status [--skills-dir DIR] [--json]
+  Installed managed skills sync locally during normal commands. See 'skill --help'.
 
 Common options:
   -h, --help              Show this quick reference.
@@ -113,11 +115,17 @@ def main(
     args_list = list(sys.argv[1:] if argv is None else argv)
     json_mode = "--json" in args_list
     try:
+        if args_list and args_list[0] == "skill":
+            if len(args_list) == 1 or "-h" in args_list or "--help" in args_list:
+                stdout.write(build_skill_help())
+                return 0
+            return _run_skill_command(args_list[1:], stdout=stdout)
+        synchronize_skill(stderr=stderr, version=__version__)
         if not args_list:
             stdout.write(build_root_help())
             return 0
         if "-h" in args_list or "--help" in args_list:
-            stdout.write(build_skill_help() if args_list[0] == "skill" else build_root_help())
+            stdout.write(build_root_help())
             return 0
         if "--version" in args_list:
             if args_list != ["--version"]:
@@ -131,8 +139,6 @@ def main(
                 f"{PROGRAM_NAME} {__version__}\n{PROJECT_SUMMARY}\nProject: {PROJECT_URL}\nLicense: {PROJECT_LICENSE}\n"
             )
             return 0
-        if args_list[0] == "skill":
-            return _run_skill_command(args_list[1:], stdout=stdout)
         args = build_parser().parse_args(args_list)
         return _run(args, stdin=stdin, stdout=stdout)
     except MarkdownDocxError as exc:
@@ -287,30 +293,56 @@ def _write_error(exc: MarkdownDocxError, *, json_mode: bool, stdout: TextIO, std
 
 def build_skill_help() -> str:
     return f"""Usage:
-  {PROGRAM_NAME} skill install [--skills-dir DIR] [--json]
+  {PROGRAM_NAME} skill install [--skills-dir DIR] [--force] [--json]
   {PROGRAM_NAME} skill remove [--skills-dir DIR] [--force] [--json]
-
-Install or remove the managed `{PROGRAM_NAME}` agent skill. The default root is ~/.agents/skills.
-Removal refuses unmanaged content unless --force is supplied.
+  {PROGRAM_NAME} skill status [--skills-dir DIR] [--json]
+
+Install, inspect, or remove the managed `{PROGRAM_NAME}` agent skill.
+The default root is ~/.agents/skills. Status is read-only.
+
+Normal commands synchronize an already-installed, pristine older managed skill
+to the running CLI version. They never install a missing skill or downgrade it.
+Modified or unverifiable skills are preserved. To replace managed edits, use:
+  uvx {PROGRAM_NAME} skill install --force
+Install --force still refuses unmanaged content. Removal --force may remove
+unmanaged content and extra files in the skill directory.
+
+Automatic synchronization uses only the standard directory. Custom directories
+require explicit installs. Local source and editable builds do not synchronize
+automatically. Skill commands never trigger automatic synchronization.
+This does not query a package index, refresh uv, or update the CLI. Updates apply
+to future agent skill loading. A running agent may retain its loaded instructions.
 """
 
 
 def _run_skill_command(args_list: list[str], *, stdout: TextIO) -> int:
     parser = CliArgumentParser(prog=f"{PROGRAM_NAME} skill", add_help=False)
-    parser.add_argument("action", choices=("install", "remove"))
+    parser.add_argument("action", choices=("install", "remove", "status"))
     parser.add_argument("--skills-dir", type=Path)
     parser.add_argument("--force", action="store_true")
     parser.add_argument("--json", action="store_true")
     args = parser.parse_args(args_list)
-    if args.action == "install" and args.force:
-        raise UsageError("--force is valid only with 'skill remove'.")
+    if args.action == "status" and args.force:
+        raise UsageError("--force is valid only with 'skill install' or 'skill remove'.")
     root = args.skills_dir.resolve() if args.skills_dir else None
-    result = install_skill(root) if args.action == "install" else remove_skill(root, force=args.force)
+    if args.action == "install":
+        result = install_skill(root, force=args.force, version=__version__)
+    elif args.action == "remove":
+        result = remove_skill(root, force=args.force)
+    else:
+        result = skill_status(root, version=__version__)
     if args.json:
         stdout.write(json.dumps({"ok": True, "mode": f"skill_{args.action}", **result}, indent=2) + "\n")
     elif args.action == "install":
         verb = "Installed" if result["created"] else "Updated" if result["updated"] else "Already installed"
         stdout.write(f"{verb} {result['path']}\n")
+    elif args.action == "status":
+        for key, value in result.items():
+            label = key.replace("_", " ").capitalize()
+            display = (
+                "not applicable" if value is None else str(value).lower() if isinstance(value, bool) else str(value)
+            )
+            stdout.write(f"{label}: {display}\n")
     elif result["removed"]:
         stdout.write(f"Removed {result['path']}\n")
     else:

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/src/markdown_docx/markdown_body.py

@@ -55,7 +55,7 @@ def parse_inline(token: Token, *, line: int, input_path: str | None) -> list[Inl
             )
         elif child_type in {"link_open", "link_close"}:
             raise UnsupportedFeatureError(
-                "Links require a public python-docx hyperlink creation API and are not supported in 0.1.0.",
+                "Links require a public python-docx hyperlink creation API and are not supported in 0.2.0.",
                 line=line,
                 input_path=input_path,
             )

{markdown_docx-0.1.0 → markdown_docx-0.2.0}/src/markdown_docx/parser.py

@@ -264,7 +264,7 @@ def _consume_blockquote(tokens: list[Token], index: int, input_path: str) -> tup
     index += 1
     while index < len(tokens) and tokens[index].type != "blockquote_close":
         if tokens[index].type != "paragraph_open":
-            _unsupported("Blockquotes may contain paragraphs only in 0.1.0.", tokens[index], input_path)
+            _unsupported("Blockquotes may contain paragraphs only in 0.2.0.", tokens[index], input_path)
         paragraph, index = _consume_paragraph(tokens, index, input_path)
         if any(fragment.kind == "image" for fragment in paragraph.fragments):
             _unsupported("Images nested in blockquotes are not supported.", opening, input_path)
@@ -299,7 +299,7 @@ def _consume_list(
         if start is not None and int(start) != 1:
             raise ParseError(
                 "ordered_list_start_unsupported",
-                "Ordered lists must begin with 1 in 0.1.0.",
+                "Ordered lists must begin with 1 in 0.2.0.",
                 line=_token_line(opening),
                 input_path=input_path,
             )