Enhance create-tool documentation and improve widget error handling

[frontegg-david]

Summary by CodeRabbit

• New Features

  • Added comprehensive MCP tool creation documentation with 27 examples covering class-based tools, function-style tools, authentication, dependency injection, error handling, rate limiting, concurrency control, UI widgets, progress tracking, and more.
  • Introduced "component layout" as an alternative skill documentation structure.
  • Added new "development/create" skill category.

• Documentation

  • New reference guides for tool development best practices and patterns.
  • Added detailed rule documentation for tool implementation standards.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR consolidates FrontMCP tool-authoring documentation into a new component-layout create-tool skill. The changes add type system infrastructure for component layouts, establish a comprehensive 27-example tool tutorial library with 11 reference guides and 10 enforced rules, integrate the new structure into the catalog manifest, and retire the separate create-tool-annotations, create-tool-output-schema-types, and create-tool-ui skills.

Changes

Component-Layout Tool Skill Consolidation

Layer / File(s)	Summary
Type System and Validation Infrastructure for Component Layout libs/skills/src/manifest.ts, libs/skills/__tests__/manifest.spec.ts, libs/skills/__tests__/skills-validation.spec.ts	Extended SkillCatalogEntry with optional `layout: 'component'
Create-Tool Skill Core Documentation and Metadata libs/skills/catalog/create-tool/SKILL.md, libs/skills/catalog/skills-manifest.json, libs/skills/catalog/TEMPLATE.md	Established create-tool as a component-layout skill with scope definition, inherited defaults, invocation guidance, decision trees, scenario routing, and verification checklist; consolidated manifest entry references 27 examples and 11 references with 10 rules; documented component layout structure in TEMPLATE.md.
Tool Example Documentation (27 Patterns) libs/skills/catalog/create-tool/examples/01-*.md through 27-*.md	Added 27 example patterns: basic class/function tools, output schemas (primitive/Zod/media/resource), DI provider injection, auth providers (OAuth/vault), rate limiting, concurrency, timeouts, progress/notifications, elicitation, annotations, availability constraints, UI widgets (HTML templates, FileSource TSX, CSP + bridge), resource links, job handoff, and tool metadata discovery.
Tool Reference Documentation (11 References) libs/skills/catalog/create-tool/references/*.md	Added quick-start, decorator options, input/output schema taxonomy, derived types, execution context API, error handling patterns, function-style builder, file layout conventions, registration patterns, remote/ESM tools, testing strategy, throttling (rate limit/concurrency/timeout), and UI widget configuration.
Tool Rule Documentation (10 Rules) libs/skills/catalog/create-tool/rules/*.md	Added enforced rules: always define output schema, derive execute types, input schema raw shape, no ToolContext generics, no try/catch around execute, register in app, snake case naming, use this.fail for business errors, widget path anchoring, and widget resource mode host detection.
Catalog Structure and Integration Updates libs/skills/catalog/frontmcp-development/SKILL.md, removal of frontmcp-development/examples/create-tool-* and frontmcp-development/references/create-tool-*.md	Consolidated tool-related scenario routing into top-level create-tool skill, removed standalone create-tool-annotations, create-tool-output-schema-types, and create-tool-ui entries, updated "Recommended Reading Order" and "Related Skills" references to reflect migration.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

This PR introduces a new catalog layout pattern, substantially reorganizes skill documentation infrastructure, and adds comprehensive tool-authoring tutorials and rules. The changes are heterogeneous: type-system updates, large test validation refactoring, 60+ new markdown files with varying scope (examples vs references vs rules), and catalog manifest consolidation. Review should focus on: (1) correctness of layout detection logic in skills-validation.spec.ts (medium density), (2) consistency of frontmatter/metadata patterns across 27 examples, (3) rule enforcement mappings, and (4) manifest entry schema/examples/rules keying for component layout.

Possibly related PRs

• agentfront/frontmcp#316: Modifies libs/skills/src/manifest.ts and validation infrastructure for skill category and manifest shape extensions, directly supporting the component-layout infrastructure in this PR.

🐰 A tale unfolds in markdown wide,
Twenty-seven tools stand side by side,
From class to function, fetch to rule,
Each pattern teaches, each is cool.
Component layouts now align the way,
Create-tool docs have come to stay! 🚀

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactoring-skills

[coderabbitai]

Actionable comments posted: 15

🧹 Nitpick comments (2)

libs/skills/catalog/create-tool/rules/derive-execute-types.md (1)

54-57: ⚡ Quick win

Verification command is shell-fragile.

grep ... src/**/*.tool.ts depends on shell globstar behavior. Prefer a portable command so users get consistent results.

Suggested fix

-# Find tool files where execute() uses an inline object literal type — likely a violation
-grep -rE 'execute\(input:\s*\{' src/**/*.tool.ts
+# Find tool files where execute() uses an inline object literal type — likely a violation
+rg -nP "execute\\(input:\\s*\\{" src --glob "**/*.tool.ts"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@libs/skills/catalog/create-tool/rules/derive-execute-types.md` around lines
54 - 57, The verification command in derive-execute-types.md uses a
shell-specific glob (src/**/*.tool.ts) which is fragile; replace it with a
portable find+grep (or git grep) invocation that reliably searches all .tool.ts
files and matches the pattern "execute(input: {" — e.g. update the snippet to
use find to locate *.tool.ts and pass them to grep/egrep (or use git grep -E
"execute\\(input:\\s*\\{" ) so the check consistently finds inline object
literal types across shells and platforms.

libs/skills/catalog/create-tool/rules/always-define-output-schema.md (1)

72-75: ⚡ Quick win

Use a shell-portable verification command.

The current grep pipeline depends on ** globstar behavior and can fail in many default shells. Prefer a single rg-based check for reliability.

Suggested fix

-# Grep for tools without outputSchema — should return 0 hits
-grep -L 'outputSchema:' $(grep -rl '`@Tool`' src/**/*.tool.ts)
+# List tool files containing `@Tool` but missing `outputSchema:` (should print nothing)
+rg -l '`@Tool`' src | xargs rg -L 'outputSchema:'

As per coding guidelines, "Publishable SDK libraries. - Review for API correctness, breaking changes, and consistency with docs."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@libs/skills/catalog/create-tool/rules/always-define-output-schema.md` around
lines 72 - 75, Replace the shell-specific grep pipeline with a portable
ripgrep-based check: remove the current command that uses globstar and instead
run a single rg-based pipeline such as "rg -g 'src/**/*.tool.ts' -l '`@Tool`' |
xargs -r rg -L 'outputSchema:'" so files that contain "`@Tool`" but lack
"outputSchema:" are listed reliably across shells; update the snippet replacing
the original grep lines (the command that greps for tools without outputSchema)
with this rg-based command.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@libs/skills/__tests__/_debug.mjs`:
- Around line 1-3: Update the test to resolve the markdown file relative to the
module instead of the CWD and import a runtime-built ESM entry for the parser:
replace the CWD-dependent fs.readFileSync call with fs.readFileSync(new
URL('./relative/path/to/01-basic-class-tool.md', import.meta.url), 'utf8') (use
the correct relative path from this test file), and change the import of
parseSkillMdFrontmatter so it comes from a runtime-resolvable ESM export (e.g.,
import { parseSkillMdFrontmatter } from '`@frontmcp/sdk`' or from the package's
dist/esm build) rather than the TypeScript source; keep the symbol
parseSkillMdFrontmatter and ensure the module exists at runtime.

In `@libs/skills/__tests__/skills-validation.spec.ts`:
- Around line 1120-1125: The code uses a non-null assertion on headingMatch
(headingMatch![0]); replace it with an explicit null check and clear failure
message: after computing headingMatch (from isComponentLayout(dir) ? ...), do if
(headingMatch === null) throw new Error("Expected heading 'Accessing this skill'
not found in README/skill docs"); then use const idx =
body.indexOf(headingMatch[0]); this removes the `!` and provides an explicit
error path; reference symbols: isComponentLayout, headingMatch, body.indexOf.

In `@libs/skills/catalog/create-tool/examples/01-basic-class-tool.md`:
- Around line 23-28: The fenced code block that shows the src/apps/main/tools/
tree in the Markdown example triggers markdownlint rule MD040 because it lacks a
language identifier; update that block by adding a language token (e.g., `text`)
right after the opening triple backticks so the snippet becomes a labeled fenced
code block (this is the tree snippet in the 01-basic-class-tool.md example).

In `@libs/skills/catalog/create-tool/examples/03-tool-with-zod-shape-output.md`:
- Line 8: The docs claim the example uses '.int().min(0).max(100)' but the Zod
schema in the example only uses '.int().min(0)'; update the example so the Zod
shape matches the prose by adding '.max(100)' to the numeric field in the
example Zod schema (or alternatively change both occurrences of
'.int().min(0).max(100)' in the markdown to describe only '.int().min(0)' if the
intended constraint is unbounded above); ensure the same symbol
'.int().min(0).max(100)' appears consistently in the markdown and the example
Zod schema so users don’t copy an incorrect constraint.

In `@libs/skills/catalog/create-tool/examples/04-tool-with-zod-schema-output.md`:
- Line 51: The example is missing the PublicMcpError import used in the snippet;
update the existing import that currently reads Tool and ToolContext to also
import PublicMcpError from the same package (i.e., add PublicMcpError to the
import list from '`@frontmcp/sdk`') so the example compiles when referencing
PublicMcpError in the code (also apply the same fix where the example repeats at
the later occurrence around the second mention).

In `@libs/skills/catalog/create-tool/examples/12-tool-with-fetch-and-retries.md`:
- Around line 79-81: The retry delay calculation assumes retry-after is numeric;
update the logic around retryAfter/baseDelay to robustly handle both
numeric-seconds and HTTP-date formats: if retryAfter is all-digits parse as
seconds, else attempt Date.parse(retryAfter) and compute seconds = (parsedDate -
Date.now())/1000 (floor to >=0); if parsing fails or yields non-positive, fall
back to BASE_DELAY_MS * 2 ** (attempt - 1); keep jitter calculation after
baseDelay. Reference variables/functions: retryAfter, baseDelay, BASE_DELAY_MS,
attempt, jitter.

In `@libs/skills/catalog/create-tool/examples/22-tool-with-ui-html-template.md`:
- Around line 68-70: The fenced code block containing the line "Parameter 'ctx'
implicitly has an 'any' type." is missing a language tag and triggers
markdown-lint MD040; update that fenced block to include a language tag (e.g.,
add ```text or ```console) so the block becomes a tagged code fence and the
linter warning is resolved.

In `@libs/skills/catalog/create-tool/examples/24-tool-with-ui-csp-and-bridge.md`:
- Around line 36-38: The fetch response is parsed unconditionally which can
throw or return bad data on non-2xx responses; update both occurrences that call
this.fetch and then await res.json() to first check the Response (use res.ok or
inspect res.status) and, on non-success, throw or return a controlled MCP error
with context (status and body/error message) instead of calling res.json()
blindly so that the tool returns a predictable error path rather than crashing
or returning misleading data.

In
`@libs/skills/catalog/create-tool/examples/26-tool-with-resource-link-output.md`:
- Around line 29-30: The example's resource_link URI allows a JSON export
whereas the registered resource shape only accepts CSV; update the example for
StartExportTool to use a registered shape or restrict the tool to CSV: either
change the returned URI to match the registered CSV shape (e.g., use
export://{exportId}.csv and ensure the tool's output format is CSV), or
register/declare a JSON resource shape and update the resource registry to
accept export://{exportId}.json; locate symbols StartExportTool and the
resource_link entries in the example and make the chosen change consistently
across all occurrences (also update the related example occurrences referenced
in the review).

In `@libs/skills/catalog/create-tool/examples/27-tool-with-examples-metadata.md`:
- Line 55: The example's execute signature uses an inline type which violates
the "derive execute types" rule; replace the inline type in async execute(input:
{ amount: number; from: string; to: string }) with the derived helper types
(e.g., async execute(input: ToolInputOf<typeof <toolIdentifier>>) and ensure any
return type uses ToolOutputOf<typeof <toolIdentifier>>), importing
ToolInputOf/ToolOutputOf and referencing the actual tool constant/name used in
the example (keep the function name execute intact).

In `@libs/skills/catalog/create-tool/references/file-layout.md`:
- Around line 12-20: The two fenced code blocks that show the directory listings
starting with "src/apps/main/tools/" are missing a fence language and should be
updated to include a language identifier; edit each opening fence from ``` to
```text so both code blocks (the short flat listing and the expanded nested
listing) explicitly use "text" as the language.

In `@libs/skills/catalog/create-tool/references/throttling.md`:
- Around line 81-85: The table examples use shorthand option objects that don't
match the documented API (e.g., `{ 60, 60_000 }`, `{ 2 }`, `{ 30_000 }`); update
each row to use the explicit option keys used by the code: replace rateLimit
shorthand with an object using its explicit keys (e.g., `rateLimit: { points:
<number>, durationMs: <number> }`), replace concurrency shorthand with
`concurrency: { maxConcurrent: <number> }`, and replace timeout shorthand with
`timeout: { executeMs: <number> }` so the `rateLimit`, `concurrency`, and
`timeout` examples in the table are valid and copy/paste-safe.

In `@libs/skills/catalog/create-tool/references/ui-widgets.md`:
- Around line 92-95: The example object literal under ui.template uses an
invalid semicolon ("file: widgetPath;"); replace it with valid TS object syntax
by removing the semicolon and using a comma if needed (e.g., ui.template.file:
use "file: widgetPath" or "file: 'widgetPath'" depending on whether widgetPath
is a variable or string literal) so the example compiles; update the snippet
referencing ui.template.file and widgetPath accordingly.

In `@libs/skills/catalog/create-tool/SKILL.md`:
- Around line 147-214: The fenced code block that begins with "1. What kind of
tool?" is missing a language tag (causing MD040); update that block in SKILL.md
to open with ```text instead of ``` so the decision-tree is marked as plain text
(look for the block containing the numbered list and the final "12. Does it hand
off long work to a job?" line) and leave the closing ``` unchanged.

In `@libs/skills/catalog/TEMPLATE.md`:
- Around line 179-183: The markdown table in TEMPLATE.md has misaligned
separators and an unescaped pipe inside the `severity` value; fix the header
separator row so it matches the actual number of columns used in the table
(remove the extra `|` separator that creates a stray empty column) and update
the `rules/` row to escape or quote the pipe in the frontmatter example (the
`severity: required | recommended` token) — e.g., wrap it in backticks or
replace `|` with an escaped entity — so the table renders correctly.

---

Nitpick comments:
In `@libs/skills/catalog/create-tool/rules/always-define-output-schema.md`:
- Around line 72-75: Replace the shell-specific grep pipeline with a portable
ripgrep-based check: remove the current command that uses globstar and instead
run a single rg-based pipeline such as "rg -g 'src/**/*.tool.ts' -l '`@Tool`' |
xargs -r rg -L 'outputSchema:'" so files that contain "`@Tool`" but lack
"outputSchema:" are listed reliably across shells; update the snippet replacing
the original grep lines (the command that greps for tools without outputSchema)
with this rg-based command.

In `@libs/skills/catalog/create-tool/rules/derive-execute-types.md`:
- Around line 54-57: The verification command in derive-execute-types.md uses a
shell-specific glob (src/**/*.tool.ts) which is fragile; replace it with a
portable find+grep (or git grep) invocation that reliably searches all .tool.ts
files and matches the pattern "execute(input: {" — e.g. update the snippet to
use find to locate *.tool.ts and pass them to grep/egrep (or use git grep -E
"execute\\(input:\\s*\\{" ) so the check consistently finds inline object
literal types across shells and platforms.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 298834f6-9b45-4348-87c8-dec803fdf537

📥 Commits

Reviewing files that changed from the base of the PR and between 6eb8b7e and 7b61940.

📒 Files selected for processing (76)

• libs/skills/__tests__/_debug.mjs
• libs/skills/__tests__/manifest.spec.ts
• libs/skills/__tests__/skills-validation.spec.ts
• libs/skills/catalog/TEMPLATE.md
• libs/skills/catalog/create-tool/SKILL.md
• libs/skills/catalog/create-tool/examples/01-basic-class-tool.md
• libs/skills/catalog/create-tool/examples/02-basic-function-tool.md
• libs/skills/catalog/create-tool/examples/03-tool-with-zod-shape-output.md
• libs/skills/catalog/create-tool/examples/04-tool-with-zod-schema-output.md
• libs/skills/catalog/create-tool/examples/05-tool-with-primitive-output.md
• libs/skills/catalog/create-tool/examples/06-tool-with-media-output.md
• libs/skills/catalog/create-tool/examples/08-tool-with-provider-injection.md
• libs/skills/catalog/create-tool/examples/09-tool-with-multiple-providers.md
• libs/skills/catalog/create-tool/examples/11-tool-with-fetch.md
• libs/skills/catalog/create-tool/examples/12-tool-with-fetch-and-retries.md
• libs/skills/catalog/create-tool/examples/13-tool-with-single-auth-provider.md
• libs/skills/catalog/create-tool/examples/14-tool-with-multiple-auth-providers.md
• libs/skills/catalog/create-tool/examples/15-tool-with-credential-vault.md
• libs/skills/catalog/create-tool/examples/16-tool-with-rate-limit.md
• libs/skills/catalog/create-tool/examples/17-tool-with-concurrency-and-timeout.md
• libs/skills/catalog/create-tool/examples/18-tool-with-progress-and-notify.md
• libs/skills/catalog/create-tool/examples/19-tool-with-elicitation.md
• libs/skills/catalog/create-tool/examples/20-tool-with-annotations.md
• libs/skills/catalog/create-tool/examples/21-tool-with-availability-constraints.md
• libs/skills/catalog/create-tool/examples/22-tool-with-ui-html-template.md
• libs/skills/catalog/create-tool/examples/23-tool-with-ui-filesource-tsx.md
• libs/skills/catalog/create-tool/examples/24-tool-with-ui-csp-and-bridge.md
• libs/skills/catalog/create-tool/examples/25-tool-handing-off-to-job.md
• libs/skills/catalog/create-tool/examples/26-tool-with-resource-link-output.md
• libs/skills/catalog/create-tool/examples/27-tool-with-examples-metadata.md
• libs/skills/catalog/create-tool/references/annotations.md
• libs/skills/catalog/create-tool/references/auth-providers.md
• libs/skills/catalog/create-tool/references/availability.md
• libs/skills/catalog/create-tool/references/decorator-options.md
• libs/skills/catalog/create-tool/references/derived-types.md
• libs/skills/catalog/create-tool/references/elicitation.md
• libs/skills/catalog/create-tool/references/error-handling.md
• libs/skills/catalog/create-tool/references/execution-context.md
• libs/skills/catalog/create-tool/references/file-layout.md
• libs/skills/catalog/create-tool/references/function-style-builder.md
• libs/skills/catalog/create-tool/references/input-schema.md
• libs/skills/catalog/create-tool/references/output-schema.md
• libs/skills/catalog/create-tool/references/quick-start.md
• libs/skills/catalog/create-tool/references/registration.md
• libs/skills/catalog/create-tool/references/remote-and-esm.md
• libs/skills/catalog/create-tool/references/testing.md
• libs/skills/catalog/create-tool/references/throttling.md
• libs/skills/catalog/create-tool/references/ui-widgets.md
• libs/skills/catalog/create-tool/rules/always-define-output-schema.md
• libs/skills/catalog/create-tool/rules/derive-execute-types.md
• libs/skills/catalog/create-tool/rules/input-schema-is-raw-shape.md
• libs/skills/catalog/create-tool/rules/no-toolcontext-generics.md
• libs/skills/catalog/create-tool/rules/no-try-catch-around-execute.md
• libs/skills/catalog/create-tool/rules/register-in-app.md
• libs/skills/catalog/create-tool/rules/snake-case-tool-names.md
• libs/skills/catalog/create-tool/rules/use-this-fail-for-business-errors.md
• libs/skills/catalog/create-tool/rules/widget-paths-anchor-with-import-meta-url.md
• libs/skills/catalog/create-tool/rules/widget-resource-mode-host-detect.md
• libs/skills/catalog/frontmcp-development/SKILL.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/destructive-delete-tool.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/readonly-query-tool.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/primitive-and-media-outputs.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-raw-shape-output.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-schema-advanced-output.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-ui/basic-html-template.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-ui/file-source-tsx-widget.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-ui/widget-with-csp-and-bridge.md
• libs/skills/catalog/frontmcp-development/examples/create-tool/basic-class-tool.md
• libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-di-and-errors.md
• libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-rate-limiting-and-progress.md
• libs/skills/catalog/frontmcp-development/references/create-tool-annotations.md
• libs/skills/catalog/frontmcp-development/references/create-tool-output-schema-types.md
• libs/skills/catalog/frontmcp-development/references/create-tool-ui.md
• libs/skills/catalog/frontmcp-development/references/create-tool.md
• libs/skills/catalog/skills-manifest.json
• libs/skills/src/manifest.ts

💤 Files with no reviewable changes (15)

• libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/readonly-query-tool.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-raw-shape-output.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-ui/widget-with-csp-and-bridge.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/destructive-delete-tool.md
• libs/skills/catalog/frontmcp-development/examples/create-tool/basic-class-tool.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-ui/basic-html-template.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/primitive-and-media-outputs.md
• libs/skills/catalog/frontmcp-development/references/create-tool.md
• libs/skills/catalog/frontmcp-development/references/create-tool-annotations.md
• libs/skills/catalog/frontmcp-development/references/create-tool-output-schema-types.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-ui/file-source-tsx-widget.md
• libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-rate-limiting-and-progress.md
• libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-di-and-errors.md
• libs/skills/catalog/frontmcp-development/references/create-tool-ui.md
• libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-schema-advanced-output.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== File: libs/skills/__tests__/_debug.mjs =="
if [ -f "libs/skills/__tests__/_debug.mjs" ]; then
  sed -n '1,200p' "libs/skills/__tests__/_debug.mjs" | cat -n
else
  echo "Missing libs/skills/__tests__/_debug.mjs"
fi

echo
echo "== Locate parseSkillMdFrontmatter =="
rg -n "parseSkillMdFrontmatter" libs | head -n 50

echo
echo "== Locate skill-md-parser entry files =="
# Try likely variants without assuming paths too hard.
fd -e ts -e tsx -e js -e mjs -e cjs -e json "skill-md-parser" libs || true
fd -e ts -e tsx -e js -e mjs -e cjs -e json "skill-md-parser" . || true

echo
echo "== Inspect potential source file =="
# Find the sdk/src/skill/skill-md-parser.* file(s)
fd "skill-md-parser" libs -a --hidden -0 | xargs -0 -I{} bash -lc 'echo "--- {}"; sed -n "1,120p" "{}" | cat -n' | head -n 120 || true

echo
echo "== Inspect package/module type for ESM resolution =="
# Look for package.json in repo root and under libs/skills and libs/sdk (if present)
for p in package.json libs/skills/package.json libs/sdk/package.json libs/package.json; do
  if [ -f "$p" ]; then
    echo "--- $p ---"
    cat "$p"
    echo
  fi
done

echo
echo "== Find how tests/debug script is run =="
rg -n "\"_debug\.mjs\"|_debug\.mjs" package.json libs/skills -S || true
rg -n "node .*_debug\.mjs|tsx .*_debug\.mjs|ts-node .*_debug\.mjs" . -S || true
rg -n "scripts" package.json -S || true

Repository: agentfront/frontmcp

Length of output: 20578

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== Check catalog file exists =="
ls -la "libs/skills/catalog/create-tool/examples/01-basic-class-tool.md" || true
ls -la "libs/skills/__tests__/../catalog/create-tool/examples/01-basic-class-tool.md" || true
ls -la "libs/skills/catalog/create-tool/examples" || true

echo
echo "== Find runtime-safe exports for parseSkillMdFrontmatter =="
rg -n "parseSkillMdFrontmatter" libs/sdk/src/index.ts libs/sdk/src/skill/index.ts libs/sdk/src -S | head -n 80

echo
echo "== Inspect libs/sdk/src/index.ts =="
if [ -f "libs/sdk/src/index.ts" ]; then
  sed -n '1,220p' "libs/sdk/src/index.ts" | cat -n
fi

echo
echo "== Inspect libs/sdk/src/skill/index.ts export surface =="
if [ -f "libs/sdk/src/skill/index.ts" ]; then
  sed -n '1,220p' "libs/sdk/src/skill/index.ts" | cat -n
fi

echo
echo "== Check for dist/esm availability (if present) =="
ls -la libs/sdk/dist/esm 2>/dev/null || true
ls -la libs/sdk/dist 2>/dev/null || true

echo
echo "== Search for skill-md-parser built JS entry (if any) =="
rg -n "skill-md-parser" libs/sdk/dist -S || true

Repository: agentfront/frontmcp

Length of output: 21411

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

rg -n "parseSkillMdFrontmatter" libs/sdk/src/index.ts libs/sdk/src -S

echo "== Search for skill module re-export in sdk/src/index.ts =="
rg -n "from '\\./skill'" libs/sdk/src/index.ts -S

echo "== Check sdk package exports for skill subpaths =="
cat libs/sdk/package.json | rg -n "\"exports\"" -n
cat libs/sdk/package.json | rg -n "skill" || true

Repository: agentfront/frontmcp

Length of output: 2696

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== Search for _debug.mjs usage =="
rg -n "_debug\.mjs" . -S || true

echo
echo "== Inspect libs/sdk/src/index.ts around where it re-exports skill =="
# Show the region that includes "from './skill'" exports seen earlier
sed -n '210,280p' libs/sdk/src/index.ts | cat -n

Repository: agentfront/frontmcp

Length of output: 2231

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail
rg -n "parseSkillMdFrontmatter" libs/sdk/src/index.ts libs/sdk/src -S

Repository: agentfront/frontmcp

Length of output: 2451

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== Locate skill-md-parser artifacts under libs/sdk =="
fd -e ts -e tsx -e js -e mjs -e cjs "skill-md-parser" libs/sdk || true
echo
echo "== Does libs/sdk/src/index.ts export parseSkillMdFrontmatter? =="
rg -n "parseSkillMdFrontmatter" libs/sdk/src/index.ts -S || true
echo
echo "== Show the skill export blocks in libs/sdk/src/index.ts =="
rg -n "from '\\./skill'" libs/sdk/src/index.ts -n
# Print around each match line
matches=$(rg -n "from '\\./skill'" libs/sdk/src/index.ts -n | cut -d: -f1)
for m in $matches; do
  start=$((m-40)); end=$((m+40));
  echo "--- around line $m ---"
  sed -n "${start},${end}p" libs/sdk/src/index.ts | cat -n
done

echo
echo "== Any dist artifacts present? =="
ls -ლა libs/sdk/dist 2>/dev/null || true
ls -la libs/sdk/dist/esm 2>/dev/null || true

Repository: agentfront/frontmcp

Length of output: 8053

---

Make libs/skills/__tests__/_debug.mjs runtime-stable for plain Node ESM

• fs.readFileSync('../catalog/create-tool/examples/01-basic-class-tool.md', 'utf8') is CWD-dependent; resolve the file via new URL(..., import.meta.url).
• parseSkillMdFrontmatter is imported from ../../sdk/src/skill/skill-md-parser (TypeScript source); plain Node ESM can’t import TS directly—switch to a runtime-resolvable JS/ESM entry (e.g., the @frontmcp/sdk export or its built dist/esm target).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@libs/skills/__tests__/_debug.mjs` around lines 1 - 3, Update the test to
resolve the markdown file relative to the module instead of the CWD and import a
runtime-built ESM entry for the parser: replace the CWD-dependent
fs.readFileSync call with fs.readFileSync(new
URL('./relative/path/to/01-basic-class-tool.md', import.meta.url), 'utf8') (use
the correct relative path from this test file), and change the import of
parseSkillMdFrontmatter so it comes from a runtime-resolvable ESM export (e.g.,
import { parseSkillMdFrontmatter } from '`@frontmcp/sdk`' or from the package's
dist/esm build) rather than the TypeScript source; keep the symbol
parseSkillMdFrontmatter and ensure the module exists at runtime.

[github-actions]

Performance Test Results

Status: ✅ All tests passed

Summary

Project	Tests	Passed	Warnings	Failed	Leaks
✅ demo-e2e-agents	4	4	0	0	0
✅ demo-e2e-cache	11	11	0	0	0
✅ demo-e2e-codecall	4	4	0	0	0
✅ demo-e2e-config	4	4	0	0	0
✅ demo-e2e-direct	3	3	0	0	0
✅ demo-e2e-elicitation	1	1	0	0	0
✅ demo-e2e-errors	4	4	0	0	0
✅ demo-e2e-hooks	3	3	0	0	0
✅ demo-e2e-multiapp	4	4	0	0	0
✅ demo-e2e-notifications	3	3	0	0	0
✅ demo-e2e-openapi	2	2	0	0	0
✅ demo-e2e-providers	4	4	0	0	0
✅ demo-e2e-public	4	4	0	0	0
✅ demo-e2e-redis	15	15	0	0	0
✅ demo-e2e-remember	4	4	0	0	0
✅ demo-e2e-remote	5	5	0	0	0
✅ demo-e2e-serverless	2	2	0	0	0
✅ demo-e2e-skills	15	15	0	0	0
✅ demo-e2e-standalone	2	2	0	0	0
✅ demo-e2e-transport-recreation	3	3	0	0	0
✅ demo-e2e-ui	4	4	0	0	0

Total: 101 tests across 21 projects

📊 View full report in workflow run

---

Generated at: 2026-05-29T10:01:23.442Z
Commit: e8059884

[coderabbitai]

🧹 Nitpick comments (1)

libs/skills/__tests__/skills-validation.spec.ts (1)

1123-1127: 💤 Low value

Consider removing the redundant assertion for clearer error messages.

The code correctly addresses the past review comment by adding an explicit null check. However, the expect(headingMatch).not.toBeNull() on line 1123 creates redundancy: if headingMatch is null, the test fails at line 1123 with Jest's generic message, and the more descriptive custom error message on line 1125 is never reached.

Consider removing line 1123 and keeping only the explicit null check. This would:

• Provide better error context when the test fails
• Eliminate functional redundancy
• Still satisfy TypeScript type narrowing requirements

♻️ Proposed refactor

         const headingMatch = isComponentLayout(dir)
           ? body.match(/^## Accessing this skill$/im)
           : body.match(/^## Accessing This Skill$/m);
-        expect(headingMatch).not.toBeNull();
         if (headingMatch === null) {
           throw new Error(`Missing "Accessing This Skill" heading for ${dir}`);
         }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@libs/skills/__tests__/skills-validation.spec.ts` around lines 1123 - 1127,
Remove the redundant Jest assertion expect(headingMatch).not.toBeNull() and rely
on the explicit null check that follows (if (headingMatch === null) throw new
Error(...)); this keeps TypeScript narrowing for subsequent use of
headingMatch[0] while providing the more descriptive custom error message
referencing dir and body, so delete the expect line and leave the null-check and
index computation (const idx = body.indexOf(headingMatch[0])) intact.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@libs/skills/__tests__/skills-validation.spec.ts`:
- Around line 1123-1127: Remove the redundant Jest assertion
expect(headingMatch).not.toBeNull() and rely on the explicit null check that
follows (if (headingMatch === null) throw new Error(...)); this keeps TypeScript
narrowing for subsequent use of headingMatch[0] while providing the more
descriptive custom error message referencing dir and body, so delete the expect
line and leave the null-check and index computation (const idx =
body.indexOf(headingMatch[0])) intact.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fec5e8c6-c93e-4972-a051-78ae091dbfea

📥 Commits

Reviewing files that changed from the base of the PR and between 7b61940 and e386164.

📒 Files selected for processing (17)

• libs/skills/__tests__/skills-validation.spec.ts
• libs/skills/catalog/TEMPLATE.md
• libs/skills/catalog/create-tool/SKILL.md
• libs/skills/catalog/create-tool/examples/01-basic-class-tool.md
• libs/skills/catalog/create-tool/examples/03-tool-with-zod-shape-output.md
• libs/skills/catalog/create-tool/examples/04-tool-with-zod-schema-output.md
• libs/skills/catalog/create-tool/examples/12-tool-with-fetch-and-retries.md
• libs/skills/catalog/create-tool/examples/22-tool-with-ui-html-template.md
• libs/skills/catalog/create-tool/examples/24-tool-with-ui-csp-and-bridge.md
• libs/skills/catalog/create-tool/examples/26-tool-with-resource-link-output.md
• libs/skills/catalog/create-tool/examples/27-tool-with-examples-metadata.md
• libs/skills/catalog/create-tool/references/file-layout.md
• libs/skills/catalog/create-tool/references/throttling.md
• libs/skills/catalog/create-tool/references/ui-widgets.md
• libs/skills/catalog/create-tool/rules/always-define-output-schema.md
• libs/skills/catalog/create-tool/rules/derive-execute-types.md
• libs/skills/catalog/skills-manifest.json

✅ Files skipped from review due to trivial changes (10)

• libs/skills/catalog/create-tool/rules/derive-execute-types.md
• libs/skills/catalog/create-tool/references/throttling.md
• libs/skills/catalog/create-tool/references/file-layout.md
• libs/skills/catalog/create-tool/SKILL.md
• libs/skills/catalog/create-tool/examples/22-tool-with-ui-html-template.md
• libs/skills/catalog/TEMPLATE.md
• libs/skills/catalog/create-tool/examples/26-tool-with-resource-link-output.md
• libs/skills/catalog/create-tool/examples/03-tool-with-zod-shape-output.md
• libs/skills/catalog/create-tool/rules/always-define-output-schema.md
• libs/skills/catalog/create-tool/references/ui-widgets.md

🚧 Files skipped from review as they are similar to previous changes (6)

• libs/skills/catalog/create-tool/examples/27-tool-with-examples-metadata.md
• libs/skills/catalog/skills-manifest.json
• libs/skills/catalog/create-tool/examples/01-basic-class-tool.md
• libs/skills/catalog/create-tool/examples/04-tool-with-zod-schema-output.md
• libs/skills/catalog/create-tool/examples/12-tool-with-fetch-and-retries.md
• libs/skills/catalog/create-tool/examples/24-tool-with-ui-csp-and-bridge.md