14 Commits
Author SHA1 Message Date
Rusty Shackleford e969ebcfb0 fix(mcp): close Skills conformance gaps with directory reads and resource metadata (#905)
* feat(mcp): support Skills directory reads and metadata listing

Expose accepted skill directories and SKILL.md metadata so MCP hosts can
browse served packages without guessing manifest filenames. Reuse catalog
selection and refresh boundaries, including empty directories and stable
pagination, and normalize strict frontmatter for YAML 1.2 Core readback.

Add regressions and a pinned official conformance runner, and update the
runbook and MCP references to describe the browsing contract.

Refs #895

* fix(mcp): preserve supporting file MIME types in directory listings

Record UTF-8 classification from the same bounded bytes used for package
digests so directory metadata agrees with resource reads for extensionless
and unknown-extension text. Reuse the existing bounded reader without
adding listing-time payload reads or changing package limits.

Share pagination with skills/list, trust the SDK's typed request boundary,
and repair the pagination regression to detect stale catalog snapshots.

Refs #895

* fix(mcp): stream supporting file metadata inspection

Buffering supporting files during catalog refresh allocated with asset size.
Restore one bounded stream for digest, size and UTF-8 classification, retaining
at most three incomplete rune bytes and consuming invalid text through EOF.
Preserve the existing same-file checks, package caps and SKILL.md byte reader.

Keep real package-load benchmarks and strengthen the existing MIME fixtures
for split runes and bytes after invalid sequences. Use one first-match sed
command for the conformance URL without a truncated pipeline under pipefail.

Scoped packages, focused race tests, vet, shell syntax/shellcheck and all 45
pinned official checks pass. Allocation stays near 48 KB for 64 KiB and 8 MiB
assets; multibyte UTF-8 validation still costs CPU versus digest-only loading.

* test(mcp): consolidate directory and frontmatter coverage

Check every directory continuation URI so a duplicated middle entry cannot
hide a missing resource. Keep the existing before/after-cursor refresh cases.

Merge nested-skill acceptance fixtures in the catalog owner, preserving all
skill-count, skip-warning and directory assertions across configured and
targetless cases. Move directory capability coverage to initialization and
merge scalar, alias and rejection cases under the existing parser test.

Give cached-page benchmark skills names that match their URI directories.
Narrow tests, benchmark smoke and vet pass; duplicate-result and stale-catalog
mutations both fail, then restored source passes. Production is unchanged.
2026-11-15 00:21:35 +08:00
Willie 1c7cf1259c fix(mcp): read only the file the link check saw
Files were checked with Lstat and then opened by path, so one replaced
by a link in between was followed and published. Each read now checks
that the opened file is the one Lstat described, and skips the skill
otherwise.
2026-10-06 16:59:50 +08:00
Willie db3840b031 fix(mcp): keep an edited serve command's -p and reject padded names
Changing the served target rebuilt the command from the dashboard scope,
so editing `skillshare mcp serve -p --target old` in the global
dashboard silently dropped -p; the command now keeps its own flag.

Skill names were trimmed before validation, so a name and directory
padded with the same spaces passed. Names are no longer trimmed, and the
spaces fail the character rule.
2026-10-06 16:36:51 +08:00
Willie a6166ed27b fix(mcp): match a skill's name to its directory exactly
The name rules are checked after NFKC, but the directory is the skill
path's last segment, which the Skills extension requires to equal the
name. A fullwidth abc in directory abc passed and was published under
a URI that did not match its name; the comparison is now exact.
2026-10-06 16:18:03 +08:00
Willie 7980c08a2d refactor(mcp): read each skill file once in skillpkg.Load
The review fixes left the per-file size and digest split across two
packages: a stat-based budget in the walk, a second bounded read in the
catalog, a SKILL.md special case hashed once per file, and the digest
format written out three times. skillpkg.Load now reads every file once
within one package budget and records its digest and size, so the
catalog only maps them, and skillpkg.Digest is the one digest format.

Also: Build settles skills in one deepest-first loop, the skills/list
cursor uses sort.Search, ParseFrontmatterMap splits the file once, mcp
serve names each value flag once, and the migration report is not
called twice in main.
2026-10-06 16:16:25 +08:00
Willie a8edbc715f fix(mcp): follow the reference validator for names and bound SKILL.md reads
The Agent Skills reference validator accepts lowercase Unicode letters
and digits after NFKC normalization and counts the 64-character limit in
characters, so names such as 技能-審查 or café were skipped although they
are valid. ValidateName now applies the same rules. sync's target naming
shares it and accepts those names too. golang.org/x/text becomes a
direct dependency at the version already in the module graph.

SKILL.md was size-checked and then read whole, so a file that grew in
between was still read into memory; the read itself now stops past 16 MiB.
2026-10-06 15:57:02 +08:00
Willie 97844aa7f8 fix(mcp): hash SKILL.md from the bytes its frontmatter came from
SKILL.md was parsed, then read again to hash, so a save in between paired
old frontmatter with the new file's digest and size, and hosts that
compare frontmatter against the file rejected the skill. The digest now
comes from the parsed bytes; a later read of a changed file is refused
until the next refresh.
2026-10-06 15:46:48 +08:00
Willie 6285e490e6 fix(mcp): reject an empty compatibility
The Agent Skills format requires a compatibility value, when present, to
hold 1 to 500 characters, so an empty one is skipped like an overlong one.
2026-10-06 15:39:06 +08:00
Willie 78857ad6f1 fix(mcp): skip a linked SKILL.md and an indented opening delimiter
The manifest lists no links, so a skill whose SKILL.md is a link was
published without its own file and could not be read. It is now skipped
with a warning.

The Agent Skills reference parser requires the file to begin with ---
exactly, so an indented delimiter no longer opens frontmatter. A CRLF
file still parses.
2026-10-06 15:16:35 +08:00
Willie b5bad20e50 fix(mcp): serve only bytes that match the listed digest
The catalog is reused for up to 5 s, so a file edited after skills/list
was read live and failed the client's digest check. A read now hashes
what it returns and reports the file as changed when the digest no
longer matches; the next refresh lists it again.

Also: a BOM-prefixed SKILL.md is parsed from the stripped bytes instead
of being skipped, a non-text compatibility is rejected rather than
treated as absent, and an oversized SKILL.md is skipped before it is
read into memory.
2026-10-06 15:09:34 +08:00
Willie d13e03adfc fix(mcp): skip skills whose compatibility exceeds the format limit
The Agent Skills format caps compatibility at 500 characters, and hosts
that validate entries reject longer ones, so serve skips such a skill
with a warning, as it does for an overlong description.

metadata is deliberately not held to the format's string values: lists
there are common, tool-fallback clients read them fine, and skipping
those skills would hide them from every client to satisfy a few.
2026-10-06 15:00:35 +08:00
Willie 96593f9411 fix(mcp): quote the served target and cap skill descriptions
A managed project's name may hold spaces, so the Skillshare tab built
`--target my app@claude`, which the save path split into two words and
serve rejected as an unknown target. The command is now joined from
quoted words.

The Agent Skills format caps a description at 1,024 characters, and
hosts validating entries reject longer ones, so serve skips such a skill
with a warning instead of advertising it. The docs list every skip reason.
2026-10-06 14:47:41 +08:00
Willie fd4f499be7 fix(mcp): keep serve digests and stdout trustworthy
Size and mtime cannot prove a file is unchanged (cp -p, rsync -t), and a
stale digest makes hosts that verify digests reject the file for good,
so every rebuild hashes every file again; 1,000 skills rebuild in about
140 ms, at most once per refresh interval.

Serve errors now go to stderr: stdout is the protocol stream, and a
startup error printed there is not JSON-RPC.

SKILL.md must begin with its frontmatter, as the Agent Skills format
requires; a later --- block no longer passes.
2026-10-06 14:39:21 +08:00
Willie cc7d802411 feat(mcp): serve skills over MCP with the SEP-2640 Skills extension
Agents on a disposable VM, in a hosted assistant or behind an MCP gateway can
reach an MCP endpoint but not the folder skills sync to, so they got tools and
none of the user's skills (#428).

`skillshare mcp serve` is a read-only server for the skills skillshare already
manages. It declares io.modelcontextprotocol/skills and implements skills/list,
skills/get and resources/read: one entry per skill, its URI from the source
path, the full frontmatter, and every file with a sha256 digest and size.
--target applies that target's selection, and the source is reread at most
every 5 seconds so install, update, enable and disable show up without a
restart; unchanged files keep their digest. stdio is the default; --http
serves Streamable HTTP and needs SKILLSHARE_MCP_TOKEN off loopback.

Skills the extension cannot carry are skipped with a warning instead of being
published incomplete: a name that breaks the Agent Skills rules or differs from
its directory, more than 512 files or 16 MiB, or a nested skill that is not
served. --check lists them without serving. The naming rules moved to
internal/skillpkg so sync and the server share them.

Few clients support the extension yet, so the server also offers list_skills
and read_skill tools. A client that declares the extension does not see them,
so it never gets each skill twice.

sync.SelectTargetSkills is the one place that turns discovered skills into a
target's selection (enabled, include/exclude, frontmatter targets).

Refs: #428
2026-10-06 14:18:16 +08:00