rust-skill-embed

Crate	Reference
skill-embed
skill-embed-clap

Ship agent skills inside a Rust binary, and give that binary a skill install command.

gh skill install fetches skills from a GitHub repository. This library does the same job from the other side. A tool carries its own skills in the executable, and writes them wherever the user's agent reads from. The flags match gh skill install. A user who knows that command already knows this one.

cargo add skill-embed include_dir

Skills live under skills/<name>/SKILL.md. That is the layout defined by the Agent Skills specification.

use std::process::ExitCode;
use std::sync::LazyLock;

use include_dir::{Dir, include_dir};
use skill_embed::{Installer, SkillSet};

static SKILLS_DIR: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/skills");

static SKILLS: LazyLock<Installer> = LazyLock::new(|| {
    Installer::new(SkillSet::from_include_dir(&SKILLS_DIR).expect("valid skills"))
        .with_tool_name("mytool")
        .with_version(env!("CARGO_PKG_VERSION"))
});

fn main() -> ExitCode {
    if let Some(code) = SKILLS.intercept() {
        return code;
    }
    // the rest of your tool
    ExitCode::SUCCESS
}

include_dir! takes everything it finds. That includes .DS_Store, Thumbs.db, desktop.ini and .localized.

One inside a skill was committed, and it ships to everyone. One beside the skills ships too, and is never installed, so refusing it would stop a binary over a file its skills do not contain. An installed skill sits in a directory a user may open in a file browser. Such a file appears there on its own.

The directories match gh skill install.

Project root: /home/me/repo

Five of the six share .agents/skills at project scope. Selecting several of them resolves to one directory. Each skill is written there once.

--agent also takes two words.

--agent is repeatable, and one value may be a comma separated list. --agent claude-code --agent cursor and --agent claude-code,cursor name the same two.

InstallOptions::agents holds AgentSelector values. A selector for one agent comes from the agent itself.

use skill_embed::{Agent, AgentSelector, InstallOptions};

let options = InstallOptions {
    agents: vec![AgentSelector::from(&Agent::CLAUDE_CODE)],
    ..InstallOptions::default()
};

detected falls back to all when it finds nothing. A fresh repository still gets its skills. In a repository that already holds .claude, only Claude Code is written to. In a home directory it is the agents in use, rather than six directories of which most are litter.

Claude Code moves its whole configuration with CLAUDE_CONFIG_DIR. User scope follows that variable when it is set.

$ demo-lint skill
Manage the agent skills embedded in demo-lint.

Usage:
  demo-lint skill install   [flags] [skill...]
  demo-lint skill uninstall [flags] [skill...]
  demo-lint skill list      [flags] [skill...]

Flags:
      --agent <AGENT>  Target agent: {github-copilot|claude-code|cursor|codex|gemini|antigravity}, or all, or detected (repeatable) [default: detected]
      --dir <DIR>      Install to a custom directory (overrides --agent and --scope)
      --scope <SCOPE>  Installation scope: {project|user} [default: project]
  -f, --force          Overwrite existing skills
      --dry-run        Report what would happen without writing
  -h, --help           Show this help

Embedded skills:
  example-adoption  Stand-in skill for the demo-lint example. A real linter ships the skill that explains how to act ...

That is examples/demo-lint in this repository, run for real. demo-lint skill install --help answers the same way, for that subcommand alone. list and uninstall also answer to ls and remove, in both front ends.

A run reports one line per skill per destination.

$ demo-lint skill install --agent claude-code
Project root: /private/tmp/readme-demo/repo

installed  example-adoption  /private/tmp/readme-demo/repo/.claude/skills/example-adoption

$ demo-lint skill list --agent claude-code
Project root: /private/tmp/readme-demo/repo

example-adoption
  Stand-in skill for the demo-lint example. A real linter ships the skill that explains how to act ...

SKILL             STATE       PATH
example-adoption  up-to-date  /private/tmp/readme-demo/repo/.claude/skills/example-adoption

usage_hint is that line. It tracks the command name and the skill count, so it cannot drift from what the command actually does.

use skill_embed::Installer;

fn usage(skills: &Installer) {
    eprintln!("usage: mytool [file...]\n\n{}", skills.usage_hint());
}

Run "mytool skill" to install the 2 agent skills embedded in mytool.

Installer::usage returns the full help text, for a tool that writes its own.

Every installed SKILL.md gains four frontmatter keys.

x-embedded-by: demo-lint
x-embedded-version: 0.0.0
x-embedded-at: "2026-09-21T00:51:51Z"
x-embedded-digest: "sha256:ec3efba1135f122842cb9215c4396cdad467af7dd11323e4bbbb2583c2836852"

The digest is what makes a second run safe. It covers the whole skill directory. The manifest is hashed with these four keys removed. An installed copy and its embedded original therefore hash the same.

A skipped skill does not stop the others. install writes everything it can. It returns one InstallResult per skill either way. The outcome beside them is Error::NeedsForce when it left anything alone.

use skill_embed::{Error, InstallOptions, Installer, Result, render_results};

fn install(skills: &Installer, options: &InstallOptions) -> Result<()> {
    let (results, outcome) = skills.install(options);
    print!("{}", render_results(&results, options.dry_run));
    if let Err(Error::NeedsForce(blocked)) = &outcome {
        eprintln!("{blocked}");
    }
    outcome
}

foreign is wider than "another tool put it there". It also covers a hand-written skill. It covers a directory with no SKILL.md, and one whose SKILL.md has no x-embedded-* keys. It covers one this tool cannot read at all, such as a directory holding a symlink. Nothing can be said about any of them, so nothing is claimed. --force remains the way through.

intercept looks at the first argument and nothing else. mytool skill install reaches it. mytool -v skill install does not. Put your own flags after the subcommand, or before a normal run.

Installer::run is for a tool that has already parsed its own arguments. It never exits the process, so a driver keeps control.

use clap::Command;
use skill_embed::{Installer, Result};

fn run(skills: &Installer) -> Result<()> {
    let cli = Command::new("mytool").subcommand(skill_embed_clap::command(skills));
    let matches = cli.get_matches();
    if let Some((name, args)) = matches.subcommand()
        && name == skills.command_name()
    {
        skill_embed_clap::run(skills, args)?;
    }
    Ok(())
}

skill_embed_clap::options reads the flags without running anything. A tool that builds its own Command uses it to reach the same options.

Every option is a method on Installer, and each one returns the installer.

Installer::status reports without changing anything. install and uninstall return one InstallResult per skill per destination.

use skill_embed::{Agent, AgentSelector, InstallOptions, Installer, Result, Scope, render_results};

fn install_for_claude_code(skills: &Installer) -> Result<()> {
    let (results, outcome) = skills.install(&InstallOptions {
        agents: vec![AgentSelector::from(&Agent::CLAUDE_CODE)],
        scope: Some(Scope::User),
        ..InstallOptions::default()
    });
    print!("{}", render_results(&results, false));
    outcome
}

render_results and render_status turn those values into the text the built-in command prints. Installer::write_report sends that text where with_output points, so a front end that calls all three reports the same way to the same place. The clap adapter does.

InstallOptions::cancel stops a run between skills. A single skill is written whole or not at all, so the flag is read between them rather than during one.

Every error a user's own input can cause is a variant of Error. A front end can tell a mistyped flag from a disk that is full.

SkillSet::from_include_dir is one of three ways in. All three end in the same place.

from_files takes a File per path, so a tool that embeds its skills some other way needs no feature flag. Turn the include_dir feature off when you use it.

skill-embed = { version = "0.1", default-features = false }

skill-embed/skills/skill-embed-adoption/SKILL.md covers adopting the library. It names which front end to choose, the traps that are silent, and how to check the result. Install it into a repository that is about to embed skills.

gh skill install mpyw/rust-skill-embed skill-embed-adoption --agent claude-code

Dispatch Tag and Release with a version, such as v0.1.0. It tags, then publishes to crates.io, then cuts the GitHub release.

That order matters. A published version can never be published again, and a GitHub release freezes its tag. Creating the release first would burn the version number on a run that failed half way, so it is the last thing that happens.

Every step is safe to run again with the same version.

So a run that failed part way is finished by dispatching Release on its own with the same version.

The first version of each crate goes up from a laptop, because a trusted publisher can only be configured for a crate that already exists.

cargo login              # a token, once, on this machine
cargo publish --workspace

Then, in each crate's Settings on crates.io, under Trusted Publishing, add two configurations:

Two, because crates.io matches the workflow_ref claim. That claim names the top level workflow rather than the reusable one it called, so the usual path arrives as tag_and_release.yml and a retry dispatched on its own arrives as release.yml.

No token is stored in this repository. The workflow asks GitHub for one that says which workflow is running, hands it to crates.io, and gets back one that lasts thirty minutes. Turning on "require Trusted Publishing" in the same settings then refuses a publish from a token at all.

./test_all.sh

The toolchain is pinned in rust-toolchain.toml. Help text is asserted with expect-test. Run UPDATE_EXPECT=1 cargo test after changing a flag or a default.

Every Rust block in this file is compiled as a doctest, so an example cannot drift from a signature.

go-skill-embed is the same library for Go. The two agree on what they write: the agent directories, the four frontmatter keys, and the digest. Under one tool name, an installation made by either reads as up-to-date to the other, and the two trees are identical apart from x-embedded-at. tests/digest.rs pins the digest to the value the Go library produces.

MIT