thoughtleaders-cli 0.9.3__py3-none-any.whl → 0.9.4__py3-none-any.whl

{thoughtleaders_cli-0.9.3.dist-info → thoughtleaders_cli-0.9.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.9.3
+Version: 0.9.4
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli
@@ -284,6 +284,21 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
 - **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).
 
+## Distributed skills
+
+Beyond the bundled set above, an organization can be granted additional skills that aren't part of a CLI release — `tl skill` fetches and installs them on demand into the same directories `tl setup` uses (Claude Code's standalone skills directory, OpenCode's skills directory, and the directory shared by Gemini and Codex), so every supported agent picks them up automatically.
+
+```bash
+tl skill list                 # skills available to your organization, with installed/latest versions
+tl skill list --all           # full catalog (full-access accounts only)
+tl skill download my-skill    # fetch and install into every AI-agent skill directory
+tl skill download my-skill --force   # overwrite a directory tl doesn't already manage
+tl skill update                # refresh every downloaded skill to its latest version
+tl skill remove my-skill        # uninstall a downloaded skill
+```
+
+A directory `tl skill download` doesn't already manage (no prior `tl`-managed install there) is left alone unless `--force` is passed — it never overwrites a skill you installed some other way. `tl` warns once a day, on any command, when a downloaded skill has a newer version available. `tl setup` and self-update re-syncs also respect these directories: a downloaded skill is never rmtree'd or overwritten, even if its name collides with a bundled skill.
+
 ## Output Formats
 
 By default, output is a styled table in the terminal and JSON when piped.

{thoughtleaders_cli-0.9.3.dist-info → thoughtleaders_cli-0.9.4.dist-info}/RECORD

@@ -1,12 +1,13 @@
-tl_cli/__init__.py,sha256=HtBnZuYCqtstGhptSV7Np9m3ZYi8GNZcrkpJixpN2mA,112
+tl_cli/__init__.py,sha256=vSA_gOKoNEuGKTTDXEGFTK9NgDyrC9oLOwpvRELGmLg,112
 tl_cli/_completions.py,sha256=kOyEUqC26vbYvyXWi513WX8fF73qQLR5WWuRSe_wqyk,164
 tl_cli/_typer_utils.py,sha256=ZiZsCVmEznPvBw-dYbr3tu3zWZ0iN6kjoQmK3gMqD28,860
 tl_cli/config.py,sha256=UV_OYTXuQnAIqbi_oVCXx0hhIdZWR678RRapVv51UwQ,1859
 tl_cli/filters.py,sha256=Yjj04lONGGmtCAIYN5i6KD12mAnUKEZ7i9heeWtdj7o,2952
 tl_cli/hints.py,sha256=cT8kuDtkAZqwXkc2RV0Yg_abofK-g9UiXwTTBunX78U,1557
-tl_cli/main.py,sha256=E5VAkLbpXmGVEy9DzK99FRKD2khmvYJVcYawN97K1zc,6013
+tl_cli/main.py,sha256=ZCzbgemmKlcIVlk_6TVznXooSsTBAjQ01k1olwQLhJQ,6435
 tl_cli/query_history.py,sha256=vA5avDU1DBZDWSb-w2ZxEZxV2MD21cqwzfYjXawOWZI,5540
 tl_cli/self_update.py,sha256=zLPCSzPQTHRAcTZTBBopRxAs5Bg-B7Ag_7PxfN94QOI,18800
+tl_cli/skill_registry.py,sha256=slB3K0tI_-mrPT7Eswzq2Sjlo8Wcwk5nDy0w9yQh6mM,11957
 tl_cli/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/auth/commands.py,sha256=CkCaKFb-xUwhCeIL92EC4-odiaSpLI1bmgg5tDCrclM,7387
 tl_cli/auth/login.py,sha256=AxdQ8LOZd1uZhFXPyaiGB_Hk0RiVuX7t37gkjgoEOCM,11568
@@ -14,16 +15,16 @@ tl_cli/auth/pkce.py,sha256=4Q6Ip-TeZFNG9c3swXNi4gH7mdMkltKa62gZZNybt8U,658
 tl_cli/auth/token_store.py,sha256=TcZnUol4-8r0jMEJhOPmABCX12_5RkAln2xfWPNdmHk,3275
 tl_cli/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/client/errors.py,sha256=HEAEeFIgw_n_ZE9bkRRw6OPyqmwGhixzNN2bAxYj7wg,3246
-tl_cli/client/http.py,sha256=pUJYYuT0q92_SwqCuMj3ozBthvchKuKL9v9U_eCQv20,4164
+tl_cli/client/http.py,sha256=vcrNMJ5Z91-DXYq-vBH55Miii3QRnq2X1kIllMQ8yw8,4565
 tl_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/commands/_comments_common.py,sha256=x91WPSpDdV8AwE8Mwx4VtZQKWXBufsnBnC1lFD0Tzys,4522
-tl_cli/commands/balance.py,sha256=JHSmKdAUNtd-9zlKZhit9_BmhHXrEk0kQ-oSlQ0Eo6Y,2732
+tl_cli/commands/balance.py,sha256=OubiqknmLKREUzk2V0FZFtqgb4_dqQMR4V5-ifz-wfk,3150
 tl_cli/commands/brands.py,sha256=uogOfAdEbpjqiGlv4L2T1UC-Iz10G6fkRhVsDBOjRIY,15340
 tl_cli/commands/bulk_import.py,sha256=d4y1k_lD52LPJcCqXxEmyHIqcIwomZgbjqs1_QxPjeQ,4536
 tl_cli/commands/changelog.py,sha256=D1PtDdHpawTlWqUHjKzVmv9yXLSU915UVmI3dZzEwyA,4241
 tl_cli/commands/channels.py,sha256=gs6jHaxi6WjB3D8jnJETFVvkTXpqzlWR-W4JkBeG3oY,20406
 tl_cli/commands/credits.py,sha256=2xCht2e420LmaFBKNdKoMz8GlTh31qSWSlJAnVzoZic,7308
-tl_cli/commands/db.py,sha256=fPqqw5m561Tx-JkRR-RE_b_otSIMtTwPMUI0neqiyZ8,8997
+tl_cli/commands/db.py,sha256=RcuGYzmTs5KMk6RgYao3oV-j883dG7IonTQclZg7UZs,9148
 tl_cli/commands/deals.py,sha256=ZK9yneInsC6DXoCPS65oyLoVR0eRW1xdRlEN7oRp1pc,2174
 tl_cli/commands/describe.py,sha256=3lURv4NllM5qPeMEBbejrIxiMzsyTwpJIz211-wuGCU,12362
 tl_cli/commands/doctor.py,sha256=KUKglwhMc7B26XXy_3M0LkHu7wqfFO5T0YPHO1SH1VY,9024
@@ -33,7 +34,8 @@ tl_cli/commands/proposals.py,sha256=IXx9DsR7lPWRM4QvKB65t7xKNAK3H6ax9LIlIj8ydEs,
 tl_cli/commands/recommender.py,sha256=BZfviKAPhpZah0zaSyH5RDa23fG8QAkUnG5FDhOdi4I,21324
 tl_cli/commands/reports.py,sha256=7CL2atr0Y4XSE8U8kbuZ5-M-m3E9PKNZ0N_0Fbd_OkQ,26388
 tl_cli/commands/schema.py,sha256=rmfg5pvKHa5kQi59YBIHCMzBNawmYPi2tBMcZP7Vrxw,6432
-tl_cli/commands/setup.py,sha256=ypimHsp45yYSWwTLywfYtPC2P_45X4arW0K3SFuwEXk,28398
+tl_cli/commands/setup.py,sha256=p71pfwbIlMJoq2TaOfy35_absD9VMSX792FlapmQv2Y,29933
+tl_cli/commands/skills.py,sha256=4Vg5ph6T7T3WcIqIZc83EJPhtB79FE7fMej9uVhElqc,15884
 tl_cli/commands/snapshots.py,sha256=exlxFwMcM1BCiDTcE9dZfaSdRO-sxaTxtWzJmEoUVWI,3434
 tl_cli/commands/sponsorships.py,sha256=PdWCm9E4mrs_qlHtckMp99JmuRP94hthlqoWMi0k4tc,10471
 tl_cli/commands/uploads.py,sha256=Tf9tqAEm9FGe3A7sr_EDX9OzdNInCmrWNr10wWGuMUo,1526
@@ -42,7 +44,7 @@ tl_cli/commands/workflows.py,sha256=ctduYa--Md6zbs8kQwO6mSyR9o1KB1UpNOaANuupDfU,
 tl_cli/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/output/formatter.py,sha256=2FOsZb9aGcjKAGvumtEyS63cjIk47JcQGNM0K7Gpdp8,23413
 tl_cli/_plugin/.claude-plugin/marketplace.json,sha256=l56PMmyjfGXNGlV30wRyOAe74B6gJNCVNCxgsBbSNxc,446
-tl_cli/_plugin/.claude-plugin/plugin.json,sha256=MlM05A2LBDupXFroa0AsFQ5Yf1ouQa79wgfhXMt6yeA,466
+tl_cli/_plugin/.claude-plugin/plugin.json,sha256=lu-QQlhwxsIG1s6N8GFNEBGMfYek73Al0_1uTolvsC4,466
 tl_cli/_plugin/agents/keyword-context-classifier.md,sha256=8Pk6WqJKuF-ERkBh54Aa-9t60CvjdOIH0RurFlG-T7I,4325
 tl_cli/_plugin/agents/keyword-entity-resolver.md,sha256=fOAeTZa2-h7te8dEXLFcmiL2tj6IXwnQ0ChUrym3yFc,5619
 tl_cli/_plugin/agents/keyword-relevance-validator.md,sha256=uPUqobAVT7xq-brRHtNaFSTns-lYyCu3MwTuU5tn538,3127
@@ -52,7 +54,7 @@ tl_cli/_plugin/hooks/hooks.json,sha256=FSWibw1xAjA-suFV3fR8btIb2kQ82LQ08otTr-Npm
 tl_cli/_plugin/hooks/scripts/load-tl-skill.mjs,sha256=EBsyZ-caei-CBJsRtqzJXJs_20O3H22MuVmDpu96umo,805
 tl_cli/_plugin/hooks/scripts/post-usage.sh,sha256=WVvZLkZik6lbeZ20Kh-wgm4JkRFHFN0Uwl4C8S3Y0sY,759
 tl_cli/_plugin/hooks/scripts/pre-check.sh,sha256=inHopPXQ9h-KRcHuebEIQ-1EZmsTaHhAAMCFQ0MyiEQ,820
-tl_cli/_plugin/skills/tl/SKILL.md,sha256=z_XKy_K0iD7SNsFyKeoQP27cgY6thOmIyQDvTlUq_NM,66356
+tl_cli/_plugin/skills/tl/SKILL.md,sha256=mFgTCMcYkEvXCO0f3uqFaQcHOJ2rJh6iZ46AdkziuVc,67959
 tl_cli/_plugin/skills/tl/references/business-glossary.md,sha256=YZ_UWygtAZB8Mfh9NPG2ld0OnmgknSBzBOpVZwN-wzs,19287
 tl_cli/_plugin/skills/tl/references/elasticsearch-schema.md,sha256=x7ZUYGbR6FJG02BSA9BjveoiC4X-7VsYxhLPBK4IH_c,23195
 tl_cli/_plugin/skills/tl/references/firebolt-schema.md,sha256=tysPKBxqQFRzfKi2vmEhHXn8PGaznep7yaKwSWZY3Jo,11110
@@ -107,8 +109,8 @@ tl_cli/_plugin/skills/tl-top-partnerships/SKILL.md,sha256=jOMMr40XRnAZv-oRLeyKJT
 tl_cli/_plugin/skills/tl-top-partnerships/scripts/top_partnerships.py,sha256=OqhoyvFe1zrtrStChcam7oPYgFnSbGHC3WAgLhLIC3w,13738
 tl_cli/_plugin/skills/tl-views-guarantee/SKILL.md,sha256=IH7q1WJDWri9TWJMiga1FMGJO_GKSbWwaDS6CVNZ9c0,9270
 tl_cli/_plugin/skills/tl-views-guarantee/scripts/vg.py,sha256=Qp5poinHEqh9374anq0bLtlxj2YL6ipBicaT960-Cws,15825
-thoughtleaders_cli-0.9.3.dist-info/METADATA,sha256=jQE0DTTvhbzQ42bXDTL_GIngJjyEapWefL7ypiE43ec,19083
-thoughtleaders_cli-0.9.3.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-thoughtleaders_cli-0.9.3.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
-thoughtleaders_cli-0.9.3.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
-thoughtleaders_cli-0.9.3.dist-info/RECORD,,
+thoughtleaders_cli-0.9.4.dist-info/METADATA,sha256=-BYaTIApwQ4wVdRWEc99Dr-7BhfIpCHK7d858ufwoFg,20457
+thoughtleaders_cli-0.9.4.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+thoughtleaders_cli-0.9.4.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
+thoughtleaders_cli-0.9.4.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
+thoughtleaders_cli-0.9.4.dist-info/RECORD,,

tl_cli/__init__.py

@@ -1,3 +1,3 @@
 """ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence."""
 
-__version__ = "0.9.3"
+__version__ = "0.9.4"

tl_cli/_plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

tl_cli/_plugin/skills/tl/SKILL.md

@@ -251,9 +251,8 @@ contact field:
 
 The channel's full email archive (`all_emails` — a JSON object keyed by email address,
 each value recording when and where the address was found) is **not editable here**;
-sending it returns a 400. It is append-only: new addresses are added with the
-internal CLI's `tl-internal channels add-email` command (superuser-only), which never
-modifies or removes existing entries.
+sending it returns a 400. It is append-only and managed through an internal-only
+process that never modifies or removes existing entries — not available via this CLI.
 
 **Profile notes.** `tl profiles update` (superuser only) edits a brand/publisher profile's
 **`superuser_notes`** — the internal free-text notes field on the customer record
@@ -503,6 +502,21 @@ tl changelog since v0.4.10             # Notes from v0.4.10 to latest
 tl changelog --md > CHANGELOG.md       # Capture for a doc
 ```
 
+#### Distributed skills — beyond the bundled set
+
+An organization can be granted additional skills that aren't part of a CLI release. `tl skill` fetches and installs them on demand into the same directories `tl setup` uses (Claude Code's standalone skills directory, OpenCode's skills directory, and the directory shared by Gemini and Codex), so every supported agent picks them up automatically — no restart or reconfiguration needed beyond re-reading the skill listing.
+
+```bash
+tl skill list                          # Skills available to your org, with installed/latest versions (free)
+tl skill list --all                    # Full catalog (full-access accounts only)
+tl skill download <name>                # Fetch and install into every AI-agent skill directory on this machine
+tl skill download <name> --force        # Overwrite a directory tl doesn't already manage
+tl skill update                         # Refresh every downloaded skill to its latest version
+tl skill remove <name>                  # Uninstall a downloaded skill
+```
+
+If a user asks to find, add, or refresh a skill by capability ("is there a skill for X", "get me the latest Y skill"), check `tl skill list` before saying no — the bundled set isn't the whole catalog. `tl skill download` never overwrites a directory it doesn't already manage unless `--force` is passed, so it's safe to run without clobbering a manually-installed skill of the same name. `tl` warns once a day, on any command, when a downloaded skill has a newer version available — surface that nag to the user rather than silently ignoring it, and offer to run `tl skill update`.
+
 #### Channel & video discovery — pick the path for the question shape
 
 Four first-class paths, each with a different signal. **Pick by the SHAPE of the user's question, not by habit.** "Recommender first" is the right default only for path 2 — for paths 1, 3, and 4 the recommender is the wrong tool.

tl_cli/client/http.py

@@ -23,8 +23,8 @@ class TLClient:
             },
         )
 
-    def get(self, path: str, params: dict | None = None) -> dict:
-        return self._request("GET", path, params=params)
+    def get(self, path: str, params: dict | None = None, timeout: float | None = None) -> dict:
+        return self._request("GET", path, params=params, timeout=timeout)
 
     def post(self, path: str, json_body: dict | None = None) -> dict:
         return self._request("POST", path, json_body=json_body)
@@ -38,20 +38,24 @@ class TLClient:
         path: str,
         params: dict | None = None,
         json_body: dict | None = None,
+        timeout: float | None = None,
     ) -> dict:
         headers = self._auth_headers()
+        # Only overrides the client's default timeout when the caller asks
+        # for one — passing `timeout=None` through to httpx means "no
+        # timeout", not "use the default", so it's omitted entirely here.
+        request_kwargs = {"params": params, "json": json_body, "headers": headers}
+        if timeout is not None:
+            request_kwargs["timeout"] = timeout
 
-        response = self._client.request(
-            method, path, params=params, json=json_body, headers=headers
-        )
+        response = self._client.request(method, path, **request_kwargs)
 
         # On 401, try refreshing the token once
         if response.status_code == 401:
             headers = self._refresh_and_get_headers()
             if headers:
-                response = self._client.request(
-                    method, path, params=params, json=json_body, headers=headers
-                )
+                request_kwargs["headers"] = headers
+                response = self._client.request(method, path, **request_kwargs)
 
         if response.status_code >= 400:
             detail = self._extract_detail(response)

tl_cli/commands/balance.py

@@ -44,6 +44,12 @@ def balance(
         allow_overage = data.get("allow_overage", False)
 
         console.print(f"\n[bold]Credit Balance:[/bold] [cyan]{balance_val}[/cyan] credits")
+        # Older servers return only the combined balance; newer ones split it
+        # into the plan-granted (top-up) pool and the purchased pool.
+        topup_val = data.get("topup_balance")
+        purchased_val = data.get("purchased_balance")
+        if topup_val is not None and purchased_val is not None:
+            console.print(f"[dim]Plan (top-up) credits: {topup_val} · Purchased: {purchased_val}[/dim]")
         if allow_overage:
             console.print("[dim]Overage: enabled[/dim]")
 

tl_cli/commands/db.py

@@ -99,9 +99,11 @@ def pg_cmd(
     Common traps — check before writing SQL:
 
     - Column names follow the current schema: subscribers, projected_views,
-      scheduled_date, is_tpp, advertiser_profile_id, views_guarantee — NOT the
-      older reach / impression / send_date / is_tl_channel / creator_profile_id
-      / impressions_guarantee.
+      scheduled_date, is_tpp, advertiser_profile_id, views_guarantee, url (the
+      channel's own URL) — NOT the older reach / impression / send_date /
+      is_tl_channel / creator_profile_id / impressions_guarantee / channel_url.
+    - thoughtleaders_adlink has no bare `url` column — the live sponsored-video
+      URL is `media_url`.
     - The sponsorship table (thoughtleaders_adlink) hides its relations behind
       joins: no channel_id/channel_name (join thoughtleaders_adspot via
       ad_spot_id, then thoughtleaders_channel) and no brand_id (join

tl_cli/commands/setup.py

@@ -21,6 +21,7 @@ from pytoon import encode as toon_encode
 from rich.console import Console
 
 from tl_cli import __version__
+from tl_cli.skill_registry import is_marked_for
 
 app = typer.Typer(cls=AlphaSortedTyperGroup, help="Set up integrations (Claude Code, OpenCode, Gemini, Codex)")
 console = Console(stderr=True)
@@ -201,6 +202,20 @@ def check_plugin_version() -> list[str]:
     return warnings
 
 
+def _warn_marker_skip(path: Path, name: str) -> None:
+    """Print the standard warning when setup leaves a tl-managed skill dir alone.
+
+    Shared by every place in this module that would otherwise rmtree/copytree
+    over a skill directory — a directory carrying a valid `.tl-skill.json`
+    marker was installed by `tl skill download` and must never be clobbered
+    by a bundled-skill sync, regardless of name collision or content match.
+    """
+    console.print(
+        f"  [yellow]![/yellow] skipping {path}: managed by 'tl skill' downloads — "
+        f"remove with [cyan]tl skill remove {name}[/cyan] if you want the bundled version"
+    )
+
+
 def _install_standalone_skills(plugin_root: Path) -> int:
     """Copy skills and commands to ~/.claude/ for non-namespaced invocation.
 
@@ -214,6 +229,9 @@ def _install_standalone_skills(plugin_root: Path) -> int:
         for skill_dir in skills_src.iterdir():
             if skill_dir.is_dir() and (skill_dir / "SKILL.md").is_file():
                 dst = CLAUDE_SKILLS_DIR / skill_dir.name
+                if dst.exists() and is_marked_for(dst, skill_dir.name):
+                    _warn_marker_skip(dst, skill_dir.name)
+                    continue
                 if dst.exists():
                     shutil.rmtree(dst)
                 shutil.copytree(skill_dir, dst)
@@ -279,6 +297,11 @@ def _remove_matching_standalone_skills(plugin_root: Path) -> tuple[int, int]:
         standalone = CLAUDE_SKILLS_DIR / skill_dir.name
         if not standalone.is_dir():
             continue
+        if is_marked_for(standalone, skill_dir.name):
+            # tl-managed download — excluded from deletion candidates entirely,
+            # regardless of whether its content happens to match the bundled skill.
+            _warn_marker_skip(standalone, skill_dir.name)
+            continue
         if _trees_identical(skill_dir, standalone):
             shutil.rmtree(standalone)
             removed += 1
@@ -537,7 +560,10 @@ def _install_skill_trees(plugin_root: Path, target_dir: Path) -> int:
     (OpenCode, Gemini, Codex) — each agent reads skills from a different
     base directory, so we just parameterise on that. A `.tl-version`
     stamp is written into the target so `check_plugin_version()` can
-    detect drift later. Returns the number of skills installed.
+    detect drift later. A destination carrying a `.tl-skill.json` marker
+    for this skill name is a `tl skill download` install — it's skipped
+    (with a warning) rather than clobbered, and isn't counted in the
+    returned total. Returns the number of skills installed.
     """
     count = 0
     skills_src = plugin_root / "skills"
@@ -545,6 +571,9 @@ def _install_skill_trees(plugin_root: Path, target_dir: Path) -> int:
         for skill_dir in skills_src.iterdir():
             if skill_dir.is_dir() and (skill_dir / "SKILL.md").is_file():
                 dst = target_dir / skill_dir.name
+                if dst.exists() and is_marked_for(dst, skill_dir.name):
+                    _warn_marker_skip(dst, skill_dir.name)
+                    continue
                 if dst.exists():
                     shutil.rmtree(dst)
                 shutil.copytree(skill_dir, dst)

tl_cli/commands/skills.py

@@ -0,0 +1,437 @@
+"""tl skill — Download, list, update, and remove server-distributed skills.
+
+Distinct from the bundled skill set `tl setup claude|opencode|gemini|codex`
+installs: these are skills an organization has been granted access to on
+the server, fetched and installed on demand.
+"""
+
+import json
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from tl_cli._typer_utils import AlphaSortedTyperGroup
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.commands.setup import AGENTS_SKILLS_DIR, CLAUDE_SKILLS_DIR, OPENCODE_SKILLS_DIR
+from tl_cli.output.formatter import detect_format, output
+from tl_cli.skill_registry import (
+    InvalidSkillNameError,
+    PathSafetyError,
+    install_skill_tree,
+    is_marked_for,
+    read_registry,
+    read_staleness_cache,
+    validate_files,
+    validate_skill_name,
+    write_registry,
+    write_staleness_cache,
+    write_staleness_failure,
+)
+
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Download, list, update, and remove distributed skills")
+console = Console(stderr=True)
+
+COLUMNS = ["name", "latest_version", "installed_version", "status", "description"]
+
+# Kept well under the client's default 30s timeout: this call runs on every
+# `tl` invocation in the background, so a hung/slow server should fail fast
+# rather than stall the user's actual command for up to 30s.
+STALENESS_CHECK_TIMEOUT_SECONDS = 5.0
+
+
+def _install_targets() -> list[Path]:
+    """Every skill-directory root a downloaded skill installs into.
+
+    Mirrors the harness targets `tl setup` uses for the bundled skill set:
+    Claude Code's standalone skills directory (the plugin/marketplace
+    channel only ships the bundled set via GitHub releases and can't
+    deliver a single downloaded skill on its own), OpenCode's skills
+    directory, and the directory shared by Gemini and Codex. Reused
+    directly from `tl_cli.commands.setup` rather than duplicated here.
+    """
+    return [CLAUDE_SKILLS_DIR, OPENCODE_SKILLS_DIR, AGENTS_SKILLS_DIR]
+
+
+def _truncate(text: str, limit: int = 80) -> str:
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1] + "…"
+
+
+def _install_one(
+    dest: Path,
+    *,
+    name: str,
+    version: str,
+    checksum: str,
+    files: dict[str, str],
+    force: bool,
+) -> dict:
+    """Install a skill tree into a single target directory.
+
+    A destination that already exists and carries our marker for `name` is
+    always replaced. A destination that exists without our marker is
+    refused unless `force` is set.
+    """
+    if dest.exists() and not is_marked_for(dest, name):
+        if not force:
+            return {
+                "path": str(dest),
+                "installed": False,
+                "action": "refused",
+                "reason": "already exists and is not managed by tl (use --force to overwrite)",
+            }
+        action = "overwritten"
+    elif dest.exists():
+        action = "replaced"
+    else:
+        action = "installed"
+
+    install_skill_tree(files, dest, name=name, version=version, checksum=checksum)
+    return {"path": str(dest), "installed": True, "action": action}
+
+
+def _fetch_skill(name: str) -> dict:
+    """GET /skills/<name>/ and return its `results` block."""
+    client = get_client()
+    try:
+        data = client.get(f"/skills/{name}/")
+    finally:
+        client.close()
+    return data.get("results", data)
+
+
+def _download_and_install(name: str, *, force: bool) -> dict:
+    """Fetch a skill and install it to every target directory.
+
+    Shared by `tl skill download` and `tl skill update` — `update` always
+    passes `force=False`: a directory that already carries our marker for
+    this skill is replaced regardless of `force`, so the flag only matters
+    for a directory `tl` doesn't recognize as its own, which `update`
+    should never silently clobber.
+    """
+    validate_skill_name(name)
+    result = _fetch_skill(name)
+    version = result["version"]
+    checksum = result["checksum"]
+    files = result["files"]
+
+    validate_files(files)
+
+    targets: list[dict] = []
+    installed_count = 0
+    for target_root in _install_targets():
+        dest = target_root / name
+        outcome = _install_one(dest, name=name, version=version, checksum=checksum, files=files, force=force)
+        targets.append(outcome)
+        if outcome["installed"]:
+            installed_count += 1
+
+    if installed_count:
+        registry = read_registry()
+        registry.setdefault("skills", {})[name] = {
+            "version": version,
+            "checksum": checksum,
+            "paths": [t["path"] for t in targets if t["installed"]],
+            "installed_at": datetime.now(timezone.utc).isoformat(),
+        }
+        write_registry(registry)
+
+    return {
+        "name": name,
+        "version": version,
+        "checksum": checksum,
+        "targets": targets,
+        "installed_count": installed_count,
+    }
+
+
+def check_skill_staleness() -> str | None:
+    """Per-run staleness nag for downloaded skills.
+
+    Entirely best-effort: any failure (empty registry, no auth, network
+    down, corrupt cache, server error) silently returns None — this must
+    never break or slow down normal CLI usage. Only hits the network when
+    the cache is empty or older than 24h; otherwise reuses the cached
+    result. A *failed* network call is itself cached for a short backoff
+    window (`STALENESS_FAILURE_TTL_SECONDS`) so an unreachable/slow server
+    doesn't force a retry — and its accompanying httpx timeout — on every
+    single `tl` invocation; a success later overwrites that stamp and
+    resumes the normal 24h cache. Returns at most one short line naming
+    every skill that has drifted from its latest available version, or
+    None when nothing has (or the check was skipped/failed).
+    """
+    try:
+        registry = read_registry()
+        installed = registry.get("skills", {})
+        if not installed:
+            return None
+
+        cache = read_staleness_cache()
+        if cache is not None:
+            if cache.get("failed"):
+                return None
+            results = cache["results"]
+        else:
+            client = get_client()
+            try:
+                names = ",".join(sorted(installed.keys()))
+                data = client.get("/skills/versions/", params={"names": names}, timeout=STALENESS_CHECK_TIMEOUT_SECONDS)
+            except Exception:
+                write_staleness_failure()
+                return None
+            finally:
+                client.close()
+            results = data.get("results", {})
+            write_staleness_cache(results)
+
+        outdated = sorted(name for name, info in installed.items() if results.get(name) and results.get(name) != info.get("version"))
+        if not outdated:
+            return None
+        return f"{len(outdated)} skill(s) outdated ({', '.join(outdated)}) — run `tl skill update`"
+    except Exception:
+        return None
+
+
+# --- Typer app -------------------------------------------------------------
+
+
+@app.callback(invoke_without_command=True)
+def skill(ctx: typer.Context) -> None:
+    """Download, list, update, and remove skills distributed to your organization."""
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(list_cmd, all_=False, json_output=False, csv_output=False, md_output=False, toon_output=False)
+
+
+@app.command("list")
+def list_cmd(
+    all_: bool = typer.Option(False, "--all", help="List the full catalog (full-access accounts only)"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """List skills available to your organization (free).
+
+    Examples:
+        tl skill list
+        tl skill list --all      # full catalog (full-access accounts only)
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    client = get_client()
+    try:
+        params = {"all": "1"} if all_ else None
+        data = client.get("/skills/", params=params)
+    except ApiError as e:
+        handle_api_error(e)
+        return
+    finally:
+        client.close()
+
+    registry = read_registry()
+    installed = registry.get("skills", {})
+
+    rows = []
+    for item in data.get("results", []):
+        name = item.get("name")
+        latest = item.get("version")
+        inst = installed.get(name)
+        installed_version = inst["version"] if inst else None
+        outdated = bool(inst and latest and installed_version != latest)
+        rows.append(
+            {
+                "name": name,
+                "latest_version": latest,
+                "installed_version": installed_version or "—",
+                "status": "outdated" if outdated else "",
+                "description": _truncate(item.get("description") or ""),
+            }
+        )
+
+    if not rows:
+        if fmt == "json":
+            print(json.dumps({"results": []}, indent=2))
+        else:
+            console.print("[dim]No skills available for your organization.[/dim]")
+        return
+
+    envelope = {
+        "results": rows,
+        "total": len(rows),
+        "usage": data.get("usage"),
+        "_breadcrumbs": data.get("_breadcrumbs", []),
+    }
+    output(envelope, fmt, columns=COLUMNS, title="Skills")
+
+
+@app.command("download")
+def download_cmd(
+    name: str = typer.Argument(..., help="Skill name"),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing directory that isn't tl-managed"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Download a skill and install it into every AI-agent skill directory on this machine.
+
+    Installs into Claude Code's standalone skills directory, OpenCode's
+    skills directory, and the directory shared by Gemini and Codex — the
+    same targets `tl setup` uses for the bundled skill set. A destination
+    that already exists and isn't tracked by a previous `tl skill download`
+    is refused unless --force is passed; a destination tl previously
+    installed is always replaced with the new version.
+
+    Examples:
+        tl skill download my-skill
+        tl skill download my-skill --force
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    try:
+        result = _download_and_install(name, force=force)
+    except InvalidSkillNameError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+    except ApiError as e:
+        handle_api_error(e)
+        return
+    except PathSafetyError as e:
+        console.print(f"[red]Error:[/red] server response contains an unsafe path: {e}")
+        raise typer.Exit(1)
+
+    if fmt == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        for t in result["targets"]:
+            if t["installed"]:
+                console.print(f"  [green]✓[/green] {t['action']}: {t['path']}")
+            else:
+                console.print(f"  [red]✗[/red] {t['action']}: {t['path']} — {t['reason']}")
+        console.print()
+
+    if result["installed_count"] == 0:
+        console.print(f"[red]{name} was not installed to any location.[/red]")
+        raise typer.Exit(1)
+
+    if fmt != "json":
+        console.print(f"installed {name} v{result['version']} to {result['installed_count']} location(s)")
+
+
+@app.command("update")
+def update_cmd(
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Refresh every downloaded skill to its latest available version.
+
+    Skills no longer available to your organization are reported, not
+    deleted — remove them explicitly with `tl skill remove <name>`.
+
+    Examples:
+        tl skill update
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    registry = read_registry()
+    installed = registry.get("skills", {})
+    if not installed:
+        if fmt == "json":
+            print(json.dumps({"updated": [], "gone": [], "unchanged": [], "failed": []}, indent=2))
+        else:
+            console.print("[dim]No downloaded skills to update.[/dim]")
+        return
+
+    client = get_client()
+    try:
+        names = ",".join(sorted(installed.keys()))
+        data = client.get("/skills/versions/", params={"names": names})
+    except ApiError as e:
+        handle_api_error(e)
+        return
+    finally:
+        client.close()
+
+    latest_versions = data.get("results", {})
+    updated: list[str] = []
+    gone: list[str] = []
+    unchanged: list[str] = []
+    failed: list[dict] = []
+
+    for name in sorted(installed.keys()):
+        latest = latest_versions.get(name)
+        current = installed[name].get("version")
+        if not latest:
+            gone.append(name)
+            continue
+        if latest == current:
+            unchanged.append(name)
+            continue
+        try:
+            _download_and_install(name, force=False)
+            updated.append(name)
+        except (ApiError, PathSafetyError, InvalidSkillNameError) as e:
+            failed.append({"name": name, "error": str(e)})
+
+    if fmt == "json":
+        print(json.dumps({"updated": updated, "gone": gone, "unchanged": unchanged, "failed": failed}, indent=2))
+        return
+
+    if updated:
+        console.print(f"[green]Updated:[/green] {', '.join(updated)}")
+    if gone:
+        console.print(f"[yellow]No longer available to your organization:[/yellow] {', '.join(gone)}")
+        console.print("  Run [bold]tl skill remove <name>[/bold] to clean these up.")
+    if unchanged:
+        console.print(f"[dim]Already up to date: {', '.join(unchanged)}[/dim]")
+    if failed:
+        console.print(f"[red]Failed:[/red] {', '.join(f['name'] for f in failed)}")
+    if not (updated or gone or unchanged or failed):
+        console.print("[dim]Nothing to update.[/dim]")
+
+
+@app.command("remove")
+def remove_cmd(
+    name: str = typer.Argument(..., help="Skill name"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Remove a downloaded skill from every location tl installed it.
+
+    Only deletes a directory if it still carries the `.tl-skill.json`
+    marker for this skill — a directory that's been manually replaced is
+    left untouched and reported as skipped.
+
+    Examples:
+        tl skill remove my-skill
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    registry = read_registry()
+    installed = registry.get("skills", {})
+    entry = installed.get(name)
+    if entry is None:
+        console.print(f"[yellow]{name} is not in the local skill registry.[/yellow]")
+        raise typer.Exit(1)
+
+    removed: list[str] = []
+    skipped: list[str] = []
+    for path_str in entry.get("paths", []):
+        path = Path(path_str)
+        if is_marked_for(path, name):
+            shutil.rmtree(path)
+            removed.append(path_str)
+        else:
+            skipped.append(path_str)
+
+    del installed[name]
+    write_registry(registry)
+
+    if fmt == "json":
+        print(json.dumps({"name": name, "removed": removed, "skipped": skipped}, indent=2))
+        return
+
+    for p in removed:
+        console.print(f"  [green]✓[/green] removed: {p}")
+    for p in skipped:
+        console.print(f"  [yellow]![/yellow] skipped (not tl-managed anymore): {p}")
+    console.print(f"{name} removed from registry ({len(removed)} location(s) deleted)")

tl_cli/main.py

@@ -32,6 +32,7 @@ from tl_cli.commands.doctor import app as doctor_app
 from tl_cli.commands.reports import app as reports_app
 from tl_cli.commands.workflows import app as workflows_app
 from tl_cli.commands.setup import app as setup_app
+from tl_cli.commands.skills import app as skills_app, check_skill_staleness
 from tl_cli.commands.snapshots import app as snapshots_app
 from tl_cli.commands.uploads import app as uploads_app
 from tl_cli.commands.whoami import app as whoami_app
@@ -82,10 +83,18 @@ def main(
         for warn in check_plugin_version():
             Console(stderr=True).print(f"[yellow]{warn}[/yellow]")
 
+    # Skip for `skill` invocations themselves — the staleness nag would be
+    # noise while the user is already running the command that fixes it.
+    if "skill" not in sys.argv:
+        warn = check_skill_staleness()
+        if warn:
+            Console(stderr=True).print(f"[yellow]{warn}[/yellow]")
+
 
 # System
 app.add_typer(auth_app, name="auth")
 app.add_typer(setup_app, name="setup")
+app.add_typer(skills_app, name="skill")
 
 # Data commands (primary interface)
 app.add_typer(sponsorships_app, name="sponsorships")

tl_cli/skill_registry.py

@@ -0,0 +1,312 @@
+"""Local bookkeeping for downloaded skills: registry, install marker, path
+safety, and atomic install.
+
+Three files this module owns:
+
+- ``~/.config/tl/skills.json`` — the registry of every skill `tl skill
+  download` has installed, and where.
+- ``.tl-skill.json`` — written inside each installed skill directory so a
+  later run can tell "this directory is ours" apart from a user's own
+  skill of the same name. `tl setup` / `tl update`'s cleanup routines are
+  expected to import ``is_marked_for`` so they never touch a marker-bearing
+  directory (see module docstring note at the bottom).
+- ``~/.config/tl/skills-check.json`` — a 24h cache for the per-run
+  staleness check in ``tl_cli.commands.skills``.
+
+Kept separate from ``tl_cli/commands/skills.py`` (the Typer app) so the
+install/registry primitives have no dependency on the HTTP client or Typer —
+that keeps them trivially importable from `tl_cli/commands/setup.py` and
+`tl_cli/self_update.py`, whose cleanup routines need `is_marked_for` to skip
+directories `tl skill download` manages (tracked as follow-up work; not part
+of this change).
+"""
+
+import json
+import ntpath
+import os
+import re
+import shutil
+import time
+import uuid
+from pathlib import Path
+
+from tl_cli.config import CONFIG_DIR
+
+REGISTRY_PATH = CONFIG_DIR / "skills.json"
+MARKER_FILENAME = ".tl-skill.json"
+STALENESS_CACHE_PATH = CONFIG_DIR / "skills-check.json"
+STALENESS_TTL_SECONDS = 24 * 3600
+# Backoff window after a *failed* staleness check (unreachable/slow server):
+# much shorter than the 24h success TTL, so the network gets retried again
+# reasonably soon, but not on literally every single `tl` invocation.
+STALENESS_FAILURE_TTL_SECONDS = 3600
+
+SKILL_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+SKILL_NAME_MAX_LENGTH = 64
+
+
+class PathSafetyError(ValueError):
+    """A server-supplied relative file path failed safety validation."""
+
+
+class InvalidSkillNameError(ValueError):
+    """A user-typed skill name doesn't match the allowed name shape."""
+
+
+def validate_skill_name(name: str) -> None:
+    """Raise `InvalidSkillNameError` unless `name` is a safe skill identifier.
+
+    Checked before any network call or path construction: `download`/`update`
+    build `target_root / name` directly from this value, so a name shaped
+    like a path (e.g. containing `/`, `..`, or backslashes) must never reach
+    that join.
+    """
+    if not isinstance(name, str) or len(name) > SKILL_NAME_MAX_LENGTH or not SKILL_NAME_RE.match(name):
+        raise InvalidSkillNameError(
+            f"invalid skill name: {name!r} — expected lowercase letters, digits, and hyphens "
+            f"(starting with a letter or digit), {SKILL_NAME_MAX_LENGTH} characters or fewer"
+        )
+
+
+# --- Path safety -------------------------------------------------------
+
+
+def validate_relpath(relpath: str) -> None:
+    """Raise `PathSafetyError` unless `relpath` is a safe relative POSIX path.
+
+    Defense in depth: the server validates the same rules before a skill
+    bundle is ever stored, but a client-side check costs nothing and
+    protects against a compromised or buggy server response before a
+    single byte is written to disk.
+    """
+    if not isinstance(relpath, str) or not relpath:
+        raise PathSafetyError(f"empty or non-string file path: {relpath!r}")
+    if "\\" in relpath:
+        raise PathSafetyError(f"backslash not allowed in path: {relpath!r}")
+    if "\x00" in relpath:
+        raise PathSafetyError(f"NUL byte not allowed in path: {relpath!r}")
+    if relpath.startswith("/"):
+        raise PathSafetyError(f"absolute path not allowed: {relpath!r}")
+    # A Windows drive-qualified path ('C:/x', 'C:x') is absolute on Windows, so
+    # joining it to the install directory would discard that directory. This is
+    # pure string logic and is correct regardless of the host OS.
+    if ntpath.splitdrive(relpath)[0]:
+        raise PathSafetyError(f"drive-qualified path not allowed: {relpath!r}")
+    for segment in relpath.split("/"):
+        if segment in ("", ".", ".."):
+            raise PathSafetyError(f"unsafe path segment in {relpath!r}")
+
+
+def validate_files(files: dict[str, str]) -> None:
+    """Validate every path in a `{relpath: content}` skill bundle upfront.
+
+    Called before any target directory is touched, so a single bad path
+    aborts the whole install rather than leaving some targets written and
+    others not.
+    """
+    for relpath, content in files.items():
+        validate_relpath(relpath)
+        if not isinstance(content, str):
+            raise PathSafetyError(f"file content for {relpath!r} must be text")
+
+
+def _resolve_within(target_dir: Path, relpath: str) -> Path:
+    """Resolve `relpath` under `target_dir`, asserting containment.
+
+    Second, independent check (path-resolution-based rather than
+    string-based) applied at write time as the ultimate safety net.
+    """
+    validate_relpath(relpath)
+    dest = (target_dir / relpath).resolve()
+    if not dest.is_relative_to(target_dir.resolve()):
+        raise PathSafetyError(f"path escapes target directory: {relpath!r}")
+    return dest
+
+
+# --- Marker --------------------------------------------------------------
+
+
+def read_marker(path: Path) -> dict | None:
+    """Read and validate `.tl-skill.json` in `path`. None if absent/invalid."""
+    marker_path = path / MARKER_FILENAME
+    try:
+        data = json.loads(marker_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    if not all(isinstance(data.get(k), str) for k in ("name", "version", "checksum", "managed_by")):
+        return None
+    return data
+
+
+def is_marked_for(path: Path, name: str) -> bool:
+    """True if `path` is a directory carrying a valid tl-managed marker for `name`.
+
+    This is the safety predicate every mutation in this module (and, per
+    the module docstring, `tl setup` / `tl update`'s cleanup routines)
+    must check before touching an existing directory: unmarked dirs are
+    never assumed to be ours.
+    """
+    if not path.is_dir():
+        return False
+    marker = read_marker(path)
+    return marker is not None and marker.get("managed_by") == "tl" and marker.get("name") == name
+
+
+def write_marker(path: Path, *, name: str, version: str, checksum: str) -> None:
+    marker = {"name": name, "version": version, "checksum": checksum, "managed_by": "tl"}
+    (path / MARKER_FILENAME).write_text(json.dumps(marker), encoding="utf-8")
+
+
+# --- Atomic install --------------------------------------------------------
+
+
+def install_skill_tree(
+    files: dict[str, str],
+    target_dir: Path,
+    *,
+    name: str,
+    version: str,
+    checksum: str,
+) -> None:
+    """Atomically write `files` (relpath -> text) into `target_dir`.
+
+    Writes the whole tree to a sibling temp directory first (same
+    filesystem, so the final rename is atomic), adds the `.tl-skill.json`
+    marker, then swaps: any existing `target_dir` is moved aside, the temp
+    directory takes its place, and the old one is deleted. On any failure
+    the temp directory is cleaned up and `target_dir` is left exactly as
+    it was — nothing partially written.
+
+    Callers are expected to have already run `validate_files` on the whole
+    bundle; the per-file `_resolve_within` check here is a second,
+    independent safety net, not the primary gate.
+    """
+    parent = target_dir.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    tmp_dir = parent / f".{name}.tmp-{uuid.uuid4().hex[:8]}"
+    try:
+        tmp_dir.mkdir(parents=True)
+        for relpath, content in files.items():
+            dest = _resolve_within(tmp_dir, relpath)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(content, encoding="utf-8")
+        write_marker(tmp_dir, name=name, version=version, checksum=checksum)
+    except Exception:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+        raise
+
+    old_dir = parent / f".{name}.old-{uuid.uuid4().hex[:8]}"
+    moved_old = False
+    if target_dir.exists():
+        target_dir.rename(old_dir)
+        moved_old = True
+    try:
+        tmp_dir.rename(target_dir)
+    except Exception:
+        if moved_old:
+            old_dir.rename(target_dir)
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+        raise
+    if moved_old:
+        shutil.rmtree(old_dir, ignore_errors=True)
+
+
+# --- Atomic JSON write -----------------------------------------------------
+
+
+def _atomic_write_json(path: Path, data: dict, *, indent: int | None = None) -> None:
+    """Write `data` as JSON to `path` via a temp file + `os.replace`.
+
+    Serialization happens before any file is touched, so a bad `data` (e.g.
+    non-serializable content) raises without disturbing `path`. The payload
+    is then written to a sibling temp file and swapped in with `os.replace`
+    — atomic on the same filesystem — so a crash mid-write can never leave
+    `path` half-written; the previous content survives untouched until the
+    swap succeeds.
+    """
+    payload = json.dumps(data, indent=indent)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.parent / f".{path.name}.tmp-{uuid.uuid4().hex[:8]}"
+    try:
+        tmp_path.write_text(payload, encoding="utf-8")
+        os.replace(tmp_path, path)
+    except OSError:
+        tmp_path.unlink(missing_ok=True)
+        raise
+
+
+# --- Registry --------------------------------------------------------------
+
+
+def read_registry() -> dict:
+    """Read `skills.json`, tolerating a missing or corrupt file."""
+    try:
+        data = json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"skills": {}}
+    if not isinstance(data, dict) or not isinstance(data.get("skills"), dict):
+        return {"skills": {}}
+    return data
+
+
+def write_registry(data: dict) -> None:
+    _atomic_write_json(REGISTRY_PATH, data, indent=2)
+
+
+# --- Staleness cache ---------------------------------------------------
+
+
+def read_staleness_cache() -> dict | None:
+    """Return the cached `/skills/versions/` outcome, success or failure.
+
+    A successful check is cached for `STALENESS_TTL_SECONDS` (24h) and
+    returns the cached `results` dict. A *failed* check (network error,
+    unreachable/slow server) is cached for the much shorter
+    `STALENESS_FAILURE_TTL_SECONDS` backoff window and returned as
+    `{"checked_at": ..., "failed": True}` — callers must check `failed`
+    before touching `results`. Returns None once either window has
+    expired, or the file is missing/corrupt/malshaped.
+    """
+    try:
+        cache = json.loads(STALENESS_CACHE_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(cache, dict):
+        return None
+    checked_at = cache.get("checked_at")
+    if not isinstance(checked_at, (int, float)):
+        return None
+
+    if cache.get("failed"):
+        if time.time() - checked_at >= STALENESS_FAILURE_TTL_SECONDS:
+            return None
+        return cache
+
+    if time.time() - checked_at >= STALENESS_TTL_SECONDS:
+        return None
+    if not isinstance(cache.get("results"), dict):
+        return None
+    return cache
+
+
+def write_staleness_cache(results: dict) -> None:
+    try:
+        _atomic_write_json(STALENESS_CACHE_PATH, {"checked_at": time.time(), "results": results})
+    except OSError:
+        pass
+
+
+def write_staleness_failure() -> None:
+    """Record a failed staleness check so the next run backs off the network.
+
+    Called instead of `write_staleness_cache` when the `/skills/versions/`
+    call itself fails — writing this stamp is what makes subsequent `tl`
+    invocations skip the network (and its timeout) for
+    `STALENESS_FAILURE_TTL_SECONDS`, instead of retrying on every run.
+    """
+    try:
+        _atomic_write_json(STALENESS_CACHE_PATH, {"checked_at": time.time(), "failed": True})
+    except OSError:
+        pass