Share the Skill, Keep the Meaning

I was excited about sharing skills across projects. Someone works out a useful way to review a specification, investigate a failure, or check a piece of work. They write it down. The next person starts with that knowledge and has a chance to improve it.

That is a generous possibility for human connection within AI development. A project can contribute more than its finished software. It can contribute some of what people learned while making it. I want to keep that joy of discovery while working with these tools: finding an approach I would not have thought of, recognizing the care someone put into it, and seeing what we might learn by trying it somewhere new.

Then I found myself deciphering how each harness wanted those skills formatted. The harness is the software around the model: the part that discovers instructions, provides tools, and manages how the work runs. I wanted to learn from someone else's process. First, I had to learn the receiving tool's preferences about the packaging.

This is where our new project, Harnessmith, started to make sense to me.

The frustration goes beyond untidy files. A skill that is not discovered may leave the agent improvising a process someone already documented. Instructions loaded too eagerly consume context before they are useful. A missing reference can lead to another search, another explanation, another attempt. Those failures can spend tokens and human attention together. I do not have a measured total for that waste, but the friction was enough to make the original pleasure of sharing feel like integration work.

There is already a common foundation. The Agent Skills specification defines a skill around a SKILL.md file, with metadata and optional supporting resources. Its loading model separates a short description from the full instructions and from material needed only for a particular task. It also acknowledges that support for the experimental allowed-tools field can vary between implementations. Shared syntax leaves some practical differences to resolve.

Anthropic's original account of skills describes packaging and sharing procedural knowledge. That remains the part I care about: making a useful practice available to someone who did not happen to be there when it was learned.

Harnessmith's current alpha audits a canonical skill and compiles packages for generic, Cursor, Claude, and Codex targets. Keeping one source gives us somewhere to improve the practice without maintaining several independently edited versions of it. The target adapters take responsibility for the differences they know how to represent.

They also have to admit when they cannot. In the current adapter contracts, a source instruction that disables user invocation can be represented by the Claude target. The Cursor target rejects that requirement. Quietly deleting the field would produce a tidier package while changing how the skill is available. A useful compiler has to be willing to stop there.

The same care applies to shortening instructions. Harnessmith can move explicitly selected sections into reference files, preserving their original text and leaving a required read instruction behind. It records transformations and hashes so the result can be inspected and verified. That gives a reviewer something more concrete than a rewritten document that merely looks equivalent.

It also creates a tempting accounting mistake. Moving a paragraph into another file does not save its tokens if the agent still has to read it every time.

The checked-in specification-analysis example makes the difference visible. Its generated manifest records a source instruction file of 12,263 characters and a compiled root of 6,416 characters: about 48% smaller. Include the references required on the normal path and the total becomes 9,747 characters, about 21% below the source. I checked the package with Harnessmith's independent verifier; its recorded metrics and regeneration checks passed.

Those are useful measurements with a narrow meaning. The project's token estimates divide character counts by four and round up. They are not measurements from a model tokenizer or a bill. This example also uses an opt-in transformation that moves extension-hook fallback instructions behind a conditional path. That conditional loading is what makes a smaller normal path possible; simply extracting mandatory sections would not do it.

All packaged instructions together are larger than the original, even before counting the generated resolver script. An actual run might load the fallback, inspect the script, or need extra tool calls. The evaluation guide explicitly separates these static estimates from runtime tokens, latency, and model quality. We should preserve that distinction when talking about the project's benefits.

The immediate value is easier to state: a repeatable way to adapt a skill, inspect what changed, catch some incompatibilities before a run, and keep improvements attached to a common source. That can lower the effort of trying someone else's approach. It can also make contributing back more practical. A correction discovered in one project has a place to go besides a private copy that quietly drifts away.

There is plenty left to improve. I want live comparisons of the canonical and compiled skill on the same tasks, with model and harness versions recorded. Did the right skill activate? Were the required instructions actually read? Did the work succeed, and how much context, time, and correction did it take? Giuseppe Destefanis's preprint on authoring agent skills argues for behavioral evaluation alongside software-engineering discipline. It supports the direction of that work; it does not establish Harnessmith's results.

Adapter knowledge also needs a maintenance process as harnesses change. A compatibility claim should say which version was checked and which behaviors remain uncertain. Better diagnostics could explain why a section belongs in the main instructions, or why moving it would hide information needed to decide when to load it. And shared recipes could carry their source version and rationale, so the next person can understand a transformation before adopting it.

Those are directions I want us to pursue, rather than benefits I can claim today. The experiment I most want to see is ordinary: take a useful skill from one project, use it in another, record the points of confusion, and return the corrections to the shared source. Measure the tokens, certainly. Also record how much explaining the person receiving it still had to do.

If you have a skill you have wanted to bring into another project, check out Harnessmith and try the README's five-minute workflow with it. See what carries over, where you get stuck, and what you discover along the way. I'd love to hear how it works for you—and what we can learn from your experience.