agentleFS
sambersamber/developer-platform-skills/skills/agent-skill-offering/SKILL.md

agent-skill-offering

Skill9 starsChanged 23 days agoMITView on GitHub

Ships an Agent Skill (SKILL.md) inside the GitHub repo of the library, CLI or SDK it documents, versioned with the code - repo placement, metadata.version bumped every release, CI that fails a release on a stale skill, tag-pinned installs (skills.sh, gh skill, ClawHub, plugin marketplaces), plugin manifests, OpenClaw gating, skill vs MCP vs CLI. Use whenever a tool maintainer mentions shipping a skill with their tool, a SKILL.md for their library, keeping a skill in sync with releases, or plugin.json versions for a skill beside code - even if they never say "agent skill". Not for standalone skill collections. Do NOT use for CLI command or --json design - use samber/developer-platform-skills@cli-interface-design; nor for MCP servers - use samber/developer-platform-skills@mcp-server-offering.

The file

Show its rules and text

We split this skill into the rules it gives an agent

24 rules. About 0 are common, 12 are distinctive, and 12 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every release tag MUST contain a skill matching that tag's code, because a tag-pinned install is the only reproducible install most …

    line 24
  2. Distinctive:

    Ask before designing; each answer changes a later step.

    line 39
  3. Distinctive:

    Place the skill in the repo.

    line 51
  4. Distinctive:

    Write the content contract.

    line 52
  5. Distinctive:

    Add the CI gates.

    line 54
  6. Distinctive:

    If your harness has persistent memory, record: the version source of truth, the tag format, the gate list, the chosen channels and the …

    line 59
  7. Very specific:

    Default rung: skill + JSON output on the CLI.

    line 77
  8. Very specific:

    Put each skill at skills/<skill-name>/SKILL.md at the repo root.

    line 81
  9. Very specific:

    Keep the skill out of the repo's own agent directories (.claude/skills/, .agents/skills/): those serve agents working on the repo itself, …

    line 85
  10. Very specific:

    Treat metadata.version and its Skill version: body copy as provenance for humans, guards and checks.

    line 121
  11. Distinctive:

    Run on every pull request that touches code or skills, and again before the tag is created.

    line 125
  12. Very specific:

    Default rung: gates 1-3 and 6 before tagging, gates 1-4 and 6 on pull requests.

    line 140
  13. Very specific:

    Add a runtime drift notice when the tool can know: compare the installed skill's recorded version with its own version and print one …

    line 153
  14. Distinctive:

    Keep the default branch releasable, or tell users that a default-branch install may document unreleased features.

    line 155
  15. Very specific:

    Every manifest's version comes from step 4's source of truth and is checked by gate 2.

    line 163
  16. Distinctive:

    Keep the skill itself harness-neutral: no harness-only frontmatter, no harness paths, capabilities described rather than tool names.

    line 165
  17. Very specific:

    Every plugin.json and marketplace.json field, source form and directory check: references/plugin-manifest-fields.md.

    line 167
  18. Very specific:

    Add repository topics that directory crawlers index (agent-skills, gemini-cli-extension), and link the install command from the tool's …

    line 172
  19. Very specific:

    Keep scripts/ few, readable, offline and dependency-pinned.

    line 176
  20. Distinctive:

    Never tell the agent to fetch and follow remote content: the most common audit finding on benign skills is exactly that indirect-injection …

    line 177
  21. Very specific:

    Run an agent-skill security scanner such as Snyk Agent Scan (snyk-agent-scan) in CI next to the spec validator, and sign release tags.

    line 178
  22. Distinctive:

    Always-needed API facts only in an on-demand skill -> the skill may never load.

    line 199
  23. Very specific:

    Every manifest's version equals the tag on the last three releases.

    line 216
  24. Distinctive:

    Every release note prints a tag-pinned install command.

    line 217

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Agent Skill Offering

You are a release engineer for agent-facing tooling. Make a library, CLI, SDK or tool ship its own Agent Skill, in its own repo, so the skill an agent loads always matches the code version it runs.

The problem this solves: coding agents misuse tools from stale training data - removed flags, renamed functions, old defaults. A shipped skill fixes that only while it matches the installed version. A skill that drifts from the code teaches the same wrong calls, now with the maintainer's authority. Everything below exists to keep the two in lockstep.

Memory (advised): When memory lives in a file, consider using developer-platform-context.md; if a different memory system is in use, rely on that instead. The file is an advisory reference, not a mandatory requirement. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

The lockstep rule

The hard rule of this skill. Audit every plan against it before anything else.

  1. The skill MUST live in the same repository as the code it documents, because a separate skills repo has its own release cadence and drifts by construction.
  2. The skill's metadata.version MUST equal the code version, bumped in the same commit or release job that bumps the code, because an installer or agent can only detect a mismatch it can read.
  3. Every release tag MUST contain a skill matching that tag's code, because a tag-pinned install is the only reproducible install most channels offer.
  4. A release MUST fail before its tag exists when the skill is stale - version mismatch, or a command, flag or symbol it names no longer exists - because a warning in a release log gets read after users installed the wrong skill.
  5. A rename or removal of a skill MUST be treated as a breaking change of the tool, because installs, routing tables and other skills point at the skill by name.

Rationalizations to reject:

RationalizationWhy it fails
"Patch release, the skill didn't change, skip the bump."The version is the lookup key. A skill still saying 1.3.0 on the 1.3.1 tag reads as stale to every check and every user. Bump it by script; content can stay identical.
"We'll keep skills for all our tools in one org/skills repo."That repo releases on its own clock. Its HEAD documents some mix of versions. The rule is per tool repo.
"Users install from the default branch anyway."Then the default branch documents unreleased features to users on the last release. Pin installs to tags (step 6), or the gap is guaranteed.
"The version check is enough."Equal versions prove only that someone bumped a string. Rule 4 also needs the content check (step 5).

Interview

Ask before designing; each answer changes a later step. Batch them - this is a tactical build, not a strategy interview.

  1. What ships: a CLI binary, a library/SDK, or both? Which language, and how do users install it (language registry, Homebrew or another binary-only package manager, release download, container image)? (binary-only channels change step 6)
  2. How is a release cut today: manual tag, release-please/changesets, goreleaser, a CI job on tag push? Where does the version live (tag only, package.json, pyproject.toml, a version constant)? Are tags prefixed (monorepo components), and are there maintenance branches or prereleases? What is the repo's license? (the skill's license matches it)
  3. Which agents should use it: coding agents with a shell and the tool installed locally, chat assistants with no shell, or unattended agent fleets? (decides step 1)
  4. What do agents get wrong today: invented flags, deprecated APIs, wrong auth flow, unsafe defaults? Collect three real failures - they become the skill's first content and its tests.
  5. Does a skill, plugin manifest or AGENTS.md already exist anywhere for this tool, including community-written ones?
  6. By when must the first skill ship, is this a one-off fix or a standing release practice, and what is the effort ceiling (one afternoon, or a maintained release-pipeline change)? May the tool's own binary gain a subcommand (step 6, bundled rung)? A near deadline keeps the default rungs; a standing practice promotes the starved ones.

Workflow

  1. Confirm what ships beside the skill.
  2. Place the skill in the repo.
  3. Write the content contract.
  4. Wire the version to the code version.
  5. Add the CI gates.
  6. Choose install channels and pinning.
  7. Publish multi-harness manifests.
  8. List and measure.

If your harness has persistent memory, record: the version source of truth, the tag format, the gate list, the chosen channels and the pinned-install command. A later release run then checks the same gates instead of re-deriving them.

1. Confirm what ships beside the skill

The skill always ships (lockstep rule). This step decides what it carries and what sits beside it, by who calls the tool and what they need:

  • Agent operates a CLI, shell available -> skill + the CLI with machine-readable output and non-interactive flags. A skill's description costs about 100 tokens until it loads; an MCP server's tool definitions typically cost one to two orders of magnitude more idle context.
  • Multi-step workflow (setup, migration, major upgrade) -> a skill with references/. This is where skills measurably help most.
  • Knowledge every call needs (current API names, removed functions) -> docs bundled in the package plus a short pointer the tool writes into the user's project agent-instructions file. On-demand skills can fail to trigger: in one framework's published evals the skill was never invoked in 56% of runs, while an always-loaded docs index scored 100%. Keep the skill for workflows and point it at the bundled docs.
  • No shell (chat assistant, hosted fleet), hosted auth or remote state -> an MCP server, shipped in the same plugin as the skill. Route its design to samber/developer-platform-skills@mcp-server-offering.
  • Agent only reads docs on the web -> agent-readable docs; see samber/developer-relations-skills@coding-agent-docs-optimization.

What to add beside the skill, for a coding-agent audience:

  • effort: MCP server > bundled docs + agent-instructions pointer > JSON output on the CLI > nothing
  • value (correct agent calls): JSON output on the CLI > bundled docs + agent-instructions pointer > MCP server > nothing
  • efficiency: JSON output on the CLI > bundled docs + agent-instructions pointer > nothing > MCP server

Default rung: skill + JSON output on the CLI; hand the CLI's command, --json and exit-code design to samber/developer-platform-skills@cli-interface-design. Add the bundled-docs pointer when agents keep calling removed APIs even with the skill installed. Promote MCP only for an audience without a shell.

2. Place the skill in the repo

  • Put each skill at skills/<skill-name>/SKILL.md at the repo root. Most installers discover skills/ without configuration, and plugin manifests point at ./skills/.
  • Name the skill after the tool, qualified by job when there are several: acme-cli, acme-cli-migrations. The name is public API (rule 5).
  • Split by job, not by command group: one skill per thing an agent is asked to do. Start with one; split when SKILL.md passes ~250 lines. Keep the set small: focused skills beat exhaustive bundles, and large skill libraries measurably shadow each other.
  • Share cross-cutting rules (auth, safety, output parsing) in one skill the others tell the agent to read first, instead of copying them.
  • Keep the skill out of the repo's own agent directories (.claude/skills/, .agents/skills/): those serve agents working on the repo itself, as does the repo's AGENTS.md. User-facing skills go in skills/.
  • In a monorepo with several tools at independent versions, give each tool its own skill, checked against that tool's own version and tag prefix.
  • Include the skill in every release artifact the code ships in (package files list, archive contents, embedded assets), and check it in CI (gate 3). A skill that exists only in git is invisible to registry users. Go modules carry skills/ in the module zip automatically.

3. Write the content contract

Split ownership so nothing is stated twice:

  • The tool owns WHAT: flags, arguments, types, defaults. Point the agent at <tool> --help, <tool> <cmd> --help or the generated reference instead of copying them.
  • The skill owns WHEN and WHY: which command for which job, ordering, safe defaults, the three failures from interview question 4, how to read errors.
  • references/ owns the long tail: per-domain detail loaded only when needed.

Open the body with a two-sided version guard the agent executes. Some harnesses never show the frontmatter to the model, so the body carries one Skill version: line outside any code fence; the bump script rewrites it and gate 2 checks it. Name no other version anywhere in the prose.

Skill version: 1.4.0
Run `acme --version` first (libraries: read the installed package version).
- Same major.minor: continue. If only the patch differs, mention the matching tag once.
- Major or minor differs, in either direction: trust `acme --help` over this skill's
  command names, and tell the user to install the skill from their version's tag.
- A development build reporting `dev`: continue.

Follow the Agent Skills spec with keys name, description, license (the repo's own license), compatibility, metadata. Omit the spec's experimental allowed-tools: it pre-approves tools without a prompt. Put the version in metadata.version as a quoted string; the spec has no top-level version. Declare the binary in compatibility without a version number ("Requires acme-cli on PATH"), so no second version string goes stale. Write the description as what + when, with the tool's name and the tasks users type. For general skill-writing quality, use your preferred skill-authoring guidance; this skill covers shipping, not prose.

Good and bad bodies for CLI and library skills: references/skill-content-examples.md.

4. Wire the version to the code version

  • Pick one source of truth: the release tag, or the file the release tool already bumps.
  • Generate every other version field from it: each SKILL.md metadata.version, .claude-plugin/plugin.json, .codex-plugin/plugin.json, .cursor-plugin/plugin.json, gemini-extension.json. Leave version out of the marketplace file's plugins[] entry: the plugin's own manifest silently wins when both are set.
  • Bump them in the commit the release tag points at. A bump made after tagging never reaches the tag. Never by hand across five files:
    • Release-PR tool (release-please, changesets): add every file to its extra-files or version step, including the Skill version: body line (step 3), so the bump lands in the release PR.
    • Tag-only version (goreleaser, plain tags): a make release VERSION=x.y.z target that runs scripts/check-skill-version.py x.y.z --write --manifest ..., then the gates, commits, tags and pushes. Goreleaser itself runs after the tag and cannot bump.
  • Between releases, each release branch carries its last released version; only a release commit changes it. Run the same bump and gates on maintenance branches (release/1.3) as on the default branch.
  • Bump on every release, prereleases included (1.5.0-rc.1). Version equality is the contract. Some plugin installers key their cache on the manifest version: a set but unbumped version reports "already latest" and users keep the stale copy.
  • Treat metadata.version and its Skill version: body copy as provenance for humans, guards and checks. No installer reads them; installers resolve a git tag, a commit or a manifest version.

5. Add the CI gates

Run on every pull request that touches code or skills, and again before the tag is created. Ranked:

  • effort: golden agent tasks > content check > changed-surface check > version equality == spec validation == security scan
  • value: content check > golden agent tasks > version equality > changed-surface check > security scan > spec validation
  • efficiency: version equality == spec validation > content check > security scan > changed-surface check > golden agent tasks

The version-equality / spec-validation tie is real: both are one offline command, and each catches a failure the other cannot.

  1. Spec validation - the reference validator from the spec (pin its version) or an equivalent frontmatter check. Fails on a missing field, a name not matching its directory, a description over 1,024 characters.
  2. Version equality - copy this skill's scripts/check-skill-version.py (Python 3.8+ standard library; --help lists the options) into the tool's repo. Run it on every pull request against the version source of truth (for tag-only repos, the last tag: git describe --tags --abbrev=0), on the release PR or in make release before tagging, and once more on the tag as a backstop (a tag-time failure means deleting the tag). It checks metadata.version, the Skill version: body line and every manifest; it rejects a top-level version:, unquoted, duplicate, flow-style or nested metadata keys (--allow-nested openclaw admits OpenClaw's block), and strips monorepo tag prefixes with --tag-prefix.
  3. Content check - on the artifact the release will publish (built with the release version stamping, before any publish step), compare the skill against a machine-readable surface (<tool> help --json, nested --help, the exported API). Stale direction: every command, flag and identifier the skill names must exist. New-surface direction: every public command added since the last release must be mentioned or allowlisted. For libraries, compile or type-check every code block. Also assert the packaged artifact contains skills/. Projects whose version checks stayed green have shipped skills naming APIs removed a major version earlier; this gate is what catches that.
  4. Changed-surface check (pull requests) - when the public surface changes and no file under skills/ changed, fail or require an explicit "skill unaffected" label.
  5. Golden agent tasks (starved) - a handful of real tasks an agent runs against the built tool with the skill installed, scored on two numbers: trigger rate (did the agent load the skill) and pass rate. Highest effort, so it is always deferred. Promote it once agents are a main user channel, or after the first issue traced to a wrong skill.
  6. Security scan - an agent-skill security scanner over skills/ (see step 8).

Default rung: gates 1-3 and 6 before tagging, gates 1-4 and 6 on pull requests. Workflow snippets, the --help extraction pattern, the library variant and release-tool hooks: references/ci-release-gates.md.

6. Choose install channels and pinning

No installer resolves "the skill matching the code I installed" by itself. Most can pin a git tag or commit; one resolves the latest tagged release when unpinned; others follow the default branch. A tag-pinned install matches only at install time: the binary can upgrade silently (package manager, auto-update) while the pinned skill stays put, which is why the guard in step 3 checks both directions. Ranked:

  • effort: bundled with the code > plugin marketplace pinned to a tag > tag-pinned git install > default-branch install
  • value (version match guaranteed): bundled with the code > plugin marketplace pinned to a tag > tag-pinned git install > default-branch install
  • efficiency: tag-pinned git install > bundled with the code > plugin marketplace pinned to a tag > default-branch install
  • Default rung: tag-pinned git install. Generate the exact tag-pinned command per channel into every release note. In the README, print the commands with a v<your-installed-version> placeholder and the tool's version command, so the README never goes stale. Near-zero effort once tags carry matching skills (rule 3).
  • Binary-only package managers (Homebrew, apt, a release download): users get the binary and no skill, so a git install is a second manual step they skip. Print the matching install command in the tool's own --help or first-run output, and treat this as the promotion condition for the bundled rung below.
  • Starved option: bundled with the code - the skill ships inside the package or binary and a subcommand installs or syncs it (<tool> install --skills, <tool> update), or the skills installer links it from the installed package. Version match by construction, highest effort. Promote it when most users install through a package manager, or when stale-skill issues keep arriving.
  • Add a runtime drift notice when the tool can know: compare the installed skill's recorded version with its own version and print one agent-parseable line, e.g. skill acme-cli 1.3.0 differs from acme 1.4.0; run: acme skills update.
  • Self-hosted plugin marketplace (source: "./"): users who add it from the default branch get merged-but-unreleased skill text under the last released version, and the cache may never refresh. Tell them to add the marketplace at a release tag, or keep a stable branch moved only at release.
  • Keep the default branch releasable, or tell users that a default-branch install may document unreleased features.
  • Prereleases: keep them off every default install. Cut them from a next branch (or tag a commit off the default branch), mark the GitHub release as a prerelease so latest-release resolution skips it, and move the stable branch or recommended marketplace tag only on final releases.

Per-channel commands, ref syntax, lockfiles, update behaviour and manifest fields: references/distribution-channels.md.

7. Publish multi-harness manifests

  • Ship at repo root, each pointing at ./skills/: .claude-plugin/plugin.json, .claude-plugin/marketplace.json (self-hosting the plugin, source: "./", no version in the entry), .codex-plugin/plugin.json, .cursor-plugin/plugin.json, gemini-extension.json.
  • Every manifest's version comes from step 4's source of truth and is checked by gate 2.
  • Copy author, homepage, repository and license from the repo's existing package metadata; never publish placeholder owners.
  • Keep the skill itself harness-neutral: no harness-only frontmatter, no harness paths, capabilities described rather than tool names.
  • OpenClaw needs no extra manifest: it installs the repo as a bundle at a git tag (from any of the manifests above) or a ClawHub publish. Add a metadata.openclaw block map whose requires.bins block list names the tool's binary, so OpenClaw offers the skill only where the tool is installed. It is a spec deviation; allow it in gate 2 only for that key. Keys, ClawHub publishing and the MIT-0 catch: references/distribution-channels.md § OpenClaw and ClawHub.
  • Every plugin.json and marketplace.json field, source form and directory check: references/plugin-manifest-fields.md.

8. List and measure

  • Install-ranked directories (skills.sh) index a repo's SKILL.md folders and rank them by installs reported by the installer's telemetry. The README install section is the listing's real driver.
  • Add repository topics that directory crawlers index (agent-skills, gemini-cli-extension), and link the install command from the tool's official docs.
  • Submit the plugin to Anthropic's Claude plugin directory from https://claude.ai/directory/manage (paid claude.ai plan): Submit new, Plugin bundle, the repository, then Validate. Set Branch or tag to the stable branch moved only at release (step 6): left empty it follows the default branch, so every merge becomes a candidate version that goes live once auto-publish is on or someone selects Publish. A tracked tag must be re-pointed each release. A README under 40 words or a missing license blocks the listing.
  • Publish under the organization's own namespace and claim obvious name variants: agents hallucinate skill names, and attackers register them.
  • Expect public security audits of listed skills, and pass them before launch:
    • Keep scripts/ few, readable, offline and dependency-pinned; call the tool's own published CLI instead of bundling binaries.
    • Never tell the agent to fetch and follow remote content: the most common audit finding on benign skills is exactly that indirect-injection exposure.
    • Run an agent-skill security scanner such as Snyk Agent Scan (snyk-agent-scan) in CI next to the spec validator, and sign release tags. Workflow step, token and flag cautions: references/ci-release-gates.md § Gate 6.
  • Measure correctness, not reach. Install counts measure interest and can be inflated. The signals that matter: trigger and pass rate per release (gate 5), issues tagged "agent misuse", and how often the drift notice fires.

Failure modes

  • Skill in a separate repo, versioned on its own clock -> lockstep rule 1.
  • version: 1.4.0 at frontmatter top level -> non-spec; move under metadata as a quoted string.
  • Version guard that checks only "older than" -> a silently upgraded binary passes it; check both directions (step 3).
  • Guard that reads only metadata.version -> invisible to the agent in harnesses that strip frontmatter; keep the Skill version: body line.
  • Install docs say owner/repo with no ref -> users get the default branch, not their version.
  • SKILL.md is a pasted flag reference -> stale on the next release; defer WHAT to --help.
  • Version bumped by hand in five manifests -> one drifts; generate them (step 4).
  • version set in both the plugin manifest and its marketplace entry -> one silently wins; keep it in the plugin manifest.
  • ClawHub publish without --version -> the registry picks its own next patch; pass the release version.
  • metadata.openclaw copied in flow form ({...} or [...]) -> strict YAML validators reject the file; convert to block style.
  • Directory submission tracking the default branch -> every merge becomes a candidate listing version; track the stable branch.
  • CI checks only version strings -> a removed flag ships in a "matching" skill; add gate 3.
  • Version gate run only on the tag -> the stale tag already exists; run it before tagging.
  • Skill script downloads and runs remote code -> fails audits and opens an injection path.
  • Silent skill rename -> broken installs and routes. Rename in a major release, and keep a stub skill under the old name for one major that points at the new one.
  • The repo's own contributor-facing AGENTS.md mistaken for the user-facing skill -> different audience, different file.
  • Always-needed API facts only in an on-demand skill -> the skill may never load; bundle the docs and point at them (step 1).

Invocation examples

  • "I maintain a Go CLI. Coding agents keep inventing flags. Ship a skill with it and keep it in sync across releases."
  • "Our npm SDK has a SKILL.md in a separate repo that's two majors behind - fix the setup."
  • "Add a CI check that fails the release if the skill's version doesn't match the tag."
  • "Should we ship an MCP server, a skill, or both for our CLI?"

Expected output: the repo layout, the version-wiring change, the CI gate list with commands, the install commands per channel, and the manifests - each checked against the lockstep rule.

Measurement

The setup passes when all hold:

  • A release with a deliberately stale metadata.version fails before its tag exists.
  • A release where the skill names a removed flag or symbol fails CI.
  • Every manifest's version equals the tag on the last three releases.
  • Every release note prints a tag-pinned install command.

References

  • samber/developer-platform-skills@api-integration-surface-strategy - for a SaaS platform choosing among all its integration surfaces; this skill starts once an agent skill is chosen.
  • samber/developer-platform-skills@sdk-package-publishing - registry publishing mechanics for the package the skill rides in.
  • samber/developer-platform-skills@github-action-offering - the same release discipline (frozen contract, immutable tags, CI gates) for the tool's official GitHub Action.
  • samber/developer-platform-skills@agent-integration-surfaces - the platform-wide agent plan the skill sits in: access policy, agent identity, signup, measurement.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.