Project Skills: let a Paca project register Agent Skills (agentskills.io format) and distribute them to any compliant client

[gorlix]

Project Skills: let a Paca project register Agent Skills (agentskills.io format) and distribute them to any compliant client

The idea

I run more than one coding agent against the same project — Claude Code,
and others that also speak the Agent Skills format (agentskills.io). Right
now each one keeps its own copy of the same skills, on whichever machine I
happened to write them on. There's no single place that owns "these are
this project's skills," so keeping them in sync across agents and machines
is manual and easy to forget.

Paca already sits at the center of the project (tasks, docs, and now — via
its MCP server and the ACP bridge — the agents themselves connect to it).
It's the natural place to also hold the project's skills as the one source
of truth, and let whichever agent is working on the project — regardless
of which one, mine or a teammate's — pull the same skills in its own
native format. That's the core of what's below.

Context

scripts/install-paca-skills.sh already does something valuable: skills
are stored once (SKILL.md — YAML frontmatter + markdown body), served from
a running Paca instance's API (GET /api/v1/skills for bundled skills, and
a plugin manifest's skills.baseUrl + skills.names[] for
plugin-contributed ones), and a single installer distributes that content
to Claude Code, Gemini CLI, Cursor, and any AGENTS.md-reading tool.

What the script actually installs today, though, is a re-shaped copy per
target — frontmatter stripped for Claude Code/Cursor, re-packed into TOML
for Gemini CLI, merged into an AGENTS.md section for the rest. That made
sense as SKILL.md's fields and progressive-disclosure conventions
(scripts/, references/, assets/) weren't yet something every target
could be assumed to understand.

That assumption is now out of date. SKILL.md is a formal open standard —
agentskills.io, originated by Anthropic, opened
as a public spec, with a directory shape (SKILL.md + optional
scripts//references//assets/), a defined frontmatter (name,
description, license, compatibility, metadata, allowed-tools),
and a validator (skills-ref validate). Both Gemini CLI and Cursor are
listed as spec-adopting clients today, alongside Claude Code, VS Code,
GitHub Copilot, ChatGPT/Codex, JetBrains Junie, Goose, and dozens more. For
any client that already speaks the spec, converting a skill into something
else and handing over a lossy copy is no longer necessary — and it's the
lossy part that actually matters: today's conversion drops scripts/,
references/, and assets/ entirely, since the current targets
(TOML prompt, flat .md, an AGENTS.md section) have no notion of a skill
directory. On a spec-compliant client, that content should never need to
be dropped.

Proposal

1. Distribute skills as real spec-shaped directories to any client that
   already reads them, instead of always re-shaping into a lossy
   single-file copy. Concretely: for a target whose own convention is a
   skills directory (e.g. Claude Code's ~/.claude/skills/<name>/, and
   whatever discovery path Gemini CLI/Cursor use for spec-compliant
   skills), copy the skill folder as-is — SKILL.md plus scripts/,
   references/, assets/, intact. Keep today's flattening path only for
   genuine single-file targets that have no directory-skill support at
   all.
2. Let a Paca project hold its own skills, not just Paca's bundled set
   and admin-installed plugins. A project's skills are exactly
   agentskills.io-shaped content — same frontmatter, same optional
   subdirectories — associated with a project instead of the Paca instance
   globally.
3. Ship this as a plugin, using the extension point that already
   exists for this exact purpose: a plugin manifest's skills.baseUrl +
   skills.names[] is already fetched and installed by
   install-paca-skills.sh today (<baseUrl>/<name>/SKILL.md). A "Project
   Skills" plugin that serves each registered skill's full directory at
   that path needs no core API or database change to be installable
   right now — the existing plugin-skills pipeline already knows how to
   consume it. Point 1 above (spec-shaped, non-lossy distribution) is the
   one piece that benefits everyone regardless of where the skill comes
   from, bundled or plugin, so it's worth doing independently of the
   plugin.

Why this fits the existing design

Point 3 needs zero core changes — it's built entirely on the plugin
extension point your own CONTRIBUTING.md lists as an open discussion area.
Point 1 is a bug-fix-shaped change to code that already exists
(install_one_skill in install-paca-skills.sh), not a new mechanism.

Open questions

• What's the actual per-client discovery path for a spec-compliant
  directory skill on Gemini CLI and Cursor today (as opposed to their
  single-file command formats, which the script currently targets)? Worth
  confirming against their docs before assuming a 1:1 swap.
• Should a plugin-provided/project skill be able to shadow a bundled skill
  of the same name, or must names be globally unique?
• For a skill whose scripts/ needs execution rather than just being
  read — does that require anything beyond what already exists for
  plugin-contributed skills?

Happy to open two separate, smaller PRs matching points 1 and 2/3 above
(keeping each focused on one concern, per the PR checklist) — wanted to
check the direction first, especially on the open questions, before
writing code.

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔}

[gorlix]

Happy to put time into this myself if the direction above sounds right — could start with the plugin (point 3), since it needs no core changes and I could get something working against a real Paca instance to validate the approach before touching anything upstream. Let me know if you'd rather I wait for a maintainer steer on the open questions first, or just go ahead and open a draft PR to make the shape concrete.

[pikann]

Thanks for the feedback!

Right now, Paca only manages skills for standard agents, while ACP agents (like Claude Code, Gemini CLI, and Cursor) handle skills on their own servers. However, we are planning to support the agentskills.io format and improve handling for skill scripts in upcoming versions.

Your proposal is very helpful and aligns with where we want to take this. Thanks again!

[gorlix]

Good to know re: standard vs ACP agents — makes sense given how the bridge works. Glad the agentskills.io direction is already on your roadmap.

Should I go ahead and open a draft PR for the plugin piece (point 3 above) to make the shape concrete, or would you rather land the agentskills.io support you mentioned first and have Project Skills build on top of that?

[pikann]

Feel free to open a PR if you'd like to work on this. Thank you!

[gorlix]

Opened a first cut of the plugin piece (point 3): https://github.com/gorlix/paca-plugin-project-skills

CRUD for a project's own SKILL.md-format skills via the plugin's own routes (/skills, /skills/:name), backed by a project-scoped DB table. Unit-tested with plugintest, and I cross-compiled the backend for wasip1/wasm to confirm it actually builds for the runtime.

One thing worth flagging explicitly: I kept every skill name on the ecosystem's paca- convention, but did not wire this into the manifest's skills.baseUrl/names mechanism. That mechanism is populated once at install time from a tarball extracted to disk by the Installer, and a WASM plugin has no filesystem access at runtime — so there's no way to keep it in sync with skills a project edits live. Details (and the reasoning) are in the README. Happy to hear if you see a way to bridge that gap I'm missing, or if a future host capability is planned that would change this.

Haven't touched point 1 (non-lossy install-paca-skills.sh distribution) yet — keeping this PR to one concern per your CONTRIBUTING guidelines, will look at that separately.

[gorlix]

Update: both pieces are now open for review.

Point 3 (plugin) — gorlix/paca-plugin-project-skills, v0.1.0 release, marketplace listing: Paca-AI/paca-plugins#31. CRUD for a project's own SKILL.md-format skills over the plugin's own routes. Tested with go test -race (86.5% coverage), golangci-lint, a real TinyGo wasm build, and — importantly — a full CRUD cycle against a real running instance (docker compose -f deploy/docker-compose.dev.yml). That live pass caught a real bug unit tests missed: manifest routes need a :projectId path segment for the host to resolve project scope at all (fixed). Also confirmed empirically that a skill created here does not leak into GET /api/v1/skills, which is expected given the architecture (details in the plugin's README).

Point 1 (non-lossy distribution) — #454, against scripts/install-paca-skills.sh. Verified directly against Claude Code's, Gemini CLI's, and Cursor's own current docs that all three now natively read the agentskills.io SKILL.md folder format — so the script now writes it verbatim (frontmatter included) for all three, instead of flattening. Also fixed a jq -r vs jq -j fidelity bug the change surfaced (an invisible extra trailing newline that only mattered once copying went byte-for-byte verbatim). Verified with a new CI job (fixture HTTP server, not a stubbed curl) and manually against the same live instance, diffed/sha256-compared against the real API response.

Neither PR closes this issue on its own — #454 doesn't touch the plugin, and the plugin isn't a PR against this repo. Happy to open a small follow-up issue about a docs/code mismatch I ran into along the way (WASM plugin signing is documented as enforced in a few places but isn't implemented anywhere in services/api) if that'd be useful — let me know.