From 6f8dfcd9baea00304fa607a516935f267a4cb3b1 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Mon, 4 May 2026 23:39:22 +0000
Subject: [PATCH 1/6] Add skillserver CLI for skill publishing and management

Introduce Netclaw.SkillServer.Cli, a .NET global tool for managing
skills on a SkillServer instance. Supports publish, batch publish,
delete, list, search, verify, config, and API key management.

Key capabilities:
- Publish skill directories (SKILL.md + resource files) with idempotent
  skip-on-conflict behavior and --force for re-publishing
- Batch publish all skills in a directory via publish-all
- Auth resolution: CLI flags > env vars > config file
- AOT-compatible with hand-rolled YAML frontmatter parser
- Distributable as dotnet global tool (PackAsTool)

Also extends Netclaw.SkillClient with resource upload support
(UploadSkillWithResourcesAsync) and API key management methods.
---
 SkillServer.slnx                              |   2 +
 src/Netclaw.SkillClient/Models.cs             |  20 ++
 src/Netclaw.SkillClient/SkillServerClient.cs  |  53 ++++
 src/Netclaw.SkillServer.Cli/CliArgsParser.cs  | 171 ++++++++++++
 .../Commands/ApiKeyCommand.cs                 | 156 +++++++++++
 .../Commands/ConfigCommand.cs                 | 130 +++++++++
 .../Commands/DeleteCommand.cs                 |  62 +++++
 .../Commands/ListCommand.cs                   |  69 +++++
 .../Commands/PublishAllCommand.cs             |  95 +++++++
 .../Commands/PublishCommand.cs                |  93 +++++++
 .../Commands/VerifyCommand.cs                 | 118 +++++++++
 .../Commands/VersionsCommand.cs               |  66 +++++
 .../Config/CliConfig.cs                       |  21 ++
 .../Config/ConfigResolver.cs                  |  65 +++++
 .../Json/CliJsonContext.cs                    |  22 ++
 .../Netclaw.SkillServer.Cli.csproj            |  43 +++
 .../Output/ConsoleOutput.cs                   |  77 ++++++
 src/Netclaw.SkillServer.Cli/Program.cs        | 126 +++++++++
 .../Publishing/PublishOrchestrator.cs         | 130 +++++++++
 .../Publishing/SkillDirectoryScanner.cs       | 123 +++++++++
 .../CliArgsParserTests.cs                     | 200 ++++++++++++++
 .../ConfigResolverTests.cs                    | 101 +++++++
 .../Netclaw.SkillServer.Cli.Tests.csproj      |  26 ++
 .../SkillDirectoryScannerTests.cs             | 248 ++++++++++++++++++
 24 files changed, 2217 insertions(+)
 create mode 100644 src/Netclaw.SkillServer.Cli/CliArgsParser.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Commands/ConfigCommand.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Commands/ListCommand.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Commands/PublishAllCommand.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Commands/PublishCommand.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Commands/VersionsCommand.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Config/CliConfig.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Json/CliJsonContext.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj
 create mode 100644 src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Program.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs
 create mode 100644 tests/Netclaw.SkillServer.Cli.Tests/CliArgsParserTests.cs
 create mode 100644 tests/Netclaw.SkillServer.Cli.Tests/ConfigResolverTests.cs
 create mode 100644 tests/Netclaw.SkillServer.Cli.Tests/Netclaw.SkillServer.Cli.Tests.csproj
 create mode 100644 tests/Netclaw.SkillServer.Cli.Tests/SkillDirectoryScannerTests.cs

diff --git a/SkillServer.slnx b/SkillServer.slnx
index ade5f1c..fc7f945 100644
--- a/SkillServer.slnx
+++ b/SkillServer.slnx
@@ -9,11 +9,13 @@
   <Folder Name="/src/">
     <Project Path="src/SkillServer/SkillServer.csproj" />
     <Project Path="src/Netclaw.SkillClient/Netclaw.SkillClient.csproj" />
+    <Project Path="src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj" />
     <Project Path="src/SkillServer.AppHost/SkillServer.AppHost.csproj" />
   </Folder>
   <Folder Name="/tests/">
     <Project Path="tests/SkillServer.Tests/SkillServer.Tests.csproj" />
     <Project Path="tests/SkillServer.Integration.Tests/SkillServer.Integration.Tests.csproj" />
+    <Project Path="tests/Netclaw.SkillServer.Cli.Tests/Netclaw.SkillServer.Cli.Tests.csproj" />
   </Folder>
   <Folder Name="/docker/">
     <File Path="docker/docker-compose.yml" />
diff --git a/src/Netclaw.SkillClient/Models.cs b/src/Netclaw.SkillClient/Models.cs
index c2e4a7b..9594674 100644
--- a/src/Netclaw.SkillClient/Models.cs
+++ b/src/Netclaw.SkillClient/Models.cs
@@ -199,6 +199,24 @@ public sealed record ApiKeySummary
     public DateTimeOffset? ExpiresAt { get; init; }
 }
 
+public sealed record CreateApiKeyRequest
+{
+    [JsonPropertyName("label")]
+    public required string Label { get; init; }
+
+    [JsonPropertyName("expiresAt")]
+    public DateTimeOffset? ExpiresAt { get; init; }
+}
+
+public sealed record ErrorResponse
+{
+    [JsonPropertyName("error")]
+    public string Error { get; init; } = "";
+
+    [JsonPropertyName("message")]
+    public string Message { get; init; } = "";
+}
+
 /// <summary>
 /// JSON serialization context for AOT support.
 /// </summary>
@@ -212,5 +230,7 @@ public sealed record ApiKeySummary
 [JsonSerializable(typeof(IReadOnlyList<ApiKeySummary>))]
 [JsonSerializable(typeof(IReadOnlyList<CheckUpdateRequest>))]
 [JsonSerializable(typeof(IReadOnlyList<CheckUpdateResponse>))]
+[JsonSerializable(typeof(CreateApiKeyRequest))]
+[JsonSerializable(typeof(ErrorResponse))]
 [JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
 public partial class SkillServerClientJsonContext : JsonSerializerContext;
diff --git a/src/Netclaw.SkillClient/SkillServerClient.cs b/src/Netclaw.SkillClient/SkillServerClient.cs
index 750df1c..e08b5d9 100644
--- a/src/Netclaw.SkillClient/SkillServerClient.cs
+++ b/src/Netclaw.SkillClient/SkillServerClient.cs
@@ -194,6 +194,14 @@ public async Task<IReadOnlyList<CheckUpdateResponse>> CheckUpdatesAsync(
     public async Task<SkillUploadResponse> UploadSkillAsync(
         string name, string version, Stream skillMdContent, string? category = null,
         CancellationToken ct = default)
+    {
+        return await UploadSkillWithResourcesAsync(name, version, skillMdContent, [], category, ct);
+    }
+
+    public async Task<SkillUploadResponse> UploadSkillWithResourcesAsync(
+        string name, string version, Stream skillMdContent,
+        IReadOnlyList<(string RelativePath, Stream Content)> resources,
+        string? category = null, CancellationToken ct = default)
     {
         using var content = new MultipartFormDataContent();
         content.Add(new StringContent(name), "name");
@@ -202,12 +210,33 @@ public async Task<SkillUploadResponse> UploadSkillAsync(
             content.Add(new StringContent(category), "category");
         content.Add(new StreamContent(skillMdContent), "file", "SKILL.md");
 
+        foreach (var (relativePath, resourceStream) in resources)
+            content.Add(new StreamContent(resourceStream), "resources", relativePath);
+
         var response = await _httpClient.PostAsync("skills", content, ct);
         response.EnsureSuccessStatusCode();
         return (await response.Content.ReadFromJsonAsync(
             SkillServerClientJsonContext.Default.SkillUploadResponse, ct))!;
     }
 
+    public async Task<HttpResponseMessage> TryUploadSkillWithResourcesAsync(
+        string name, string version, Stream skillMdContent,
+        IReadOnlyList<(string RelativePath, Stream Content)> resources,
+        string? category = null, CancellationToken ct = default)
+    {
+        using var content = new MultipartFormDataContent();
+        content.Add(new StringContent(name), "name");
+        content.Add(new StringContent(version), "version");
+        if (category is not null)
+            content.Add(new StringContent(category), "category");
+        content.Add(new StreamContent(skillMdContent), "file", "SKILL.md");
+
+        foreach (var (relativePath, resourceStream) in resources)
+            content.Add(new StreamContent(resourceStream), "resources", relativePath);
+
+        return await _httpClient.PostAsync("skills", content, ct);
+    }
+
     public async Task DeleteVersionAsync(string name, string version, CancellationToken ct = default)
     {
         var response = await _httpClient.DeleteAsync(
@@ -215,6 +244,30 @@ public async Task DeleteVersionAsync(string name, string version, CancellationTo
         response.EnsureSuccessStatusCode();
     }
 
+    public async Task<CreateApiKeyResponse> CreateApiKeyAsync(
+        string label, DateTimeOffset? expiresAt = null, CancellationToken ct = default)
+    {
+        var request = new CreateApiKeyRequest { Label = label, ExpiresAt = expiresAt };
+        var response = await _httpClient.PostAsJsonAsync("api-keys",
+            request, SkillServerClientJsonContext.Default.CreateApiKeyRequest, ct);
+        response.EnsureSuccessStatusCode();
+        return (await response.Content.ReadFromJsonAsync(
+            SkillServerClientJsonContext.Default.CreateApiKeyResponse, ct))!;
+    }
+
+    public async Task<IReadOnlyList<ApiKeySummary>> ListApiKeysAsync(CancellationToken ct = default)
+    {
+        var result = await _httpClient.GetFromJsonAsync("api-keys",
+            SkillServerClientJsonContext.Default.IReadOnlyListApiKeySummary, ct);
+        return result ?? [];
+    }
+
+    public async Task DeleteApiKeyAsync(long id, CancellationToken ct = default)
+    {
+        var response = await _httpClient.DeleteAsync($"api-keys/{id}", ct);
+        response.EnsureSuccessStatusCode();
+    }
+
     public void Dispose()
     {
         if (_ownsHttpClient)
diff --git a/src/Netclaw.SkillServer.Cli/CliArgsParser.cs b/src/Netclaw.SkillServer.Cli/CliArgsParser.cs
new file mode 100644
index 0000000..49b29bf
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/CliArgsParser.cs
@@ -0,0 +1,171 @@
+// -----------------------------------------------------------------------
+// <copyright file="CliArgsParser.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Netclaw.SkillServer.Cli;
+
+public sealed class ParsedArgs
+{
+    public string Command { get; init; } = "";
+    public string SubCommand { get; init; } = "";
+    public IReadOnlyList<string> Positional { get; init; } = [];
+    public string? ServerUrl { get; init; }
+    public string? ApiKey { get; init; }
+    public string? OutputFormat { get; init; }
+    public bool Verbose { get; init; }
+    public bool Help { get; init; }
+    public bool Version { get; init; }
+    public bool Force { get; init; }
+    public bool DryRun { get; init; }
+    public bool Yes { get; init; }
+    public string? VersionOverride { get; init; }
+    public string? Search { get; init; }
+    public int? Skip { get; init; }
+    public int? Take { get; init; }
+    public string? Label { get; init; }
+    public string? ExpiresAt { get; init; }
+    public string? Key { get; init; }
+    public string? Value { get; init; }
+}
+
+public static class CliArgsParser
+{
+    public static ParsedArgs Parse(string[] args)
+    {
+        var positional = new List<string>();
+        string? serverUrl = null, apiKey = null, outputFormat = null;
+        string? versionOverride = null, search = null, label = null, expiresAt = null;
+        string? configKey = null, configValue = null;
+        int? skip = null, take = null;
+        bool verbose = false, help = false, version = false, force = false, dryRun = false, yes = false;
+
+        var command = "";
+        var subCommand = "";
+        var commandParsed = false;
+
+        for (var i = 0; i < args.Length; i++)
+        {
+            var arg = args[i];
+
+            if (!commandParsed && !arg.StartsWith('-'))
+            {
+                if (command == "")
+                {
+                    command = arg.ToLowerInvariant();
+
+                    // Two-word commands
+                    if (command is "api-key" or "config" or "publish-all")
+                    {
+                        if (command is "api-key" or "config" && i + 1 < args.Length && !args[i + 1].StartsWith('-'))
+                        {
+                            subCommand = args[++i].ToLowerInvariant();
+                        }
+
+                        commandParsed = true;
+                    }
+                    else
+                    {
+                        commandParsed = true;
+                    }
+
+                    continue;
+                }
+            }
+
+            switch (arg)
+            {
+                case "--server-url" when i + 1 < args.Length:
+                    serverUrl = args[++i];
+                    break;
+                case "--api-key" when i + 1 < args.Length:
+                    apiKey = args[++i];
+                    break;
+                case "--output" when i + 1 < args.Length:
+                    outputFormat = args[++i].ToLowerInvariant();
+                    break;
+                case "--version" when command == "":
+                    version = true;
+                    break;
+                case "--version" when i + 1 < args.Length:
+                    versionOverride = args[++i];
+                    break;
+                case "--search" when i + 1 < args.Length:
+                    search = args[++i];
+                    break;
+                case "--skip" when i + 1 < args.Length:
+                    if (int.TryParse(args[++i], out var s)) skip = s;
+                    break;
+                case "--take" when i + 1 < args.Length:
+                    if (int.TryParse(args[++i], out var t)) take = t;
+                    break;
+                case "--label" when i + 1 < args.Length:
+                    label = args[++i];
+                    break;
+                case "--expires-at" when i + 1 < args.Length:
+                    expiresAt = args[++i];
+                    break;
+                case "--verbose" or "-v":
+                    verbose = true;
+                    break;
+                case "--help" or "-h":
+                    help = true;
+                    break;
+                case "--force" or "-f":
+                    force = true;
+                    break;
+                case "--dry-run":
+                    dryRun = true;
+                    break;
+                case "--yes" or "-y":
+                    yes = true;
+                    break;
+                case "-V":
+                    version = true;
+                    break;
+                default:
+                    if (!arg.StartsWith('-'))
+                    {
+                        // For config set, first two positionals are key/value
+                        if (command == "config" && subCommand == "set")
+                        {
+                            if (configKey is null)
+                                configKey = arg;
+                            else
+                                configValue ??= arg;
+                        }
+                        else
+                        {
+                            positional.Add(arg);
+                        }
+                    }
+                    break;
+            }
+        }
+
+        return new ParsedArgs
+        {
+            Command = command,
+            SubCommand = subCommand,
+            Positional = positional,
+            ServerUrl = serverUrl,
+            ApiKey = apiKey,
+            OutputFormat = outputFormat,
+            Verbose = verbose,
+            Help = help,
+            Version = version,
+            Force = force,
+            DryRun = dryRun,
+            Yes = yes,
+            VersionOverride = versionOverride,
+            Search = search,
+            Skip = skip,
+            Take = take,
+            Label = label,
+            ExpiresAt = expiresAt,
+            Key = configKey,
+            Value = configValue
+        };
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs
new file mode 100644
index 0000000..0c108e8
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs
@@ -0,0 +1,156 @@
+// -----------------------------------------------------------------------
+// <copyright file="ApiKeyCommand.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Text.Json;
+using Netclaw.SkillClient;
+using Netclaw.SkillServer.Cli.Json;
+using Netclaw.SkillServer.Cli.Output;
+
+namespace Netclaw.SkillServer.Cli.Commands;
+
+public static class ApiKeyCommand
+{
+    public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
+    {
+        if (args.Help)
+        {
+            PrintHelp();
+            return 0;
+        }
+
+        return args.SubCommand switch
+        {
+            "create" => await Create(args, client),
+            "list" => await List(args, client),
+            "delete" => await Delete(args, client),
+            _ => ShowSubcommandHelp()
+        };
+    }
+
+    private static async Task<int> Create(ParsedArgs args, SkillServerClient client)
+    {
+        var label = args.Label;
+        if (string.IsNullOrWhiteSpace(label))
+        {
+            ConsoleOutput.WriteError("Error: --label is required.");
+            return 1;
+        }
+
+        DateTimeOffset? expiresAt = null;
+        if (!string.IsNullOrWhiteSpace(args.ExpiresAt))
+        {
+            if (DateTimeOffset.TryParse(args.ExpiresAt, out var parsed))
+                expiresAt = parsed;
+            else
+            {
+                ConsoleOutput.WriteError($"Error: Invalid date format for --expires-at: '{args.ExpiresAt}'");
+                return 1;
+            }
+        }
+
+        try
+        {
+            var response = await client.CreateApiKeyAsync(label, expiresAt);
+            ConsoleOutput.WriteSuccess($"Created API key: {response.Key}");
+            ConsoleOutput.WriteInfo($"Label: {response.Label}");
+            ConsoleOutput.WriteInfo($"ID: {response.Id}");
+            return 0;
+        }
+        catch (HttpRequestException ex)
+        {
+            ConsoleOutput.WriteError($"Error: {ex.Message}");
+            return 1;
+        }
+    }
+
+    private static async Task<int> List(ParsedArgs args, SkillServerClient client)
+    {
+        try
+        {
+            var keys = await client.ListApiKeysAsync();
+
+            if (args.OutputFormat == "json")
+            {
+                var json = JsonSerializer.Serialize(keys,
+                    CliJsonContext.Default.IReadOnlyListApiKeySummary);
+                Console.WriteLine(json);
+                return 0;
+            }
+
+            if (keys.Count == 0)
+            {
+                ConsoleOutput.WriteInfo("No API keys found.");
+                return 0;
+            }
+
+            var headers = new[] { "ID", "LABEL", "CREATED", "EXPIRES" };
+            var rows = keys.Select(k => new[]
+            {
+                k.Id.ToString(),
+                k.Label,
+                k.CreatedAt.ToString("yyyy-MM-dd"),
+                k.ExpiresAt?.ToString("yyyy-MM-dd") ?? "never"
+            }).ToList();
+
+            ConsoleOutput.WriteTable(headers, rows);
+            return 0;
+        }
+        catch (HttpRequestException ex)
+        {
+            ConsoleOutput.WriteError($"Error: {ex.Message}");
+            return 1;
+        }
+    }
+
+    private static async Task<int> Delete(ParsedArgs args, SkillServerClient client)
+    {
+        if (args.Positional.Count == 0)
+        {
+            ConsoleOutput.WriteError("Usage: skillserver api-key delete <id>");
+            return 1;
+        }
+
+        if (!long.TryParse(args.Positional[0], out var id))
+        {
+            ConsoleOutput.WriteError($"Error: Invalid API key ID: '{args.Positional[0]}'");
+            return 1;
+        }
+
+        try
+        {
+            await client.DeleteApiKeyAsync(id);
+            ConsoleOutput.WriteSuccess($"Deleted API key {id}");
+            return 0;
+        }
+        catch (HttpRequestException ex)
+        {
+            ConsoleOutput.WriteError($"Error: {ex.Message}");
+            return 1;
+        }
+    }
+
+    private static int ShowSubcommandHelp()
+    {
+        PrintHelp();
+        return 1;
+    }
+
+    private static void PrintHelp()
+    {
+        Console.WriteLine("Usage: skillserver api-key <subcommand> [options]");
+        Console.WriteLine();
+        Console.WriteLine("Manage server API keys.");
+        Console.WriteLine();
+        Console.WriteLine("Subcommands:");
+        Console.WriteLine("  create                Create a new API key");
+        Console.WriteLine("  list                  List all API keys");
+        Console.WriteLine("  delete <id>           Delete an API key");
+        Console.WriteLine();
+        Console.WriteLine("Create options:");
+        Console.WriteLine("  --label <label>       Key label (required)");
+        Console.WriteLine("  --expires-at <date>   Expiration date (optional)");
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Commands/ConfigCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/ConfigCommand.cs
new file mode 100644
index 0000000..8f6ff5a
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Commands/ConfigCommand.cs
@@ -0,0 +1,130 @@
+// -----------------------------------------------------------------------
+// <copyright file="ConfigCommand.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using Netclaw.SkillServer.Cli.Config;
+using Netclaw.SkillServer.Cli.Output;
+
+namespace Netclaw.SkillServer.Cli.Commands;
+
+public static class ConfigCommand
+{
+    public static Task<int> ExecuteAsync(ParsedArgs args)
+    {
+        if (args.Help)
+        {
+            PrintHelp();
+            return Task.FromResult(0);
+        }
+
+        return args.SubCommand switch
+        {
+            "init" => Task.FromResult(Init()),
+            "set" => Task.FromResult(Set(args)),
+            "show" => Task.FromResult(Show()),
+            _ => Task.FromResult(ShowSubcommandHelp())
+        };
+    }
+
+    private static int Init()
+    {
+        Console.Write("SkillServer URL: ");
+        var serverUrl = Console.ReadLine()?.Trim();
+
+        Console.Write("API Key: ");
+        var apiKey = Console.ReadLine()?.Trim();
+
+        if (string.IsNullOrWhiteSpace(serverUrl))
+        {
+            ConsoleOutput.WriteError("Error: Server URL is required.");
+            return 1;
+        }
+
+        var config = new CliConfig
+        {
+            ServerUrl = serverUrl,
+            ApiKey = string.IsNullOrWhiteSpace(apiKey) ? null : apiKey
+        };
+
+        ConfigResolver.SaveConfigFile(config);
+        ConsoleOutput.WriteSuccess($"Configuration saved to {ConfigResolver.ConfigFilePath}");
+        return 0;
+    }
+
+    private static int Set(ParsedArgs args)
+    {
+        if (args.Key is null || args.Value is null)
+        {
+            ConsoleOutput.WriteError("Usage: skillserver config set <key> <value>");
+            ConsoleOutput.WriteError("Keys: server-url, api-key");
+            return 1;
+        }
+
+        var config = ConfigResolver.LoadConfigFile() ?? new CliConfig();
+
+        switch (args.Key.ToLowerInvariant())
+        {
+            case "server-url":
+                config.ServerUrl = args.Value;
+                break;
+            case "api-key":
+                config.ApiKey = args.Value;
+                break;
+            default:
+                ConsoleOutput.WriteError($"Unknown config key: '{args.Key}'. Valid keys: server-url, api-key");
+                return 1;
+        }
+
+        ConfigResolver.SaveConfigFile(config);
+        ConsoleOutput.WriteSuccess($"Set {args.Key} in {ConfigResolver.ConfigFilePath}");
+        return 0;
+    }
+
+    private static int Show()
+    {
+        var config = ConfigResolver.LoadConfigFile();
+
+        if (config is null)
+        {
+            ConsoleOutput.WriteInfo("No configuration file found.");
+            ConsoleOutput.WriteInfo($"Run 'skillserver config init' to create one at {ConfigResolver.ConfigFilePath}");
+            return 0;
+        }
+
+        ConsoleOutput.WriteInfo($"server-url: {config.ServerUrl ?? "(not set)"}");
+        ConsoleOutput.WriteInfo($"api-key:    {(config.ApiKey is not null ? ConsoleOutput.MaskApiKey(config.ApiKey) : "(not set)")}");
+        ConsoleOutput.WriteDim($"source:     {ConfigResolver.ConfigFilePath}");
+
+        // Show env var overrides if present
+        var envUrl = Environment.GetEnvironmentVariable("SKILLSERVER_URL");
+        var envKey = Environment.GetEnvironmentVariable("SKILLSERVER_API_KEY");
+        if (envUrl is not null)
+            ConsoleOutput.WriteWarning($"SKILLSERVER_URL env var set (overrides config): {envUrl}");
+        if (envKey is not null)
+            ConsoleOutput.WriteWarning($"SKILLSERVER_API_KEY env var set (overrides config)");
+
+        return 0;
+    }
+
+    private static int ShowSubcommandHelp()
+    {
+        PrintHelp();
+        return 1;
+    }
+
+    private static void PrintHelp()
+    {
+        Console.WriteLine("Usage: skillserver config <subcommand>");
+        Console.WriteLine();
+        Console.WriteLine("Manage CLI configuration.");
+        Console.WriteLine();
+        Console.WriteLine("Subcommands:");
+        Console.WriteLine("  init                  Interactive first-run setup");
+        Console.WriteLine("  set <key> <value>     Set a configuration value");
+        Console.WriteLine("  show                  Show current configuration");
+        Console.WriteLine();
+        Console.WriteLine("Keys: server-url, api-key");
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs
new file mode 100644
index 0000000..f395ae8
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs
@@ -0,0 +1,62 @@
+// -----------------------------------------------------------------------
+// <copyright file="DeleteCommand.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using Netclaw.SkillClient;
+using Netclaw.SkillServer.Cli.Output;
+
+namespace Netclaw.SkillServer.Cli.Commands;
+
+public static class DeleteCommand
+{
+    public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
+    {
+        if (args.Help || args.Positional.Count < 2)
+        {
+            PrintHelp();
+            return args.Help ? 0 : 1;
+        }
+
+        var name = args.Positional[0];
+        var version = args.Positional[1];
+
+        if (!args.Yes)
+        {
+            Console.Write($"Delete {name}@{version}? [y/N]: ");
+            var response = Console.ReadLine()?.Trim().ToLowerInvariant();
+            if (response is not "y" and not "yes")
+            {
+                ConsoleOutput.WriteInfo("Cancelled.");
+                return 0;
+            }
+        }
+
+        try
+        {
+            await client.DeleteVersionAsync(name, version);
+            ConsoleOutput.WriteSuccess($"Deleted {name}@{version}");
+            return 0;
+        }
+        catch (HttpRequestException ex)
+        {
+            ConsoleOutput.WriteError($"Error: {ex.Message}");
+            return 1;
+        }
+    }
+
+    private static void PrintHelp()
+    {
+        Console.WriteLine("Usage: skillserver delete <name> <version> [options]");
+        Console.WriteLine();
+        Console.WriteLine("Delete a published skill version.");
+        Console.WriteLine();
+        Console.WriteLine("Arguments:");
+        Console.WriteLine("  <name>                Skill name");
+        Console.WriteLine("  <version>             Version to delete");
+        Console.WriteLine();
+        Console.WriteLine("Options:");
+        Console.WriteLine("  --yes, -y             Skip confirmation prompt");
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Commands/ListCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/ListCommand.cs
new file mode 100644
index 0000000..42f56d5
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Commands/ListCommand.cs
@@ -0,0 +1,69 @@
+// -----------------------------------------------------------------------
+// <copyright file="ListCommand.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Text.Json;
+using Netclaw.SkillClient;
+using Netclaw.SkillServer.Cli.Json;
+using Netclaw.SkillServer.Cli.Output;
+
+namespace Netclaw.SkillServer.Cli.Commands;
+
+public static class ListCommand
+{
+    public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
+    {
+        if (args.Help)
+        {
+            PrintHelp();
+            return 0;
+        }
+
+        IReadOnlyList<SkillSummary> skills;
+
+        if (!string.IsNullOrWhiteSpace(args.Search))
+            skills = await client.SearchSkillsAsync(args.Search, args.Skip, args.Take);
+        else
+            skills = await client.ListSkillsAsync(args.Skip, args.Take);
+
+        if (args.OutputFormat == "json")
+        {
+            var json = JsonSerializer.Serialize(skills, CliJsonContext.Default.IReadOnlyListSkillSummary);
+            Console.WriteLine(json);
+            return 0;
+        }
+
+        if (skills.Count == 0)
+        {
+            ConsoleOutput.WriteInfo("No skills found.");
+            return 0;
+        }
+
+        var headers = new[] { "NAME", "LATEST", "VERSIONS", "UPDATED" };
+        var rows = skills.Select(s => new[]
+        {
+            s.Name,
+            s.LatestVersion,
+            s.VersionCount.ToString(),
+            s.UpdatedAt.ToString("yyyy-MM-dd")
+        }).ToList();
+
+        ConsoleOutput.WriteTable(headers, rows);
+        return 0;
+    }
+
+    private static void PrintHelp()
+    {
+        Console.WriteLine("Usage: skillserver list [options]");
+        Console.WriteLine();
+        Console.WriteLine("List skills on the server.");
+        Console.WriteLine();
+        Console.WriteLine("Options:");
+        Console.WriteLine("  --search <query>      Search skills by name or description");
+        Console.WriteLine("  --skip <n>            Skip first n results");
+        Console.WriteLine("  --take <n>            Limit to n results");
+        Console.WriteLine("  --output <text|json>  Output format (default: text)");
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Commands/PublishAllCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/PublishAllCommand.cs
new file mode 100644
index 0000000..aec6031
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Commands/PublishAllCommand.cs
@@ -0,0 +1,95 @@
+// -----------------------------------------------------------------------
+// <copyright file="PublishAllCommand.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using Netclaw.SkillClient;
+using Netclaw.SkillServer.Cli.Output;
+using Netclaw.SkillServer.Cli.Publishing;
+
+namespace Netclaw.SkillServer.Cli.Commands;
+
+public static class PublishAllCommand
+{
+    public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
+    {
+        if (args.Help || args.Positional.Count == 0)
+        {
+            PrintHelp();
+            return args.Help ? 0 : 1;
+        }
+
+        var path = args.Positional[0];
+        var skills = SkillDirectoryScanner.ScanAll(path);
+
+        if (skills.Count == 0)
+        {
+            ConsoleOutput.WriteWarning($"No skills found in '{path}'.");
+            return 0;
+        }
+
+        ConsoleOutput.WriteInfo($"Scanning {path}...");
+        ConsoleOutput.WriteInfo($"Found {skills.Count} skill(s) to publish.");
+        Console.WriteLine();
+
+        if (args.DryRun)
+        {
+            foreach (var skill in skills)
+            {
+                var resourceInfo = skill.Resources.Count > 0
+                    ? $"SKILL.md + {skill.Resources.Count} resources"
+                    : "SKILL.md only";
+                ConsoleOutput.WriteInfo($"  {skill.Name}@{skill.Version} ({resourceInfo})");
+            }
+
+            return 0;
+        }
+
+        var orchestrator = new PublishOrchestrator(client);
+        int published = 0, skipped = 0, failed = 0;
+
+        foreach (var skill in skills)
+        {
+            var result = await orchestrator.PublishAsync(
+                skill, force: args.Force, verbose: args.Verbose);
+
+            switch (result.Outcome)
+            {
+                case PublishOutcome.Published:
+                    ConsoleOutput.WriteSuccess($"  {result.Name}@{result.Version}    Published");
+                    published++;
+                    break;
+                case PublishOutcome.Skipped:
+                    ConsoleOutput.WriteDim($"  {result.Name}@{result.Version}    Skipped ({result.Message})");
+                    skipped++;
+                    break;
+                case PublishOutcome.Failed:
+                    ConsoleOutput.WriteError($"  {result.Name}@{result.Version}    Failed: {result.Message}");
+                    failed++;
+                    break;
+            }
+        }
+
+        Console.WriteLine();
+        ConsoleOutput.WriteInfo($"Results: {published} published, {skipped} skipped, {failed} failed");
+
+        return failed > 0 ? 2 : 0;
+    }
+
+    private static void PrintHelp()
+    {
+        Console.WriteLine("Usage: skillserver publish-all <path> [options]");
+        Console.WriteLine();
+        Console.WriteLine("Batch-publish all skills found in subdirectories of <path>.");
+        Console.WriteLine("Each subdirectory must contain a SKILL.md with name and version in frontmatter.");
+        Console.WriteLine();
+        Console.WriteLine("Arguments:");
+        Console.WriteLine("  <path>                Parent directory containing skill subdirectories");
+        Console.WriteLine();
+        Console.WriteLine("Options:");
+        Console.WriteLine("  --force, -f           Delete existing versions before re-publishing");
+        Console.WriteLine("  --dry-run             Show what would be published without uploading");
+        Console.WriteLine("  --verbose, -v         Show detailed upload progress");
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Commands/PublishCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/PublishCommand.cs
new file mode 100644
index 0000000..ef602c3
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Commands/PublishCommand.cs
@@ -0,0 +1,93 @@
+// -----------------------------------------------------------------------
+// <copyright file="PublishCommand.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using Netclaw.SkillClient;
+using Netclaw.SkillServer.Cli.Output;
+using Netclaw.SkillServer.Cli.Publishing;
+
+namespace Netclaw.SkillServer.Cli.Commands;
+
+public static class PublishCommand
+{
+    public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
+    {
+        if (args.Help || args.Positional.Count == 0)
+        {
+            PrintHelp();
+            return args.Help ? 0 : 1;
+        }
+
+        var path = args.Positional[0];
+        var skill = SkillDirectoryScanner.ScanDirectory(path);
+
+        if (skill is null)
+        {
+            ConsoleOutput.WriteError($"Error: No valid SKILL.md found in '{path}'.");
+            ConsoleOutput.WriteError("The SKILL.md must have YAML frontmatter with 'name' and 'version' fields.");
+            return 1;
+        }
+
+        var orchestrator = new PublishOrchestrator(client);
+        var version = args.VersionOverride ?? skill.Version;
+
+        if (args.DryRun)
+        {
+            var resourceInfo = skill.Resources.Count > 0
+                ? $"SKILL.md + {skill.Resources.Count} resources"
+                : "SKILL.md only";
+            ConsoleOutput.WriteInfo($"Would publish {skill.Name}@{version} ({resourceInfo})");
+            return 0;
+        }
+
+        ConsoleOutput.WriteInfo($"Publishing {skill.Name}@{version}...");
+
+        var result = await orchestrator.PublishAsync(
+            skill, args.VersionOverride, args.Force, false, args.Verbose);
+
+        return PrintResult(result);
+    }
+
+    internal static int PrintResult(PublishResult result)
+    {
+        switch (result.Outcome)
+        {
+            case PublishOutcome.Published:
+                ConsoleOutput.WriteSuccess($"Published {result.Name}@{result.Version}");
+                if (result.Response is not null)
+                {
+                    ConsoleOutput.WriteDim($"  {result.Response.Sha256}");
+                    ConsoleOutput.WriteDim($"  {result.Response.Url}");
+                }
+                return 0;
+
+            case PublishOutcome.Skipped:
+                ConsoleOutput.WriteWarning($"Skipped {result.Name}@{result.Version} ({result.Message})");
+                return 0;
+
+            case PublishOutcome.Failed:
+                ConsoleOutput.WriteError($"Failed {result.Name}@{result.Version}: {result.Message}");
+                return 1;
+        }
+
+        return 1;
+    }
+
+    private static void PrintHelp()
+    {
+        Console.WriteLine("Usage: skillserver publish <path> [options]");
+        Console.WriteLine();
+        Console.WriteLine("Publish a skill directory to the server.");
+        Console.WriteLine();
+        Console.WriteLine("Arguments:");
+        Console.WriteLine("  <path>                Path to skill directory containing SKILL.md");
+        Console.WriteLine();
+        Console.WriteLine("Options:");
+        Console.WriteLine("  --version <version>   Override the version from frontmatter");
+        Console.WriteLine("  --force, -f           Delete existing version before re-publishing");
+        Console.WriteLine("  --dry-run             Show what would be published without uploading");
+        Console.WriteLine("  --verbose, -v         Show detailed upload progress");
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs
new file mode 100644
index 0000000..91e979d
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs
@@ -0,0 +1,118 @@
+// -----------------------------------------------------------------------
+// <copyright file="VerifyCommand.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Security.Cryptography;
+using Netclaw.SkillClient;
+using Netclaw.SkillServer.Cli.Output;
+using Netclaw.SkillServer.Cli.Publishing;
+
+namespace Netclaw.SkillServer.Cli.Commands;
+
+public static class VerifyCommand
+{
+    public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
+    {
+        if (args.Help || args.Positional.Count == 0)
+        {
+            PrintHelp();
+            return args.Help ? 0 : 1;
+        }
+
+        var path = args.Positional[0];
+        var skill = SkillDirectoryScanner.ScanDirectory(path);
+
+        if (skill is null)
+        {
+            ConsoleOutput.WriteError($"Error: No valid SKILL.md found in '{path}'.");
+            return 1;
+        }
+
+        var version = args.VersionOverride ?? skill.Version;
+        ConsoleOutput.WriteInfo($"Verifying {skill.Name}@{version}...");
+
+        try
+        {
+            var serverVersion = await client.GetVersionAsync(skill.Name, version);
+            if (serverVersion is null)
+            {
+                ConsoleOutput.WriteError($"Error: {skill.Name}@{version} not found on server.");
+                return 1;
+            }
+
+            var allMatch = true;
+
+            // Verify SKILL.md
+            var localDigest = await ComputeFileDigestAsync(skill.SkillMdPath);
+            var serverDigest = serverVersion.Sha256;
+            var match = string.Equals(localDigest, serverDigest, StringComparison.OrdinalIgnoreCase);
+            if (match)
+                ConsoleOutput.WriteSuccess("  SKILL.md    match");
+            else
+            {
+                ConsoleOutput.WriteError($"  SKILL.md    MISMATCH (local: {localDigest[..15]}... server: {serverDigest[..15]}...)");
+                allMatch = false;
+            }
+
+            // Verify resources by downloading and comparing
+            foreach (var resource in skill.Resources)
+            {
+                try
+                {
+                    var serverContent = await client.GetSkillFileAsStringAsync(
+                        skill.Name, version, resource.RelativePath);
+                    var localContent = await File.ReadAllTextAsync(resource.AbsolutePath);
+
+                    if (localContent == serverContent)
+                        ConsoleOutput.WriteSuccess($"  {resource.RelativePath}    match");
+                    else
+                    {
+                        ConsoleOutput.WriteError($"  {resource.RelativePath}    MISMATCH");
+                        allMatch = false;
+                    }
+                }
+                catch (HttpRequestException)
+                {
+                    ConsoleOutput.WriteError($"  {resource.RelativePath}    NOT FOUND on server");
+                    allMatch = false;
+                }
+            }
+
+            if (allMatch)
+            {
+                ConsoleOutput.WriteSuccess("All files verified");
+                return 0;
+            }
+
+            ConsoleOutput.WriteError("Verification failed");
+            return 1;
+        }
+        catch (HttpRequestException ex)
+        {
+            ConsoleOutput.WriteError($"Error: {ex.Message}");
+            return 1;
+        }
+    }
+
+    private static async Task<string> ComputeFileDigestAsync(string filePath)
+    {
+        await using var stream = File.OpenRead(filePath);
+        var hash = await SHA256.HashDataAsync(stream);
+        return "sha256:" + Convert.ToHexString(hash).ToLowerInvariant();
+    }
+
+    private static void PrintHelp()
+    {
+        Console.WriteLine("Usage: skillserver verify <path> [options]");
+        Console.WriteLine();
+        Console.WriteLine("Verify that a local skill directory matches the published version.");
+        Console.WriteLine();
+        Console.WriteLine("Arguments:");
+        Console.WriteLine("  <path>                Path to skill directory containing SKILL.md");
+        Console.WriteLine();
+        Console.WriteLine("Options:");
+        Console.WriteLine("  --version <version>   Version to verify against (default: from frontmatter)");
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Commands/VersionsCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/VersionsCommand.cs
new file mode 100644
index 0000000..dd2d46d
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Commands/VersionsCommand.cs
@@ -0,0 +1,66 @@
+// -----------------------------------------------------------------------
+// <copyright file="VersionsCommand.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Text.Json;
+using Netclaw.SkillClient;
+using Netclaw.SkillServer.Cli.Json;
+using Netclaw.SkillServer.Cli.Output;
+
+namespace Netclaw.SkillServer.Cli.Commands;
+
+public static class VersionsCommand
+{
+    public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
+    {
+        if (args.Help || args.Positional.Count == 0)
+        {
+            PrintHelp();
+            return args.Help ? 0 : 1;
+        }
+
+        var name = args.Positional[0];
+        var versions = await client.GetSkillVersionsAsync(name);
+
+        if (args.OutputFormat == "json")
+        {
+            var json = JsonSerializer.Serialize(versions,
+                CliJsonContext.Default.IReadOnlyListSkillVersionSummary);
+            Console.WriteLine(json);
+            return 0;
+        }
+
+        if (versions.Count == 0)
+        {
+            ConsoleOutput.WriteInfo($"No versions found for '{name}'.");
+            return 0;
+        }
+
+        var headers = new[] { "VERSION", "PUBLISHED", "LATEST", "SHA256" };
+        var rows = versions.Select(v => new[]
+        {
+            v.Version,
+            v.PublishedAt.ToString("yyyy-MM-dd"),
+            v.IsLatest ? "*" : "",
+            v.Sha256.Length > 15 ? v.Sha256[..15] + "..." : v.Sha256
+        }).ToList();
+
+        ConsoleOutput.WriteTable(headers, rows);
+        return 0;
+    }
+
+    private static void PrintHelp()
+    {
+        Console.WriteLine("Usage: skillserver versions <name> [options]");
+        Console.WriteLine();
+        Console.WriteLine("List all versions of a skill.");
+        Console.WriteLine();
+        Console.WriteLine("Arguments:");
+        Console.WriteLine("  <name>                Skill name");
+        Console.WriteLine();
+        Console.WriteLine("Options:");
+        Console.WriteLine("  --output <text|json>  Output format (default: text)");
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Config/CliConfig.cs b/src/Netclaw.SkillServer.Cli/Config/CliConfig.cs
new file mode 100644
index 0000000..3fbb673
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Config/CliConfig.cs
@@ -0,0 +1,21 @@
+// -----------------------------------------------------------------------
+// <copyright file="CliConfig.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Text.Json.Serialization;
+
+namespace Netclaw.SkillServer.Cli.Config;
+
+public sealed class CliConfig
+{
+    [JsonPropertyName("configVersion")]
+    public int ConfigVersion { get; set; } = 1;
+
+    [JsonPropertyName("serverUrl")]
+    public string? ServerUrl { get; set; }
+
+    [JsonPropertyName("apiKey")]
+    public string? ApiKey { get; set; }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs b/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
new file mode 100644
index 0000000..ef64a49
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
@@ -0,0 +1,65 @@
+// -----------------------------------------------------------------------
+// <copyright file="ConfigResolver.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Runtime.InteropServices;
+using System.Text.Json;
+using Netclaw.SkillServer.Cli.Json;
+
+namespace Netclaw.SkillServer.Cli.Config;
+
+public sealed class ConfigResolver
+{
+    public static readonly string ConfigDirectory = Path.Combine(
+        Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
+        ".skillserver");
+
+    public static readonly string ConfigFilePath = Path.Combine(ConfigDirectory, "config.json");
+
+    public ResolvedConfig Resolve(string? flagServerUrl = null, string? flagApiKey = null)
+    {
+        // Priority: CLI flags > env vars > config file
+        var fileConfig = LoadConfigFile();
+
+        var serverUrl = flagServerUrl
+                        ?? Environment.GetEnvironmentVariable("SKILLSERVER_URL")
+                        ?? fileConfig?.ServerUrl;
+
+        var apiKey = flagApiKey
+                     ?? Environment.GetEnvironmentVariable("SKILLSERVER_API_KEY")
+                     ?? fileConfig?.ApiKey;
+
+        return new ResolvedConfig(serverUrl, apiKey);
+    }
+
+    public static CliConfig? LoadConfigFile()
+    {
+        if (!File.Exists(ConfigFilePath))
+            return null;
+
+        var json = File.ReadAllText(ConfigFilePath);
+        return JsonSerializer.Deserialize(json, CliJsonContext.Default.CliConfig);
+    }
+
+    public static void SaveConfigFile(CliConfig config)
+    {
+        Directory.CreateDirectory(ConfigDirectory);
+        var json = JsonSerializer.Serialize(config, CliJsonContext.Default.CliConfig);
+        File.WriteAllText(ConfigFilePath, json);
+
+        // Set file permissions to owner-only on Unix
+        if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+        {
+            File.SetUnixFileMode(ConfigFilePath,
+                UnixFileMode.UserRead | UnixFileMode.UserWrite);
+        }
+    }
+}
+
+public sealed record ResolvedConfig(string? ServerUrl, string? ApiKey)
+{
+    public bool HasServerUrl => !string.IsNullOrWhiteSpace(ServerUrl);
+    public bool HasApiKey => !string.IsNullOrWhiteSpace(ApiKey);
+}
diff --git a/src/Netclaw.SkillServer.Cli/Json/CliJsonContext.cs b/src/Netclaw.SkillServer.Cli/Json/CliJsonContext.cs
new file mode 100644
index 0000000..e92e00a
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Json/CliJsonContext.cs
@@ -0,0 +1,22 @@
+// -----------------------------------------------------------------------
+// <copyright file="CliJsonContext.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Text.Json.Serialization;
+using Netclaw.SkillServer.Cli.Config;
+using Netclaw.SkillClient;
+
+namespace Netclaw.SkillServer.Cli.Json;
+
+[JsonSerializable(typeof(CliConfig))]
+[JsonSerializable(typeof(IReadOnlyList<SkillSummary>))]
+[JsonSerializable(typeof(IReadOnlyList<SkillVersionSummary>))]
+[JsonSerializable(typeof(IReadOnlyList<ApiKeySummary>))]
+[JsonSerializable(typeof(SkillUploadResponse))]
+[JsonSerializable(typeof(ErrorResponse))]
+[JsonSourceGenerationOptions(
+    WriteIndented = true,
+    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
+public sealed partial class CliJsonContext : JsonSerializerContext;
diff --git a/src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj b/src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj
new file mode 100644
index 0000000..71fdea4
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj
@@ -0,0 +1,43 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>$(NetLibVersion)</TargetFramework>
+    <AssemblyName>skillserver</AssemblyName>
+    <RootNamespace>Netclaw.SkillServer.Cli</RootNamespace>
+    <Description>CLI tool for publishing and managing skills on a SkillServer instance.</Description>
+    <IsPackable>true</IsPackable>
+    <PackAsTool>true</PackAsTool>
+    <ToolCommandName>skillserver</ToolCommandName>
+  </PropertyGroup>
+
+  <!-- AOT Compatibility -->
+  <PropertyGroup>
+    <IsAotCompatible>true</IsAotCompatible>
+    <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
+    <JsonSerializerIsReflectionEnabledByDefault>false</JsonSerializerIsReflectionEnabledByDefault>
+    <InvariantGlobalization>true</InvariantGlobalization>
+  </PropertyGroup>
+
+  <!-- Self-contained single-file publishing -->
+  <PropertyGroup Condition="'$(PublishSingleFile)' == 'true'">
+    <SelfContained>true</SelfContained>
+    <EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
+    <IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
+  </PropertyGroup>
+
+  <!-- Override Directory.Build.props README with CLI-specific one -->
+  <ItemGroup>
+    <None Remove="$(MSBuildThisFileDirectory)..\..\README.md" />
+    <None Include="README.md" Pack="true" PackagePath="\" Condition="Exists('README.md')" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <InternalsVisibleTo Include="Netclaw.SkillServer.Cli.Tests" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Netclaw.SkillClient\Netclaw.SkillClient.csproj" />
+  </ItemGroup>
+
+</Project>
diff --git a/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs b/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs
new file mode 100644
index 0000000..8cf364b
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs
@@ -0,0 +1,77 @@
+// -----------------------------------------------------------------------
+// <copyright file="ConsoleOutput.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Netclaw.SkillServer.Cli.Output;
+
+public static class ConsoleOutput
+{
+    private static bool IsTty => !Console.IsOutputRedirected;
+
+    public static void WriteSuccess(string message)
+    {
+        if (IsTty) Console.ForegroundColor = ConsoleColor.Green;
+        Console.WriteLine(message);
+        if (IsTty) Console.ResetColor();
+    }
+
+    public static void WriteError(string message)
+    {
+        if (IsTty) Console.ForegroundColor = ConsoleColor.Red;
+        Console.Error.WriteLine(message);
+        if (IsTty) Console.ResetColor();
+    }
+
+    public static void WriteWarning(string message)
+    {
+        if (IsTty) Console.ForegroundColor = ConsoleColor.Yellow;
+        Console.Error.WriteLine(message);
+        if (IsTty) Console.ResetColor();
+    }
+
+    public static void WriteInfo(string message)
+    {
+        Console.WriteLine(message);
+    }
+
+    public static void WriteDim(string message)
+    {
+        if (IsTty) Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine(message);
+        if (IsTty) Console.ResetColor();
+    }
+
+    public static void WriteTable(string[] headers, IReadOnlyList<string[]> rows)
+    {
+        var widths = new int[headers.Length];
+        for (var i = 0; i < headers.Length; i++)
+            widths[i] = headers[i].Length;
+
+        foreach (var row in rows)
+        {
+            for (var i = 0; i < row.Length && i < widths.Length; i++)
+            {
+                if (row[i].Length > widths[i])
+                    widths[i] = row[i].Length;
+            }
+        }
+
+        var header = string.Join("  ", headers.Select((h, i) => h.PadRight(widths[i])));
+        Console.WriteLine(header);
+
+        foreach (var row in rows)
+        {
+            var line = string.Join("  ", row.Select((v, i) => i < widths.Length ? v.PadRight(widths[i]) : v));
+            Console.WriteLine(line);
+        }
+    }
+
+    public static string MaskApiKey(string key)
+    {
+        if (key.Length <= 10)
+            return new string('*', key.Length);
+        return key[..6] + "..." + key[^4..];
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Program.cs b/src/Netclaw.SkillServer.Cli/Program.cs
new file mode 100644
index 0000000..25229ae
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Program.cs
@@ -0,0 +1,126 @@
+// -----------------------------------------------------------------------
+// <copyright file="Program.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Reflection;
+using Netclaw.SkillClient;
+using Netclaw.SkillServer.Cli;
+using Netclaw.SkillServer.Cli.Commands;
+using Netclaw.SkillServer.Cli.Config;
+using Netclaw.SkillServer.Cli.Output;
+
+var parsedArgs = CliArgsParser.Parse(args);
+
+if (parsedArgs.Version)
+{
+    var version = Assembly.GetExecutingAssembly()
+        .GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion
+        ?? Assembly.GetExecutingAssembly().GetName().Version?.ToString()
+        ?? "unknown";
+    Console.WriteLine($"skillserver {version}");
+    return 0;
+}
+
+if (parsedArgs.Help && parsedArgs.Command == "")
+{
+    PrintHelp();
+    return 0;
+}
+
+if (parsedArgs.Command == "")
+{
+    PrintHelp();
+    return 1;
+}
+
+// Config command doesn't need a server connection
+if (parsedArgs.Command == "config")
+    return await ConfigCommand.ExecuteAsync(parsedArgs);
+
+// --help on subcommands should work without auth
+if (parsedArgs.Help)
+{
+    using var helpClient = new SkillServerClient("http://placeholder");
+    return parsedArgs.Command switch
+    {
+        "publish" => await PublishCommand.ExecuteAsync(parsedArgs, helpClient),
+        "publish-all" => await PublishAllCommand.ExecuteAsync(parsedArgs, helpClient),
+        "delete" => await DeleteCommand.ExecuteAsync(parsedArgs, helpClient),
+        "list" => await ListCommand.ExecuteAsync(parsedArgs, helpClient),
+        "versions" => await VersionsCommand.ExecuteAsync(parsedArgs, helpClient),
+        "verify" => await VerifyCommand.ExecuteAsync(parsedArgs, helpClient),
+        "api-key" => await ApiKeyCommand.ExecuteAsync(parsedArgs, helpClient),
+        _ => UnknownCommand(parsedArgs.Command)
+    };
+}
+
+// All other commands need resolved config
+var resolver = new ConfigResolver();
+var config = resolver.Resolve(parsedArgs.ServerUrl, parsedArgs.ApiKey);
+
+// Read-only commands that don't require auth
+var readOnlyCommands = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+    { "list", "versions", "verify" };
+
+var requiresAuth = !readOnlyCommands.Contains(parsedArgs.Command);
+
+if (!config.HasServerUrl)
+{
+    ConsoleOutput.WriteError("Error: Server URL not configured.");
+    ConsoleOutput.WriteError("Set SKILLSERVER_URL or run 'skillserver config init'");
+    return 1;
+}
+
+if (requiresAuth && !config.HasApiKey)
+{
+    ConsoleOutput.WriteError("Error: Authentication required.");
+    ConsoleOutput.WriteError("Set SKILLSERVER_API_KEY or run 'skillserver config init'");
+    return 1;
+}
+
+using var client = new SkillServerClient(config.ServerUrl!, config.ApiKey);
+
+return parsedArgs.Command switch
+{
+    "publish" => await PublishCommand.ExecuteAsync(parsedArgs, client),
+    "publish-all" => await PublishAllCommand.ExecuteAsync(parsedArgs, client),
+    "delete" => await DeleteCommand.ExecuteAsync(parsedArgs, client),
+    "list" => await ListCommand.ExecuteAsync(parsedArgs, client),
+    "versions" => await VersionsCommand.ExecuteAsync(parsedArgs, client),
+    "verify" => await VerifyCommand.ExecuteAsync(parsedArgs, client),
+    "api-key" => await ApiKeyCommand.ExecuteAsync(parsedArgs, client),
+    _ => UnknownCommand(parsedArgs.Command)
+};
+
+static int UnknownCommand(string command)
+{
+    ConsoleOutput.WriteError($"Unknown command: '{command}'");
+    Console.WriteLine();
+    PrintHelp();
+    return 1;
+}
+
+static void PrintHelp()
+{
+    Console.WriteLine("Usage: skillserver <command> [options]");
+    Console.WriteLine();
+    Console.WriteLine("Commands:");
+    Console.WriteLine("  publish <path>            Publish a skill directory to the server");
+    Console.WriteLine("  publish-all <path>        Batch-publish all skills in a directory");
+    Console.WriteLine("  delete <name> <version>   Delete a published skill version");
+    Console.WriteLine("  list                      List skills on the server");
+    Console.WriteLine("  versions <name>           List all versions of a skill");
+    Console.WriteLine("  verify <path>             Verify local skill matches published version");
+    Console.WriteLine("  config                    Manage CLI configuration");
+    Console.WriteLine("  api-key                   Manage server API keys");
+    Console.WriteLine();
+    Console.WriteLine("Global options:");
+    Console.WriteLine("  --server-url <url>        SkillServer URL (overrides config/env)");
+    Console.WriteLine("  --api-key <key>           API key (overrides config/env)");
+    Console.WriteLine("  --output <text|json>      Output format (default: text)");
+    Console.WriteLine("  --verbose, -v             Enable verbose output");
+    Console.WriteLine("  --help, -h                Show help");
+    Console.WriteLine("  --version                 Show version");
+}
diff --git a/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs b/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs
new file mode 100644
index 0000000..3ea52f6
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs
@@ -0,0 +1,130 @@
+// -----------------------------------------------------------------------
+// <copyright file="PublishOrchestrator.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Net;
+using System.Net.Http.Json;
+using Netclaw.SkillClient;
+using Netclaw.SkillServer.Cli.Output;
+
+namespace Netclaw.SkillServer.Cli.Publishing;
+
+public enum PublishOutcome
+{
+    Published,
+    Skipped,
+    Failed
+}
+
+public sealed record PublishResult(
+    string Name,
+    string Version,
+    PublishOutcome Outcome,
+    string? Message = null,
+    SkillUploadResponse? Response = null);
+
+public sealed class PublishOrchestrator
+{
+    private readonly SkillServerClient _client;
+
+    public PublishOrchestrator(SkillServerClient client)
+    {
+        _client = client;
+    }
+
+    public async Task<PublishResult> PublishAsync(
+        ScannedSkill skill,
+        string? versionOverride = null,
+        bool force = false,
+        bool dryRun = false,
+        bool verbose = false,
+        CancellationToken ct = default)
+    {
+        var version = versionOverride ?? skill.Version;
+
+        if (dryRun)
+        {
+            var resourceInfo = skill.Resources.Count > 0
+                ? $"SKILL.md + {skill.Resources.Count} resources"
+                : "SKILL.md only";
+            return new PublishResult(skill.Name, version, PublishOutcome.Skipped,
+                $"Would publish ({resourceInfo})");
+        }
+
+        if (force)
+        {
+            try
+            {
+                await _client.DeleteVersionAsync(skill.Name, version, ct);
+                if (verbose)
+                    ConsoleOutput.WriteDim($"  Deleted existing {skill.Name}@{version}");
+            }
+            catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
+            {
+                if (verbose)
+                    ConsoleOutput.WriteDim($"  No existing version to delete for {skill.Name}@{version}");
+            }
+        }
+
+        var resources = new List<(string RelativePath, Stream Content)>();
+        FileStream? skillMdStream = null;
+        try
+        {
+            skillMdStream = File.OpenRead(skill.SkillMdPath);
+
+            foreach (var resource in skill.Resources)
+            {
+                resources.Add((resource.RelativePath, File.OpenRead(resource.AbsolutePath)));
+            }
+
+            if (verbose)
+            {
+                var fileSize = new FileInfo(skill.SkillMdPath).Length;
+                ConsoleOutput.WriteDim($"  Uploading SKILL.md ({FormatSize(fileSize)})");
+                foreach (var resource in skill.Resources)
+                {
+                    var size = new FileInfo(resource.AbsolutePath).Length;
+                    ConsoleOutput.WriteDim($"  Uploading {resource.RelativePath} ({FormatSize(size)})");
+                }
+            }
+
+            var response = await _client.TryUploadSkillWithResourcesAsync(
+                skill.Name, version, skillMdStream, resources, skill.Category, ct);
+
+            if (response.StatusCode == HttpStatusCode.Conflict)
+            {
+                return new PublishResult(skill.Name, version, PublishOutcome.Skipped,
+                    "Already published");
+            }
+
+            response.EnsureSuccessStatusCode();
+
+            var uploadResponse = await response.Content.ReadFromJsonAsync(
+                SkillServerClientJsonContext.Default.SkillUploadResponse, ct);
+
+            return new PublishResult(skill.Name, version, PublishOutcome.Published,
+                Response: uploadResponse);
+        }
+        catch (HttpRequestException ex)
+        {
+            return new PublishResult(skill.Name, version, PublishOutcome.Failed,
+                ex.Message);
+        }
+        finally
+        {
+            if (skillMdStream is not null)
+                await skillMdStream.DisposeAsync();
+            foreach (var (_, stream) in resources)
+                await stream.DisposeAsync();
+        }
+    }
+
+    private static string FormatSize(long bytes) => bytes switch
+    {
+        < 1024 => $"{bytes} B",
+        < 1024 * 1024 => $"{bytes / 1024.0:F1} KB",
+        _ => $"{bytes / (1024.0 * 1024.0):F1} MB"
+    };
+}
diff --git a/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs b/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs
new file mode 100644
index 0000000..adcd2fc
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs
@@ -0,0 +1,123 @@
+// -----------------------------------------------------------------------
+// <copyright file="SkillDirectoryScanner.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Text.RegularExpressions;
+
+namespace Netclaw.SkillServer.Cli.Publishing;
+
+public sealed record ScannedSkill(
+    string DirectoryPath,
+    string Name,
+    string Version,
+    string? Category,
+    string? Description,
+    string SkillMdPath,
+    IReadOnlyList<ScannedResource> Resources);
+
+public sealed record ScannedResource(string RelativePath, string AbsolutePath);
+
+public static partial class SkillDirectoryScanner
+{
+    [GeneratedRegex(@"^---\s*\n(.*?)\n---", RegexOptions.Singleline)]
+    private static partial Regex FrontmatterRegex();
+
+    public static ScannedSkill? ScanDirectory(string directoryPath)
+    {
+        var dir = Path.GetFullPath(directoryPath);
+        if (!Directory.Exists(dir))
+            return null;
+
+        var skillMdPath = Path.Combine(dir, "SKILL.md");
+        if (!File.Exists(skillMdPath))
+            return null;
+
+        var content = File.ReadAllText(skillMdPath);
+        var frontmatter = ParseFrontmatter(content);
+        if (frontmatter is null)
+            return null;
+
+        var name = frontmatter.GetValueOrDefault("name");
+        var version = frontmatter.GetValueOrDefault("version");
+        var category = frontmatter.GetValueOrDefault("category");
+        var description = frontmatter.GetValueOrDefault("description");
+
+        if (string.IsNullOrWhiteSpace(name) || string.IsNullOrWhiteSpace(version))
+            return null;
+
+        var resources = ScanResources(dir);
+
+        return new ScannedSkill(dir, name, version, category, description, skillMdPath, resources);
+    }
+
+    public static IReadOnlyList<ScannedSkill> ScanAll(string parentDirectory)
+    {
+        var dir = Path.GetFullPath(parentDirectory);
+        if (!Directory.Exists(dir))
+            return [];
+
+        var results = new List<ScannedSkill>();
+        foreach (var subDir in Directory.EnumerateDirectories(dir).OrderBy(d => d, StringComparer.OrdinalIgnoreCase))
+        {
+            var scanned = ScanDirectory(subDir);
+            if (scanned is not null)
+                results.Add(scanned);
+        }
+
+        return results;
+    }
+
+    private static IReadOnlyList<ScannedResource> ScanResources(string skillDirectory)
+    {
+        var resources = new List<ScannedResource>();
+
+        foreach (var subDir in Directory.EnumerateDirectories(skillDirectory))
+        {
+            foreach (var file in Directory.EnumerateFiles(subDir, "*", SearchOption.AllDirectories))
+            {
+                var relativePath = Path.GetRelativePath(skillDirectory, file)
+                    .Replace('\\', '/');
+                resources.Add(new ScannedResource(relativePath, file));
+            }
+        }
+
+        return resources;
+    }
+
+    internal static Dictionary<string, string>? ParseFrontmatter(string content)
+    {
+        var match = FrontmatterRegex().Match(content);
+        if (!match.Success)
+            return null;
+
+        var yaml = match.Groups[1].Value;
+        var result = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var line in yaml.Split('\n', StringSplitOptions.TrimEntries))
+        {
+            if (string.IsNullOrEmpty(line) || line.StartsWith('#'))
+                continue;
+
+            var colonIndex = line.IndexOf(':');
+            if (colonIndex <= 0)
+                continue;
+
+            var key = line[..colonIndex].Trim();
+            var value = line[(colonIndex + 1)..].Trim();
+
+            // Strip surrounding quotes
+            if (value.Length >= 2 &&
+                ((value[0] == '"' && value[^1] == '"') ||
+                 (value[0] == '\'' && value[^1] == '\'')))
+            {
+                value = value[1..^1];
+            }
+
+            result[key] = value;
+        }
+
+        return result.Count > 0 ? result : null;
+    }
+}
diff --git a/tests/Netclaw.SkillServer.Cli.Tests/CliArgsParserTests.cs b/tests/Netclaw.SkillServer.Cli.Tests/CliArgsParserTests.cs
new file mode 100644
index 0000000..b62fc43
--- /dev/null
+++ b/tests/Netclaw.SkillServer.Cli.Tests/CliArgsParserTests.cs
@@ -0,0 +1,200 @@
+// -----------------------------------------------------------------------
+// <copyright file="CliArgsParserTests.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using Xunit;
+
+namespace Netclaw.SkillServer.Cli.Tests;
+
+public sealed class CliArgsParserTests
+{
+    [Fact]
+    public void Parse_VersionFlag_SetsVersion()
+    {
+        var result = CliArgsParser.Parse(["--version"]);
+
+        Assert.True(result.Version);
+        Assert.Equal("", result.Command);
+    }
+
+    [Fact]
+    public void Parse_HelpFlag_SetsHelp()
+    {
+        var result = CliArgsParser.Parse(["--help"]);
+
+        Assert.True(result.Help);
+    }
+
+    [Fact]
+    public void Parse_ShortHelpFlag_SetsHelp()
+    {
+        var result = CliArgsParser.Parse(["-h"]);
+
+        Assert.True(result.Help);
+    }
+
+    [Fact]
+    public void Parse_PublishCommand_WithPath()
+    {
+        var result = CliArgsParser.Parse(["publish", "./my-skill"]);
+
+        Assert.Equal("publish", result.Command);
+        Assert.Single(result.Positional);
+        Assert.Equal("./my-skill", result.Positional[0]);
+    }
+
+    [Fact]
+    public void Parse_PublishCommand_WithAllFlags()
+    {
+        var result = CliArgsParser.Parse([
+            "publish", "./my-skill",
+            "--version", "2.0.0",
+            "--force",
+            "--dry-run",
+            "--verbose",
+            "--server-url", "https://example.com",
+            "--api-key", "sk-test"
+        ]);
+
+        Assert.Equal("publish", result.Command);
+        Assert.Equal("./my-skill", result.Positional[0]);
+        Assert.Equal("2.0.0", result.VersionOverride);
+        Assert.True(result.Force);
+        Assert.True(result.DryRun);
+        Assert.True(result.Verbose);
+        Assert.Equal("https://example.com", result.ServerUrl);
+        Assert.Equal("sk-test", result.ApiKey);
+    }
+
+    [Fact]
+    public void Parse_PublishAllCommand()
+    {
+        var result = CliArgsParser.Parse(["publish-all", "./skills"]);
+
+        Assert.Equal("publish-all", result.Command);
+        Assert.Single(result.Positional);
+        Assert.Equal("./skills", result.Positional[0]);
+    }
+
+    [Fact]
+    public void Parse_ListCommand_WithSearch()
+    {
+        var result = CliArgsParser.Parse(["list", "--search", "akka", "--take", "10"]);
+
+        Assert.Equal("list", result.Command);
+        Assert.Equal("akka", result.Search);
+        Assert.Equal(10, result.Take);
+    }
+
+    [Fact]
+    public void Parse_ListCommand_WithJsonOutput()
+    {
+        var result = CliArgsParser.Parse(["list", "--output", "json"]);
+
+        Assert.Equal("list", result.Command);
+        Assert.Equal("json", result.OutputFormat);
+    }
+
+    [Fact]
+    public void Parse_DeleteCommand_WithArgs()
+    {
+        var result = CliArgsParser.Parse(["delete", "my-skill", "1.0.0", "--yes"]);
+
+        Assert.Equal("delete", result.Command);
+        Assert.Equal(2, result.Positional.Count);
+        Assert.Equal("my-skill", result.Positional[0]);
+        Assert.Equal("1.0.0", result.Positional[1]);
+        Assert.True(result.Yes);
+    }
+
+    [Fact]
+    public void Parse_VersionsCommand()
+    {
+        var result = CliArgsParser.Parse(["versions", "my-skill"]);
+
+        Assert.Equal("versions", result.Command);
+        Assert.Single(result.Positional);
+        Assert.Equal("my-skill", result.Positional[0]);
+    }
+
+    [Fact]
+    public void Parse_ConfigInit()
+    {
+        var result = CliArgsParser.Parse(["config", "init"]);
+
+        Assert.Equal("config", result.Command);
+        Assert.Equal("init", result.SubCommand);
+    }
+
+    [Fact]
+    public void Parse_ConfigSet()
+    {
+        var result = CliArgsParser.Parse(["config", "set", "server-url", "https://example.com"]);
+
+        Assert.Equal("config", result.Command);
+        Assert.Equal("set", result.SubCommand);
+        Assert.Equal("server-url", result.Key);
+        Assert.Equal("https://example.com", result.Value);
+    }
+
+    [Fact]
+    public void Parse_ApiKeyCreate()
+    {
+        var result = CliArgsParser.Parse(["api-key", "create", "--label", "CI Pipeline"]);
+
+        Assert.Equal("api-key", result.Command);
+        Assert.Equal("create", result.SubCommand);
+        Assert.Equal("CI Pipeline", result.Label);
+    }
+
+    [Fact]
+    public void Parse_ApiKeyDelete()
+    {
+        var result = CliArgsParser.Parse(["api-key", "delete", "7"]);
+
+        Assert.Equal("api-key", result.Command);
+        Assert.Equal("delete", result.SubCommand);
+        Assert.Single(result.Positional);
+        Assert.Equal("7", result.Positional[0]);
+    }
+
+    [Fact]
+    public void Parse_ShortFlags()
+    {
+        var result = CliArgsParser.Parse(["publish", "./skill", "-f", "-v"]);
+
+        Assert.True(result.Force);
+        Assert.True(result.Verbose);
+    }
+
+    [Fact]
+    public void Parse_EmptyArgs_NoCommand()
+    {
+        var result = CliArgsParser.Parse([]);
+
+        Assert.Equal("", result.Command);
+        Assert.False(result.Help);
+        Assert.False(result.Version);
+    }
+
+    [Fact]
+    public void Parse_SkipAndTake()
+    {
+        var result = CliArgsParser.Parse(["list", "--skip", "20", "--take", "50"]);
+
+        Assert.Equal(20, result.Skip);
+        Assert.Equal(50, result.Take);
+    }
+
+    [Fact]
+    public void Parse_VerifyCommand()
+    {
+        var result = CliArgsParser.Parse(["verify", "./my-skill", "--version", "1.0.0"]);
+
+        Assert.Equal("verify", result.Command);
+        Assert.Equal("./my-skill", result.Positional[0]);
+        Assert.Equal("1.0.0", result.VersionOverride);
+    }
+}
diff --git a/tests/Netclaw.SkillServer.Cli.Tests/ConfigResolverTests.cs b/tests/Netclaw.SkillServer.Cli.Tests/ConfigResolverTests.cs
new file mode 100644
index 0000000..b3ab94a
--- /dev/null
+++ b/tests/Netclaw.SkillServer.Cli.Tests/ConfigResolverTests.cs
@@ -0,0 +1,101 @@
+// -----------------------------------------------------------------------
+// <copyright file="ConfigResolverTests.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using Netclaw.SkillServer.Cli.Config;
+using Xunit;
+
+namespace Netclaw.SkillServer.Cli.Tests;
+
+public sealed class ConfigResolverTests
+{
+    [Fact]
+    public void Resolve_CliFlags_TakePriority()
+    {
+        var resolver = new ConfigResolver();
+        var result = resolver.Resolve(
+            flagServerUrl: "https://flag.example.com",
+            flagApiKey: "flag-key");
+
+        Assert.Equal("https://flag.example.com", result.ServerUrl);
+        Assert.Equal("flag-key", result.ApiKey);
+        Assert.True(result.HasServerUrl);
+        Assert.True(result.HasApiKey);
+    }
+
+    [Fact]
+    public void Resolve_NoConfig_ReturnsEmpty()
+    {
+        var originalUrl = Environment.GetEnvironmentVariable("SKILLSERVER_URL");
+        var originalKey = Environment.GetEnvironmentVariable("SKILLSERVER_API_KEY");
+
+        try
+        {
+            Environment.SetEnvironmentVariable("SKILLSERVER_URL", null);
+            Environment.SetEnvironmentVariable("SKILLSERVER_API_KEY", null);
+
+            var resolver = new ConfigResolver();
+            var result = resolver.Resolve();
+
+            Assert.False(result.HasServerUrl);
+            Assert.False(result.HasApiKey);
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable("SKILLSERVER_URL", originalUrl);
+            Environment.SetEnvironmentVariable("SKILLSERVER_API_KEY", originalKey);
+        }
+    }
+
+    [Fact]
+    public void Resolve_EnvVars_UsedWhenNoFlags()
+    {
+        var originalUrl = Environment.GetEnvironmentVariable("SKILLSERVER_URL");
+        var originalKey = Environment.GetEnvironmentVariable("SKILLSERVER_API_KEY");
+
+        try
+        {
+            Environment.SetEnvironmentVariable("SKILLSERVER_URL", "https://env.example.com");
+            Environment.SetEnvironmentVariable("SKILLSERVER_API_KEY", "env-key");
+
+            var resolver = new ConfigResolver();
+            var result = resolver.Resolve();
+
+            Assert.Equal("https://env.example.com", result.ServerUrl);
+            Assert.Equal("env-key", result.ApiKey);
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable("SKILLSERVER_URL", originalUrl);
+            Environment.SetEnvironmentVariable("SKILLSERVER_API_KEY", originalKey);
+        }
+    }
+
+    [Fact]
+    public void Resolve_Flags_OverrideEnvVars()
+    {
+        var originalUrl = Environment.GetEnvironmentVariable("SKILLSERVER_URL");
+        var originalKey = Environment.GetEnvironmentVariable("SKILLSERVER_API_KEY");
+
+        try
+        {
+            Environment.SetEnvironmentVariable("SKILLSERVER_URL", "https://env.example.com");
+            Environment.SetEnvironmentVariable("SKILLSERVER_API_KEY", "env-key");
+
+            var resolver = new ConfigResolver();
+            var result = resolver.Resolve(
+                flagServerUrl: "https://flag.example.com",
+                flagApiKey: "flag-key");
+
+            Assert.Equal("https://flag.example.com", result.ServerUrl);
+            Assert.Equal("flag-key", result.ApiKey);
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable("SKILLSERVER_URL", originalUrl);
+            Environment.SetEnvironmentVariable("SKILLSERVER_API_KEY", originalKey);
+        }
+    }
+}
diff --git a/tests/Netclaw.SkillServer.Cli.Tests/Netclaw.SkillServer.Cli.Tests.csproj b/tests/Netclaw.SkillServer.Cli.Tests/Netclaw.SkillServer.Cli.Tests.csproj
new file mode 100644
index 0000000..cb849c8
--- /dev/null
+++ b/tests/Netclaw.SkillServer.Cli.Tests/Netclaw.SkillServer.Cli.Tests.csproj
@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>$(NetTestVersion)</TargetFramework>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="xunit.v3" />
+    <PackageReference Include="xunit.runner.visualstudio">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="coverlet.collector">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Netclaw.SkillServer.Cli\Netclaw.SkillServer.Cli.csproj" />
+  </ItemGroup>
+
+</Project>
diff --git a/tests/Netclaw.SkillServer.Cli.Tests/SkillDirectoryScannerTests.cs b/tests/Netclaw.SkillServer.Cli.Tests/SkillDirectoryScannerTests.cs
new file mode 100644
index 0000000..78f41e3
--- /dev/null
+++ b/tests/Netclaw.SkillServer.Cli.Tests/SkillDirectoryScannerTests.cs
@@ -0,0 +1,248 @@
+// -----------------------------------------------------------------------
+// <copyright file="SkillDirectoryScannerTests.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using Netclaw.SkillServer.Cli.Publishing;
+using Xunit;
+
+namespace Netclaw.SkillServer.Cli.Tests;
+
+public sealed class SkillDirectoryScannerTests : IDisposable
+{
+    private readonly string _tempDir;
+
+    public SkillDirectoryScannerTests()
+    {
+        _tempDir = Path.Combine(Path.GetTempPath(), "skillserver-test-" + Guid.NewGuid().ToString("N")[..8]);
+        Directory.CreateDirectory(_tempDir);
+    }
+
+    public void Dispose()
+    {
+        if (Directory.Exists(_tempDir))
+            Directory.Delete(_tempDir, true);
+    }
+
+    [Fact]
+    public void ScanDirectory_WithValidSkill_ReturnsScannedSkill()
+    {
+        var skillDir = Path.Combine(_tempDir, "my-skill");
+        Directory.CreateDirectory(skillDir);
+        File.WriteAllText(Path.Combine(skillDir, "SKILL.md"), """
+            ---
+            name: my-skill
+            version: 1.0.0
+            description: A test skill
+            category: testing
+            ---
+            # My Skill
+            Content here.
+            """);
+
+        var result = SkillDirectoryScanner.ScanDirectory(skillDir);
+
+        Assert.NotNull(result);
+        Assert.Equal("my-skill", result.Name);
+        Assert.Equal("1.0.0", result.Version);
+        Assert.Equal("testing", result.Category);
+        Assert.Equal("A test skill", result.Description);
+        Assert.Empty(result.Resources);
+    }
+
+    [Fact]
+    public void ScanDirectory_WithResources_FindsResourceFiles()
+    {
+        var skillDir = Path.Combine(_tempDir, "skill-with-resources");
+        Directory.CreateDirectory(skillDir);
+        File.WriteAllText(Path.Combine(skillDir, "SKILL.md"), """
+            ---
+            name: skill-with-resources
+            version: 2.0.0
+            description: Has resources
+            ---
+            # Skill
+            """);
+
+        var refDir = Path.Combine(skillDir, "references");
+        Directory.CreateDirectory(refDir);
+        File.WriteAllText(Path.Combine(refDir, "guide.md"), "# Guide");
+        File.WriteAllText(Path.Combine(refDir, "config.md"), "# Config");
+
+        var result = SkillDirectoryScanner.ScanDirectory(skillDir);
+
+        Assert.NotNull(result);
+        Assert.Equal(2, result.Resources.Count);
+        Assert.Contains(result.Resources, r => r.RelativePath == "references/guide.md");
+        Assert.Contains(result.Resources, r => r.RelativePath == "references/config.md");
+    }
+
+    [Fact]
+    public void ScanDirectory_MissingSkillMd_ReturnsNull()
+    {
+        var skillDir = Path.Combine(_tempDir, "empty-skill");
+        Directory.CreateDirectory(skillDir);
+
+        var result = SkillDirectoryScanner.ScanDirectory(skillDir);
+
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public void ScanDirectory_MissingFrontmatter_ReturnsNull()
+    {
+        var skillDir = Path.Combine(_tempDir, "no-frontmatter");
+        Directory.CreateDirectory(skillDir);
+        File.WriteAllText(Path.Combine(skillDir, "SKILL.md"), "# Just content, no frontmatter");
+
+        var result = SkillDirectoryScanner.ScanDirectory(skillDir);
+
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public void ScanDirectory_MissingName_ReturnsNull()
+    {
+        var skillDir = Path.Combine(_tempDir, "no-name");
+        Directory.CreateDirectory(skillDir);
+        File.WriteAllText(Path.Combine(skillDir, "SKILL.md"), """
+            ---
+            version: 1.0.0
+            description: Missing name
+            ---
+            # Content
+            """);
+
+        var result = SkillDirectoryScanner.ScanDirectory(skillDir);
+
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public void ScanDirectory_MissingVersion_ReturnsNull()
+    {
+        var skillDir = Path.Combine(_tempDir, "no-version");
+        Directory.CreateDirectory(skillDir);
+        File.WriteAllText(Path.Combine(skillDir, "SKILL.md"), """
+            ---
+            name: no-version
+            description: Missing version
+            ---
+            # Content
+            """);
+
+        var result = SkillDirectoryScanner.ScanDirectory(skillDir);
+
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public void ScanDirectory_NonexistentPath_ReturnsNull()
+    {
+        var result = SkillDirectoryScanner.ScanDirectory("/nonexistent/path");
+
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public void ScanAll_FindsMultipleSkills()
+    {
+        CreateSkill("alpha", "1.0.0");
+        CreateSkill("beta", "2.0.0");
+        CreateSkill("gamma", "0.1.0");
+
+        // Create a non-skill directory
+        Directory.CreateDirectory(Path.Combine(_tempDir, "not-a-skill"));
+
+        var results = SkillDirectoryScanner.ScanAll(_tempDir);
+
+        Assert.Equal(3, results.Count);
+        Assert.Equal("alpha", results[0].Name);
+        Assert.Equal("beta", results[1].Name);
+        Assert.Equal("gamma", results[2].Name);
+    }
+
+    [Fact]
+    public void ScanAll_EmptyDirectory_ReturnsEmpty()
+    {
+        var results = SkillDirectoryScanner.ScanAll(_tempDir);
+
+        Assert.Empty(results);
+    }
+
+    [Fact]
+    public void ScanAll_NonexistentDirectory_ReturnsEmpty()
+    {
+        var results = SkillDirectoryScanner.ScanAll("/nonexistent/path");
+
+        Assert.Empty(results);
+    }
+
+    [Fact]
+    public void ParseFrontmatter_ValidYaml_ReturnsDictionary()
+    {
+        var content = """
+            ---
+            name: test-skill
+            version: 1.0.0
+            description: A test
+            ---
+            # Content
+            """;
+
+        var result = SkillDirectoryScanner.ParseFrontmatter(content);
+
+        Assert.NotNull(result);
+        Assert.Equal("test-skill", result["name"]);
+        Assert.Equal("1.0.0", result["version"]);
+        Assert.Equal("A test", result["description"]);
+    }
+
+    [Fact]
+    public void ParseFrontmatter_NoFrontmatter_ReturnsNull()
+    {
+        var result = SkillDirectoryScanner.ParseFrontmatter("# Just content");
+
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public void ScanDirectory_NestedResources_FindsAll()
+    {
+        var skillDir = Path.Combine(_tempDir, "nested-resources");
+        Directory.CreateDirectory(skillDir);
+        File.WriteAllText(Path.Combine(skillDir, "SKILL.md"), """
+            ---
+            name: nested-resources
+            version: 1.0.0
+            description: Has nested resources
+            ---
+            # Skill
+            """);
+
+        var deepDir = Path.Combine(skillDir, "assets", "images");
+        Directory.CreateDirectory(deepDir);
+        File.WriteAllText(Path.Combine(deepDir, "diagram.md"), "# Diagram");
+
+        var result = SkillDirectoryScanner.ScanDirectory(skillDir);
+
+        Assert.NotNull(result);
+        Assert.Single(result.Resources);
+        Assert.Equal("assets/images/diagram.md", result.Resources[0].RelativePath);
+    }
+
+    private void CreateSkill(string name, string version)
+    {
+        var dir = Path.Combine(_tempDir, name);
+        Directory.CreateDirectory(dir);
+        File.WriteAllText(Path.Combine(dir, "SKILL.md"), $"""
+            ---
+            name: {name}
+            version: {version}
+            description: Skill {name}
+            ---
+            # {name}
+            """);
+    }
+}

From 456b1f77db9abb37462b89ffef233247c72aa862 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Mon, 4 May 2026 23:48:59 +0000
Subject: [PATCH 2/6] Simplify CLI: eliminate duplication, tighten visibility,
 extract PublishOptions

- Consolidate UploadSkillWithResourcesAsync to delegate to the Try
  variant instead of duplicating multipart form construction
- Extract PublishOptions record to replace boolean parameter sprawl
- Unify dry-run handling in PublishOrchestrator with shared formatting
- Deduplicate command dispatch into single DispatchAsync method
- Change all CLI types to internal (InternalsVisibleTo covers tests)
- Fix HttpResponseMessage leak in PublishOrchestrator
- Use stream.Length instead of redundant FileInfo allocations
- Remove explanatory WHAT comments per project conventions
---
 src/Netclaw.SkillClient/SkillServerClient.cs  | 13 +----
 src/Netclaw.SkillServer.Cli/CliArgsParser.cs  |  5 +-
 .../Commands/ApiKeyCommand.cs                 |  2 +-
 .../Commands/ConfigCommand.cs                 |  2 +-
 .../Commands/DeleteCommand.cs                 |  2 +-
 .../Commands/ListCommand.cs                   |  2 +-
 .../Commands/PublishAllCommand.cs             | 19 ++-----
 .../Commands/PublishCommand.cs                | 22 +++-----
 .../Commands/VerifyCommand.cs                 |  2 +-
 .../Commands/VersionsCommand.cs               |  2 +-
 .../Config/CliConfig.cs                       |  2 +-
 .../Config/ConfigResolver.cs                  |  4 +-
 .../Json/CliJsonContext.cs                    |  2 +-
 .../Output/ConsoleOutput.cs                   |  2 +-
 src/Netclaw.SkillServer.Cli/Program.cs        | 46 ++++++-----------
 .../Publishing/PublishOrchestrator.cs         | 51 ++++++++++---------
 .../Publishing/SkillDirectoryScanner.cs       |  6 +--
 17 files changed, 70 insertions(+), 114 deletions(-)

diff --git a/src/Netclaw.SkillClient/SkillServerClient.cs b/src/Netclaw.SkillClient/SkillServerClient.cs
index e08b5d9..7989521 100644
--- a/src/Netclaw.SkillClient/SkillServerClient.cs
+++ b/src/Netclaw.SkillClient/SkillServerClient.cs
@@ -203,17 +203,8 @@ public async Task<SkillUploadResponse> UploadSkillWithResourcesAsync(
         IReadOnlyList<(string RelativePath, Stream Content)> resources,
         string? category = null, CancellationToken ct = default)
     {
-        using var content = new MultipartFormDataContent();
-        content.Add(new StringContent(name), "name");
-        content.Add(new StringContent(version), "version");
-        if (category is not null)
-            content.Add(new StringContent(category), "category");
-        content.Add(new StreamContent(skillMdContent), "file", "SKILL.md");
-
-        foreach (var (relativePath, resourceStream) in resources)
-            content.Add(new StreamContent(resourceStream), "resources", relativePath);
-
-        var response = await _httpClient.PostAsync("skills", content, ct);
+        using var response = await TryUploadSkillWithResourcesAsync(
+            name, version, skillMdContent, resources, category, ct);
         response.EnsureSuccessStatusCode();
         return (await response.Content.ReadFromJsonAsync(
             SkillServerClientJsonContext.Default.SkillUploadResponse, ct))!;
diff --git a/src/Netclaw.SkillServer.Cli/CliArgsParser.cs b/src/Netclaw.SkillServer.Cli/CliArgsParser.cs
index 49b29bf..503b196 100644
--- a/src/Netclaw.SkillServer.Cli/CliArgsParser.cs
+++ b/src/Netclaw.SkillServer.Cli/CliArgsParser.cs
@@ -6,7 +6,7 @@
 
 namespace Netclaw.SkillServer.Cli;
 
-public sealed class ParsedArgs
+internal sealed class ParsedArgs
 {
     public string Command { get; init; } = "";
     public string SubCommand { get; init; } = "";
@@ -30,7 +30,7 @@ public sealed class ParsedArgs
     public string? Value { get; init; }
 }
 
-public static class CliArgsParser
+internal static class CliArgsParser
 {
     public static ParsedArgs Parse(string[] args)
     {
@@ -55,7 +55,6 @@ public static ParsedArgs Parse(string[] args)
                 {
                     command = arg.ToLowerInvariant();
 
-                    // Two-word commands
                     if (command is "api-key" or "config" or "publish-all")
                     {
                         if (command is "api-key" or "config" && i + 1 < args.Length && !args[i + 1].StartsWith('-'))
diff --git a/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs
index 0c108e8..1296297 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs
@@ -11,7 +11,7 @@
 
 namespace Netclaw.SkillServer.Cli.Commands;
 
-public static class ApiKeyCommand
+internal static class ApiKeyCommand
 {
     public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
     {
diff --git a/src/Netclaw.SkillServer.Cli/Commands/ConfigCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/ConfigCommand.cs
index 8f6ff5a..76154da 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/ConfigCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/ConfigCommand.cs
@@ -9,7 +9,7 @@
 
 namespace Netclaw.SkillServer.Cli.Commands;
 
-public static class ConfigCommand
+internal static class ConfigCommand
 {
     public static Task<int> ExecuteAsync(ParsedArgs args)
     {
diff --git a/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs
index f395ae8..cc9e132 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs
@@ -9,7 +9,7 @@
 
 namespace Netclaw.SkillServer.Cli.Commands;
 
-public static class DeleteCommand
+internal static class DeleteCommand
 {
     public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
     {
diff --git a/src/Netclaw.SkillServer.Cli/Commands/ListCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/ListCommand.cs
index 42f56d5..566fe5c 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/ListCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/ListCommand.cs
@@ -11,7 +11,7 @@
 
 namespace Netclaw.SkillServer.Cli.Commands;
 
-public static class ListCommand
+internal static class ListCommand
 {
     public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
     {
diff --git a/src/Netclaw.SkillServer.Cli/Commands/PublishAllCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/PublishAllCommand.cs
index aec6031..2a5995e 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/PublishAllCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/PublishAllCommand.cs
@@ -10,7 +10,7 @@
 
 namespace Netclaw.SkillServer.Cli.Commands;
 
-public static class PublishAllCommand
+internal static class PublishAllCommand
 {
     public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
     {
@@ -33,26 +33,13 @@ public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient cl
         ConsoleOutput.WriteInfo($"Found {skills.Count} skill(s) to publish.");
         Console.WriteLine();
 
-        if (args.DryRun)
-        {
-            foreach (var skill in skills)
-            {
-                var resourceInfo = skill.Resources.Count > 0
-                    ? $"SKILL.md + {skill.Resources.Count} resources"
-                    : "SKILL.md only";
-                ConsoleOutput.WriteInfo($"  {skill.Name}@{skill.Version} ({resourceInfo})");
-            }
-
-            return 0;
-        }
-
+        var options = new PublishOptions(Force: args.Force, DryRun: args.DryRun, Verbose: args.Verbose);
         var orchestrator = new PublishOrchestrator(client);
         int published = 0, skipped = 0, failed = 0;
 
         foreach (var skill in skills)
         {
-            var result = await orchestrator.PublishAsync(
-                skill, force: args.Force, verbose: args.Verbose);
+            var result = await orchestrator.PublishAsync(skill, options);
 
             switch (result.Outcome)
             {
diff --git a/src/Netclaw.SkillServer.Cli/Commands/PublishCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/PublishCommand.cs
index ef602c3..acdeb28 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/PublishCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/PublishCommand.cs
@@ -10,7 +10,7 @@
 
 namespace Netclaw.SkillServer.Cli.Commands;
 
-public static class PublishCommand
+internal static class PublishCommand
 {
     public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
     {
@@ -30,22 +30,14 @@ public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient cl
             return 1;
         }
 
-        var orchestrator = new PublishOrchestrator(client);
-        var version = args.VersionOverride ?? skill.Version;
+        var options = new PublishOptions(args.VersionOverride, args.Force, args.DryRun, args.Verbose);
+        var version = options.VersionOverride ?? skill.Version;
 
-        if (args.DryRun)
-        {
-            var resourceInfo = skill.Resources.Count > 0
-                ? $"SKILL.md + {skill.Resources.Count} resources"
-                : "SKILL.md only";
-            ConsoleOutput.WriteInfo($"Would publish {skill.Name}@{version} ({resourceInfo})");
-            return 0;
-        }
+        if (!args.DryRun)
+            ConsoleOutput.WriteInfo($"Publishing {skill.Name}@{version}...");
 
-        ConsoleOutput.WriteInfo($"Publishing {skill.Name}@{version}...");
-
-        var result = await orchestrator.PublishAsync(
-            skill, args.VersionOverride, args.Force, false, args.Verbose);
+        var orchestrator = new PublishOrchestrator(client);
+        var result = await orchestrator.PublishAsync(skill, options);
 
         return PrintResult(result);
     }
diff --git a/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs
index 91e979d..f569a06 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs
@@ -11,7 +11,7 @@
 
 namespace Netclaw.SkillServer.Cli.Commands;
 
-public static class VerifyCommand
+internal static class VerifyCommand
 {
     public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
     {
diff --git a/src/Netclaw.SkillServer.Cli/Commands/VersionsCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/VersionsCommand.cs
index dd2d46d..097c5a0 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/VersionsCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/VersionsCommand.cs
@@ -11,7 +11,7 @@
 
 namespace Netclaw.SkillServer.Cli.Commands;
 
-public static class VersionsCommand
+internal static class VersionsCommand
 {
     public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient client)
     {
diff --git a/src/Netclaw.SkillServer.Cli/Config/CliConfig.cs b/src/Netclaw.SkillServer.Cli/Config/CliConfig.cs
index 3fbb673..563fbfd 100644
--- a/src/Netclaw.SkillServer.Cli/Config/CliConfig.cs
+++ b/src/Netclaw.SkillServer.Cli/Config/CliConfig.cs
@@ -8,7 +8,7 @@
 
 namespace Netclaw.SkillServer.Cli.Config;
 
-public sealed class CliConfig
+internal sealed class CliConfig
 {
     [JsonPropertyName("configVersion")]
     public int ConfigVersion { get; set; } = 1;
diff --git a/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs b/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
index ef64a49..4fdbf5f 100644
--- a/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
+++ b/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
@@ -10,7 +10,7 @@
 
 namespace Netclaw.SkillServer.Cli.Config;
 
-public sealed class ConfigResolver
+internal sealed class ConfigResolver
 {
     public static readonly string ConfigDirectory = Path.Combine(
         Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
@@ -58,7 +58,7 @@ public static void SaveConfigFile(CliConfig config)
     }
 }
 
-public sealed record ResolvedConfig(string? ServerUrl, string? ApiKey)
+internal sealed record ResolvedConfig(string? ServerUrl, string? ApiKey)
 {
     public bool HasServerUrl => !string.IsNullOrWhiteSpace(ServerUrl);
     public bool HasApiKey => !string.IsNullOrWhiteSpace(ApiKey);
diff --git a/src/Netclaw.SkillServer.Cli/Json/CliJsonContext.cs b/src/Netclaw.SkillServer.Cli/Json/CliJsonContext.cs
index e92e00a..e6de857 100644
--- a/src/Netclaw.SkillServer.Cli/Json/CliJsonContext.cs
+++ b/src/Netclaw.SkillServer.Cli/Json/CliJsonContext.cs
@@ -19,4 +19,4 @@ namespace Netclaw.SkillServer.Cli.Json;
 [JsonSourceGenerationOptions(
     WriteIndented = true,
     PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
-public sealed partial class CliJsonContext : JsonSerializerContext;
+internal sealed partial class CliJsonContext : JsonSerializerContext;
diff --git a/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs b/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs
index 8cf364b..c947fa5 100644
--- a/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs
+++ b/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs
@@ -6,7 +6,7 @@
 
 namespace Netclaw.SkillServer.Cli.Output;
 
-public static class ConsoleOutput
+internal static class ConsoleOutput
 {
     private static bool IsTty => !Console.IsOutputRedirected;
 
diff --git a/src/Netclaw.SkillServer.Cli/Program.cs b/src/Netclaw.SkillServer.Cli/Program.cs
index 25229ae..0869090 100644
--- a/src/Netclaw.SkillServer.Cli/Program.cs
+++ b/src/Netclaw.SkillServer.Cli/Program.cs
@@ -35,36 +35,20 @@
     return 1;
 }
 
-// Config command doesn't need a server connection
 if (parsedArgs.Command == "config")
     return await ConfigCommand.ExecuteAsync(parsedArgs);
 
-// --help on subcommands should work without auth
+// --help on subcommands works without auth
 if (parsedArgs.Help)
 {
     using var helpClient = new SkillServerClient("http://placeholder");
-    return parsedArgs.Command switch
-    {
-        "publish" => await PublishCommand.ExecuteAsync(parsedArgs, helpClient),
-        "publish-all" => await PublishAllCommand.ExecuteAsync(parsedArgs, helpClient),
-        "delete" => await DeleteCommand.ExecuteAsync(parsedArgs, helpClient),
-        "list" => await ListCommand.ExecuteAsync(parsedArgs, helpClient),
-        "versions" => await VersionsCommand.ExecuteAsync(parsedArgs, helpClient),
-        "verify" => await VerifyCommand.ExecuteAsync(parsedArgs, helpClient),
-        "api-key" => await ApiKeyCommand.ExecuteAsync(parsedArgs, helpClient),
-        _ => UnknownCommand(parsedArgs.Command)
-    };
+    return await DispatchAsync(parsedArgs, helpClient);
 }
 
-// All other commands need resolved config
 var resolver = new ConfigResolver();
 var config = resolver.Resolve(parsedArgs.ServerUrl, parsedArgs.ApiKey);
 
-// Read-only commands that don't require auth
-var readOnlyCommands = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
-    { "list", "versions", "verify" };
-
-var requiresAuth = !readOnlyCommands.Contains(parsedArgs.Command);
+var requiresAuth = parsedArgs.Command is not "list" and not "versions" and not "verify";
 
 if (!config.HasServerUrl)
 {
@@ -81,18 +65,20 @@
 }
 
 using var client = new SkillServerClient(config.ServerUrl!, config.ApiKey);
+return await DispatchAsync(parsedArgs, client);
 
-return parsedArgs.Command switch
-{
-    "publish" => await PublishCommand.ExecuteAsync(parsedArgs, client),
-    "publish-all" => await PublishAllCommand.ExecuteAsync(parsedArgs, client),
-    "delete" => await DeleteCommand.ExecuteAsync(parsedArgs, client),
-    "list" => await ListCommand.ExecuteAsync(parsedArgs, client),
-    "versions" => await VersionsCommand.ExecuteAsync(parsedArgs, client),
-    "verify" => await VerifyCommand.ExecuteAsync(parsedArgs, client),
-    "api-key" => await ApiKeyCommand.ExecuteAsync(parsedArgs, client),
-    _ => UnknownCommand(parsedArgs.Command)
-};
+static async Task<int> DispatchAsync(ParsedArgs parsedArgs, SkillServerClient client) =>
+    parsedArgs.Command switch
+    {
+        "publish" => await PublishCommand.ExecuteAsync(parsedArgs, client),
+        "publish-all" => await PublishAllCommand.ExecuteAsync(parsedArgs, client),
+        "delete" => await DeleteCommand.ExecuteAsync(parsedArgs, client),
+        "list" => await ListCommand.ExecuteAsync(parsedArgs, client),
+        "versions" => await VersionsCommand.ExecuteAsync(parsedArgs, client),
+        "verify" => await VerifyCommand.ExecuteAsync(parsedArgs, client),
+        "api-key" => await ApiKeyCommand.ExecuteAsync(parsedArgs, client),
+        _ => UnknownCommand(parsedArgs.Command)
+    };
 
 static int UnknownCommand(string command)
 {
diff --git a/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs b/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs
index 3ea52f6..3055071 100644
--- a/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs
+++ b/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs
@@ -11,21 +11,27 @@
 
 namespace Netclaw.SkillServer.Cli.Publishing;
 
-public enum PublishOutcome
+internal enum PublishOutcome
 {
     Published,
     Skipped,
     Failed
 }
 
-public sealed record PublishResult(
+internal sealed record PublishOptions(
+    string? VersionOverride = null,
+    bool Force = false,
+    bool DryRun = false,
+    bool Verbose = false);
+
+internal sealed record PublishResult(
     string Name,
     string Version,
     PublishOutcome Outcome,
     string? Message = null,
     SkillUploadResponse? Response = null);
 
-public sealed class PublishOrchestrator
+internal sealed class PublishOrchestrator
 {
     private readonly SkillServerClient _client;
 
@@ -36,34 +42,28 @@ public PublishOrchestrator(SkillServerClient client)
 
     public async Task<PublishResult> PublishAsync(
         ScannedSkill skill,
-        string? versionOverride = null,
-        bool force = false,
-        bool dryRun = false,
-        bool verbose = false,
+        PublishOptions options,
         CancellationToken ct = default)
     {
-        var version = versionOverride ?? skill.Version;
+        var version = options.VersionOverride ?? skill.Version;
 
-        if (dryRun)
+        if (options.DryRun)
         {
-            var resourceInfo = skill.Resources.Count > 0
-                ? $"SKILL.md + {skill.Resources.Count} resources"
-                : "SKILL.md only";
             return new PublishResult(skill.Name, version, PublishOutcome.Skipped,
-                $"Would publish ({resourceInfo})");
+                $"Would publish ({FormatResourceInfo(skill)})");
         }
 
-        if (force)
+        if (options.Force)
         {
             try
             {
                 await _client.DeleteVersionAsync(skill.Name, version, ct);
-                if (verbose)
+                if (options.Verbose)
                     ConsoleOutput.WriteDim($"  Deleted existing {skill.Name}@{version}");
             }
             catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
             {
-                if (verbose)
+                if (options.Verbose)
                     ConsoleOutput.WriteDim($"  No existing version to delete for {skill.Name}@{version}");
             }
         }
@@ -79,18 +79,14 @@ public async Task<PublishResult> PublishAsync(
                 resources.Add((resource.RelativePath, File.OpenRead(resource.AbsolutePath)));
             }
 
-            if (verbose)
+            if (options.Verbose)
             {
-                var fileSize = new FileInfo(skill.SkillMdPath).Length;
-                ConsoleOutput.WriteDim($"  Uploading SKILL.md ({FormatSize(fileSize)})");
-                foreach (var resource in skill.Resources)
-                {
-                    var size = new FileInfo(resource.AbsolutePath).Length;
-                    ConsoleOutput.WriteDim($"  Uploading {resource.RelativePath} ({FormatSize(size)})");
-                }
+                ConsoleOutput.WriteDim($"  Uploading SKILL.md ({FormatSize(skillMdStream.Length)})");
+                foreach (var (relativePath, stream) in resources)
+                    ConsoleOutput.WriteDim($"  Uploading {relativePath} ({FormatSize(stream.Length)})");
             }
 
-            var response = await _client.TryUploadSkillWithResourcesAsync(
+            using var response = await _client.TryUploadSkillWithResourcesAsync(
                 skill.Name, version, skillMdStream, resources, skill.Category, ct);
 
             if (response.StatusCode == HttpStatusCode.Conflict)
@@ -121,6 +117,11 @@ public async Task<PublishResult> PublishAsync(
         }
     }
 
+    internal static string FormatResourceInfo(ScannedSkill skill) =>
+        skill.Resources.Count > 0
+            ? $"SKILL.md + {skill.Resources.Count} resources"
+            : "SKILL.md only";
+
     private static string FormatSize(long bytes) => bytes switch
     {
         < 1024 => $"{bytes} B",
diff --git a/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs b/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs
index adcd2fc..f89ffe1 100644
--- a/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs
+++ b/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs
@@ -8,7 +8,7 @@
 
 namespace Netclaw.SkillServer.Cli.Publishing;
 
-public sealed record ScannedSkill(
+internal sealed record ScannedSkill(
     string DirectoryPath,
     string Name,
     string Version,
@@ -17,9 +17,9 @@ public sealed record ScannedSkill(
     string SkillMdPath,
     IReadOnlyList<ScannedResource> Resources);
 
-public sealed record ScannedResource(string RelativePath, string AbsolutePath);
+internal sealed record ScannedResource(string RelativePath, string AbsolutePath);
 
-public static partial class SkillDirectoryScanner
+internal static partial class SkillDirectoryScanner
 {
     [GeneratedRegex(@"^---\s*\n(.*?)\n---", RegexOptions.Singleline)]
     private static partial Regex FrontmatterRegex();

From 9765992e2532cf7c7024a290779a3df29166d5b7 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Mon, 4 May 2026 23:58:12 +0000
Subject: [PATCH 3/6] Replace leaky HttpResponseMessage API with typed
 UploadSkillIfNotExistsAsync

- Remove TryUploadSkillWithResourcesAsync (exposed raw HttpResponseMessage)
- Add UploadSkillIfNotExistsAsync returning SkillUploadResponse? (null = 409)
- Extract PostSkillAsync as private helper to eliminate form-building duplication
- Seal SkillServerClientJsonContext
- Convert ScannedResource, PublishOptions, ResolvedConfig to readonly record structs
---
 src/Netclaw.SkillClient/Models.cs             |  2 +-
 src/Netclaw.SkillClient/SkillServerClient.cs  | 21 ++++++++++++++++---
 .../Config/ConfigResolver.cs                  |  2 +-
 .../Publishing/PublishOrchestrator.cs         | 12 +++--------
 .../Publishing/SkillDirectoryScanner.cs       |  2 +-
 5 files changed, 24 insertions(+), 15 deletions(-)

diff --git a/src/Netclaw.SkillClient/Models.cs b/src/Netclaw.SkillClient/Models.cs
index 9594674..bba8800 100644
--- a/src/Netclaw.SkillClient/Models.cs
+++ b/src/Netclaw.SkillClient/Models.cs
@@ -233,4 +233,4 @@ public sealed record ErrorResponse
 [JsonSerializable(typeof(CreateApiKeyRequest))]
 [JsonSerializable(typeof(ErrorResponse))]
 [JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
-public partial class SkillServerClientJsonContext : JsonSerializerContext;
+public sealed partial class SkillServerClientJsonContext : JsonSerializerContext;
diff --git a/src/Netclaw.SkillClient/SkillServerClient.cs b/src/Netclaw.SkillClient/SkillServerClient.cs
index 7989521..b3e3fdc 100644
--- a/src/Netclaw.SkillClient/SkillServerClient.cs
+++ b/src/Netclaw.SkillClient/SkillServerClient.cs
@@ -3,6 +3,7 @@
 //      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
 // </copyright>
 // -----------------------------------------------------------------------
+using System.Net;
 using System.Net.Http.Json;
 using System.Security.Cryptography;
 using System.Text.Json;
@@ -203,17 +204,31 @@ public async Task<SkillUploadResponse> UploadSkillWithResourcesAsync(
         IReadOnlyList<(string RelativePath, Stream Content)> resources,
         string? category = null, CancellationToken ct = default)
     {
-        using var response = await TryUploadSkillWithResourcesAsync(
-            name, version, skillMdContent, resources, category, ct);
+        using var response = await PostSkillAsync(name, version, skillMdContent, resources, category, ct);
         response.EnsureSuccessStatusCode();
         return (await response.Content.ReadFromJsonAsync(
             SkillServerClientJsonContext.Default.SkillUploadResponse, ct))!;
     }
 
-    public async Task<HttpResponseMessage> TryUploadSkillWithResourcesAsync(
+    public async Task<SkillUploadResponse?> UploadSkillIfNotExistsAsync(
         string name, string version, Stream skillMdContent,
         IReadOnlyList<(string RelativePath, Stream Content)> resources,
         string? category = null, CancellationToken ct = default)
+    {
+        using var response = await PostSkillAsync(name, version, skillMdContent, resources, category, ct);
+
+        if (response.StatusCode == HttpStatusCode.Conflict)
+            return null;
+
+        response.EnsureSuccessStatusCode();
+        return (await response.Content.ReadFromJsonAsync(
+            SkillServerClientJsonContext.Default.SkillUploadResponse, ct))!;
+    }
+
+    private async Task<HttpResponseMessage> PostSkillAsync(
+        string name, string version, Stream skillMdContent,
+        IReadOnlyList<(string RelativePath, Stream Content)> resources,
+        string? category, CancellationToken ct)
     {
         using var content = new MultipartFormDataContent();
         content.Add(new StringContent(name), "name");
diff --git a/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs b/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
index 4fdbf5f..77faca8 100644
--- a/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
+++ b/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
@@ -58,7 +58,7 @@ public static void SaveConfigFile(CliConfig config)
     }
 }
 
-internal sealed record ResolvedConfig(string? ServerUrl, string? ApiKey)
+internal readonly record struct ResolvedConfig(string? ServerUrl, string? ApiKey)
 {
     public bool HasServerUrl => !string.IsNullOrWhiteSpace(ServerUrl);
     public bool HasApiKey => !string.IsNullOrWhiteSpace(ApiKey);
diff --git a/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs b/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs
index 3055071..eaf2003 100644
--- a/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs
+++ b/src/Netclaw.SkillServer.Cli/Publishing/PublishOrchestrator.cs
@@ -5,7 +5,6 @@
 // -----------------------------------------------------------------------
 
 using System.Net;
-using System.Net.Http.Json;
 using Netclaw.SkillClient;
 using Netclaw.SkillServer.Cli.Output;
 
@@ -18,7 +17,7 @@ internal enum PublishOutcome
     Failed
 }
 
-internal sealed record PublishOptions(
+internal readonly record struct PublishOptions(
     string? VersionOverride = null,
     bool Force = false,
     bool DryRun = false,
@@ -86,20 +85,15 @@ public async Task<PublishResult> PublishAsync(
                     ConsoleOutput.WriteDim($"  Uploading {relativePath} ({FormatSize(stream.Length)})");
             }
 
-            using var response = await _client.TryUploadSkillWithResourcesAsync(
+            var uploadResponse = await _client.UploadSkillIfNotExistsAsync(
                 skill.Name, version, skillMdStream, resources, skill.Category, ct);
 
-            if (response.StatusCode == HttpStatusCode.Conflict)
+            if (uploadResponse is null)
             {
                 return new PublishResult(skill.Name, version, PublishOutcome.Skipped,
                     "Already published");
             }
 
-            response.EnsureSuccessStatusCode();
-
-            var uploadResponse = await response.Content.ReadFromJsonAsync(
-                SkillServerClientJsonContext.Default.SkillUploadResponse, ct);
-
             return new PublishResult(skill.Name, version, PublishOutcome.Published,
                 Response: uploadResponse);
         }
diff --git a/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs b/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs
index f89ffe1..bb3a40d 100644
--- a/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs
+++ b/src/Netclaw.SkillServer.Cli/Publishing/SkillDirectoryScanner.cs
@@ -17,7 +17,7 @@ internal sealed record ScannedSkill(
     string SkillMdPath,
     IReadOnlyList<ScannedResource> Resources);
 
-internal sealed record ScannedResource(string RelativePath, string AbsolutePath);
+internal readonly record struct ScannedResource(string RelativePath, string AbsolutePath);
 
 internal static partial class SkillDirectoryScanner
 {

From d5f50bcb628c382499473a764a3cc9e9273e9255 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Tue, 5 May 2026 00:22:57 +0000
Subject: [PATCH 4/6] Add end-to-end workflow tests for SkillServerClient

Exercise full CLI workflows against a real in-process SkillServer:
publish, list, versions, verify, delete, idempotent upload, force
republish, resource uploads, multi-version tracking, search, digest
verification, and API key management.

Add AuthenticatedClient to SkillServerFixture to separate read
operations (no auth) from write operations (auth required).
---
 .../CliWorkflowTests.cs                       | 251 ++++++++++++++++++
 .../SkillServerFixture.cs                     |   6 +
 2 files changed, 257 insertions(+)
 create mode 100644 tests/SkillServer.Integration.Tests/CliWorkflowTests.cs

diff --git a/tests/SkillServer.Integration.Tests/CliWorkflowTests.cs b/tests/SkillServer.Integration.Tests/CliWorkflowTests.cs
new file mode 100644
index 0000000..8a6a414
--- /dev/null
+++ b/tests/SkillServer.Integration.Tests/CliWorkflowTests.cs
@@ -0,0 +1,251 @@
+// -----------------------------------------------------------------------
+// <copyright file="CliWorkflowTests.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Text;
+using Netclaw.SkillClient;
+using Xunit;
+
+namespace SkillServer.Integration.Tests;
+
+[Collection("SkillServer")]
+public sealed class CliWorkflowTests
+{
+    private readonly SkillServerFixture _fixture;
+
+    public CliWorkflowTests(SkillServerFixture fixture)
+    {
+        _fixture = fixture;
+    }
+
+    private static MemoryStream ToStream(string content) =>
+        new(Encoding.UTF8.GetBytes(content));
+
+    [Fact]
+    public async Task PublishListVerifyDelete_FullWorkflow()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var skillName = $"wf-full-{Guid.NewGuid():N}"[..20];
+
+        var skillMd = $"""
+            ---
+            name: {skillName}
+            version: 1.0.0
+            category: testing
+            description: Full workflow test
+            ---
+
+            # {skillName}
+
+            Workflow test content.
+            """;
+
+        // Publish (auth required)
+        using var stream = ToStream(skillMd);
+        var uploadResponse = await _fixture.AuthenticatedClient.UploadSkillWithResourcesAsync(
+            skillName, "1.0.0", stream, [], "testing", ct);
+
+        Assert.Equal(skillName, uploadResponse.Name);
+        Assert.Equal("1.0.0", uploadResponse.Version);
+        Assert.StartsWith("sha256:", uploadResponse.Sha256);
+
+        // List — no auth needed
+        var skills = await _fixture.Client.ListSkillsAsync(ct: ct);
+        Assert.Contains(skills, s => s.Name == skillName);
+
+        // Versions — no auth needed
+        var versions = await _fixture.Client.GetSkillVersionsAsync(skillName, ct);
+        Assert.Single(versions);
+        Assert.Equal("1.0.0", versions[0].Version);
+        Assert.True(versions[0].IsLatest);
+
+        // Verify digest — no auth needed
+        var verified = await _fixture.Client.VerifyDigestAsync(
+            skillName, "1.0.0", uploadResponse.Sha256, ct);
+        Assert.True(verified);
+
+        // Download — no auth needed
+        var downloaded = await _fixture.Client.GetSkillFileAsStringAsync(
+            skillName, "1.0.0", ct: ct);
+        Assert.Contains("Workflow test content.", downloaded);
+
+        // Delete (auth required)
+        await _fixture.AuthenticatedClient.DeleteVersionAsync(skillName, "1.0.0", ct);
+
+        // Verify gone
+        var versionsAfter = await _fixture.Client.GetSkillVersionsAsync(skillName, ct);
+        Assert.Empty(versionsAfter);
+    }
+
+    [Fact]
+    public async Task IdempotentUpload_ReturnsNull()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var skillName = $"wf-idem-{Guid.NewGuid():N}"[..20];
+
+        var skillMd = $"---\nname: {skillName}\nversion: 1.0.0\ndescription: test\n---\n# Test";
+
+        using var stream1 = ToStream(skillMd);
+        var first = await _fixture.AuthenticatedClient.UploadSkillIfNotExistsAsync(
+            skillName, "1.0.0", stream1, [], ct: ct);
+        Assert.NotNull(first);
+
+        using var stream2 = ToStream(skillMd);
+        var second = await _fixture.AuthenticatedClient.UploadSkillIfNotExistsAsync(
+            skillName, "1.0.0", stream2, [], ct: ct);
+        Assert.Null(second);
+    }
+
+    [Fact]
+    public async Task ForceRepublish_DeleteThenUpload()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var skillName = $"wf-force-{Guid.NewGuid():N}"[..20];
+
+        using var stream1 = ToStream(
+            $"---\nname: {skillName}\nversion: 1.0.0\ndescription: v1\n---\n# V1");
+        await _fixture.AuthenticatedClient.UploadSkillWithResourcesAsync(
+            skillName, "1.0.0", stream1, [], ct: ct);
+
+        await _fixture.AuthenticatedClient.DeleteVersionAsync(skillName, "1.0.0", ct);
+
+        using var stream2 = ToStream(
+            $"---\nname: {skillName}\nversion: 1.0.0\ndescription: v1-updated\n---\n# V1 Updated");
+        var second = await _fixture.AuthenticatedClient.UploadSkillWithResourcesAsync(
+            skillName, "1.0.0", stream2, [], ct: ct);
+        Assert.NotNull(second);
+
+        var downloaded = await _fixture.Client.GetSkillFileAsStringAsync(
+            skillName, "1.0.0", ct: ct);
+        Assert.Contains("V1 Updated", downloaded);
+
+        var versions = await _fixture.Client.GetSkillVersionsAsync(skillName, ct);
+        Assert.Single(versions);
+    }
+
+    [Fact]
+    public async Task PublishWithResources_AllAccessible()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var skillName = $"wf-res-{Guid.NewGuid():N}"[..20];
+
+        var resources = new List<(string RelativePath, Stream Content)>
+        {
+            ("references/patterns.md", ToStream("# Patterns\nContent here.")),
+            ("references/examples.md", ToStream("# Examples\nMore content.")),
+            ("scripts/setup.sh", ToStream("#!/bin/bash\necho hello"))
+        };
+
+        using var skillStream = ToStream(
+            $"---\nname: {skillName}\nversion: 1.0.0\ndescription: test\n---\n# {skillName}");
+        await _fixture.AuthenticatedClient.UploadSkillWithResourcesAsync(
+            skillName, "1.0.0", skillStream, resources, ct: ct);
+
+        var patterns = await _fixture.Client.GetSkillFileAsStringAsync(
+            skillName, "1.0.0", "references/patterns.md", ct);
+        Assert.Contains("# Patterns", patterns);
+
+        var examples = await _fixture.Client.GetSkillFileAsStringAsync(
+            skillName, "1.0.0", "references/examples.md", ct);
+        Assert.Contains("# Examples", examples);
+
+        var setup = await _fixture.Client.GetSkillFileAsStringAsync(
+            skillName, "1.0.0", "scripts/setup.sh", ct);
+        Assert.Contains("echo hello", setup);
+
+        foreach (var (_, stream) in resources)
+            stream.Dispose();
+    }
+
+    [Fact]
+    public async Task MultipleVersions_LatestTracked()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var skillName = $"wf-ver-{Guid.NewGuid():N}"[..20];
+
+        using var v1 = ToStream(
+            $"---\nname: {skillName}\nversion: 1.0.0\ndescription: test\n---\n# V1");
+        await _fixture.AuthenticatedClient.UploadSkillWithResourcesAsync(
+            skillName, "1.0.0", v1, [], ct: ct);
+
+        using var v2 = ToStream(
+            $"---\nname: {skillName}\nversion: 2.0.0\ndescription: test\n---\n# V2");
+        await _fixture.AuthenticatedClient.UploadSkillWithResourcesAsync(
+            skillName, "2.0.0", v2, [], ct: ct);
+
+        var versions = await _fixture.Client.GetSkillVersionsAsync(skillName, ct);
+        Assert.Equal(2, versions.Count);
+
+        var latest = await _fixture.Client.GetLatestVersionAsync(skillName, ct);
+        Assert.NotNull(latest);
+        Assert.Equal("2.0.0", latest.Version);
+
+        var updates = await _fixture.Client.CheckUpdatesAsync([
+            new CheckUpdateRequest { Name = skillName, Version = "1.0.0" }
+        ], ct);
+        Assert.Single(updates);
+        Assert.True(updates[0].HasUpdate);
+        Assert.Equal("2.0.0", updates[0].LatestVersion);
+    }
+
+    [Fact]
+    public async Task SearchSkills_FindsByName()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var uniqueToken = Guid.NewGuid().ToString("N")[..8];
+        var skillName = $"wf-srch-{uniqueToken}";
+
+        using var stream = ToStream(
+            $"---\nname: {skillName}\nversion: 1.0.0\ndescription: Searchable skill\n---\n# {skillName}");
+        await _fixture.AuthenticatedClient.UploadSkillWithResourcesAsync(
+            skillName, "1.0.0", stream, [], ct: ct);
+
+        var results = await _fixture.Client.SearchSkillsAsync(uniqueToken, ct: ct);
+        Assert.Contains(results, s => s.Name == skillName);
+    }
+
+    [Fact]
+    public async Task DigestMismatch_Detected()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var skillName = $"wf-dig-{Guid.NewGuid():N}"[..20];
+
+        using var stream = ToStream(
+            $"---\nname: {skillName}\nversion: 1.0.0\ndescription: test\n---\n# Test");
+        await _fixture.AuthenticatedClient.UploadSkillWithResourcesAsync(
+            skillName, "1.0.0", stream, [], ct: ct);
+
+        var mismatch = await _fixture.Client.VerifyDigestAsync(
+            skillName, "1.0.0", "sha256:0000000000000000000000000000000000000000000000000000000000000000", ct);
+        Assert.False(mismatch);
+    }
+
+    [Fact]
+    public async Task DeleteNonexistent_Throws()
+    {
+        var ct = TestContext.Current.CancellationToken;
+
+        await Assert.ThrowsAsync<HttpRequestException>(() =>
+            _fixture.AuthenticatedClient.DeleteVersionAsync("nonexistent-skill", "99.99.99", ct));
+    }
+
+    [Fact]
+    public async Task ApiKeyManagement_ViaClient()
+    {
+        var ct = TestContext.Current.CancellationToken;
+
+        var created = await _fixture.AuthenticatedClient.CreateApiKeyAsync("e2e-test-key", ct: ct);
+        Assert.NotEmpty(created.Key);
+        Assert.Equal("e2e-test-key", created.Label);
+
+        var keys = await _fixture.AuthenticatedClient.ListApiKeysAsync(ct);
+        Assert.Contains(keys, k => k.Id == created.Id);
+
+        await _fixture.AuthenticatedClient.DeleteApiKeyAsync(created.Id, ct);
+
+        var keysAfter = await _fixture.AuthenticatedClient.ListApiKeysAsync(ct);
+        Assert.DoesNotContain(keysAfter, k => k.Id == created.Id);
+    }
+}
diff --git a/tests/SkillServer.Integration.Tests/SkillServerFixture.cs b/tests/SkillServer.Integration.Tests/SkillServerFixture.cs
index 448ab03..a92faa6 100644
--- a/tests/SkillServer.Integration.Tests/SkillServerFixture.cs
+++ b/tests/SkillServer.Integration.Tests/SkillServerFixture.cs
@@ -17,6 +17,7 @@ public sealed class SkillServerFixture : IAsyncLifetime
     private HttpClient? _httpClient;
     private HttpClient? _authHttpClient;
     private SkillServerClient? _client;
+    private SkillServerClient? _authClient;
 
     public HttpClient HttpClient => _httpClient
         ?? throw new InvalidOperationException("HttpClient not initialized");
@@ -27,6 +28,9 @@ public sealed class SkillServerFixture : IAsyncLifetime
     public SkillServerClient Client => _client
         ?? throw new InvalidOperationException("Client not initialized");
 
+    public SkillServerClient AuthenticatedClient => _authClient
+        ?? throw new InvalidOperationException("AuthenticatedClient not initialized");
+
     public ValueTask InitializeAsync()
     {
         _factory = new WebApplicationFactory<Program>();
@@ -37,6 +41,7 @@ public ValueTask InitializeAsync()
             new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", TestApiKey);
 
         _client = new SkillServerClient(_httpClient);
+        _authClient = new SkillServerClient(_authHttpClient);
 
         return ValueTask.CompletedTask;
     }
@@ -46,6 +51,7 @@ public async ValueTask DisposeAsync()
         _httpClient?.Dispose();
         _authHttpClient?.Dispose();
         _client?.Dispose();
+        _authClient?.Dispose();
 
         if (_factory is not null)
         {

From 3a373c5319ba1a8bcb738355696e5d364a9f057f Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Tue, 5 May 2026 00:32:26 +0000
Subject: [PATCH 5/6] Reduce duplication and improve efficiency in CLI commands

Extract HandleHttpError helper to ConsoleOutput, replacing 5 identical
catch blocks across ApiKeyCommand, DeleteCommand, and VerifyCommand.
Parallelize resource verification in VerifyCommand using Task.WhenAll.
Change IsTty to static readonly field. Remove explanatory comments.
---
 src/Netclaw.SkillServer.Cli/CliArgsParser.cs  |  1 -
 .../Commands/ApiKeyCommand.cs                 |  9 ++--
 .../Commands/DeleteCommand.cs                 |  3 +-
 .../Commands/VerifyCommand.cs                 | 49 +++++++++++--------
 .../Config/ConfigResolver.cs                  |  1 -
 .../Output/ConsoleOutput.cs                   |  8 ++-
 6 files changed, 39 insertions(+), 32 deletions(-)

diff --git a/src/Netclaw.SkillServer.Cli/CliArgsParser.cs b/src/Netclaw.SkillServer.Cli/CliArgsParser.cs
index 503b196..2b4c414 100644
--- a/src/Netclaw.SkillServer.Cli/CliArgsParser.cs
+++ b/src/Netclaw.SkillServer.Cli/CliArgsParser.cs
@@ -126,7 +126,6 @@ public static ParsedArgs Parse(string[] args)
                 default:
                     if (!arg.StartsWith('-'))
                     {
-                        // For config set, first two positionals are key/value
                         if (command == "config" && subCommand == "set")
                         {
                             if (configKey is null)
diff --git a/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs
index 1296297..836dc30 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/ApiKeyCommand.cs
@@ -61,8 +61,7 @@ private static async Task<int> Create(ParsedArgs args, SkillServerClient client)
         }
         catch (HttpRequestException ex)
         {
-            ConsoleOutput.WriteError($"Error: {ex.Message}");
-            return 1;
+            return ConsoleOutput.HandleHttpError(ex);
         }
     }
 
@@ -100,8 +99,7 @@ private static async Task<int> List(ParsedArgs args, SkillServerClient client)
         }
         catch (HttpRequestException ex)
         {
-            ConsoleOutput.WriteError($"Error: {ex.Message}");
-            return 1;
+            return ConsoleOutput.HandleHttpError(ex);
         }
     }
 
@@ -127,8 +125,7 @@ private static async Task<int> Delete(ParsedArgs args, SkillServerClient client)
         }
         catch (HttpRequestException ex)
         {
-            ConsoleOutput.WriteError($"Error: {ex.Message}");
-            return 1;
+            return ConsoleOutput.HandleHttpError(ex);
         }
     }
 
diff --git a/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs
index cc9e132..97c5136 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/DeleteCommand.cs
@@ -41,8 +41,7 @@ public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient cl
         }
         catch (HttpRequestException ex)
         {
-            ConsoleOutput.WriteError($"Error: {ex.Message}");
-            return 1;
+            return ConsoleOutput.HandleHttpError(ex);
         }
     }
 
diff --git a/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs b/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs
index f569a06..b591fb4 100644
--- a/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs
+++ b/src/Netclaw.SkillServer.Cli/Commands/VerifyCommand.cs
@@ -44,7 +44,6 @@ public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient cl
 
             var allMatch = true;
 
-            // Verify SKILL.md
             var localDigest = await ComputeFileDigestAsync(skill.SkillMdPath);
             var serverDigest = serverVersion.Sha256;
             var match = string.Equals(localDigest, serverDigest, StringComparison.OrdinalIgnoreCase);
@@ -56,26 +55,17 @@ public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient cl
                 allMatch = false;
             }
 
-            // Verify resources by downloading and comparing
-            foreach (var resource in skill.Resources)
+            var verifyTasks = skill.Resources.Select(resource =>
+                VerifyResourceAsync(client, skill.Name, version, resource));
+            var results = await Task.WhenAll(verifyTasks);
+
+            foreach (var (resource, matched) in results)
             {
-                try
-                {
-                    var serverContent = await client.GetSkillFileAsStringAsync(
-                        skill.Name, version, resource.RelativePath);
-                    var localContent = await File.ReadAllTextAsync(resource.AbsolutePath);
-
-                    if (localContent == serverContent)
-                        ConsoleOutput.WriteSuccess($"  {resource.RelativePath}    match");
-                    else
-                    {
-                        ConsoleOutput.WriteError($"  {resource.RelativePath}    MISMATCH");
-                        allMatch = false;
-                    }
-                }
-                catch (HttpRequestException)
+                if (matched)
+                    ConsoleOutput.WriteSuccess($"  {resource}    match");
+                else
                 {
-                    ConsoleOutput.WriteError($"  {resource.RelativePath}    NOT FOUND on server");
+                    ConsoleOutput.WriteError($"  {resource}    MISMATCH");
                     allMatch = false;
                 }
             }
@@ -91,8 +81,25 @@ public static async Task<int> ExecuteAsync(ParsedArgs args, SkillServerClient cl
         }
         catch (HttpRequestException ex)
         {
-            ConsoleOutput.WriteError($"Error: {ex.Message}");
-            return 1;
+            return ConsoleOutput.HandleHttpError(ex);
+        }
+    }
+
+    private static async Task<(string RelativePath, bool Matched)> VerifyResourceAsync(
+        SkillServerClient client, string skillName, string version, ScannedResource resource)
+    {
+        try
+        {
+            var serverTask = client.GetSkillFileAsStringAsync(
+                skillName, version, resource.RelativePath);
+            var localTask = File.ReadAllTextAsync(resource.AbsolutePath);
+            await Task.WhenAll(serverTask, localTask);
+
+            return (resource.RelativePath, localTask.Result == serverTask.Result);
+        }
+        catch (HttpRequestException)
+        {
+            return (resource.RelativePath, false);
         }
     }
 
diff --git a/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs b/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
index 77faca8..5271872 100644
--- a/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
+++ b/src/Netclaw.SkillServer.Cli/Config/ConfigResolver.cs
@@ -49,7 +49,6 @@ public static void SaveConfigFile(CliConfig config)
         var json = JsonSerializer.Serialize(config, CliJsonContext.Default.CliConfig);
         File.WriteAllText(ConfigFilePath, json);
 
-        // Set file permissions to owner-only on Unix
         if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
         {
             File.SetUnixFileMode(ConfigFilePath,
diff --git a/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs b/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs
index c947fa5..a0af826 100644
--- a/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs
+++ b/src/Netclaw.SkillServer.Cli/Output/ConsoleOutput.cs
@@ -8,7 +8,7 @@ namespace Netclaw.SkillServer.Cli.Output;
 
 internal static class ConsoleOutput
 {
-    private static bool IsTty => !Console.IsOutputRedirected;
+    private static readonly bool IsTty = !Console.IsOutputRedirected;
 
     public static void WriteSuccess(string message)
     {
@@ -68,6 +68,12 @@ public static void WriteTable(string[] headers, IReadOnlyList<string[]> rows)
         }
     }
 
+    public static int HandleHttpError(HttpRequestException ex)
+    {
+        WriteError($"Error: {ex.Message}");
+        return 1;
+    }
+
     public static string MaskApiKey(string key)
     {
         if (key.Length <= 10)

From a3a254f81148289f112597c4396d0d16ee545893 Mon Sep 17 00:00:00 2001
From: Aaron Stannard <aaron@petabridge.com>
Date: Tue, 5 May 2026 00:54:51 +0000
Subject: [PATCH 6/6] Add unified release pipeline, install scripts, and
 verbose logging

Consolidate publish_nuget.yml and publish_container.yml into a single
release.yml that builds NuGet packages, CLI binaries (linux-x64,
linux-arm64, osx-arm64, win-x64), and container images in parallel,
then publishes everything in a coordinated final stage.

Add install scripts for Linux/macOS (bash) and Windows (PowerShell)
that download platform binaries from GitHub Releases.

Enable trimming for self-contained CLI publishes (38MB -> 14MB). Add
VerboseLoggingHandler for --verbose HTTP request/response logging.

Update pr_validation.yml with trim warning checks, smoke tests, and
shellcheck/PowerShell linting. Add CLI README for NuGet package page
and update root README with component overview.
---
 .github/workflows/pr_validation.yml           |  68 +++++
 .github/workflows/publish_container.yml       |  81 -----
 .github/workflows/publish_nuget.yml           |  74 -----
 .github/workflows/release.yml                 | 280 ++++++++++++++++++
 README.md                                     |  51 +++-
 scripts/install-skillserver.ps1               | 114 +++++++
 scripts/install-skillserver.sh                | 132 +++++++++
 .../Netclaw.SkillServer.Cli.csproj            |   2 +
 .../Output/VerboseLoggingHandler.cs           |  30 ++
 src/Netclaw.SkillServer.Cli/Program.cs        |  22 +-
 src/Netclaw.SkillServer.Cli/README.md         | 137 +++++++++
 11 files changed, 826 insertions(+), 165 deletions(-)
 delete mode 100644 .github/workflows/publish_container.yml
 delete mode 100644 .github/workflows/publish_nuget.yml
 create mode 100644 .github/workflows/release.yml
 create mode 100644 scripts/install-skillserver.ps1
 create mode 100755 scripts/install-skillserver.sh
 create mode 100644 src/Netclaw.SkillServer.Cli/Output/VerboseLoggingHandler.cs
 create mode 100644 src/Netclaw.SkillServer.Cli/README.md

diff --git a/.github/workflows/pr_validation.yml b/.github/workflows/pr_validation.yml
index fb81dda..c9fee88 100644
--- a/.github/workflows/pr_validation.yml
+++ b/.github/workflows/pr_validation.yml
@@ -98,6 +98,74 @@ jobs:
       - name: "slopwatch analyze"
         run: dotnet slopwatch analyze
 
+  script-lint:
+    name: Script Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+      - name: "ShellCheck (bash)"
+        run: shellcheck scripts/install-skillserver.sh
+
+      - name: "Syntax check (PowerShell)"
+        shell: pwsh
+        run: |
+          $errors = $null
+          [System.Management.Automation.PSParser]::Tokenize(
+            (Get-Content -Raw scripts/install-skillserver.ps1), [ref]$errors) | Out-Null
+          if ($errors.Count -gt 0) {
+            $errors | ForEach-Object { Write-Error $_.Message }
+            exit 1
+          }
+          Write-Host "PowerShell syntax OK"
+
+  cli-publish:
+    name: CLI Publish Dry Run
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          lfs: true
+          fetch-depth: 0
+
+      - name: "Install .NET SDK"
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7
+        with:
+          global-json-file: "./global.json"
+
+      - name: "Publish CLI (trimmed, linux-x64)"
+        run: |
+          dotnet publish src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj \
+            -c Release \
+            -r linux-x64 \
+            --self-contained \
+            /p:PublishSingleFile=true \
+            /p:TrimmerSingleWarn=false \
+            -o ./publish/linux-x64
+
+      - name: "Check trim warnings"
+        run: |
+          dotnet publish src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj \
+            -c Release \
+            -r linux-x64 \
+            --self-contained \
+            /p:PublishSingleFile=true \
+            /p:TrimmerSingleWarn=false \
+            /p:TreatWarningsAsErrors=true \
+            /warnAsError:IL2026 /warnAsError:IL2057 \
+            /warnAsError:IL2067 /warnAsError:IL2075 \
+            /warnAsError:IL2096 /warnAsError:IL3050
+
+      - name: "Smoke test"
+        run: |
+          ./publish/linux-x64/skillserver --version
+          ./publish/linux-x64/skillserver --help
+
   docker:
     name: Docker Build
     runs-on: ubuntu-latest
diff --git a/.github/workflows/publish_container.yml b/.github/workflows/publish_container.yml
deleted file mode 100644
index ea0a82f..0000000
--- a/.github/workflows/publish_container.yml
+++ /dev/null
@@ -1,81 +0,0 @@
-name: Publish Container
-
-on:
-  push:
-    tags:
-      - '*'
-
-permissions:
-  contents: read
-  packages: write
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: ${{ github.repository_owner }}/skillserver
-
-jobs:
-  build-container:
-    name: build-${{ matrix.arch }}
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        include:
-          - arch: x64
-            rid: linux-x64
-          - arch: arm64
-            rid: linux-arm64
-
-    steps:
-    - name: "Checkout"
-      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-      with:
-        lfs: true
-        fetch-depth: 0
-
-    - name: "Install .NET SDK"
-      uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7
-      with:
-        global-json-file: "./global.json"
-
-    - name: "Login to GitHub Container Registry"
-      uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
-      with:
-        registry: ${{ env.REGISTRY }}
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: "Build and Push Container"
-      run: |
-        dotnet publish src/SkillServer/SkillServer.csproj \
-          -c Release \
-          /t:PublishContainer \
-          /p:ContainerRegistry=${{ env.REGISTRY }} \
-          /p:ContainerRepository=${{ env.IMAGE_NAME }} \
-          /p:ContainerRuntimeIdentifier=${{ matrix.rid }} \
-          /p:ContainerImageTags='"${{ github.ref_name }}-${{ matrix.arch }}"'
-
-  create-manifest:
-    name: create-manifest
-    runs-on: ubuntu-latest
-    needs: build-container
-
-    steps:
-    - name: "Login to GitHub Container Registry"
-      uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
-      with:
-        registry: ${{ env.REGISTRY }}
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: "Create and Push Multi-Arch Manifest"
-      run: |
-        docker manifest create ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }} \
-          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}-x64 \
-          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}-arm64
-
-        docker manifest create ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest \
-          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}-x64 \
-          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}-arm64
-
-        docker manifest push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}
-        docker manifest push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
diff --git a/.github/workflows/publish_nuget.yml b/.github/workflows/publish_nuget.yml
deleted file mode 100644
index 582ce23..0000000
--- a/.github/workflows/publish_nuget.yml
+++ /dev/null
@@ -1,74 +0,0 @@
-name: Publish NuGet
-
-on:
-  push:
-    tags:
-      - '*'
-
-permissions:
-   contents: write
-   id-token: write
-
-jobs:
-  publish-nuget:
-
-    name: publish-nuget
-    environment: nuget
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-
-    steps:
-    - name: "Checkout"
-      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-      with:
-        lfs: true
-        fetch-depth: 0
-        
-    - name: "Install .NET SDK"
-      uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7
-      with:
-        global-json-file: "./global.json"
-
-    - name: "Restore .NET tools"
-      run: dotnet tool restore
-
-    - name: "Update release notes"
-      shell: pwsh
-      run: |
-        ./build.ps1
-
-    - name: Create Packages
-      run:  dotnet pack /p:PackageVersion=${{ github.ref_name }} -c Release -o ./output
-
-    - name: NuGet login (OIDC → temp API key)
-      uses: NuGet/login@v1
-      id: nuget-login
-      with:
-        user: ${{ secrets.NUGET_USER }}
-
-    - name: Push Packages
-      run: |
-        dotnet nuget push "output/*.nupkg" --api-key ${{ steps.nuget-login.outputs.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
-        dotnet nuget push "output/*.snupkg" --api-key ${{ steps.nuget-login.outputs.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
-
-    - name: "Extract latest release notes"
-      shell: pwsh
-      run: |
-        $content = Get-Content RELEASE_NOTES.md -Raw
-        # Match from the first #### heading to just before the second one
-        if ($content -match '(?s)(####.+?)(?=\n####|\z)') {
-          $Matches[1].Trim() | Set-Content RELEASE_NOTES_LATEST.md
-        } else {
-          $content | Set-Content RELEASE_NOTES_LATEST.md
-        }
-
-    - name: Create GitHub Release
-      run: |
-        gh release create "${{ github.ref_name }}" \
-          --title "SkillServer ${{ github.ref_name }}" \
-          --notes-file RELEASE_NOTES_LATEST.md \
-          output/*.nupkg output/*.snupkg
-      env:
-        GH_TOKEN: ${{ github.token }}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..ab8b52b
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,280 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - '*'
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
+env:
+  CONTAINER_REGISTRY: ghcr.io
+  CONTAINER_IMAGE: ${{ github.repository_owner }}/skillserver
+
+jobs:
+  # ─── Stage 1: Build everything in parallel ───────────────────────────
+
+  nuget-pack:
+    name: NuGet Pack
+    runs-on: ubuntu-latest
+    environment: nuget
+
+    steps:
+    - name: "Checkout"
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      with:
+        lfs: true
+        fetch-depth: 0
+
+    - name: "Install .NET SDK"
+      uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7
+      with:
+        global-json-file: "./global.json"
+
+    - name: "Restore .NET tools"
+      run: dotnet tool restore
+
+    - name: "Update release notes"
+      shell: pwsh
+      run: ./build.ps1
+
+    - name: "Pack"
+      run: dotnet pack /p:PackageVersion=${{ github.ref_name }} -c Release -o ./output
+
+    - name: "Upload artifacts"
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+      with:
+        name: nuget-packages
+        path: |
+          output/*.nupkg
+          output/*.snupkg
+        retention-days: 7
+
+  cli-binaries:
+    name: CLI-${{ matrix.rid }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - rid: linux-x64
+            os: ubuntu-latest
+            archive: tar
+          - rid: linux-arm64
+            os: ubuntu-latest
+            archive: tar
+          - rid: osx-arm64
+            os: macos-latest
+            archive: tar
+          - rid: win-x64
+            os: windows-latest
+            archive: zip
+
+    steps:
+    - name: "Checkout"
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      with:
+        lfs: true
+        fetch-depth: 0
+
+    - name: "Install .NET SDK"
+      uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7
+      with:
+        global-json-file: "./global.json"
+
+    - name: "Restore .NET tools"
+      run: dotnet tool restore
+
+    - name: "Update release notes"
+      shell: pwsh
+      run: ./build.ps1
+
+    - name: "Set version"
+      shell: bash
+      run: |
+        VERSION=${{ github.ref_name }}
+        VERSION=${VERSION#v}
+        echo "VERSION=$VERSION" >> $GITHUB_ENV
+        ASSEMBLY_VERSION=$(echo $VERSION | cut -d'-' -f1)
+        echo "ASSEMBLY_VERSION=$ASSEMBLY_VERSION" >> $GITHUB_ENV
+
+    - name: "Publish CLI"
+      shell: bash
+      run: |
+        dotnet publish src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj \
+          -c Release \
+          -r ${{ matrix.rid }} \
+          --self-contained \
+          /p:PublishSingleFile=true \
+          /p:Version=${{ env.VERSION }} \
+          /p:AssemblyVersion=${{ env.ASSEMBLY_VERSION }} \
+          /p:FileVersion=${{ env.ASSEMBLY_VERSION }} \
+          -o ./publish
+
+    - name: "Smoke test"
+      if: matrix.rid != 'linux-arm64'
+      shell: bash
+      run: |
+        if [[ "${{ matrix.rid }}" == win-* ]]; then
+          ./publish/skillserver.exe --version
+          ./publish/skillserver.exe --help
+        else
+          ./publish/skillserver --version
+          ./publish/skillserver --help
+        fi
+
+    - name: "Package (tar.gz)"
+      if: matrix.archive == 'tar'
+      shell: bash
+      run: |
+        cd publish
+        tar -czf ../skillserver-${{ env.VERSION }}-${{ matrix.rid }}.tar.gz *
+        cd ..
+        sha256sum skillserver-${{ env.VERSION }}-${{ matrix.rid }}.tar.gz \
+          > skillserver-${{ env.VERSION }}-${{ matrix.rid }}.tar.gz.sha256
+
+    - name: "Package (zip)"
+      if: matrix.archive == 'zip'
+      shell: pwsh
+      run: |
+        Compress-Archive -Path publish/* -DestinationPath skillserver-${{ env.VERSION }}-${{ matrix.rid }}.zip
+        $hash = (Get-FileHash -Algorithm SHA256 skillserver-${{ env.VERSION }}-${{ matrix.rid }}.zip).Hash.ToLower()
+        "$hash  skillserver-${{ env.VERSION }}-${{ matrix.rid }}.zip" | Set-Content skillserver-${{ env.VERSION }}-${{ matrix.rid }}.zip.sha256
+
+    - name: "Upload artifacts"
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+      with:
+        name: cli-${{ matrix.rid }}
+        path: |
+          skillserver-${{ env.VERSION }}-${{ matrix.rid }}.*
+        retention-days: 7
+
+  container-images:
+    name: Container-${{ matrix.arch }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: x64
+            rid: linux-x64
+          - arch: arm64
+            rid: linux-arm64
+
+    steps:
+    - name: "Checkout"
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      with:
+        lfs: true
+        fetch-depth: 0
+
+    - name: "Install .NET SDK"
+      uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7
+      with:
+        global-json-file: "./global.json"
+
+    - name: "Login to GitHub Container Registry"
+      uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      with:
+        registry: ${{ env.CONTAINER_REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: "Build and Push Container"
+      run: |
+        dotnet publish src/SkillServer/SkillServer.csproj \
+          -c Release \
+          /t:PublishContainer \
+          /p:ContainerRegistry=${{ env.CONTAINER_REGISTRY }} \
+          /p:ContainerRepository=${{ env.CONTAINER_IMAGE }} \
+          /p:ContainerRuntimeIdentifier=${{ matrix.rid }} \
+          /p:ContainerImageTags='"${{ github.ref_name }}-${{ matrix.arch }}"'
+
+  # ─── Stage 2: Publish everything once all builds succeed ─────────────
+
+  publish-release:
+    name: Publish Release
+    runs-on: ubuntu-latest
+    needs: [nuget-pack, cli-binaries, container-images]
+    environment: nuget
+
+    steps:
+    - name: "Checkout"
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      with:
+        fetch-depth: 0
+
+    - name: "Install .NET SDK"
+      uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7
+      with:
+        global-json-file: "./global.json"
+
+    - name: "Download NuGet packages"
+      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+      with:
+        name: nuget-packages
+        path: ./nuget
+
+    - name: "Download CLI binaries"
+      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+      with:
+        pattern: cli-*
+        merge-multiple: true
+        path: ./cli
+
+    - name: "NuGet login (OIDC)"
+      uses: NuGet/login@v1
+      id: nuget-login
+      with:
+        user: ${{ secrets.NUGET_USER }}
+
+    - name: "Push NuGet packages"
+      run: |
+        dotnet nuget push "nuget/*.nupkg" \
+          --api-key ${{ steps.nuget-login.outputs.NUGET_API_KEY }} \
+          --source https://api.nuget.org/v3/index.json \
+          --skip-duplicate
+        dotnet nuget push "nuget/*.snupkg" \
+          --api-key ${{ steps.nuget-login.outputs.NUGET_API_KEY }} \
+          --source https://api.nuget.org/v3/index.json \
+          --skip-duplicate
+
+    - name: "Create Docker multi-arch manifest"
+      run: |
+        echo "${{ secrets.GITHUB_TOKEN }}" | \
+          docker login ${{ env.CONTAINER_REGISTRY }} -u ${{ github.actor }} --password-stdin
+
+        docker manifest create \
+          ${{ env.CONTAINER_REGISTRY }}/${{ env.CONTAINER_IMAGE }}:${{ github.ref_name }} \
+          ${{ env.CONTAINER_REGISTRY }}/${{ env.CONTAINER_IMAGE }}:${{ github.ref_name }}-x64 \
+          ${{ env.CONTAINER_REGISTRY }}/${{ env.CONTAINER_IMAGE }}:${{ github.ref_name }}-arm64
+
+        docker manifest create \
+          ${{ env.CONTAINER_REGISTRY }}/${{ env.CONTAINER_IMAGE }}:latest \
+          ${{ env.CONTAINER_REGISTRY }}/${{ env.CONTAINER_IMAGE }}:${{ github.ref_name }}-x64 \
+          ${{ env.CONTAINER_REGISTRY }}/${{ env.CONTAINER_IMAGE }}:${{ github.ref_name }}-arm64
+
+        docker manifest push ${{ env.CONTAINER_REGISTRY }}/${{ env.CONTAINER_IMAGE }}:${{ github.ref_name }}
+        docker manifest push ${{ env.CONTAINER_REGISTRY }}/${{ env.CONTAINER_IMAGE }}:latest
+
+    - name: "Extract release notes"
+      shell: pwsh
+      run: |
+        $content = Get-Content RELEASE_NOTES.md -Raw
+        if ($content -match '(?s)(####.+?)(?=\n####|\z)') {
+          $Matches[1].Trim() | Set-Content RELEASE_NOTES_LATEST.md
+        } else {
+          $content | Set-Content RELEASE_NOTES_LATEST.md
+        }
+
+    - name: "Create GitHub Release"
+      run: |
+        gh release create "${{ github.ref_name }}" \
+          --title "SkillServer ${{ github.ref_name }}" \
+          --notes-file RELEASE_NOTES_LATEST.md \
+          nuget/*.nupkg nuget/*.snupkg cli/*
+      env:
+        GH_TOKEN: ${{ github.token }}
diff --git a/README.md b/README.md
index d72ffe1..59cc7a9 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # SkillServer
 
-[![NuGet](https://img.shields.io/nuget/v/Netclaw.SkillClient)](https://www.nuget.org/packages/Netclaw.SkillClient)
+[![NuGet - Client](https://img.shields.io/nuget/v/Netclaw.SkillClient?label=Netclaw.SkillClient)](https://www.nuget.org/packages/Netclaw.SkillClient)
+[![NuGet - CLI](https://img.shields.io/nuget/v/Netclaw.SkillServer.Cli?label=skillserver%20CLI)](https://www.nuget.org/packages/Netclaw.SkillServer.Cli)
 [![GitHub Container](https://ghcr-badge.egpl.dev/netclaw-dev/skillserver/latest_tag?label=container)](https://ghcr.io/netclaw-dev/skillserver)
 
 A self-hosted skill server for managing AI agent skills internally within organizations. Similar to self-hosted package registries (BaGet for NuGet, Verdaccio for npm, Docker Registry), SkillServer enables companies to:
@@ -10,6 +11,14 @@ A self-hosted skill server for managing AI agent skills internally within organi
 - Version skills with full history
 - Integrate with NetClaw CLI and other AgentSkills.io-compatible agents
 
+This repository contains three components:
+
+| Component | Description | Install |
+|-----------|-------------|---------|
+| **SkillServer** | Self-hosted skill registry (web server) | `docker pull ghcr.io/netclaw-dev/skillserver` |
+| **skillserver CLI** | Command-line tool for publishing and managing skills | `dotnet tool install -g Netclaw.SkillServer.Cli` |
+| **Netclaw.SkillClient** | Typed .NET client library | `dotnet add package Netclaw.SkillClient` |
+
 ## Standards Support
 
 SkillServer implements two complementary standards:
@@ -90,19 +99,43 @@ Configuration is via environment variables or `appsettings.json`:
 |----------|-------------|
 | `GET /health` | Health check |
 
-## Uploading Skills
+## CLI Tool
 
-Upload a SKILL.md file:
+The `skillserver` CLI is the recommended way to publish and manage skills.
+
+### Install
 
 ```bash
-curl -X POST http://localhost:8080/skills \
-  -H "Authorization: Bearer sk-your-api-key" \
-  -F "name=my-skill" \
-  -F "version=1.0.0" \
-  -F "category=internal" \
-  -F "file=@SKILL.md"
+# .NET global tool
+dotnet tool install --global Netclaw.SkillServer.Cli
+
+# Or standalone binary (Linux/macOS)
+curl -fsSL https://raw.githubusercontent.com/netclaw-dev/skill-server/dev/scripts/install-skillserver.sh | bash
+
+# Or standalone binary (Windows PowerShell)
+iwr -useb https://raw.githubusercontent.com/netclaw-dev/skill-server/dev/scripts/install-skillserver.ps1 | iex
 ```
 
+### Usage
+
+```bash
+# Configure
+skillserver config init
+
+# Publish a skill
+skillserver publish ./my-skill
+
+# Batch publish
+skillserver publish-all ./skills
+
+# List, search, verify, delete
+skillserver list --search kubernetes
+skillserver verify ./my-skill
+skillserver delete my-skill 1.0.0 --yes
+```
+
+See the [CLI README](src/Netclaw.SkillServer.Cli/README.md) for the full command reference.
+
 ## Client Library
 
 The `Netclaw.SkillClient` NuGet package provides a typed .NET client for SkillServer.
diff --git a/scripts/install-skillserver.ps1 b/scripts/install-skillserver.ps1
new file mode 100644
index 0000000..0b0cd65
--- /dev/null
+++ b/scripts/install-skillserver.ps1
@@ -0,0 +1,114 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Install the skillserver CLI on Windows.
+.DESCRIPTION
+    Downloads and installs the skillserver CLI binary from GitHub Releases.
+    No administrator permissions required - installs to your home directory.
+.PARAMETER Version
+    Version to install. Defaults to "latest".
+.PARAMETER InstallDir
+    Installation directory. Defaults to $env:LOCALAPPDATA\Programs\skillserver.
+.EXAMPLE
+    iwr -useb https://raw.githubusercontent.com/netclaw-dev/skill-server/dev/scripts/install-skillserver.ps1 | iex
+.EXAMPLE
+    .\install-skillserver.ps1 -Version 0.2.1
+#>
+param(
+    [string]$Version = "latest",
+    [string]$InstallDir = ""
+)
+
+$ErrorActionPreference = "Stop"
+$Repo = "netclaw-dev/skill-server"
+$BinaryName = "skillserver"
+$Rid = "win-x64"
+
+if (-not $InstallDir) {
+    $InstallDir = Join-Path $env:LOCALAPPDATA "Programs" $BinaryName
+}
+
+function Resolve-LatestVersion {
+    if ($script:Version -eq "latest") {
+        try {
+            $response = Invoke-WebRequest -Uri "https://github.com/$Repo/releases/latest" `
+                -MaximumRedirection 0 -ErrorAction SilentlyContinue -UseBasicParsing
+            if ($response.StatusCode -eq 302) {
+                $redirectUrl = $response.Headers.Location
+            } else {
+                $redirectUrl = $response.BaseResponse.ResponseUri.AbsoluteUri
+            }
+        } catch {
+            $redirectUrl = $_.Exception.Response.Headers.Location.AbsoluteUri
+        }
+        $script:Version = ($redirectUrl -split '/')[-1]
+        if (-not $script:Version) {
+            throw "Could not determine latest version"
+        }
+    }
+    $script:Version = $script:Version.TrimStart('v')
+}
+
+function Main {
+    Write-Host "Installing $BinaryName..."
+
+    Resolve-LatestVersion
+
+    $archiveName = "$BinaryName-$Version-$Rid.zip"
+    $downloadUrl = "https://github.com/$Repo/releases/download/$Version/$archiveName"
+    $checksumUrl = "$downloadUrl.sha256"
+
+    Write-Host "  Platform:  $Rid"
+    Write-Host "  Version:   $Version"
+    Write-Host "  Directory: $InstallDir"
+    Write-Host ""
+
+    $tmpDir = Join-Path ([System.IO.Path]::GetTempPath()) ([System.Guid]::NewGuid().ToString())
+    New-Item -ItemType Directory -Path $tmpDir -Force | Out-Null
+
+    try {
+        Write-Host "  Downloading $archiveName..."
+        try {
+            Invoke-WebRequest -Uri $downloadUrl -OutFile (Join-Path $tmpDir $archiveName) -UseBasicParsing
+        } catch {
+            Write-Error "Failed to download $archiveName from $downloadUrl"
+            return
+        }
+
+        Write-Host "  Verifying checksum..."
+        try {
+            Invoke-WebRequest -Uri $checksumUrl -OutFile (Join-Path $tmpDir "$archiveName.sha256") -UseBasicParsing
+            $expectedLine = Get-Content (Join-Path $tmpDir "$archiveName.sha256") -Raw
+            $expected = ($expectedLine -split '\s+')[0].ToLower()
+            $actual = (Get-FileHash -Algorithm SHA256 (Join-Path $tmpDir $archiveName)).Hash.ToLower()
+            if ($expected -ne $actual) {
+                throw "Checksum mismatch: expected $expected, got $actual"
+            }
+        } catch [System.Net.WebException] {
+            Write-Warning "Checksum file not available, skipping verification"
+        }
+
+        Write-Host "  Extracting..."
+        if (-not (Test-Path $InstallDir)) {
+            New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
+        }
+        Expand-Archive -Path (Join-Path $tmpDir $archiveName) -DestinationPath $InstallDir -Force
+
+        $userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
+        if ($userPath -notlike "*$InstallDir*") {
+            [Environment]::SetEnvironmentVariable("PATH", "$userPath;$InstallDir", "User")
+            $env:PATH = "$env:PATH;$InstallDir"
+            Write-Host "  Added $InstallDir to user PATH"
+        }
+
+        Write-Host ""
+        Write-Host "  Installed $BinaryName $Version to $InstallDir\$BinaryName.exe"
+        Write-Host ""
+        Write-Host "  Run '$BinaryName --version' to verify."
+        Write-Host "  You may need to restart your terminal for PATH changes to take effect."
+    } finally {
+        Remove-Item -Path $tmpDir -Recurse -Force -ErrorAction SilentlyContinue
+    }
+}
+
+Main
diff --git a/scripts/install-skillserver.sh b/scripts/install-skillserver.sh
new file mode 100755
index 0000000..639f78e
--- /dev/null
+++ b/scripts/install-skillserver.sh
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/netclaw-dev/skill-server/dev/scripts/install-skillserver.sh | bash
+#   ./install-skillserver.sh
+#   ./install-skillserver.sh 0.2.1
+#   INSTALL_DIR=/custom/path ./install-skillserver.sh
+#
+set -euo pipefail
+
+REPO="netclaw-dev/skill-server"
+BINARY_NAME="skillserver"
+INSTALL_DIR="${INSTALL_DIR:-${HOME}/.local/bin}"
+VERSION="${1:-latest}"
+
+detect_platform() {
+    local os arch
+    os="$(uname -s)"
+    arch="$(uname -m)"
+
+    case "$os" in
+        Linux)  os="linux" ;;
+        Darwin) os="osx" ;;
+        *)
+            echo "Error: Unsupported OS: $os" >&2
+            exit 1
+            ;;
+    esac
+
+    case "$arch" in
+        x86_64|amd64) arch="x64" ;;
+        aarch64|arm64) arch="arm64" ;;
+        *)
+            echo "Error: Unsupported architecture: $arch" >&2
+            exit 1
+            ;;
+    esac
+
+    echo "${os}-${arch}"
+}
+
+resolve_version() {
+    if [ "$VERSION" = "latest" ]; then
+        VERSION=$(curl -sI "https://github.com/${REPO}/releases/latest" \
+            | grep -i "^location:" \
+            | sed 's|.*/||' \
+            | tr -d '\r\n')
+
+        if [ -z "$VERSION" ]; then
+            echo "Error: Could not determine latest version" >&2
+            exit 1
+        fi
+    fi
+    VERSION="${VERSION#v}"
+}
+
+main() {
+    local rid archive_name download_url checksum_url tmp_dir
+
+    echo "Installing ${BINARY_NAME}..."
+
+    rid=$(detect_platform)
+    resolve_version
+
+    archive_name="${BINARY_NAME}-${VERSION}-${rid}.tar.gz"
+    download_url="https://github.com/${REPO}/releases/download/${VERSION}/${archive_name}"
+    checksum_url="${download_url}.sha256"
+
+    tmp_dir=$(mktemp -d)
+    trap 'rm -rf "$tmp_dir"' EXIT
+
+    echo "  Platform:  ${rid}"
+    echo "  Version:   ${VERSION}"
+    echo "  Directory: ${INSTALL_DIR}"
+    echo ""
+
+    echo "  Downloading ${archive_name}..."
+    if ! curl -fsSL -o "${tmp_dir}/${archive_name}" "$download_url"; then
+        echo "Error: Failed to download ${archive_name}" >&2
+        echo "  URL: ${download_url}" >&2
+        echo "  Available platforms: linux-x64, linux-arm64, osx-arm64" >&2
+        exit 1
+    fi
+
+    echo "  Verifying checksum..."
+    if curl -fsSL -o "${tmp_dir}/${archive_name}.sha256" "$checksum_url" 2>/dev/null; then
+        cd "$tmp_dir"
+        if command -v sha256sum > /dev/null 2>&1; then
+            sha256sum -c "${archive_name}.sha256" --quiet
+        elif command -v shasum > /dev/null 2>&1; then
+            expected=$(awk '{print $1}' "${archive_name}.sha256")
+            actual=$(shasum -a 256 "${archive_name}" | awk '{print $1}')
+            if [ "$expected" != "$actual" ]; then
+                echo "Error: Checksum mismatch" >&2
+                exit 1
+            fi
+        fi
+        cd - > /dev/null
+    else
+        echo "  Warning: Checksum file not available, skipping verification" >&2
+    fi
+
+    echo "  Extracting..."
+    tar -xzf "${tmp_dir}/${archive_name}" -C "$tmp_dir"
+
+    mkdir -p "${INSTALL_DIR}"
+    cp "${tmp_dir}/${BINARY_NAME}" "${INSTALL_DIR}/${BINARY_NAME}"
+    chmod +x "${INSTALL_DIR}/${BINARY_NAME}"
+
+    echo ""
+    echo "  Installed ${BINARY_NAME} ${VERSION} to ${INSTALL_DIR}/${BINARY_NAME}"
+
+    case ":${PATH}:" in
+        *":${INSTALL_DIR}:"*) ;;
+        *)
+            echo ""
+            echo "  Warning: ${INSTALL_DIR} is not in your PATH."
+            echo "  Add it by running:"
+            echo ""
+            if [ -n "${ZSH_VERSION:-}" ] || [ -f "${HOME}/.zshrc" ]; then
+                echo "    echo 'export PATH=\"${INSTALL_DIR}:\$PATH\"' >> ~/.zshrc && source ~/.zshrc"
+            else
+                echo "    echo 'export PATH=\"${INSTALL_DIR}:\$PATH\"' >> ~/.bashrc && source ~/.bashrc"
+            fi
+            ;;
+    esac
+
+    echo ""
+    echo "  Run '${BINARY_NAME} --version' to verify."
+}
+
+main
diff --git a/src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj b/src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj
index 71fdea4..c41ea2b 100644
--- a/src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj
+++ b/src/Netclaw.SkillServer.Cli/Netclaw.SkillServer.Cli.csproj
@@ -22,6 +22,8 @@
   <!-- Self-contained single-file publishing -->
   <PropertyGroup Condition="'$(PublishSingleFile)' == 'true'">
     <SelfContained>true</SelfContained>
+    <PublishTrimmed>true</PublishTrimmed>
+    <TrimMode>full</TrimMode>
     <EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
     <IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
   </PropertyGroup>
diff --git a/src/Netclaw.SkillServer.Cli/Output/VerboseLoggingHandler.cs b/src/Netclaw.SkillServer.Cli/Output/VerboseLoggingHandler.cs
new file mode 100644
index 0000000..ee6a04e
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/Output/VerboseLoggingHandler.cs
@@ -0,0 +1,30 @@
+// -----------------------------------------------------------------------
+// <copyright file="VerboseLoggingHandler.cs" company="Petabridge, LLC">
+//      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
+// </copyright>
+// -----------------------------------------------------------------------
+
+using System.Diagnostics;
+
+namespace Netclaw.SkillServer.Cli.Output;
+
+internal sealed class VerboseLoggingHandler : DelegatingHandler
+{
+    public VerboseLoggingHandler() : base(new HttpClientHandler())
+    {
+    }
+
+    protected override async Task<HttpResponseMessage> SendAsync(
+        HttpRequestMessage request, CancellationToken cancellationToken)
+    {
+        ConsoleOutput.WriteDim($"  > {request.Method} {request.RequestUri}");
+
+        var sw = Stopwatch.StartNew();
+        var response = await base.SendAsync(request, cancellationToken);
+        sw.Stop();
+
+        ConsoleOutput.WriteDim($"  < {(int)response.StatusCode} {response.StatusCode} ({sw.ElapsedMilliseconds}ms)");
+
+        return response;
+    }
+}
diff --git a/src/Netclaw.SkillServer.Cli/Program.cs b/src/Netclaw.SkillServer.Cli/Program.cs
index 0869090..bf232d6 100644
--- a/src/Netclaw.SkillServer.Cli/Program.cs
+++ b/src/Netclaw.SkillServer.Cli/Program.cs
@@ -9,6 +9,7 @@
 using Netclaw.SkillServer.Cli;
 using Netclaw.SkillServer.Cli.Commands;
 using Netclaw.SkillServer.Cli.Config;
+using System.Net.Http.Headers;
 using Netclaw.SkillServer.Cli.Output;
 
 var parsedArgs = CliArgsParser.Parse(args);
@@ -64,7 +65,8 @@
     return 1;
 }
 
-using var client = new SkillServerClient(config.ServerUrl!, config.ApiKey);
+using var httpClient = CreateHttpClient(config, parsedArgs.Verbose);
+using var client = new SkillServerClient(httpClient);
 return await DispatchAsync(parsedArgs, client);
 
 static async Task<int> DispatchAsync(ParsedArgs parsedArgs, SkillServerClient client) =>
@@ -88,6 +90,24 @@ static int UnknownCommand(string command)
     return 1;
 }
 
+static HttpClient CreateHttpClient(ResolvedConfig config, bool verbose)
+{
+    HttpMessageHandler handler = verbose
+        ? new VerboseLoggingHandler()
+        : new HttpClientHandler();
+
+    var client = new HttpClient(handler)
+    {
+        BaseAddress = new Uri(config.ServerUrl!.TrimEnd('/') + "/")
+    };
+
+    if (!string.IsNullOrEmpty(config.ApiKey))
+        client.DefaultRequestHeaders.Authorization =
+            new AuthenticationHeaderValue("Bearer", config.ApiKey);
+
+    return client;
+}
+
 static void PrintHelp()
 {
     Console.WriteLine("Usage: skillserver <command> [options]");
diff --git a/src/Netclaw.SkillServer.Cli/README.md b/src/Netclaw.SkillServer.Cli/README.md
new file mode 100644
index 0000000..0c1e269
--- /dev/null
+++ b/src/Netclaw.SkillServer.Cli/README.md
@@ -0,0 +1,137 @@
+# skillserver CLI
+
+Command-line tool for publishing and managing skills on a [SkillServer](https://github.com/netclaw-dev/skill-server) instance.
+
+## Installation
+
+### .NET Global Tool
+
+```bash
+dotnet tool install --global Netclaw.SkillServer.Cli
+```
+
+### Standalone Binary (Linux/macOS)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/netclaw-dev/skill-server/dev/scripts/install-skillserver.sh | bash
+```
+
+### Standalone Binary (Windows)
+
+```powershell
+iwr -useb https://raw.githubusercontent.com/netclaw-dev/skill-server/dev/scripts/install-skillserver.ps1 | iex
+```
+
+Standalone binaries are self-contained and trimmed -- no .NET runtime required.
+
+## Configuration
+
+Configure your server URL and API key:
+
+```bash
+skillserver config init
+```
+
+Or set individually:
+
+```bash
+skillserver config set server-url https://skills.example.com
+skillserver config set api-key sk-your-key
+```
+
+For CI/CD, use environment variables:
+
+```bash
+export SKILLSERVER_URL=https://skills.example.com
+export SKILLSERVER_API_KEY=sk-your-key
+```
+
+Priority: CLI flags > environment variables > config file (`~/.skillserver/config.json`).
+
+## Commands
+
+### Publishing
+
+```bash
+# Publish a single skill (reads name/version from SKILL.md frontmatter)
+skillserver publish ./my-skill
+
+# Override version
+skillserver publish ./my-skill --version 2.0.0-rc.1
+
+# Re-publish (idempotent -- skips if version exists)
+skillserver publish ./my-skill
+
+# Force re-publish (delete + re-upload)
+skillserver publish ./my-skill --force
+
+# Batch publish all skills in a directory
+skillserver publish-all ./skills
+
+# Dry run
+skillserver publish-all ./skills --dry-run
+```
+
+### Listing and Search
+
+```bash
+# List all skills
+skillserver list
+
+# Search
+skillserver list --search akka
+
+# List versions of a skill
+skillserver versions my-skill
+
+# JSON output
+skillserver list --output json
+```
+
+### Verification
+
+```bash
+# Verify local files match the published version
+skillserver verify ./my-skill
+```
+
+### Deleting
+
+```bash
+# Delete a version (with confirmation prompt)
+skillserver delete my-skill 1.0.0
+
+# Skip confirmation
+skillserver delete my-skill 1.0.0 --yes
+```
+
+### API Key Management
+
+```bash
+skillserver api-key create --label "CI Pipeline"
+skillserver api-key list
+skillserver api-key delete 7
+```
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--server-url <url>` | SkillServer URL (overrides config/env) |
+| `--api-key <key>` | API key (overrides config/env) |
+| `--output <text\|json>` | Output format (default: text) |
+| `--verbose, -v` | Show HTTP request/response details |
+| `--help, -h` | Show help |
+| `--version` | Show version |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error |
+| 2 | Partial failure (batch operations) |
+
+## License
+
+Apache-2.0 - Copyright 2025 [Petabridge, LLC](https://petabridge.com)