Skip to content

Per-server <bin> skills install for @Skill-registered skills is undocumented (and may not exist) #415

Description

@alexmercerpo

Describe the bug
A project that wants to ship its own skill alongside its server has no documented path. frontmcp-setup/references/frontmcp-skills-usage.md describes frontmcp skills install <name> --provider claude for the bundled catalog but never mentions a per-bin equivalent for that server's own @Skills. frontmcp-development/references/create-skill.md describes the @Skill decorator (name, description, instructions: { file }, resources: { references }) but never mentions how the registered skill becomes installable on a user's machine after the package is published — no <bin> skills install, no postinstall hook, no frontmcp skills install --from-package. create-skill-with-tools.md has the same gap. A project author looking at the skills system from either angle (the catalog CLI or the decorator) ends up with two disconnected halves and no documented bridge — and ends up hand-rolling a filesystem writer.

To Reproduce
Steps to reproduce the gap:

  1. frontmcp skills read frontmcp-development create-skill — search for skills install. Zero hits.
  2. frontmcp skills read frontmcp-setup frontmcp-skills-usage — search for @Skill. Zero hits.
  3. frontmcp skills install --help — only operates on the framework catalog (selectors are name, --all, --tag, --category); there is no --from-package, --from-server, or similar that would pick up @Skills declared in a project's source.
  4. As a project author, end up either (a) hand-rolling a filesystem writer (what example did at src/skills/example-project/installer.ts) or (b) assuming custom skills are MCP-discovery-only and unavailable to Claude Code's filesystem-based loader.

Expected behavior
There should be a documented, supported way to install a project's own @Skill-registered skills onto a user's machine. Two equally fine shapes:

Shape A — per-bin subcommand inherited from the framework: Every FrontMCP-built bin inherits a skills install subcommand that operates on that server's own @Skill registrations:

@Skill({
  name: 'example-project',
  description: 'Use when editing files inside a example project folder...',
  instructions: { file: './SKILL.md' },
  resources: { references: { dir: './references' } },
})
export default class ExampleProjectSkill extends SkillContext {}
# Single skill, single provider
example skills install example-project -p claude

# All @Skills the server registers
example skills install --all -p claude

# From a fresh checkout, no global install
npx example skills install --all -p claude

Most ergonomic option — users already learn <framework> skills install from the catalog flow.

Shape B — frontmcp skills install --from-package <pkg>: The framework CLI gains a flag that resolves a published package's exported @Skills and installs them:

frontmcp skills install --from-package example --all -p claude
frontmcp skills install --from-package example example-project -p claude

Either shape closes the gap. Shape A requires per-bin CLI plumbing; Shape B keeps everything inside the frontmcp bin.

Screenshots
N/A — CLI / framework issue, no UI.

Environment (please complete the following information):

  • OS: macOS (Darwin 25.3.0)
  • Node: v24.x
  • Packages: frontmcp 1.2.1, @frontmcp/sdk 1.2.1

Additional context

Workaround: we shipped a hand-rolled installer at src/skills/example-project/installer.ts that writes the SKILL.md content directly into .claude/skills/example-project/ on server startup. It works, but it duplicates logic the framework already owns (provider-dir resolution, write/skip on drift, banner stamping, override folder convention).

Notes:

  • The catalog has 11 router skills today — every one of them is installed via frontmcp skills install <name> --provider claude. The mental model ("install puts SKILL.md on disk for Claude Code") is already established; it just needs to be extended to a project's own @Skills.

Acceptance signals:

  • A code+CLI example showing a project's own @Skill being installed (via Shape A or Shape B).
  • A note in create-skill.md pointing at the install flow.
  • A note in frontmcp-skills-usage.md clarifying that project-defined skills have a documented install path, not just the catalog.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions