[Proposal]: Treat skills as packages — a language-agnostic manifest for skill dependency management #243

Summary

Proposes treating skills as versioned packages managed by a dedicated, language-agnostic manifest file — only the manifest gets committed, not the skill files themselves. For teams and companies needing npm-like skill management, a tool like sklz demonstrates this workflow in practice.

Problem

The current discussions around skill distribution (#81, #214) have converged on a real gap: there is no standard way to declare, share, and reproduce which skills a project depends on, without either:

• Committing the skill files directly into the repo (treating skills like vendored code), or
• Coupling distribution to a language-specific package manager (package.json, pyproject.toml, Cargo.toml).

Both approaches have friction. Vendoring skill files means every update is a manual copy-paste, diffs are noisy, and there's no concept of a version. Language-specific manifests work well for library authors shipping skills alongside their code, but they create a conceptual mismatch for the general case: not every project that uses skills is a Node project, a Python project, or a Rust project. A team with a mixed-language monorepo, a documentation repo, an infrastructure repo — all of them might want to manage skills without adopting a foreign package manager just for that purpose.

The pattern we're missing a dedicated manifest + lockfile that tracks dependencies without vendoring them.

Proposal

Introduce a skill manifest file — a small, language-agnostic JSON file that serves the same conceptual role as package.json + a lockfile, but scoped exclusively to skill management.

The core idea:

• Only the manifest is committed — not the skill files themselves.
• Skills are installed on demand from their declared sources (git repos, registries, or any source a tooling layer supports).
• Reproducibility is guaranteed by pinning to a specific version or commit hash in the manifest.
• You can reference private skills since the tool uses you git to do de pulls from the repos.

A minimal manifest could look like:

{
  "sklz": {
    "flexoki": {
      "repo": "https://github.com/AlissonSteffens/alisson-skils",
      "repoName": "alisson-skils",
      "version": "0.0.0",
      "commit": "46c4cdb",
      "installedAt": "2026-03-11T02:58:39.549Z",
      "tags": []
    }
    "react-patterns": {
      "source": "https://github.com/another-org/frontend-skills.git",
      "version": "0.9.1",
      "commit": "f4e5d6c"
    }
  }
}

The installed skills directory (e.g. .agents/skills/) would be gitignored. A collaborator cloning the repo runs a single install command to reproduce the exact same skill set.

Why not package.json?

package.json is a reasonable answer for JavaScript/Node projects — and the npm-based approach in #81 makes good sense for library authors. But:

• A repository that contains only infrastructure code, documentation, or multi-language services has no reason to have a package.json. Forcing one just to manage skills is significant conceptual overhead.
• The agentskills field proposed in RFC: Standardize npm/JavaScript Package Distribution #81 lives inside npm's resolver logic, meaning the entire npm dependency graph is involved in what is essentially a skills concern.

A dedicated manifest sidesteps all of this. It has one job. It doesn't care about your language stack.

Why not skill.json or skills.json?

The obvious naming choice would be skill.json or skills.json — but both names create a practical problem with agents.

In testing, when a file named skill.json or skills.json is present at the repo root, agents tend to consume it as the source of truth for skill content, instead of reading the actual skill files from the installed directory (e.g. .agents/skills/). The filename is close enough to SKILL.md semantically that agents treat it as an instruction source rather than a tooling artifact.

I encountered this behavior directly while building a proof of concept for this proposal (more on that below). The manifest needs a name that is clearly machine/tooling-facing, not agent-facing. Something like sklz.json or another name that doesn't pattern-match to skill content is safer in practice.

This is also a reason to be cautious about the skill.json proposal in #214 — if it becomes widespread, agents may start reading it as a skill source, which was not its intent.

Proof of Concept

I built sklz as a proof of concept for this proposal — a CLI that manages skills from git repos using a dedicated manifest file (sklz.json). It is early-stage and the name/format are not the point; the workflow it demonstrates is:

# declare a skills source
sklz repo add https://github.com/AlissonSteffens/alisson-skils.git

# install a skill — updates sklz.json
sklz install flexoki

# teammates reproduce the exact same state
sklz install

Only sklz.json is committed. .agents/skills/ is gitignored. The naming (sklz.json) was deliberately chosen to avoid the agent-consumption problem described above — a name that is unambiguously tooling metadata.

The implementation is available as a reference for what the DX and manifest format could look like, independent of whether sklz itself is adopted.

This enables companies and teams to work smarter with skills, without poluting repositories.

What This Proposal Asks

1. Acknowledge the consumer-side manifest as a missing piece in the current spec, distinct from skill.json ([Proposal]: Add skill.json as an optional package-level metadata file #214) and npm distribution (RFC: Standardize npm/JavaScript Package Distribution #81).
2. Define the concept — a language-agnostic manifest file that tracks skill dependencies by source + version, without vendoring the files.
3. Choose a name that avoids agent confusion — explicitly avoid skill.json / skills.json for the manifest, given demonstrated interference with agent behavior.
4. Leave the implementation open — the spec can define the contract (what fields the manifest must contain) without mandating a specific tool.

Open Questions

• Should the manifest format be defined in the spec, or just the concept (leaving format to tooling)?
• Is a single file enough, or do we need a manifest + separate lockfile (like npm's package.json + package-lock.json)?
• How should the spec handle conflicts between skills from different sources that share the same name?
• What naming convention avoids agent confusion while remaining intuitive for humans? (sklz.json, skills.lock, agent-skills.json?)

DISCLOSURE: Written with AI assistance. Reviewed and edited by the author.

Use case scenario at this comment