MackySoft.AgentSkills 2.0.0

Agent Skills

Agent Skills helps product teams ship agent SKILL packages with their own CLI.

Use it when your product owns:

• the skill catalog and release cadence;
• the category names represented by source definition directories;
• the public CLI shape and output envelope.

Agent Skills provides the build tool, package format, host materialization, command runtime, and report data needed to list, export, install, update, uninstall, prune, and diagnose those skills.

Packages

All packages are versioned together.

Create Skill Packages

Agent Skills separates skill source files from generated packages. Keep the source files in the product repository and ship the generated package directory with the product CLI.

Define Source Skills

Create bundle.json at the bundle root. The source file contains exactly these properties in this order:

{
  "schemaVersion": 1,
  "catalogId": "com.example.skills",
  "skillBundleVersion": 1
}

For each skill, create definitions/<category>/<skill-name>/skill.json. The category and skill name come from those two directory names and are not repeated in the file. The source metadata contains exactly these properties in this order:

{
  "schemaVersion": 1,
  "displayName": "Example Review",
  "description": "Review a completed example.",
  "dependencies": []
}

Do not add catalogId, skillBundleVersion, category, skillName, a reference-file list, digests, or host-artifact metadata to skill.json. Bundle-wide values belong to bundle.json; category and skill name come from the directory structure; reference names come from files under references; integrity and host-materialization metadata are generated.

Use the Agent Skills source definition contract shipped with the agent-skills-packaging skill as the complete source-input contract for layout, metadata, naming, dependencies, content, and canonical file encoding. The examples and tables above show the authored schema shape and ownership boundary; the linked contract is the normative source for all input constraints.

Generate Shipped Packages

Install the build tool in the product repository.

dotnet new tool-manifest
dotnet tool install MackySoft.AgentSkills.Cli --version 1.0.0

Generate the package root from the source definitions.

dotnet tool run agent-skills -- build --root skills

The command reads bundle.json and definitions under the bundle root and replaces its generated directory. Do not edit generated files manually; edit the source bundle and run the build again. When packaging the product CLI, ship the generated directory as <PackageBaseDirectory>/skills.

By default, the build uses the skillBundleVersion authored in bundle.json and never infers a new version from source changes. To advance the bundle, provide the exact target version:

dotnet tool run agent-skills -- build --root skills --skill-bundle-version 2

The target must equal the authored version or its next revision. When the next revision is selected, the command updates bundle.json and generated output together. Repeating the same exact target is a no-op after the bundle is current. A version-only change preserves bundleDigest and each package's contentDigest, but changes each manifestDigest because it covers skillBundleVersion.

Generated Package Metadata

The generator owns generated/bundle.json, every generated agent-skill.json, and all generated package files. Do not edit them manually.

The generated root bundle.json contains exactly these properties in canonical order:

The bundle digest is canonical lowercase SHA-256 text without a prefix.

Each <skill-name>/agent-skill.json contains exactly these properties in canonical order:

Each hostArtifacts entry contains host and materializedFrontmatterDigest. Hosts that generate a separate metadata file also contain path and digest; those two properties are either both present or both absent. All digest values use canonical lowercase SHA-256 text without a prefix.

The manifest does not repeat reference file names and does not contain bundleDigest, source paths, generation timestamps, Agent Skills tool or NuGet package versions, Git commits, install target paths, reload guidance, or host capability definitions. Reference file names come from the files under references in the package set, bundleDigest belongs to the generated root descriptor, and the remaining values belong to the source repository or runtime.

Verify and Synchronize Generated Packages

When generated output already matches the source definition and bundle version, the command does not write any files. To verify committed output without changing the working tree, use:

dotnet tool run agent-skills -- build --root skills --check

The repository provides separate verify and sync composite GitHub Actions. Both accept root, a bundle root relative to the GitHub workspace that resolves inside the checked-out Git worktree, and restore the CLI version pinned by the caller's .NET tool manifest. sync also accepts an optional exact skill-bundle-version.

Use verify for pull requests and other read-only checks. It runs build --check, fails when committed output is stale, and never generates or commits files.

- name: Checkout
  uses: actions/checkout@v5

- name: Verify Agent Skills
  uses: mackysoft/agent-skills/actions/verify@1.0.0
  with:
    root: skills

Use sync only from a branch workflow with contents: write. When reconciliation is required, it requires a clean Git index, synchronizes generated output, updates bundle.json when the exact next version is selected, stages only <root>/bundle.json and <root>/generated, creates a github-actions[bot] commit, and pushes that commit to the current branch. Its changed output is true only after that push succeeds.

permissions:
  contents: write

steps:
  - name: Checkout
    uses: actions/checkout@v5

  - name: Sync Agent Skills
    id: agent-skills
    uses: mackysoft/agent-skills/actions/sync@1.0.0
    with:
      root: skills
      skill-bundle-version: 2

Omit skill-bundle-version when synchronization should preserve the value authored in bundle.json.

Pushes made with the default GITHUB_TOKEN do not trigger another workflow run. If the caller supplies credentials that do trigger workflows, the synchronized bundle makes the next run a no-op because build --check passes. Branch protection still applies; use verify when direct bot pushes are not permitted.

Add Agent Skills to a Product CLI

Use the hosting package when the product CLI wants standard Agent Skills command behavior, report data, and DI registration.

Command Runtime

Add the hosting package to the product CLI.

dotnet add <PROJECT>.csproj package MackySoft.AgentSkills.Hosting --version 1.0.0

Register the runtime in the product's DI container.

using MackySoft.AgentSkills.Hosting.Composition;

services.AddAgentSkillsCommandRuntime(options =>
{
    options.ProductName = "Example CLI";
    options.PackageBaseDirectory = AppContext.BaseDirectory;
    options.CommandRoot = "skills";
});

The package base directory must contain the shipped generated packages under skills/.

<PackageBaseDirectory>/
  skills/
    bundle.json
    <skill-name>/
      SKILL.md
      agent-skill.json
      agents/
      references/

The runtime reads the catalog identity and available categories from the generated bundle descriptor and package manifests. Categories are not configured separately in product code.

Project-scope commands use the current directory when --repository-root is omitted. If the product CLI already has a repository-root policy, set RepositoryRootResolver to keep Agent Skills commands aligned with it.

services.AddAgentSkillsCommandRuntime(options =>
{
    options.RepositoryRootResolver = currentDirectory =>
        ProductRepositoryResolver.Resolve(currentDirectory);
    // Set the required options shown above.
});

ConsoleAppFramework Integration

Use the ConsoleAppFramework integration when the product CLI already uses ConsoleAppFramework and wants Agent Skills to add the standard command group to the existing app builder.

Add the integration package to the product CLI.

dotnet add <PROJECT>.csproj package MackySoft.AgentSkills.ConsoleAppFramework --version 1.0.0
dotnet add <PROJECT>.csproj package Microsoft.Extensions.Hosting

Register Agent Skills on the product's existing ConsoleAppBuilder. The product still creates and runs the builder.

using ConsoleAppFramework;
using MackySoft.AgentSkills.ConsoleAppFramework;
using MackySoft.AgentSkills.Hosting.Composition;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddAgentSkillsCommandRuntime(options =>
{
    options.ProductName = "Example CLI";
    options.PackageBaseDirectory = AppContext.BaseDirectory;
    options.CommandRoot = "skills";
});

ConsoleApp.ConsoleAppBuilder app = builder.ToConsoleAppBuilder();

// Register product filters, global options, and product commands as usual.
app.RegisterAgentSkillsCommands();

await app.RunAsync(args);
return Environment.ExitCode;

RegisterAgentSkillsCommands() adds the Agent Skills command group to the builder. It does not create a builder, run the app, set ConsoleApp.LogError, replace the service provider, register filters, or change command validation.

The default command root is skills. To expose another root, set the ConsoleAppFramework integration's MSBuild property and keep the runtime option aligned.

<PropertyGroup>
  <AgentSkillsConsoleAppFrameworkCommandRoot>agent-skills</AgentSkillsConsoleAppFrameworkCommandRoot>
</PropertyGroup>

services.AddAgentSkillsCommandRuntime(options =>
{
    options.CommandRoot = "agent-skills";
    // Set the other required options here.
});

The command root must be one or more lower-kebab command tokens separated by a single space, such as skills, agent-skills, or tools skills. Command results use dot-separated names, so tools skills list is reported as tools.skills.list.

If your CLI validates unknown commands before ConsoleAppFramework dispatch, keep that product policy in sync with the configured command root. AgentSkillsCommandNames and AgentSkillsCommandMetadata provide stable subcommand literals for that purpose.

The command examples in this README use ConsoleAppFramework's default kebab-case option names. If the product exposes different public option names, keep that compatibility in the product CLI before ConsoleAppFramework dispatch.

Product Responsibilities

The product CLI still owns:

• when generated packages are built and how they are shipped;
• the source bundle.json, category directories, and skill definitions;
• ProductName, PackageBaseDirectory, CommandRoot, and the default repository-root policy;
• the public command surface outside the configured Agent Skills command root;
• pre-dispatch command validation, option-name compatibility, help policy, filters, global options, and logging;
• the output envelope, if the default JSON result shape is not appropriate.

Register your own IAgentSkillsCommandResultEmitter after AddAgentSkillsCommandRuntime(...) when the product needs its own JSON envelope or text output.

Run Standard Commands

The ConsoleAppFramework integration registers these commands under the configured command root. With the default root, the commands are:

skills list
skills export
skills install
skills update
skills uninstall
skills prune
skills doctor

The standalone MackySoft.AgentSkills.Cli is the top-level composition root for the same command adapter and ships this repository's generated basic/agent-skills-packaging skill. Its standard commands are registered at the process root because the executable name already supplies the command root:

dotnet tool run agent-skills -- list --pretty
dotnet tool run agent-skills -- install --host openai --scope project --category basic --dryRun --pretty

The standalone executable preserves exact C# parameter names for multiword options: --repositoryRoot, --targetDir, --dryRun, and --printDiff. The product CLI examples and common-options table below use ConsoleAppFramework's default kebab-case conversion instead.

skills list can omit selectors and then lists every bundled category. Other commands require --category, --skill, or both.

Examples

example skills list
example skills export --host openai --category core --output ./exported-skills
example skills install --host openai --scope project --category core
example skills update --host openai --scope project --skill example-review
example skills uninstall --host openai --scope project --skill example-review
example skills prune --host openai --scope project --category core
example skills doctor --host openai --scope project --category core

Common Options

Supported Hosts

OpenAI / Codex and GitHub Copilot CLI discover skills below an additional catalog directory, so Agent Skills uses that directory as the managed bundle boundary. Claude Code uses a flat skills directory because its plain skill discovery does not treat an arbitrary parent directory as a package boundary. Each skill is installed directly below the bundle target shown above.

For a default target, Agent Skills first checks the current layout and the host adapter's compatible previous layouts. If exactly one target root already contains the same managed catalogId, install, update, uninstall, prune, and doctor continue to use that root. A new catalog uses the current layout. The operation stops instead of choosing arbitrarily if the same catalog exists under multiple compatible roots or the current catalog directory is already occupied by a flat skill.

--target-dir identifies the bundle target itself. Agent Skills does not append <catalogId> to an explicit target, regardless of host or scope. The catalog directory separates managed files on disk; it does not namespace the skill name exposed to the host.

Prune Removed Skills

Use skills prune when a product removes or renames a managed skill and wants old installed output cleaned up.

Prune compares installed managed skills with the complete current catalog identified by the bundled catalogId. A narrow selector limits the installed target directories that prune considers, but prune still reads the full current catalog so valid catalog members are not treated as removed.

--skill can name a managed skill that was removed from the current generated package set. --category selects installed managed targets whose manifest has that category.

Prune deletes only managed, clean, current-host skill directories that belong to the bundled catalog and no longer exist in the current generated package set. It skips unmanaged directories, foreign catalogs, current catalog members, invalid manifests, name collisions, and host conflicts. --force allows deleting locally modified managed orphans, but it does not turn unsafe or foreign targets into delete candidates.

skills update --prune is not part of the command set. Run skills prune explicitly so product CLIs can report update and cleanup as separate operations.