@frontmcp/skills 1.1.2 → 1.2.1

package/catalog/TEMPLATE.md

@@ -145,17 +145,22 @@ Add a `## Examples` section at the bottom of each reference file (before `## Ref
 
 ## Resource Access
 
-Skills are accessible via the `skills://` URI scheme as MCP resources with auto-complete:
-
-| URI                                               | Returns                                   |
-| ------------------------------------------------- | ----------------------------------------- |
-| `skills://catalog`                                | JSON list of all available skills         |
-| `skills://{skillName}`                            | Full SKILL.md content (formatted for LLM) |
-| `skills://{skillName}/SKILL.md`                   | Same as above (explicit path alias)       |
-| `skills://{skillName}/references`                 | JSON list of references for this skill    |
-| `skills://{skillName}/references/{referenceName}` | Reference markdown content                |
-| `skills://{skillName}/examples`                   | JSON list of examples for this skill      |
-| `skills://{skillName}/examples/{exampleName}`     | Example markdown content                  |
+Skills are accessible via the `skill://` URI scheme as MCP resources per
+[SEP-2640 (Skills Extension)](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640),
+with auto-complete on `skillPath`:
+
+| URI                                        | Returns                                                                  |
+| ------------------------------------------ | ------------------------------------------------------------------------ |
+| `skill://index.json`                       | SEP-2640 discovery document (agentskills.io schema)                      |
+| `skill://{skillPath}/SKILL.md`             | Raw SKILL.md (YAML frontmatter + markdown body, identical to filesystem) |
+| `skill://{skillPath}/references/{file}.md` | Reference markdown content                                               |
+| `skill://{skillPath}/examples/{file}.md`   | Example markdown content                                                 |
+| `skill://{skillPath}/scripts/{file}`       | Script asset (any media type)                                            |
+| `skill://{skillPath}/assets/{file}`        | Bundled asset (any media type)                                           |
+
+`{skillPath}` may be a single segment (`git-workflow`) or nested
+(`acme/billing/refunds`). Its final segment must equal the skill's
+frontmatter `name`.
 
 ## Reference
 

package/catalog/frontmcp-authorities/SKILL.md

@@ -106,7 +106,12 @@ authorities: {
 }
 ```
 
-If no `claimsMapping` is provided, the engine falls back to `authInfo.user.roles` and `authInfo.user.permissions`. For non-standard token shapes, use `claimsResolver` instead (see Common Patterns below).
+If no `claimsMapping` is provided, the engine falls back to (in order):
+
+- **roles**: `authInfo.user.roles` → `authInfo.extra.authorization.scopes` → `[]`
+- **permissions**: `authInfo.user.permissions` → `[]`
+
+The OAuth-scopes-as-roles fallback means a token with no `roles` claim but with `scope: "admin read"` will be treated as having `roles: ['admin', 'read']`. Configure explicit `claimsMapping.roles` to opt out. For non-standard token shapes, use `claimsResolver` instead (see Common Patterns below).
 
 ### Step 3: Register Named Profiles
 
@@ -198,6 +203,87 @@ export default class PublishContentTool extends ToolContext { ... }
 export default class SensitiveActionTool extends ToolContext { ... }
 ```
 
+**Async guards (one-shot DB/Redis/API checks):**
+
+For dynamic, async authorization that does not warrant a reusable custom evaluator, use the
+`guards` field. Each guard receives the same `AuthoritiesEvaluationContext` and returns
+`true` on grant, or `false`/a denial string on deny. Guards run in sequence and combine with
+other policy fields via `operator` (default AND).
+
+```typescript
+import type { AuthorityGuardFn } from '@frontmcp/auth';
+
+const requireActiveSubscription: AuthorityGuardFn = async (ctx) => {
+  const active = await db.isSubscriptionActive(ctx.user.sub);
+  return active ? true : 'subscription is not active';
+};
+
+@Tool({
+  name: 'premium_feature',
+  authorities: {
+    roles: { any: ['user'] },
+    guards: [requireActiveSubscription],
+  },
+})
+export default class PremiumFeatureTool extends ToolContext { ... }
+```
+
+Use `guards` for one-off async checks; promote to a registered custom evaluator when the
+same logic is reused across many entries (see `references/custom-evaluators.md`).
+
+### Optional: Map Denials to OAuth Scope Challenges (`scopeMapping`)
+
+If your transport layer issues OAuth scope challenges (RFC 6750 `insufficient_scope`),
+declare a `scopeMapping` so authority denials are converted into the right `WWW-Authenticate`
+challenge with the required scopes. Mapping is explicit only — no automatic
+permission-to-scope inference.
+
+```typescript
+authorities: {
+  scopeMapping: {
+    roles: { admin: ['admin:all'] },
+    permissions: { 'repo:write': ['repo'] },
+    profiles: { admin: ['admin:all'] },
+  },
+}
+```
+
+When a request is denied because the user lacks role `admin`, the response surfaces
+the `admin:all` scope as the required challenge.
+
+### Optional: Extract Custom Auth Context Fields (`pipes`)
+
+`pipes` are functions that run during auth context construction and merge their output into
+`FrontMcpAuthContext`. Use them to extract custom typed fields from JWT claims so they are
+available to your tools as strongly typed accessors. Declare the resulting fields by
+augmenting `ExtendFrontMcpAuthContext`:
+
+A pipe receives the **raw JWT claims** (a `Readonly<Record<string, unknown>>`) and
+returns a `Partial<ExtendFrontMcpAuthContext>` (sync or async). It does **not**
+receive the `AuthInfo` envelope — there is no `.user` accessor on the input.
+
+```typescript
+// Pipe signature (defined inline; do not import — AuthContextPipe is not
+// re-exported from `@frontmcp/auth`):
+//   (claims: Readonly<Record<string, unknown>>) =>
+//     Partial<ExtendFrontMcpAuthContext> | Promise<Partial<ExtendFrontMcpAuthContext>>
+
+const tenantPipe = (claims: Readonly<Record<string, unknown>>) => ({
+  tenantId: claims['tenantId'] as string | undefined,
+});
+
+declare global {
+  interface ExtendFrontMcpAuthContext {
+    tenantId?: string;
+  }
+}
+
+// In @FrontMcp({ authorities: { ... } })
+authorities: {
+  pipes: [tenantPipe],
+}
+```
+
 ## Scenario Routing Table
 
 | Scenario                              | Approach                                                         | Reference                          |
@@ -253,16 +339,35 @@ export default class SensitiveActionTool extends ToolContext { ... }
 
 ## Troubleshooting
 
-| Problem                                         | Cause                                                                 | Solution                                                                           |
-| ----------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `profile 'admin' is not registered`             | Profile used in decorator but not in `authorities.profiles` config    | Add the profile to the `profiles` field in `@FrontMcp({ authorities })`            |
-| All users denied despite correct roles          | `claimsMapping.roles` path does not match the actual JWT claim path   | Decode a real JWT and verify the dot-path resolves to the roles array              |
-| `authorities` field not recognized on decorator | `@frontmcp/auth` not imported (metadata augmentation not active)      | Add `import '@frontmcp/auth'` or import any type from `@frontmcp/auth/authorities` |
-| ABAC condition always fails                     | `{ fromInput: 'tenantId' }` but tool input field is named `tenant_id` | The `fromInput` key must exactly match the tool's input schema field name          |
-| ReBAC always denies                             | No `relationshipResolver` provided                                    | Implement `RelationshipResolver` and pass it to plugin options                     |
-| Custom evaluator not found                      | Key in `custom.*` policy does not match registered evaluator name     | Ensure the evaluator is registered with the same key used in the policy            |
-| List endpoints show all entries                 | No `authorities` config in `@FrontMcp()` or hook priority conflict    | Verify `authorities: { ... }` is set on `@FrontMcp()` decorator                    |
-| `AuthorityDeniedError` has no detail            | `deniedBy` field shows generic message                                | Check the `evaluatedPolicies` array on the error for which policy type failed      |
+| Problem                                                                                   | Cause                                                                                                                                                                                     | Solution                                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `profile 'admin' is not registered`                                                       | Profile used in decorator but not in `authorities.profiles` config                                                                                                                        | Add the profile to the `profiles` field in `@FrontMcp({ authorities })`                                                                                                                      |
+| All users denied despite correct roles                                                    | `claimsMapping.roles` path does not match the actual JWT claim path                                                                                                                       | Decode a real JWT and verify the dot-path resolves to the roles array                                                                                                                        |
+| `authorities` field not recognized on decorator                                           | `@frontmcp/auth` not imported (metadata augmentation not active)                                                                                                                          | Add `import '@frontmcp/auth'` (or `import type ... from '@frontmcp/auth'`) anywhere in your project to activate the metadata augmentation. There is no `@frontmcp/auth/authorities` subpath. |
+| ABAC condition always fails                                                               | `{ fromInput: 'tenantId' }` but tool input field is named `tenant_id`                                                                                                                     | The `fromInput` key must exactly match the tool's input schema field name                                                                                                                    |
+| ReBAC always denies                                                                       | No `relationshipResolver` provided                                                                                                                                                        | Implement `RelationshipResolver` and pass it to plugin options                                                                                                                               |
+| Custom evaluator not found                                                                | Key in `custom.*` policy does not match registered evaluator name                                                                                                                         | Ensure the evaluator is registered with the same key used in the policy                                                                                                                      |
+| List endpoints show all entries                                                           | No `authorities` config in `@FrontMcp()` or hook priority conflict                                                                                                                        | Verify `authorities: { ... }` is set on `@FrontMcp()` decorator                                                                                                                              |
+| `AuthorityDeniedError` has no detail                                                      | `deniedBy` field shows generic message                                                                                                                                                    | Check the `evaluatedPolicies` array on the error for which policy type failed                                                                                                                |
+| TS error: `evaluators`/`relationshipResolver`/`claimsResolver` not on `AuthoritiesConfig` | The runtime Zod schema accepts these keys but the exported `AuthoritiesConfig` interface in `authorities.profiles.ts` only declares `claimsMapping`, `profiles`, `scopeMapping`, `pipes`. | Pass the config inline (TS infers from the decorator's broader type) or cast the typed config as the interface catches up.                                                                   |
+
+## Examples
+
+This skill currently exposes only references; see [`references/`](./references/) for guidance.
+
+## Accessing This Skill
+
+Skills are distributed as plain SKILL.md files plus a sibling `references/`
+and `examples/` tree, so consumers can pick whichever access mode fits:
+
+| Mode               | How it works                                                                                                                                                                                                                                                                                                                                              |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem**     | Read `libs/skills/catalog/frontmcp-authorities/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point.                                                                                                                                                                                  |
+| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-authorities`, `frontmcp skills read frontmcp-authorities:references/<file>.md`, `frontmcp skills install frontmcp-authorities` — no server required.                                                                                                                                               |
+| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-authorities/SKILL.md`, `skill://frontmcp-authorities/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |
+
+The catalog itself is **not** an MCP server. The `skill://` URIs only resolve
+when a server has been configured to host this skill.
 
 ## Reference
 

package/catalog/frontmcp-authorities/references/authority-profiles.md

@@ -17,40 +17,40 @@ import { FrontMcp } from '@frontmcp/sdk';
 @FrontMcp({
   name: 'my-server',
   authorities: {
-    claimsMapping: { roles: 'realm_access.roles', permissions: 'scope' },
+    claimsMapping: {
+      roles: 'realm_access.roles',
+      permissions: 'resource_access.my-client.roles',
+    },
     profiles: {
-        // RBAC: user must have at least one of these roles
-        admin: {
-          roles: { any: ['admin', 'superadmin'] },
-        },
+      // RBAC: user must have at least one of these roles
+      admin: {
+        roles: { any: ['admin', 'superadmin'] },
+      },
 
-        // ABAC: user must be authenticated (sub exists)
-        authenticated: {
-          attributes: {
-            conditions: [{ path: 'user.sub', op: 'exists', value: true }],
-          },
+      // ABAC: user must be authenticated (sub exists)
+      authenticated: {
+        attributes: {
+          conditions: [{ path: 'user.sub', op: 'exists', value: true }],
         },
+      },
 
-        // ABAC: tenant from JWT must match the tenantId input argument
-        matchTenant: {
-          attributes: {
-            conditions: [
-              { path: 'claims.org_id', op: 'eq', value: { fromInput: 'tenantId' } },
-            ],
-          },
+      // ABAC: tenant from JWT must match the tenantId input argument
+      matchTenant: {
+        attributes: {
+          conditions: [{ path: 'claims.org_id', op: 'eq', value: { fromInput: 'tenantId' } }],
         },
+      },
 
-        // RBAC: permission-based
-        canPublish: {
-          permissions: { all: ['content:publish'] },
-        },
+      // RBAC: permission-based
+      canPublish: {
+        permissions: { all: ['content:publish'] },
+      },
 
-        // Combined: role AND permission
-        editorWithPublish: {
-          roles: { any: ['editor'] },
-          permissions: { all: ['content:publish'] },
-          // operator defaults to 'AND', so both must pass
-        },
+      // Combined: role AND permission
+      editorWithPublish: {
+        roles: { any: ['editor'] },
+        permissions: { all: ['content:publish'] },
+        // operator defaults to 'AND', so both must pass
       },
     },
   },
@@ -78,8 +78,11 @@ export default class DeleteUserTool extends ToolContext {
   authorities: 'admin',
 })
 export default class InternalMetricsResource extends ResourceContext {
-  async read() {
-    // only admin can read this resource
+  async execute(uri: string, _params: Record<string, string>) {
+    // only admin can reach here
+    return {
+      contents: [{ uri, mimeType: 'application/json', text: JSON.stringify({ ok: true }) }],
+    };
   }
 }
 
@@ -246,13 +249,13 @@ This filtering happens automatically. No additional configuration is needed. Ent
 
 ## Profile Design Guidelines
 
-| Guideline | Example |
-| --- | --- |
-| Name profiles after the role or intent, not the technical check | `admin` not `hasAdminRole` |
-| Keep profiles single-purpose | `matchTenant` does tenant check only; combine with `['authenticated', 'matchTenant']` |
-| Use `allOf`/`anyOf` for complex compositions in inline policies | Do not create profiles that duplicate combinator logic |
-| Document your profiles in a central file | `types/authorities.d.ts` with augmentation and comments |
-| Test profiles with both authorized and unauthorized users | See `frontmcp-testing` skill for auth testing patterns |
+| Guideline                                                       | Example                                                                               |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Name profiles after the role or intent, not the technical check | `admin` not `hasAdminRole`                                                            |
+| Keep profiles single-purpose                                    | `matchTenant` does tenant check only; combine with `['authenticated', 'matchTenant']` |
+| Use `allOf`/`anyOf` for complex compositions in inline policies | Do not create profiles that duplicate combinator logic                                |
+| Document your profiles in a central file                        | `types/authorities.d.ts` with augmentation and comments                               |
+| Test profiles with both authorized and unauthorized users       | See `frontmcp-testing` skill for auth testing patterns                                |
 
 ## Reference
 

package/catalog/frontmcp-authorities/references/claims-mapping.md

@@ -234,6 +234,13 @@ authorities: {
     return {
       roles,
       permissions,
+      // Merge order matches the engine's default in
+      // `authorities.context.ts` (`{ ...authorizationClaims, ...user }`):
+      // spread the raw `authorization.claims` first, then `authInfo.user` so
+      // IdP-provided user fields (`sub`, `name`, `email`, `tenantId`, ...)
+      // override any same-named server-side authorization claim on conflict.
+      // Reverse this order only if you intentionally want authorization
+      // claims to win over user identity fields.
       claims: { ...claims, ...user },
     };
   },

package/catalog/frontmcp-authorities/references/custom-evaluators.md

@@ -12,7 +12,7 @@ When the built-in RBAC, ABAC, and ReBAC models do not cover your authorization r
 Every custom evaluator must implement the `AuthoritiesEvaluator` interface from `@frontmcp/auth`.
 
 ```typescript
-import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+import type { AuthoritiesEvaluationContext, AuthoritiesEvaluator, AuthoritiesResult } from '@frontmcp/auth';
 
 interface AuthoritiesEvaluator {
   /** Evaluator name (must match the key under `custom.*` in policies) */
@@ -30,13 +30,28 @@ The return value must be an `AuthoritiesResult`:
 interface AuthoritiesResult {
   /** Whether access was granted */
   granted: boolean;
-  /** Human-readable reason for denial */
+  /** Human-readable reason for denial (kept for backward compatibility) */
   deniedBy?: string;
+  /** Structured denial data (machine-parsable) */
+  denial?: AuthoritiesDenial;
   /** List of policy types that were evaluated (for audit) */
   evaluatedPolicies: string[];
   /** Optional detailed message */
   message?: string;
 }
+
+interface AuthoritiesDenial {
+  /** Which policy type caused the denial */
+  kind: 'roles' | 'permissions' | 'attributes' | 'relationships' | 'custom' | 'profile' | 'not' | 'allOf' | 'anyOf';
+  /** Dot-path into the policy that failed (e.g., "custom.ipAllowList") */
+  path: string;
+  /** Values that were required but missing */
+  missing?: string[];
+  /** Expected value */
+  expected?: unknown;
+  /** Actual value found */
+  actual?: unknown;
+}
 ```
 
 ## Registering Custom Evaluators
@@ -45,8 +60,9 @@ Custom evaluators are registered in the `evaluators` field of the `authorities`
 
 ```typescript
 import { FrontMcp } from '@frontmcp/sdk';
-import { ipAllowListEvaluator } from './evaluators/ip-allow-list';
+
 import { featureFlagEvaluator } from './evaluators/feature-flag';
+import { ipAllowListEvaluator } from './evaluators/ip-allow-list';
 import { timeWindowEvaluator } from './evaluators/time-window';
 
 @FrontMcp({
@@ -123,13 +139,41 @@ const featureFlagGuard: AuthoritiesEvaluator = {
 };
 ```
 
-### When to Use Custom Evaluators vs Hooks
+### When to Use Custom Evaluators vs Guards vs Hooks
+
+| Approach                                 | When to Use                                                                                       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| **Custom evaluator**                     | Reusable async check across many tools — register once, reference via `custom.<name>` in policies |
+| **`guards: AuthorityGuardFn[]`**         | One-off async check on a single entry — declare inline, no registration required                  |
+| **`Will('checkEntryAuthorities')` hook** | Cross-cutting pre/post logic across the whole flow stage (audit, logging, replacement)            |
+| **Static `authorities` policy**          | Roles, permissions, attributes — no I/O needed                                                    |
+
+#### Inline `guards` example
+
+```typescript
+import type { AuthorityGuardFn } from '@frontmcp/auth';
+
+const tenantInAllowlist: AuthorityGuardFn = async (ctx) => {
+  const tenantId = ctx.input['tenantId'] as string | undefined;
+  if (!tenantId) return 'tenantId missing from input';
+  const ok = await redis.sismember('allowed-tenants', tenantId);
+  return ok ? true : `tenant '${tenantId}' is not allowlisted`;
+};
+
+@Tool({
+  name: 'tenant_action',
+  authorities: {
+    roles: { any: ['user'] },
+    guards: [tenantInAllowlist],
+  },
+})
+export default class TenantActionTool extends ToolContext { ... }
+```
 
-| Approach                                 | When to Use                                                                          |
-| ---------------------------------------- | ------------------------------------------------------------------------------------ |
-| **Custom evaluator**                     | Reusable async check across many tools — register once, reference via `custom` field |
-| **`Will('checkEntryAuthorities')` hook** | One-off async check for a specific plugin/app, not tied to a specific tool           |
-| **Static `authorities` policy**          | Roles, permissions, attributes — no I/O needed                                       |
+Guards combine with sibling policy fields via `operator` (default AND). They are the
+simplest async authorization mechanism — no registry, no `name` field, no `custom.*`
+indirection — and are preferred over hooks for "this single entry needs an extra
+async check" scenarios.
 
 ## Using Custom Evaluators in Policies
 
@@ -156,7 +200,7 @@ Restricts access to requests from specific CIDR ranges.
 
 ```typescript
 // evaluators/ip-allow-list.ts
-import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+import type { AuthoritiesEvaluationContext, AuthoritiesEvaluator, AuthoritiesResult } from '@frontmcp/auth';
 
 interface IpAllowListPolicy {
   cidr: string[];
@@ -174,12 +218,17 @@ export const ipAllowListEvaluator: AuthoritiesEvaluator = {
   name: 'ipAllowList',
   async evaluate(policy: unknown, ctx: AuthoritiesEvaluationContext): Promise<AuthoritiesResult> {
     const { cidr } = policy as IpAllowListPolicy;
+    // The SDK does not populate ctx.env by default — the engine's `env` defaults to `{}`.
+    // To use this evaluator, populate `env.remoteIp` yourself: register an
+    // `Around('checkEntryAuthorities')` hook (or transport adapter middleware) that reads
+    // the request's remote IP (e.g., from `X-Forwarded-For`) and merges it into the
+    // evaluation context env before the engine runs.
     const remoteIp = ctx.env['remoteIp'] as string | undefined;
 
     if (!remoteIp) {
       return {
         granted: false,
-        deniedBy: 'custom.ipAllowList: remoteIp not available in env',
+        deniedBy: 'custom.ipAllowList: remoteIp not populated in env (configure a hook/middleware to set it)',
         evaluatedPolicies: ['custom.ipAllowList'],
       };
     }
@@ -215,7 +264,7 @@ Gates access behind a feature flag service.
 
 ```typescript
 // evaluators/feature-flag.ts
-import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+import type { AuthoritiesEvaluationContext, AuthoritiesEvaluator, AuthoritiesResult } from '@frontmcp/auth';
 
 interface FeatureFlagPolicy {
   flag: string;
@@ -264,7 +313,7 @@ Restricts access to specific time windows (e.g., business hours only).
 
 ```typescript
 // evaluators/time-window.ts
-import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+import type { AuthoritiesEvaluationContext, AuthoritiesEvaluator, AuthoritiesResult } from '@frontmcp/auth';
 
 interface TimeWindowPolicy {
   /** Allowed days (0=Sunday, 6=Saturday) */
@@ -334,7 +383,7 @@ Denies access when a per-user rate limit is exceeded.
 
 ```typescript
 // evaluators/rate-limit.ts
-import type { AuthoritiesEvaluator, AuthoritiesEvaluationContext, AuthoritiesResult } from '@frontmcp/auth';
+import type { AuthoritiesEvaluationContext, AuthoritiesEvaluator, AuthoritiesResult } from '@frontmcp/auth';
 
 interface RateLimitPolicy {
   /** Maximum calls allowed */

package/catalog/frontmcp-channels/SKILL.md

@@ -115,6 +115,42 @@ Build push-based notification channels that stream real-time events into Claude
 | Duplicate notifications      | Multiple sessions subscribed    | This is correct behavior -- each session gets its own copy         |
 | Events lost on reconnect     | Channels are in-memory          | Channel state resets on server restart; use persistent sources     |
 
+## Examples
+
+Each reference has matching examples under [`examples/<reference>/`](./examples/):
+
+### `channel-sources`
+
+| Example                                                                | Level        | Description                                                                                                                      |
+| ---------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| [`webhook-github`](./examples/channel-sources/webhook-github.md)       | Basic        | Forward GitHub webhook events (PRs, pushes, CI) into Claude Code                                                                 |
+| [`app-errors`](./examples/channel-sources/app-errors.md)               | Basic        | Forward application errors to Claude Code via the in-process event bus                                                           |
+| [`agent-notify`](./examples/channel-sources/agent-notify.md)           | Intermediate | Notify Claude Code when AI agents complete their tasks                                                                           |
+| [`job-completion`](./examples/channel-sources/job-completion.md)       | Intermediate | Notify Claude Code when background jobs and workflows complete                                                                   |
+| [`service-connector`](./examples/channel-sources/service-connector.md) | Advanced     | Build a persistent service connector that lets Claude send and receive messages through WhatsApp, Telegram, or any messaging API |
+| [`file-watcher`](./examples/channel-sources/file-watcher.md)           | Intermediate | Watch files for changes and notify Claude Code in real-time                                                                      |
+| [`replay-buffer`](./examples/channel-sources/replay-buffer.md)         | Advanced     | Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline                       |
+
+### `channel-two-way`
+
+| Example                                                            | Level    | Description                                                                            |
+| ------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------- |
+| [`whatsapp-bridge`](./examples/channel-two-way/whatsapp-bridge.md) | Advanced | Full WhatsApp Business API bridge allowing users to chat with Claude Code via WhatsApp |
+
+## Accessing This Skill
+
+Skills are distributed as plain SKILL.md files plus a sibling `references/`
+and `examples/` tree, so consumers can pick whichever access mode fits:
+
+| Mode               | How it works                                                                                                                                                                                                                                                                                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem**     | Read `libs/skills/catalog/frontmcp-channels/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point.                                                                                                                                                                               |
+| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-channels`, `frontmcp skills read frontmcp-channels:references/<file>.md`, `frontmcp skills install frontmcp-channels` — no server required.                                                                                                                                                  |
+| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-channels/SKILL.md`, `skill://frontmcp-channels/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |
+
+The catalog itself is **not** an MCP server. The `skill://` URIs only resolve
+when a server has been configured to host this skill.
+
 ## Reference
 
 - [Claude Code Channels Reference](https://code.claude.com/docs/en/channels-reference)

package/catalog/frontmcp-channels/examples/channel-sources/file-watcher.md

@@ -19,9 +19,15 @@ Watch files for changes and notify Claude Code in real-time
 
 ```typescript
 // src/apps/monitoring/channels/log-watcher.channel.ts
-import { Channel, ChannelContext } from '@frontmcp/sdk';
-import type { ChannelNotification } from '@frontmcp/sdk';
+
+// NOTE: We normally read/write files via `@frontmcp/utils`, but it does not
+// expose a file-watcher helper because watching is platform-specific (inotify
+// on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows) and not
+// available in browser/edge runtimes. `node:fs` is the right call here; this
+// channel is Node-only by design.
 import { watch } from 'node:fs';
+
+import { Channel, ChannelContext, type ChannelNotification } from '@frontmcp/sdk';
 import { readFile } from '@frontmcp/utils';
 
 @Channel({