feat(agents): deploy only the skills an agent references, inline

Fold referenced-skill deployment into deploy_agents.py: resolve_skills now
publishes each skill the agent spec names (deploy_skills.deploy_skill — create or
new version) and attaches it at latest, instead of relying on a blanket
'deploy_skills.py --skill all' step. Only the skills an agent actually uses are
published. Drop that step from deploy-agents.yml. A missing repo skill dir now
fails fast; dry-run publishes nothing. Standalone skill publishing still lives in
deploy-skills.yml. Tests + README updated.

Author: yoomlam

.github/workflows/deploy-agents.yml

@@ -1,8 +1,9 @@
 # Deploy agent + environment specs under `claude_platform/` to Claude Managed Agents platform.
 # Manually dispatched (like deploy-skills.yml / deploy-images.yml) — a maintainer chooses which agent
 # to publish after the spec change has been reviewed and merged. Resources are resolved by name
-# (create-if-absent, else update in place); agents reference skills by name. Skills are deployed FIRST
-# in this same run so every referenced skill exists before an agent attaches it. See
+# (create-if-absent, else update in place); agents reference skills by name. deploy_agents.py deploys
+# exactly the skills each selected agent references (create or new version), then attaches them at
+# latest — only the skills an agent uses are published. See
 # docs/plans/2026-07-24-001-feat-agent-spec-deploy-pipeline-plan.md.
 #
 # Prerequisites (set once in repo Settings, on the `prod` environment):
@@ -37,16 +38,11 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v7
 
-      # Skills first (R3): an agent references skills by name, resolved to skill_ids at deploy time —
-      # they must already exist on the platform. Deploying all skills here keeps them current before
-      # any agent attaches them.
-      - name: Deploy skills
-        working-directory: scripts
-        env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-        run: uv run python deploy_skills.py --skill all
-
-      - name: Deploy agent(s) and environment(s)
+      # deploy_agents.py deploys exactly the skills each selected agent references (create or new
+      # version) before attaching them at latest — so only the skills an agent uses are published,
+      # and there's no separate skills step here. To publish a skill independently of any agent, use
+      # the "Deploy skills to Claude platform" workflow (deploy-skills.yml).
+      - name: Deploy agent(s), their skills, and environment(s)
         working-directory: scripts
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

scripts/README.md

@@ -32,23 +32,25 @@ environment.
 ## `deploy_agents.py` — publish agents + environments (recurring)
 
 Deploys the agent and environment specs under `claude_platform/`, resolving each **by name**
-(create if absent, else update in place). An agent's `skills` are listed by name and translated to
-platform `skill_id`s at deploy time (reusing `deploy_skills.find_existing_skill_id`), pinned to
-`latest` — so the skill must be deployed first. Environments are always synced so an agent's
+(create if absent, else update in place). An agent's `skills` are listed by name; deploy_agents
+**publishes exactly those skills first** (via `deploy_skills.deploy_skill` — create or new version),
+then attaches them at `latest`. So only the skills an agent actually references are published — no
+separate skills step, no blanket `--skill all`. Environments are always synced so an agent's
 environment exists.
 
-Normally run by the **Deploy agents to Managed Agents** GitHub Action (manual dispatch, choose which
-agent), which runs `deploy_skills.py --skill all` first. To run locally against the real API:
+Normally run by the **Deploy agents to Claude platform** GitHub Action (manual dispatch, choose which
+agent). To run locally against the real API:
 
 ```sh
-# deploy skills first, then agents (agents reference skills by name):
-ANTHROPIC_API_KEY=sk-ant-api03-... uv run python deploy_skills.py --skill all
 ANTHROPIC_API_KEY=sk-ant-api03-... uv run python deploy_agents.py --agent all
 # or a single agent (filename stem under claude_platform/agents/):
 ANTHROPIC_API_KEY=sk-ant-api03-... uv run python deploy_agents.py --agent lik-query-project-index
-# --dry-run prints the plan (still queries the platform to decide create-vs-update) without mutating.
+# --dry-run prints the plan (still queries the platform to decide create-vs-update) without publishing.
 ```
 
+To publish a skill on its own — independent of any agent — use `deploy_skills.py` (or the
+**Deploy skills to Claude platform** workflow) directly.
+
 An agent references skills by **name**, not `skill_id` — no platform ids live in the repo. lik-ui
 likewise resolves agent/environment names to ids at startup, so the roster (`lik-ui`'s `agents.toml`)
 and specs stay id-free and survive re-initializing into a new workspace.

scripts/deploy_agents.py

@@ -4,21 +4,22 @@
 docs/plans/2026-07-24-001-feat-agent-spec-deploy-pipeline-plan.md). Each agent is a raw
 platform-format YAML under `claude_platform/agents/`; each environment is a raw-format YAML under
 `claude_platform/environments/`. This script resolves each resource **by name** (create if absent,
-else update in place) and, for agents, translates a skill *name* into its platform `skill_id` before
-the SDK call — so no ids live in the repo.
+else update in place). An agent references its skills *by name*; this script deploys exactly those
+skills first (via `deploy_skills.deploy_skill` — create or new version) and attaches them at
+`latest`, so no ids live in the repo and only the skills an agent actually uses are published.
 
-Run from the repo root (deploy skills first so referenced skills exist — the CI workflow does this):
+Run from the repo root:
 
     ANTHROPIC_API_KEY=sk-ant-... uv run --project scripts python scripts/deploy_agents.py --agent all
 
 `--agent` accepts `all` (every spec under `claude_platform/agents/`) or a single agent spec name
 (the filename stem). Environments are always synced (all specs under `claude_platform/environments/`),
 so an agent's environment exists regardless of which agent is selected. `--dry-run` prints the planned
-actions (still queries the platform to decide create-vs-update) without mutating.
+actions (still queries the platform to decide create-vs-update) without publishing anything.
 
-Skill-name resolution reuses `deploy_skills.find_existing_skill_id`, so the two scripts agree on how a
-name maps to a platform id. The Anthropic SDK is imported lazily (via `deploy_skills.build_client`) so
-the pure helpers below stay importable and unit-testable without the dependency.
+Skill deployment reuses `deploy_skills.deploy_skill` / `select_skill_dirs`, so agents and the
+standalone skill deploy agree on packaging and id resolution. The Anthropic SDK is imported lazily
+(via `deploy_skills.build_client`) so the pure helpers below stay importable and unit-testable.
 """
 
 from __future__ import annotations
@@ -101,21 +102,25 @@ def find_existing_environment(client, name: str):
     return _match_by_name(list(client.beta.environments.list()), name)
 
 
-def resolve_skills(client, skills_spec) -> list[dict]:
+def resolve_skills(client, skills_spec, *, deploy: bool = True) -> list[dict]:
     """Translate a spec's by-name ``skills`` list into platform skill refs pinned to ``latest``.
 
-    Each entry must be ``{name: <skill dir name>}``. Errors if a referenced skill isn't on the
-    platform yet — deploy it first with deploy_skills.py (the CI workflow runs that step first)."""
+    Each entry must be ``{name: <skill dir name>}``. When ``deploy`` is true (a real run), the
+    referenced skill is published first — ``deploy_skills.deploy_skill`` creates it or adds a new
+    version — and its resulting id is used, so deploying an agent also deploys exactly the skills it
+    references (and nothing else). Errors if a referenced skill has no directory under
+    ``claude_platform/skills/``. When ``deploy`` is false (dry run), nothing is published: the id is
+    resolved from the platform if the skill already exists, else shown as a placeholder."""
     resolved: list[dict] = []
     for entry in skills_spec or []:
         name = entry.get("name") if isinstance(entry, dict) else None
         if not name:
             raise ValueError(f"skill entry must reference a skill by name: {entry!r}")
-        skill_id = ds.find_existing_skill_id(client, name)
-        if skill_id is None:
-            raise ValueError(
-                f"skill '{name}' not found on the platform — deploy it first with deploy_skills.py"
-            )
+        if deploy:
+            skill_dir = ds.select_skill_dirs(name)[0]  # validates the skill exists in the repo
+            skill_id = ds.deploy_skill(client, skill_dir).skill_id
+        else:
+            skill_id = ds.find_existing_skill_id(client, name) or "<will-be-created>"
         resolved.append({"type": "custom", "skill_id": skill_id, "version": "latest"})
     return resolved
 
@@ -146,7 +151,9 @@ def deploy_agent(client, spec_path: Path, *, apply: bool = True) -> DeployResult
     agent's current version so the new version does not drop fields."""
     spec = read_spec(spec_path)
     name = spec["name"]
-    payload = {**spec, "skills": resolve_skills(client, spec.get("skills"))}
+    # Deploy exactly the skills this agent references (create/version), then attach at latest.
+    # In a dry run nothing is published.
+    payload = {**spec, "skills": resolve_skills(client, spec.get("skills"), deploy=apply)}
     existing = find_existing_agent(client, name)
     if not apply:
         return DeployResult(

scripts/test_deploy_agents.py

@@ -57,14 +57,35 @@ def update(self, env_id, **kwargs):
         return SimpleNamespace(id=env_id, name=kwargs.get("name"))
 
 
+class FakeSkills:
+    """Records create / versions.create and answers list() from a seeded set (mirrors
+    test_deploy_skills.FakeSkills) — deploy_agents now publishes referenced skills itself."""
+
+    def __init__(self, existing=None):
+        # existing: list of (skill_id, display_title)
+        self._existing = [SimpleNamespace(id=i, display_title=t) for i, t in (existing or [])]
+        self.create_calls = []
+        self.version_calls = []
+        self.versions = SimpleNamespace(create=self._version_create)
+
+    def list(self):
+        return list(self._existing)
+
+    def create(self, *, files, display_title):
+        self.create_calls.append({"files": files, "display_title": display_title})
+        return SimpleNamespace(id="skill_new", latest_version=111)
+
+    def _version_create(self, skill_id, *, files):
+        self.version_calls.append({"skill_id": skill_id, "files": files})
+        return SimpleNamespace(version=222)
+
+
 class FakeClient:
     def __init__(self, *, agents=None, environments=None, skills_list=None):
         self.beta = SimpleNamespace(
             agents=FakeAgents(agents),
             environments=FakeEnvironments(environments),
-            skills=SimpleNamespace(
-                list=lambda: [SimpleNamespace(id=i, display_title=t) for i, t in (skills_list or [])]
-            ),
+            skills=FakeSkills(skills_list),
         )
 
 
@@ -97,17 +118,25 @@ def __init__(self, *, agents=None, environments=None, skills_list=None):
 """
 
 
-def _wire(tmp_path: Path, monkeypatch, *, agent=AGENT_YAML, env=ENV_YAML):
+def _wire(tmp_path: Path, monkeypatch, *, agent=AGENT_YAML, env=ENV_YAML, skill="lik-query-project-index"):
     agents_root = tmp_path / "agents"
     envs_root = tmp_path / "environments"
+    skills_root = tmp_path / "skills"
     agents_root.mkdir()
     envs_root.mkdir()
+    skills_root.mkdir()
     if agent is not None:
         (agents_root / "lik-query-project-index.yaml").write_text(agent, encoding="utf-8")
     if env is not None:
         (envs_root / "lik-ui.yaml").write_text(env, encoding="utf-8")
+    if skill is not None:
+        # The skill the agent references, so deploy_agents can publish it (dir name == SKILL.md name).
+        sdir = skills_root / skill
+        sdir.mkdir()
+        (sdir / "SKILL.md").write_text(f"---\nname: {skill}\ndescription: test\n---\n# {skill}\n", encoding="utf-8")
     monkeypatch.setattr(da, "AGENTS_ROOT", agents_root)
     monkeypatch.setattr(da, "ENVIRONMENTS_ROOT", envs_root)
+    monkeypatch.setattr(da.ds, "SKILLS_ROOT", skills_root)
     return agents_root, envs_root
 
 
@@ -148,27 +177,50 @@ def test_match_by_name_ambiguous_raises():
         da._match_by_name(items, "A")
 
 
-# --- resolve_skills (name -> id substitution) --------------------------------------------------
+# --- resolve_skills (deploy referenced skills + name -> id substitution) -----------------------
+
+
+def test_resolve_skills_publishes_new_skill_and_substitutes_id(tmp_path, monkeypatch):
+    _wire(tmp_path, monkeypatch)
+    client = FakeClient(skills_list=[])  # skill not on platform yet -> create
+    out = da.resolve_skills(client, [{"name": "lik-query-project-index"}])
+    assert out == [{"type": "custom", "skill_id": "skill_new", "version": "latest"}]
+    assert client.beta.skills.create_calls  # the referenced skill was published
 
 
-def test_resolve_skills_substitutes_ids():
+def test_resolve_skills_publishes_new_version_when_skill_exists(tmp_path, monkeypatch):
+    _wire(tmp_path, monkeypatch)
     client = FakeClient(skills_list=[("skill_abc", "lik-query-project-index")])
     out = da.resolve_skills(client, [{"name": "lik-query-project-index"}])
     assert out == [{"type": "custom", "skill_id": "skill_abc", "version": "latest"}]
+    assert client.beta.skills.version_calls  # new version, not a duplicate create
+    assert client.beta.skills.create_calls == []
 
 
-def test_resolve_skills_missing_skill_fails_fast():
-    client = FakeClient(skills_list=[("skill_abc", "some-other-skill")])
+def test_resolve_skills_missing_repo_dir_fails_fast(tmp_path, monkeypatch):
+    _wire(tmp_path, monkeypatch)
+    client = FakeClient(skills_list=[])
     with pytest.raises(ValueError):
-        da.resolve_skills(client, [{"name": "lik-query-project-index"}])
+        da.resolve_skills(client, [{"name": "no-such-skill-in-repo"}])
+    assert client.beta.skills.create_calls == []  # nothing published
 
 
-def test_resolve_skills_entry_without_name_fails():
+def test_resolve_skills_entry_without_name_fails(tmp_path, monkeypatch):
+    _wire(tmp_path, monkeypatch)
     client = FakeClient(skills_list=[])
     with pytest.raises(ValueError):
         da.resolve_skills(client, [{"skill_id": "skill_abc"}])
 
 
+def test_resolve_skills_dry_run_does_not_publish(tmp_path, monkeypatch):
+    _wire(tmp_path, monkeypatch)
+    client = FakeClient(skills_list=[("skill_abc", "lik-query-project-index")])
+    out = da.resolve_skills(client, [{"name": "lik-query-project-index"}], deploy=False)
+    assert out == [{"type": "custom", "skill_id": "skill_abc", "version": "latest"}]
+    assert client.beta.skills.create_calls == []
+    assert client.beta.skills.version_calls == []
+
+
 # --- deploy_agent: create vs update ------------------------------------------------------------
 
 
@@ -204,13 +256,15 @@ def test_deploy_existing_agent_updates_preserving_version(tmp_path, monkeypatch)
     assert call["skills"] == [{"type": "custom", "skill_id": "skill_abc", "version": "latest"}]
 
 
-def test_deploy_agent_missing_skill_makes_no_write(tmp_path, monkeypatch):
-    agents_root, _ = _wire(tmp_path, monkeypatch)
-    client = FakeClient(agents=[], skills_list=[])  # skill not on platform
+def test_deploy_agent_missing_skill_dir_makes_no_write(tmp_path, monkeypatch):
+    # The referenced skill has no directory under claude_platform/skills/ -> fail fast, nothing written.
+    agents_root, _ = _wire(tmp_path, monkeypatch, skill=None)  # no skill dir in the repo
+    client = FakeClient(agents=[], skills_list=[])
     with pytest.raises(ValueError):
         da.deploy_agent(client, agents_root / "lik-query-project-index.yaml")
     assert client.beta.agents.create_calls == []
     assert client.beta.agents.update_calls == []
+    assert client.beta.skills.create_calls == []
 
 
 def test_deploy_agent_dry_run_makes_no_write(tmp_path, monkeypatch):
@@ -257,6 +311,8 @@ def test_main_syncs_envs_then_selected_agent(tmp_path, monkeypatch):
     # environment created before the agent
     assert client.beta.environments.create_calls[0]["name"] == "lik-ui"
     assert client.beta.agents.create_calls[0]["name"] == "LIK Query: Project Index"
+    # the agent's referenced skill was published as part of the same run
+    assert client.beta.skills.version_calls  # skill existed -> new version published
 
 
 def test_main_dry_run_mutates_nothing(tmp_path, monkeypatch):
@@ -268,3 +324,5 @@ def test_main_dry_run_mutates_nothing(tmp_path, monkeypatch):
     assert rc == 0
     assert client.beta.agents.create_calls == []
     assert client.beta.environments.create_calls == []
+    assert client.beta.skills.create_calls == []  # dry run publishes no skills either
+    assert client.beta.skills.version_calls == []