Super unclear how the global scope works in OpenPackage, plus some feedback

[PaulRBerg]

From the README:

Installs to home dir, ex: ~/.cursor/, ~/.opencode/
opkg install github:anthropics/claude-code -g

How does opkg know where to put the package I want to install?

Also, if the goal is solve the scattered-files problem, how does OpenPackage achieve that if it installs files in so many directories (global directories, at any rate)?

When I first heard about OpenPackage, my expectation was that you were creating a new standard global directory, e.g. ~/.opkg, in which all plugins live. The format would be either a custom one that you generate on-the-fly, or Claude plugin's format (because it's the most popular one). Then, additional global ~/.cursor and ~/.codex directories would either by symlinked or cloned/recreated to match their specific formats.

So unfortunately, opkg isn't super helpful as it's currently built. The ecosystem won't go through the hassle of adding openpackage.yml files to their plugins if all they get is a multitude of agent directories.

Tip

Take a look at skills/add-skill CLI built by Vercel. They are on the right track as they're putting all skills under ~/.agents/skills, and then all other agent directories simply symlink into ~/agents. Maybe you could also use ~/.agents for OpenPackage? And then, recreate directories for custom stuff.

[hyericlee]

Hmm OpenPackage actually does what you have described, but it just skips installation to .openpackage/ dir.

What Vercel Skills does is it installs to ~/.agents/ and then individually adds symlink files/dirs to ~/.cursor/, ~/.opencode/, ~/.claude/, etc.
What OpenPackage does is it converts plugins to .openpackage/ format in memory, and installs straight to ~/.cursor/, ~/.opencode/, ~/.claude/, etc.

It tracks installs Claude Plugins as "dependencies" (auto-created) under ~/.openpackage/openpackage.yml and ~/.openpackage/openpackage.index.yml. These two files alone provide enough information for the CLI to know which files are installed to where.

So they actually use essentially the same logic behind the scenes, sans writing files to ~/.openpackage/ (this seems redundant to me).

Regarding

The ecosystem won't go through the hassle of adding openpackage.yml files to their plugins if all they get is a multitude of agent directories.

This isn't actually necessary, OpenPackage CLI will auto detect .claude-plugin/plugin.json, you only need to use openpackage.yml if you're authoring an OpenPackage native format package.

Do let me know if I misunderstood something!

[PaulRBerg]

Thank you for the clarifications @hyericlee. It's clearer now. Some suggestions/feedback/questions:

1. I don't find it redundant to write those files to ~/.openpackage. When I use a tool like this, I want determinism and version control. For example, I've recently created a dot-agents repo to store all of my agent skills there (installed via npx skills add). I'd like to have a similar repo for OpenPackage, but I can't do that if OpenPackage doesn't generate the files.

• Or maybe keeping the openpackage.yml and openpackage.index.yml files would suffice?

2. How about renaming the global dir to ~/.opkg to match the CLI name?

P.S. as discussed in #12, an ASCII diagram in the README would go a long way.

[hyericlee]

Yeah, the beauty with OpenPackage is that it's essentially a package/dependency manager itself.

If you are installing plugins, each plugin you install will be stored as "dependencies" in the .openpackage/openpackage.yml file, this achieves the determinism and version control part and you would only need to keep the openpackage.yml file, drop it into any codebase, and run opkg install (very similar to package.json with npm install).

But I think I understand your use case though when you mentioned I'd like to have a similar repo for OpenPackage, but I can't do that if OpenPackage doesn't generate the files., that's a valid concern. I need to think about this a bit to see how I can work this out, it's a bit tricky.

(BTW I'm currently finalizing the next major update to OpenPackage, which will allow you to install individual Skills just like Vercel Skills and list them as dependencies, instead of bulk installing everything in a Claude Plugin.)

[hyericlee]

As for renaming to .opkg/, the backstory with this name is that openpackage namespace is already taken on npm while opkg isn't, and it's also a nice shorthand for openpackage (using openpackage install is actually valid and works). So like .opencode/, it makes more sense imo that it's using the full name of the "platform" for full clarity.

P.S. Really appreciate your feedback btw, really gets me thinking and allows me to hone in on the specific use cases and desired behaviors, so thank you!

[NatEvory]

@PaulRBerg One thing that I didn't notice at first, that really helped solidify the workflow was opkg pack for my personal skills/plugins. I keep skills that I personally created in a folder/repo, and I use opkg pack to add them to my local registry so that I can opkg install them for individual projects (I don't always want them on the global scope).

[PaulRBerg]

P.S. Really appreciate your feedback btw

You're weclome, @hyericlee! I also appreciate the quick replies. I rarely get this kind of support on GitHub!

[hyericlee]

@NatEvory That's very interesting, I actually thought nobody was using this!

I'm planning on removing opkg pack and the ~/.openpackage/registry/ actually, it has caused a lot of confusion due to it behaving differently than npm pack.

The alternative would be adding your packages under ~/.openpackage/packages/ instead. You will still be able to perform opkg install via package name (it checks the ~/.openpackage/packages/ dir), only difference is that it doesn't snapshot individual versions.

What's your full workflow when using opkg pack?