On July 14, 2026, five malicious versions of four @asyncapi npm packages went out carrying fully valid npm trusted publishing signatures. That is the detail worth sitting with. Trusted publishing and provenance attestations are the mitigation the package-manager ecosystem has spent the last two years converging on, and they did exactly what they were designed to do here. The packages still shipped a credential-stealing implant to everyone who imported them.

What happened

Microsoft's Threat Intelligence team published the incident writeup on July 15, 2026. Five versions across four packages were affected: @asyncapi/specs@6.11.2-alpha.1 and 6.11.2, @asyncapi/generator@3.3.1, @asyncapi/generator-components@0.7.1, and @asyncapi/generator-helpers@1.1.1. AsyncAPI's tooling is widely used for generating code and docs from AsyncAPI specifications, so the blast radius was every build that pulled a fresh install in the roughly 24 hours the versions were live.

The entry point was a GitHub Actions workflow triggered on pull_request_target, which runs with the base repository's permissions and secrets even when it checks out a fork's code. Microsoft's writeup describes this as placing "the job in the base repository's security context" while still checking out untrusted code - the standard failure mode for that trigger, well documented, and still exploitable here. That exposed the asyncapi-bot personal access token, which the attacker used to push unauthorized commits that then rode the project's own, legitimate release workflow to npm.

That release workflow used npm trusted publishing: GitHub Actions OIDC tokens instead of a long-lived npm auth token, with npm issuing a signed provenance attestation tying each published version to the exact source commit and workflow run that built it. It is the configuration npm's own documentation recommends, and none of it failed. Per Microsoft, "the attestations accurately identified the legitimate repositories, commits, and workflows that created the packages, even though the triggering commits were unauthorized." The chain of custody was genuine. The commit at the start of that chain was not one a human maintainer intended to ship.

The payload itself is worth noting for a second reason: it runs at import time, when the package is required or imported, rather than during npm install. That means the standard defensive advice to run npm install --ignore-scripts does nothing here - there is no install script to skip. The loader spawns a detached process that pulls an encrypted ~8.2 MB second stage from IPFS and launches what Microsoft calls the Miasma runtime, with command-and-control, persistence, and credential harvesting.

What provenance is actually for

Provenance attestations answer one question: did this exact artifact come from this exact commit, built by this exact workflow, on this exact CI provider? That is a real, useful, previously-unanswerable question, and the AsyncAPI incident proves the answer works - the forensic reconstruction in Microsoft's writeup exists because the attestations correctly recorded which commits and runs produced the malicious tarballs.

What provenance was never designed to answer is whether the commit at the end of that chain reflects what a maintainer meant to publish. A stolen PAT and a trusted release pipeline produce an attestation indistinguishable from a legitimate one, because from the attestation's point of view, nothing about the pipeline misbehaved. The compromise happened one layer up, in the trigger that decided which code got to run with the bot's credentials at all.

That is a narrower, more precise claim than "provenance doesn't work," and it is the one the incident actually supports.

Where this connects, and where it stops

skillfold's own lockfile makes a structurally similar promise for skill and rule sources: a resolved commit SHA or exact npm version, plus a sha256 integrity hash computed over the fetched files, checked again on every install --frozen or check. That is real - I read src/lock.ts and src/resolve.ts to confirm it holds - and it buys the same thing npm's attestation buys: proof that what is on disk today matches what was originally pinned, byte for byte, whoever or whatever produced it.

It buys nothing about what was pinned. If a skill or an npm package is compromised at the exact moment someone runs skillfold add or skillfold update against it, the lockfile pins the compromised version as faithfully as a clean one, hashes it, and reports ok on every subsequent install. This is the same blind spot as npm's OIDC attestation, for the same structural reason: a cryptographic record of what got published and from where cannot see backward into whether the commit behind it was the one a human actually meant to ship.

One thing does not carry over directly, and it is worth being precise about rather than reaching for the scarier-sounding claim: skillfold's npm resolution runs npm pack to download a tarball and extracts it with tar - it never runs npm install and never requires or executes any code from the package. So the specific mechanism in this incident, code that runs at import time and bypasses --ignore-scripts, does not touch skillfold's own fetch path, because skillfold never imports what it fetches in the first place. What an agent later does with the instructions or scripts inside a fetched skill is a separate question skillfold's pinning does not answer either way.

The takeaway

Trusted publishing and provenance are worth adopting - they closed off credential theft as an attack path here, and the forensic trail in Microsoft's writeup only exists because they were in place. But treat them, and any lockfile that makes similar promises, as answering "has this changed since I looked at it," not "was this safe when I looked at it." Those are different questions, and the second one still needs a human to read the diff before the pipeline runs, rather than trusting the signature after it does.

Agent skills have quietly become software artifacts with dependencies: a SKILL.md can tell an agent to invoke another skill, shell out to an npm package, or call an external service. Almost none of them say so. That is the finding of "Skills Are Not Islands: Measuring Dependency and Risk in Agent Skill Supply Chains", a paper submitted July 1, 2026 by Changguo Jia, Tianqi Zhao, Runzhi He, and Minghui Zhou, which is the first attempt to treat agent skills as a dependency graph at ecosystem scale and measure what is actually inside it.

What they built and ran

The paper introduces "Agent Skill Supply Chains" (ASSCs) as a formal model - skills, packages, and services as nodes, with edges for skill-to-skill, skill-to-package, and skill-to-service dependencies - and a tool called SkillDepAnalyzer (SDA) that extracts those edges from a skill's frontmatter and prose using natural-language evidence, the same way an SBOM tool would extract edges from a manifest file, except here there usually is no manifest file to read.

They ran SDA against 1,434,046 skills downloaded from the SkillsMP registry on June 6, 2026 - 87.4% of the 1,640,440 skills the registry listed at the time. That is the largest dependency analysis of the agent skill ecosystem published so far.

Present, but not declared

The paper's core finding is a pattern it names skill metadata that is "activation-ready but governance-poor". Frontmatter of some kind is present in 99.55% of the corpus, and the two fields an agent needs to activate a skill are almost as universal: a name in 99.49%, a description in 99.52%. Fields that would let a tool reason about what a skill depends on appear in only 1.40%. Name collisions compound the problem: 58.73% of skill names collide with at least one other skill in the corpus, which the paper notes makes identity resolution fragile even before dependencies enter the picture.

Where SDA did find dependency evidence - mostly in the prose telling an agent what to run or call, not in structured fields - the breakdown across the full corpus was:

So more than a third of skills pull in something beyond their own files, and almost none of that is declared anywhere a tool could check without running an LLM-assisted extractor over the skill's prose first.

The security signal

The paper also traced known-risky packages, services, and skills through the graph to see how far they reach via transitive dependency, not just direct use. It found 194 root skills reaching a known malicious skill, 13.40% of that exposure arriving only transitively; 3,342 skills touching a dangerous code pattern, 78.43% transitively; 3,413 skills reaching the axios package specifically, 98.01% transitively; and 29 root skills reaching a vulnerable MCP service, 93.10% transitively. The consistent shape across all four numbers is that most of the exposure is inherited from something the skill depends on, not something the skill's own author wrote - which is exactly why an undeclared dependency graph is a worse problem than an undeclared dependency count.

What the paper recommends

Section VII of the paper splits its recommendations by who is responsible. For registries: require a typed dependency manifest that separates skill, package, and service dependencies; treat clusters of interdependent skills as a first-class object to manage rather than inspecting skills one at a time; and expose an audit command "analogous to npm audit." For skill developers: maintain a lockfile-like record of exact versions, source repositories, paths, and dependency status.

That is, structurally, the two-file shape most package ecosystems converged on after their own supply-chain incidents: a manifest a human edits, and a lockfile a tool writes and nobody hand-edits. It is also, not coincidentally, the shape skillfold already uses for the slice of this problem it covers: skillfold.yaml is a typed manifest across skills, compose, and rules, and skillfold install writes skillfold.lock with the exact resolved commit SHA or version and a sha256 content hash per entry (see the manifest reference). compose entries record their use list in the lock too, so a skill built from other skills has that skill-to-skill edge pinned and checkable - skillfold check fails the build if an installed composed skill no longer matches what its locked inputs would generate.

What this does not solve

That overlap is narrower than it sounds, and worth being precise about. skillfold's manifest only captures skill-to-skill dependency, and only the explicit kind: an entry in compose.use. It has no equivalent of SDA's skill-to-package or skill-to-service edges - if a skill's body tells an agent to npm install something or call an external API, skillfold has no visibility into that dependency at all, and neither does anything else in the current tooling landscape; that is precisely the gap this paper is pointing at. A sha256 integrity hash also is not a vulnerability scan: it proves a pinned skill's content has not changed since the day it was pinned, which is a different guarantee than "this skill's content is safe." Nothing about the manifest or lockfile would have caught the axios exposure or the malicious-skill reachability the paper measured, because both require walking dependencies inside a skill's own instructions, and skillfold's lockfile only reasons about the skills a project explicitly declares in its own manifest, not the graph underneath them.

Eight days apart, Microsoft moved Agent Skills support in its Agent Framework from experimental to stable, first for .NET on July 7, 2026, then for Python on July 15, 2026. Both posts explicitly point at agentskills.io as the spec they're implementing. That's worth pausing on, because it's a data point about who now treats SKILL.md as infrastructure worth a stable API, not just a convention Claude clients happen to read.

What actually shipped

The .NET announcement describes removing the [Experimental] attribute from the Agent Skills API, promoting it to production-ready. The Python announcement is more direct about it: "Agent Skills for Python in Microsoft Agent Framework is stable and shipping: the core skills API has no experimental gate."

Both languages support three ways to author a skill:

• File-based skills - a directory with a SKILL.md file, optionally bundling scripts and reference docs. This is the same shape agentskills.io specifies and the same shape skillfold installs.
• Class-based skills - a C# class or Python class, distributed as a NuGet or PyPI package.
• Code-defined skills - skills constructed dynamically at runtime inside application code.

Both posts describe the same progressive-disclosure loading pattern the spec itself uses: advertise a skill's name and description first, load the full instructions only when a task matches, then pull in bundled scripts or reference files as needed. The Python post frames it as four steps ("advertise skill names → load instructions → read resources → run scripts"), the spec's own overview frames it as three (discovery, activation, execution) - same mechanism, different granularity of description, not a disagreement.

Why this is more than another integration

agentskills.io's client showcase - fetched July 25, 2026 - lists 44 adopting tools: terminal agents (Claude Code, OpenAI Codex, Gemini CLI, OpenCode, Goose), editors (VS Code, Cursor, JetBrains' Junie), and platforms (Snowflake Cortex Code, Databricks Genie Code). Most of those are end-user products reading SKILL.md directories that someone else wrote.

Microsoft's Agent Framework is a different kind of adopter: it's an SDK people use to build agents, and it just gave SKILL.md a stable, non-experimental API alongside two other authoring paths that aren't file-based at all. That's a vendor betting that file-based skills are worth committing to as a public contract, not an experimental flag they might pull next quarter.

It's also not the first SDK to add SKILL.md support - Spring AI shipped a generic Agent Skills implementation back on January 13, 2026, built specifically to work "across many LLM providers." But that implementation ships under the spring-ai-community group ID at version 0.4.2 against a Spring AI milestone build, and its own "Current Limitations" section flags unsandboxed script execution and no human-in-the-loop controls. Microsoft's release, by contrast, leads with production concerns: the .NET and Python posts both describe human-in-the-loop approval, controlled script execution, filtering, caching, and an extensible source pipeline for custom skill discovery. The gap between those two isn't the file format - both read the same SKILL.md - it's how much a vendor is willing to say "you can run this in production, unattended, against untrusted skill content."

What this doesn't solve

A stable API in one more SDK doesn't make the ecosystem interoperable. Each of those 44 clients, and now the Agent Framework, still has its own discovery convention - where it looks for skills, what it expects alongside SKILL.md, how it resolves updates. agentskills.io standardizes the file format inside the directory; it doesn't standardize where the directory lives or how it gets there.

That's the gap skillfold works in, and this release doesn't close it either

• it makes it slightly bigger. Skillfold today installs into two targets, claude and codex, mapping to fixed locations (.claude/skills / .agents/skills, and a managed block in AGENTS.md for Codex; see src/targets.ts). It has no idea where the Agent Framework expects a file-based skill directory to sit, so a manifest-managed skill doesn't reach it without a new target being taught to skillfold deliberately. And the class-based and code-defined authoring paths aren't directories at all - they're code, shipped through NuGet or PyPI, with their own versioning and audit story. A lockfile built for pinning and hashing file trees has nothing to say about a C# class compiled into a package.

So the honest read is narrower than "the standard won": one more vendor now has a stable reason to keep SKILL.md working, which is good news for anyone betting on the format's durability. It is not evidence that installing a skill into any given tool got easier this month.

Sources

• Agent Skills for .NET Is Now Released, Microsoft Agent Framework blog, July 7, 2026
• Agent Skills for Python Is Now Released, Microsoft Agent Framework blog, July 15, 2026
• agentskills.io, specification overview and client showcase, accessed July 25, 2026
• Spring AI generic Agent Skills, Spring blog, January 13, 2026

The Model Context Protocol - the wire format most agent tools now use to reach external tools and data sources - ships its largest revision since launch on July 28, 2026. The release candidate has been locked since May 21, giving SDK maintainers a ten-week window to catch up, according to the official MCP specification blog. The headline change is not a new feature. It is the removal of the one thing every MCP deployment has depended on since the protocol's first release: the session.

What a stateless core actually removes

Every MCP connection used to start with an initialize handshake that returned an Mcp-Session-Id header, and every request after that had to reach the same server instance that issued it. That is gone. Protocol version, client identity, and capabilities now travel in a _meta field on every request instead of being negotiated once and pinned to a session. Any server instance can now answer any request, per the specification blog, which means a remote MCP deployment that needed sticky routing, a shared session store, or packet inspection at the load balancer to keep requests on the right instance no longer needs any of that.

Server-initiated requests - a confirmation prompt mid-task, for example - had to assume a persistent connection back to the client. They are restructured too: a server can only issue one while actively handling a client request, and the client can resume the exchange from any instance using a requestState payload it echoes back on retry.

Three things are removed outright: the initialize/initialized handshake, the Mcp-Session-Id header, and the tasks/list method, which the spec blog says "can't be scoped safely without sessions". A non-standard -32002 error code for missing resources is replaced with the JSON-RPC standard -32602.

Three features that were part of the core are marked deprecated rather than removed: Roots, Sampling, and Logging. They still work.

The part that is actually new: a deprecation clock

Protocol revisions have shipped breaking changes before. What has not existed until this one is a written commitment about how much notice the next breaking change gets. The spec blog now defines a formal lifecycle - Active, Deprecated, Removed - and guarantees, in its own words, "at least twelve months between deprecation and the earliest possible removal." A conformance suite gates new Standards Track proposals from reaching Final status without going through that lifecycle.

That is the detail worth sitting with if you build against MCP rather than just consume it through a client. A protocol that reserves the right to change anything at any time is a protocol you can only track by reading every release. A protocol that commits to twelve months' notice is one you can plan a migration against - which is a different, better problem to have, even though this particular revision predates the policy that would have given it more runway.

Extensions get the same kind of structure applied going forward: reverse-DNS identifiers, independent versioning, and their own repositories under the SEP process, rather than accreting into the core spec. Tasks - previously an experimental core feature for long-running operations - moves into one of the first such extensions, redesigned so a server returns a task handle and the client drives progress with tasks/get, tasks/update, and tasks/cancel instead of relying on a live connection.

Who this actually disrupts

Coverage from The Register quotes Anthropic's David Soria Parra putting the disruption where it actually lands: "If you built your own implementation, it's going to be a lot of uplift to make this correct." Anyone on an official SDK is expected to absorb the change within the ten-week validation window Tier 1 SDKs get before the July 28 ship date. Anyone who hand-rolled a client or server against the wire format directly inherits the session-removal work themselves, and backward compatibility between the old and new protocol revisions is not guaranteed - a server speaking 2026-07-28 and a client still expecting a session id will not silently interoperate.

Six SEPs also tighten authorization against current OAuth 2.0 and OpenID Connect practice: iss parameter validation per RFC 9207, an application_type declaration during dynamic client registration, and credentials bound to the server that issued them. None of that is optional hardening bolted on top - it is part of the same revision.

What this has nothing to do with

MCP governs how an agent talks to a tool or data source over the wire. It says nothing about how the instructions an agent loads - a SKILL.md, a project's AGENTS.md, a rules file - got onto the machine running that agent, and it has no equivalent yet of pinning a specific server to a specific protocol revision the way a lockfile pins a package to a commit. skillfold's manifest and lockfile resolve and hash skill sources; they say nothing about MCP servers and do not touch protocol versions at all. If your agent setup depends on MCP servers, this migration is a client and server compatibility problem you handle independently of anything a skill manifest covers, and as of this specification there still isn't a standard way to declare and reproduce "which MCP protocol revision does this agent's setup expect" the way you can declare which skill revision it expects. That gap is worth naming, not papering over with an unrelated tool.

If you maintain an MCP server or client directly rather than through an official SDK, the ten-week window closes soon. If you consume MCP only through a client that tracks the spec, the practical action item this week is confirming which SDK version you are on and whether it has picked up the 2026-07-28 revision yet.

Agent skills got their own security literature in the first half of 2026. Not think pieces: vendor disclosures with sample counts, a CVE trail, and papers on arXiv. If you install skills from anywhere other than your own repository, the findings are worth reading, and the recommended mitigations are worth reading more carefully than the findings.

The numbers, with their attributions:

• Snyk's February 2026 audit of 3,984 skills from the ClawHub registry found 36.82% contained at least one security flaw and 76 carried confirmed malicious payloads, per the Cloud Security Alliance's briefing.
• Koi Security disclosed 341 malicious skills in its ClawHavoc report, a typosquatting campaign against the registry's users.
• Bitdefender Labs reported that roughly 17% of the skills it analyzed in the platform's first weeks carried malicious payloads, cited in Unit 42's writeup.
• Unit 42's own February to May 2026 analysis walked through five skills that were live and unblocked at the time of writing, spanning macOS infostealers, scanner evasion, and runtime affiliate injection.

There is also academic work: see Towards Secure Agent Skills for a threat taxonomy, and Formal Analysis and Supply Chain Security for Agentic AI Skills.

What those numbers do and do not measure

Start with the caveat, because it is the part most coverage drops. The large datasets above come from ClawHub, the marketplace for the OpenClaw agent framework. They are not measurements of Anthropic's skill directory, of skills.sh, or of whatever you have in .claude/skills right now. Anyone telling you "a third of Claude skills are malicious" is misreading a ClawHub audit.

What does carry across is the mechanism. SKILL.md is the same format across roughly forty tools now, and the attacks in these reports target the format and the trust model rather than any one client. A finding about how a markdown instruction file can smuggle behavior is a finding about every tool that loads markdown instruction files.

The client side has not been clean either. The CSA briefing traces two patched Claude Code CVEs, CVE-2025-59536 (CVSS 8.7, October 2025) and CVE-2026-21852 (CVSS 5.3, January 2026), and its list of immediate actions starts with patching the client before anything else.

The attack surface is the instructions

The interesting part of this research is how little of it involves code execution in the traditional sense.

Some attacks are ordinary supply-chain fare: Unit 42 documents base64-encoded curl-pipe-bash droppers, paste sites like rentry.co used as redirect intermediaries, and one skill padded with 22 MB of filler characters to push it past scanners' size limits.

The rest are attacks on meaning. Unit 42 calls it semantic instruction hijacking: text that reads as documentation to a human and as a directive to a model. The CSA briefing documents the same class, including instructions hidden in Unicode tag characters (U+E0000 to U+E007F), which are invisible in most editors and processed normally by a language model. Their worked example is a skill that appends API keys as query parameters before fetching an external URL, which is not malware by any classical definition. It is a sentence.

This is why "the skill has no scripts in it" is not a safety property. The prose is the payload.

The mitigations converge

Read enough of these reports and the recommendations start to rhyme. The CSA briefing's short-term controls are the clearest statement of the pattern: restrict which registries skills may be sourced from, and require content hash verification before loading skills into production. It also points at internal registries with content signing. Unit 42 asks for line-by-line source audits and outbound traffic monitoring against a documented spec.

Strip the vendor-specific parts and three ideas remain:

1. Know where a skill came from. Not "the marketplace", a specific source at a specific revision.
2. Know it has not changed since. A hash, checked before load, not a version string you trust the publisher to bump.
3. Review it once, deliberately, and make that review durable. A review is worthless if the reviewed thing can be swapped out afterwards.

None of that is novel. It is what package ecosystems concluded years ago, arriving late to a format that spread faster than its tooling.

Where a lockfile fits

This is the part skillfold is built for, so read it with appropriate suspicion.

A manifest names each skill's source, and the lockfile records the full commit SHA it resolved to plus a sha256 over every file in the directory:

skills:
  frontend-design:
    source: github:anthropics/skills/skills/frontend-design@v1.2.0
    resolved: github:anthropics/skills/skills/frontend-design@8f3a9c1e...
    integrity: sha256-...

That maps onto the first two ideas directly. resolved pins the revision, so a moving tag or a latest dist-tag cannot quietly become something else; install reuses the pin until you deliberately run update. integrity covers the content, so a modified file is detectable whether it was changed upstream or in your working copy. skillfold install --frozen verifies every hash before writing anything and is the mode meant for CI, and skillfold check does the same verification offline.

It also means nothing gets fetched at agent runtime. Skills are materialized into place at install time from pinned sources, so the set of instructions an agent can load is a build product you can diff, not a live lookup.

What a lockfile does not do

A content hash proves that the bytes did not change since you pinned them. It says nothing whatsoever about whether those bytes were safe.

If you install a skill carrying a hidden instruction to exfiltrate your repository, skillfold will pin it, hash it, verify it on every subsequent install, and reproduce it faithfully on every machine your team owns. It will report ok: 4 skills in sync. The lockfile makes the compromise reproducible, which is genuinely better than making it random, and is not remotely the same thing as making it safe.

skillfold has no scanner. It does not read skill content for suspicious instructions, does not strip invisible Unicode, does not check publisher identity or signatures, and does not sandbox anything. It is a fetch-and-place tool, and treating it as a security control is a mistake worth naming plainly.

What it can do is make the review the CSA briefing asks for actually worth performing. Auditing a skill you cannot pin is theatre, because the thing you audited is not necessarily the thing that loads tomorrow. Pinning is what turns a one-time read of a SKILL.md into a durable statement about what your agent runs.

What to do this week

Independent of any tool: patch your client. Then list every skill you have installed and ask, for each one, where it came from and whether you have read it. For most people the honest answer to the second question is no for at least half the list, which is the actual finding here.

Read them. Pay attention to prose that instructs rather than describes, especially anything constructing a URL. Then pin whatever survives, so you only have to do this once.

Skills are portable. The agent skills standard is a directory with a SKILL.md in it, and the tools that consume it agree on that much. What they do not agree on is where to look.

Claude Code reads skills from .claude/skills and loads rules from .claude/rules. Codex reads skills from .agents/skills and has no rules directory at all: its instructions live in AGENTS.md, a single file you also write by hand.

If you use both, you currently maintain the same skill in two places and the same standing instructions in two formats. That is a synchronization problem, and synchronization problems are what a manifest is for.

targets: [claude, codex]

That is the whole feature from the user's side. One line, and skillfold install materializes every declared skill into both locations from the same pins.

Rules are the hard part

Skills were easy: same format, different directory, copy twice. Rules were not, because Codex does not have a rules directory. It has one markdown file that the user also owns.

So the codex target syncs rules into a marker-fenced block:

<!-- skillfold:rules:start -->
...your rules, one section per rule...
<!-- skillfold:rules:end -->

Everything outside those markers is yours and is never read, rewritten, or reformatted. The block is created on first install, updated when a rule changes, and removed entirely when you drop the last rule from the manifest. skillfold check verifies it offline like any other installed file, so a hand edit inside the block shows up as drift.

Two guards matter here, because this is a tool writing into a file a human is also editing:

• Rules must be UTF-8 text. Binary content in a file meant for an agent to read is a mistake, not a use case.
• A rule whose content contains skillfold marker lines is rejected with an explicit error rather than installed. Otherwise the markers nest and the next install cannot tell where its own block ends.

Both fail the install with a message instead of producing a subtly corrupted AGENTS.md.

Adding a target to an existing project

The interesting case is not the greenfield one. It is the project that already has fifteen skills in .agents/skills, put there by hand, that now wants skillfold to manage them.

The lockfile records which targets it has installed for. A newly added target starts with nothing managed, which means every file already sitting in its locations is treated as hand-authored. From there:

• If the existing content is byte-identical to what skillfold would install, it is adopted silently. Nothing changes on disk, and the skill becomes managed.
• If it differs, the install stops and tells you. Taking ownership of a file whose contents you did not put there requires --force.

This is the same rule that applies everywhere else in the tool: skillfold overwrites and prunes exactly what its lockfile names, and nothing else. Adding a target does not hand it the directory.

In global mode (-g) the codex target manages ~/.agents/skills and ~/.codex/AGENTS.md, honoring CODEX_HOME.

One thing that does not generalize

skillsDir and rulesDir override the claude locations only. Codex scans fixed conventional paths, so pointing skillsDir somewhere else does not move the Codex install, and it should not: a configurable path for a tool that does not read configurable paths is a footgun that looks like a feature.

If you need skills somewhere unusual for a third tool, that is a new target, not an override.

Try it

npx skillfold init
# add targets: [claude, codex] to skillfold.yaml
npx skillfold install
npx skillfold check

This repository installs its own config for both targets in CI, which is how the sharp edges above got found in the first place.

You have a code-review skill and a testing skill. You want a third one that does both, because in review you always want the tests considered alongside the diff.

Without tooling there are two options and both are bad. Write a reviewer skill that duplicates the bodies of the other two, and accept that it will drift from them within a month. Or write a reviewer skill that says "also follow the code-review and testing skills", and hope the agent goes and reads them.

Composition is the third option: declare the combination and let the tool generate the file.

skills:
  code-review: npm:skillfold/code-review
  testing: npm:skillfold/testing

compose:
  reviewer:
    description: Review code changes together with their tests.
    use: [code-review, testing]

After skillfold install, .claude/skills/reviewer/SKILL.md contains both bodies in order, with frontmatter stripped from the inputs and a fresh header on top. It installs like any other skill, it is hashed in the lockfile like any other skill, and it is regenerated whenever either input changes.

What "concatenate" actually has to handle

The word makes it sound trivial. It is not, and the interesting parts are the ones that are not string joining.

Supporting files come along. A skill is a directory, not a file. If code-review ships a references/checklist.md and its body says "see references/checklist.md", that relative path has to keep resolving after composition. So the used skills' supporting files are copied into the composed directory. Identical duplicates collapse silently. Two skills providing the same path with different contents is an error rather than a coin flip, because there is no correct answer and silently picking one produces a skill that is subtly wrong.

allowed-tools is a union, but only sometimes. The default is the union of the used skills' allowed-tools. There is one rule that is easy to get backwards: a skill with no allowed-tools is unrestricted, so if any input is unrestricted, the union is unrestricted too. Taking the union of only the skills that declared a list would quietly narrow permissions the composed skill is supposed to have. You can always override explicitly:

compose:
  reviewer:
    use: [code-review, testing]
    allowed-tools: [Read, Grep]

Nesting works, cycles do not. A compose entry can use another compose entry, resolved recursively. Cycles are rejected when the manifest is parsed, not when it is installed, so you get the error at the point where you made the mistake.

It is a build product

The generated SKILL.md carries provenance comments marking it as generated, and it gets its own integrity hash in the lockfile:

compose:
  reviewer:
    use: [code-review, testing]
    integrity: sha256-...

That hash is what makes skillfold check useful for composed skills. Bump code-review with skillfold update, and the composed output changes, and the hash changes, and CI tells you the lockfile needs refreshing. The composition is not a one-time scaffold you generate and then own forever. It is derived state, and the tool knows it.

This repository dogfoods that, which is how we found the sharp edge: a composed skill's hash depends on its inputs, so any change to an upstream skill means a lockfile refresh even though nothing in the manifest changed. That is correct behavior, and it is also the kind of thing you only notice by running your own tool against your own config in CI.

When not to compose

Composition concatenates instructions. It does not summarize them, resolve contradictions between them, or shorten them. Two 3000-word skills compose into a 6000-word skill, and a 6000-word skill is a real cost in every request that loads it.

The cases where it earns its keep are the ones where the combination is genuinely how you work: review-plus-testing, research-plus-writing, a house style rule appended to several task skills. The cases where it does not are the ones where you are composing to avoid deciding which skill you actually want.

If you find yourself composing four skills to cover a workflow, the honest fix is usually to write one skill for that workflow. Composition is for combinations that are real but not worth maintaining by hand.

Reference

The full set of options is in the manifest reference: use, description, and allowed-tools, and that is all of them. It is a small feature on purpose.

Open .claude/skills on any machine that has been doing real work for a month. You will find a dozen directories. Some were written by hand. Some were pasted out of a blog post. Some were copied from a teammate over Slack, then edited in place because the original did not quite fit. At least one is a stale copy of something that has moved on three versions upstream.

Now answer these questions about that directory:

• Where did each skill come from?
• Which version is it?
• Has anyone edited it since it arrived?
• Is your teammate running the same bytes?

You cannot answer any of them from the filesystem, because none of that information is written down anywhere. The directory is the only record, and the directory records only its current contents.

This is the exact problem node_modules had before package.json, and that node_modules still has without package-lock.json. We solved it in 2010. The solution is not novel and it does not need to be: a manifest says what you want, a lockfile says what you got, and one command makes the filesystem match.

The manifest

skillfold.yaml is a mapping of names to sources. That is nearly all of it.

skills:
  commit-helper: ./skills/commit-helper
  frontend-design: github:anthropics/skills/skills/frontend-design@v1.2.0
  planning: npm:skillfold/planning@2.0.0

Three source kinds cover where skills actually live today. A local directory, for the skill you are actively writing. A directory in a GitHub repo, for the ninety percent of skills that are published as "here is a folder in my repo". An npm package, for skills that want versioning and discovery.

The name on the left is the installed directory name, not a property of the skill. If upstream calls it frontend-design and you want it at design, you rename the key. Skillfold rewrites the frontmatter name in the installed copy to match, changing that one line and nothing else. Renaming a skill stops being a file operation and becomes a diff.

The lockfile

skillfold install resolves every source and writes skillfold.lock next to the manifest:

lockfileVersion: 1
skills:
  frontend-design:
    source: github:anthropics/skills/skills/frontend-design@v1.2.0
    resolved: github:anthropics/skills/skills/frontend-design@8f3a9c1e...
    integrity: sha256-...

Two things are recorded that the manifest cannot express. resolved is the full commit SHA that v1.2.0 pointed at when you installed. integrity is a sha256 over every file in the skill directory.

The resolved field is what makes installs repeatable. Tags move. Branches move. latest moves by definition. Once a skill is in the lockfile, install reuses the pin and never re-resolves it, even for a moving ref. The only things that move a pin are skillfold update, or you editing the source string in the manifest. This is the same contract npm has, and it matters more here than it does for libraries: a skill is a prompt, and a prompt that silently changes underneath you changes your agent's behavior with no stack trace to show for it.

The integrity field is what makes drift visible. It hashes the content, not the metadata, so it catches the case the SHA cannot: someone edited the installed copy.

Making the filesystem match

$ skillfold install
  + commit-helper            ./skills/commit-helper
  + frontend-design          github:anthropics/skills/skills/frontend-design@v1.2.0 -> 8f3a9c1
  + planning                 npm:skillfold/planning -> 2.0.0

3 installed, 0 unchanged -> .claude/skills
lockfile: skillfold.lock

On a fresh clone, skillfold install --frozen is the CI mode: it refuses to run if the manifest and lockfile disagree, and it verifies every content hash before writing anything. It is npm ci, for the same reasons.

The offline half of that is skillfold check, which verifies that the manifest, the lockfile, and the files actually on disk all agree. No network, nonzero exit on drift, so it works as a build step:

- uses: byronxlg/skillfold@main

Now "which version of that skill is the agent running" has an answer that a build can enforce.

The part that stops people

The objection I hear most is that this is a lot of ceremony for some markdown files. It is worth being precise about what the ceremony buys, because the answer is not "correctness" in the usual sense. Nothing crashes if a skill drifts.

What it buys is the ability to reason about a change. When an agent starts behaving differently than it did last week, the search space is your code, your prompt, the model, and your skills. Three of those four are already under version control. Making the fourth one a build product from a committed manifest removes it from the search space entirely, or points straight at it.

What skillfold refuses to do

One design constraint is worth stating because it is what makes adoption cheap: skillfold only touches directories named in its lockfile.

Hand-authored skills sitting next to managed ones are never overwritten and never pruned. You can adopt skillfold for two skills in a directory of fifteen, and the other thirteen are exactly as untouched as they were before. There is no all-or-nothing migration, and no moment where a tool you just installed deletes work you did not back up.

Nothing executes skill content, either. Skillfold copies files and hashes them. It is a fetch-and-place tool, not a runtime.

Start small

npx skillfold init
npx skillfold add github:anthropics/skills/skills/frontend-design
npx skillfold install

Commit skillfold.yaml and skillfold.lock. That is the whole workflow. Everything else in the tool is a consequence of those two files existing.