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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions