melon

A dependency manager for agentic markdown — skills, agents, and prompts for your AI tools.

Installation · Quick Start · Why melon? · How it works · Manifest Reference · Commands

What is melon?

Melon manages markdown-based packages that AI coding assistants read as context. It resolves dependencies from GitHub, fetches them into a local cache, and places them into your agent's expected directory (e.g. .claude/skills/) so they are available immediately.

Installation

📦 Global install

npm install -g @playsthisgame/melon

🐹 Go

go install github.com/playsthisgame/melon/cmd/mln@latest

Requires Git to be available on your PATH.

Quick Start

1. Initialize a project

mln init

This creates a melon.yml manifest and the .melon/ cache directory. You'll be prompted for a package name, type, and which AI tools you use.

2. Add a dependency

Edit melon.yml directly:

dependencies:
  github.com/playsthisgame/skills/agentic-spec-dev: "^1.0.0"
  github.com/anthropics/skills/skills/skill-creator: "main"

Dependency names are GitHub paths. You can use:

• A full repo: github.com/owner/repo
• A monorepo subdirectory: github.com/owner/repo/path/to/skill
• A GitHub web URL: github.com/owner/repo/tree/main/path/to/skill (the tree/<branch>/ is stripped automatically)

Versions can be a semver constraint (^1.2.0, ~2.0.0, 1.0.0) or a branch name ("main").

3. Install

mln install

Melon resolves each dependency, fetches it via sparse git checkout, writes melon.lock, and places skills into your tool directories.

  resolving github.com/playsthisgame/skills/agentic-spec-dev (^1.0.0)...
  fetching github.com/playsthisgame/skills/agentic-spec-dev@1.0.0...
  + github.com/playsthisgame/skills/agentic-spec-dev@1.0.0
  linked github.com/playsthisgame/skills/agentic-spec-dev -> .claude/playsthisgame/agentic-spec-dev

How it works

melon.yml          — declares your dependencies and target AI tools    ← commit
melon.lock         — pins exact versions, git tags, and content hashes ← commit
.melon/            — local cache; one directory per dep@version        ← commit
.claude/skills/    — symlinks into .melon/ created by mln install      ← commit

Skills are fetched once into .melon/ and symlinked into the configured tools directories.

Manifest Reference

# melon.yml

name: my-agent
version: 0.1.0

description: "My coding agent"

dependencies:
  github.com/anthropics/skills/skills/skill-creator: "main"
  github.com/playsthisgame/skills/agentic-spec-dev: "^1.0.0"

# tool_compat drives where mln install places skills.
# Melon knows the conventions for each agent automatically:
#   claude-code    -> .claude/skills/
#   cursor         -> .agents/skills/
#   windsurf       -> .windsurf/skills/
#   roo            -> .roo/skills/
#   ... (and more)
tool_compat:
  - claude-code

# outputs is optional. Use it to override the automatic placement paths.
# outputs:
#   .claude/skills/: "*"

tags: []

Supported AI tools

Commands

mln init

Scaffold a new melon.yml and create the .melon/ store directory.

mln init
mln init --yes        # accept all defaults (for scripting)
mln init --dir ./app  # initialize in a different directory

mln install

Resolve dependencies, fetch them into .melon/, write melon.lock, and symlink skills into tool directories.

mln install
mln install --frozen    # fail if melon.lock would change (useful in CI)
mln install --no-place  # fetch and lock only — skip placement into agent dirs

mln add

Add a dependency to melon.yml and run install. If no version is specified, the latest semver tag is resolved automatically.

mln add github.com/playsthisgame/skills/agentic-spec-dev          # resolves latest tag → ^1.2.0
mln add github.com/playsthisgame/skills/agentic-spec-dev@^1.0.0   # explicit constraint
mln add github.com/playsthisgame/skills/agentic-spec-dev@main     # branch pin

mln remove

Remove a dependency from melon.yml, unlink its agent symlinks, and delete its .melon/ cache entry.

mln remove github.com/playsthisgame/skills/agentic-spec-dev

Lock file

melon.lock is generated by mln install and should be committed to version control. It pins the exact version, git tag, repo URL, subdirectory, and a SHA-256 tree hash for each dependency.

generated_at: "2025-03-31T12:00:00Z"
dependencies:
  - name: github.com/playsthisgame/skills/agentic-spec-dev
    version: "1.2.0"
    git_tag: v1.2.0
    repo_url: https://github.com/playsthisgame/skills/agentic-spec-dev
    subdir: ""
    entrypoint: SKILL.md
    tree_hash: "sha256:abc123..."
    files:
      - SKILL.md

Use --frozen in CI to ensure the lock file is always up to date:

mln install --frozen

Why melon?

As AI coding assistants become more capable, teams are building and sharing libraries of skills. Without a proper dependency manager, keeping these skills consistent across developers, environments, and CI becomes a manual, error-prone process.

Melon gives you a single source of truth. Define all the skills your project needs in one melon.yml file, commit it alongside your code, and every developer (and your CI pipeline) gets exactly the same set of skills with a single mln install.

Skills are versioned, not just copied. Melon pins exact versions, git tags, and SHA-256 content hashes in melon.lock. If a skill author publishes a breaking change, your team won't silently pick it up, you'll see the diff in the lock file and upgrade intentionally. This means you can trust that the skill running in CI today is the same one that ran last week.

It works naturally with CI. Run mln install --frozen in your pipeline to fail fast if the lock file is out of sync with the manifest. No surprises, no drift. Because .melon/ and the generated symlinks are committed to the repo, CI doesn't even need network access to place skills, everything is already there.

Works across your whole team and all your tools. List the AI tools your project uses under tool_compat and melon places each skill into every agent's expected directory at once. One manifest, one install command, every agent ready to go.

Why melon instead of npx skill installers?

Many agent skill collections ship a one-liner like npx install-skill <name> that copies files into your project. Melon takes a different approach:

License

MIT