Add Skills as Resources reference implementation

.gitignore

@@ -1 +1,11 @@
 .claude/settings.local.json
+
+# Local reference repos and planning docs
+TODO.md
+
+# Build artifacts
+node_modules/
+dist/
+__pycache__/
+*.egg-info/
+.eggs/

examples/sample-skills/code-review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: code-review
+description: Perform structured code reviews focusing on correctness, readability, and maintainability. Use when asked to review code changes or pull requests.
+metadata:
+  author: skills-over-mcp-ig
+  version: "0.1"
+---
+
+# Code Review
+
+Perform structured code reviews using a consistent methodology.
+
+## When to Use
+
+- User asks you to review code, a diff, or a pull request
+- User asks for feedback on code quality
+- You are evaluating code changes before merge
+
+## Process
+
+1. **Understand the context** — read the PR description or ask what the change is trying to accomplish
+2. **Review for correctness** — does the code do what it claims? Are there logic errors, off-by-one bugs, or unhandled edge cases?
+3. **Review for security** — check for injection vulnerabilities, improper input validation, hardcoded secrets, and OWASP top 10 issues
+4. **Review for readability** — are names clear? Is the structure easy to follow? Is there unnecessary complexity?
+5. **Review for maintainability** — is the code testable? Are dependencies reasonable? Will this be easy to change later?
+6. **Check the tests** — are there tests? Do they cover the important cases? Are they testing behavior, not implementation?
+
+## Severity Levels
+
+- **Blocker**: Must fix before merge (security issues, data loss risk, broken functionality)
+- **Major**: Should fix before merge (logic errors, missing edge cases, poor error handling)
+- **Minor**: Nice to fix (naming, style, minor simplifications)
+- **Nit**: Optional (personal preference, cosmetic)
+
+## Reference
+
+For a detailed checklist, see `references/REFERENCE.md` in this skill's directory.
+
+## Output Format
+
+For each finding:
+- **File and line**: Where the issue is
+- **Severity**: Blocker / Major / Minor / Nit
+- **Issue**: What's wrong
+- **Suggestion**: How to fix it
+
+End with an overall summary: approve, request changes, or comment.

examples/sample-skills/code-review/references/REFERENCE.md

@@ -0,0 +1,36 @@
+# Code Review Checklist
+
+## Correctness
+- [ ] Logic matches the stated intent
+- [ ] Edge cases handled (null, empty, boundary values)
+- [ ] Error paths return meaningful messages
+- [ ] Async operations properly awaited
+- [ ] Resources cleaned up (connections, file handles, timers)
+
+## Security
+- [ ] User input validated and sanitized
+- [ ] No SQL injection, XSS, or command injection vectors
+- [ ] No hardcoded secrets or credentials
+- [ ] Authentication/authorization checks in place
+- [ ] Sensitive data not logged or exposed in errors
+
+## Readability
+- [ ] Names describe purpose (not implementation)
+- [ ] Functions do one thing
+- [ ] No deeply nested conditionals (max 3 levels)
+- [ ] Comments explain "why", not "what"
+- [ ] Consistent formatting with project style
+
+## Maintainability
+- [ ] No code duplication (DRY where appropriate)
+- [ ] Dependencies are justified
+- [ ] Configuration externalized (not hardcoded)
+- [ ] Backward compatibility considered
+- [ ] Migration path documented if breaking
+
+## Testing
+- [ ] Tests exist for new/changed behavior
+- [ ] Tests cover happy path and error cases
+- [ ] Tests are independent (no shared mutable state)
+- [ ] Test names describe the scenario
+- [ ] No flaky tests (timing, ordering, external dependencies)

examples/sample-skills/git-commit-review/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: git-commit-review
+description: Review git commits for quality, conventional commit format compliance, and potential issues. Use when asked to review commits or improve commit messages.
+metadata:
+  author: skills-over-mcp-ig
+  version: "0.1"
+---
+
+# Git Commit Review
+
+Review git commits against conventional commit standards and common quality issues.
+
+## When to Use
+
+- User asks you to review a commit or commit message
+- User asks for help improving commit quality
+- You are reviewing a PR and want to assess commit hygiene
+
+## Process
+
+1. **Read the commit message** — check for conventional commit format: `type(scope): description`
+2. **Verify the type** — must be one of: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`, `build`, `perf`
+3. **Check the description** — should be imperative mood, lowercase, no period at end, under 72 characters
+4. **Review the body** (if present) — should explain *why* not *what*, wrapped at 72 characters
+5. **Check for breaking changes** — must include `BREAKING CHANGE:` footer or `!` after type/scope
+6. **Assess the diff** — does the commit message accurately describe the changes?
+
+## Common Issues
+
+- Vague messages ("fix stuff", "update code", "wip")
+- Type mismatch (using `feat` for a bug fix)
+- Scope too broad (single commit touching unrelated files)
+- Missing breaking change annotation
+- Commit contains unrelated changes that should be separate commits
+
+## Output Format
+
+Provide a structured review:
+- **Format**: Pass/Fail with specific issues
+- **Message quality**: Rating and suggestions
+- **Scope assessment**: Whether changes match the stated scope
+- **Recommendations**: Concrete improvements

examples/skills-as-resources/README.md

@@ -0,0 +1,187 @@
+# Skills as Resources — Reference Implementation
+
+> **Experimental** — This is a reference implementation for evaluation by the Skills Over MCP Interest Group.
+
+## Pattern Overview
+
+This example demonstrates the **Resources approach** from [`docs/approaches.md`](../../docs/approaches.md): exposing agent skills via MCP resources using the `skill://` URI scheme, combined with a `load_skill` tool for model-controlled progressive disclosure.
+
+An MCP server scans a directory for SKILL.md files and exposes them as resources and tools:
+
+| Type | Name / URI | MIME Type | Purpose |
+| :--- | :--- | :--- | :--- |
+| Resource | `skill://{name}/SKILL.md` | `text/markdown` | Full SKILL.md content (listed) |
+| Resource | `skill://{name}/_manifest` | `application/json` | File inventory with SHA256 hashes (listed) |
+| Resource | `skill://{name}/{+path}` | varies | Supporting file (template, not listed); text files return UTF-8 content, binary files return base64-encoded blobs |
+| Resource | `skill://prompt-xml` | `application/xml` | XML for system prompt injection (optional) |
+| Tool | `load_skill` | — | Model-controlled skill loading |
+
+The URI scheme is aligned with the [SkillsDotNet](https://github.com/bradwilson/skillsdotnet) conventions, enabling interoperability between TypeScript and C# implementations. Clients can discover skills by scanning `resources/list` for URIs matching `skill://*/SKILL.md`.
+
+This is a **hybrid** approach: resources provide **application-controlled** access (the host/client decides when to read), while the `load_skill` tool provides **model-controlled** access (the LLM decides when to invoke). See [Open Question #9](../../docs/open-questions.md) for the control model discussion.
+
+## How It Works
+
+```
+┌─────────────┐     ┌──────────────────────┐     ┌──────────────┐
+│  MCP Client  │────▶│  Skills as Resources  │────▶│  Skill Files  │
+│  (e.g. Claude│◀────│     MCP Server        │◀────│  (SKILL.md)   │
+│   Code)      │     └──────────────────────┘     └──────────────┘
+└─────────────┘
+```
+
+1. **Startup**: Server scans the configured skills directory for `*/SKILL.md` (or `skill.md`) files and supplementary documents; computes SHA256 hashes and builds file manifests
+2. **Discovery**: Parses YAML frontmatter to extract `name` and `description`
+3. **Registration**: Registers static resources (`SKILL.md` + `_manifest`) for each skill, a `ResourceTemplate` for supporting files with auto-completion hints (skill name and file path), and a `load_skill` tool
+4. **Progressive disclosure** (two paths):
+   - **Application-controlled** (via resources): `resources/list` → scan for `skill://*/SKILL.md` → read `skill://{name}/SKILL.md` on demand → read `skill://{name}/_manifest` for file inventory → read `skill://{name}/{path}` for supporting files
+   - **Model-controlled** (via tool): `tools/list` → discover `load_skill` with available skill names in description → call `load_skill("code-review")` to get full content
+5. **System prompt injection**: `skill://prompt-xml` provides XML that hosts can inject into system prompts
+6. **Capability declaration**: Server declares `resources.listChanged` and `resources.subscribe` capabilities
+7. **Resource subscriptions**: Clients can call `resources/subscribe` on any `skill://` URI to receive `notifications/resources/updated` when the underlying file(s) change on disk. Watchers are created on-demand via [chokidar](https://github.com/paulmillr/chokidar) and cleaned up on unsubscribe.
+8. **Dynamic skill management (hot-reload)**: The server watches the skills directory for structural changes — new or removed skill subdirectories and `SKILL.md` files appearing or disappearing. When changes are detected (debounced at 500ms), the server re-scans the directory: new skills get their `SKILL.md` and `_manifest` resources registered, removed skills get their resources unregistered and subscriptions cleaned up, and the `load_skill` tool description is updated with the current skill list. A `notifications/resources/list_changed` notification is sent to connected clients so they can refresh their resource lists.
+
+## Implementations
+
+### TypeScript
+
+**Prerequisites**: Node.js >= 18, npm
+
+```bash
+cd typescript
+npm install
+npm run build
+```
+
+**Run with MCP Inspector**:
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js ../../sample-skills
+```
+
+**Development mode** (no build step):
+```bash
+npm run dev -- ../../sample-skills
+```
+
+### Options
+
+| Flag | Default | Description |
+| :--- | :--- | :--- |
+| `[skillsDir]` | `examples/sample-skills/` | Path to the skills directory |
+| `--no-embed-catalog` | off (catalog embedded) | Disable embedding `<available_skills>` XML in the `load_skill` tool description. Use when the client already injects skill context from resources, to avoid duplicate injection. |
+
+**Example** — disable catalog embedding for a client with native `skill://` support:
+```bash
+node dist/index.js ../../sample-skills --no-embed-catalog
+```
+
+## Security Features
+
+The implementation includes:
+
+- **Path traversal protection** — Resolved paths are checked against the skills directory boundary using `realpathSync`. Symlink escapes are detected.
+- **Skill name validation** — Resources and the `load_skill` tool look up names by key in the discovered skills map. User input is never used to construct file paths.
+- **File path validation** — Paths containing `..` are rejected. All paths are verified to be within the skills directory.
+- **File size limits** — Files larger than 1MB are skipped during discovery and rejected on read.
+- **Safe YAML parsing** — Uses the `yaml` package which is safe by default.
+- **Content integrity** — The `_manifest` resource includes SHA256 hashes for all files, enabling clients to verify downloaded content.
+
+## Sample Skills
+
+Two shared sample skills are included in [`examples/sample-skills/`](../../sample-skills/) for testing:
+
+| Skill | Description | Documents | Notes |
+| :--- | :--- | :--- | :--- |
+| `code-review` | Structured code review methodology | `references/REFERENCE.md` | Tests document scanning, `_manifest` with hashes, and `ResourceTemplate` |
+| `git-commit-review` | Review commits for quality and conventional format | None | Tests basic skill resource with no supporting files |
+
+## Key Design Decisions
+
+- **Hybrid approach (resources + tool)**: Resources provide application-controlled access for hosts that want to manage context. The `load_skill` tool provides model-controlled access for progressive disclosure. Experimental findings show models reliably use tools but tend to ignore resources (see [`docs/experimental-findings.md`](../../docs/experimental-findings.md)), making the hybrid approach more practical than resources alone.
+- **`load_skill` per server — duplication trade-off**: Including `load_skill` in each skill server means clients with native `skill://` resource loading support see duplicate context — the client already parsed frontmatter from resources AND the tool description lists available skills. However, for clients *without* native support for loading skills as resources, `load_skill` is the only way to provide skills via MCP without manually selecting resources. The `--no-embed-catalog` flag mitigates description-level duplication. Long-term, `load_skill` may be better served as a well-known client-side tool (like [SkillsDotNet](https://github.com/pederhp/skillsdotnet)'s `SkillCatalog`) or a generic `load_resource` tool, avoiding per-server duplication entirely. See [PR #16 discussion](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/16#discussion_r2829745543) for context.
+- **URI scheme aligned with skillsdotnet**: The `skill://{name}/SKILL.md` and `skill://{name}/_manifest` URI conventions match the [SkillsDotNet](https://github.com/pederhp/skillsdotnet) C# implementation. This enables cross-implementation interoperability — a client-side `SkillCatalog` can discover skills from either implementation by scanning `resources/list` for `skill://*/SKILL.md` URIs.
+- **`_manifest` with SHA256 hashes**: Pre-computed at startup with file sizes and content hashes. Enables download/sync workflows and cache invalidation without re-reading files on each request.
+- **Listed resources for skills, template for supporting files**: Each skill's `SKILL.md` and `_manifest` are concrete resources visible in `resources/list`. Supporting files are accessed via a `ResourceTemplate` (`skill://{name}/{+path}`) and are discoverable through the `_manifest` — keeping `resources/list` clean.
+- **`skill://prompt-xml` for injection**: Optional convenience resource that allows hosts to inject skill awareness into system prompts using the resources primitive.
+
+## Resource Annotations
+
+All resources include MCP [resource annotations](https://modelcontextprotocol.io/specification/draft/server/resources#annotations) to help clients filter, prioritize, and display skill resources appropriately.
+
+| Resource | `audience` | `priority` | `lastModified` |
+| :--- | :--- | :--- | :--- |
+| `skill://{name}/SKILL.md` | `["user", "assistant"]` | `1.0` | SKILL.md file mtime |
+| `skill://{name}/_manifest` | `["user", "assistant"]` | `0.5` | SKILL.md file mtime |
+| `skill://{name}/{+path}` | `["user", "assistant"]` | `0.2` | — |
+| `skill://prompt-xml` | `["user", "assistant"]` | `0.3` | — |
+
+All resources default to both audiences. The [Agent Skills specification](https://agentskills.org) is actively discussing a frontmatter `metadata` field (e.g., `invocation: model | user`) that would allow skill authors to narrow the intended audience per-skill. When that is finalized, this implementation will parse it from `metadata` and map it to the MCP `audience` annotation accordingly.
+
+### Priority Scale
+
+- **1.0** — Primary skill content (SKILL.md). Clients should include these in context.
+- **0.5** — Supporting metadata (\_manifest). Include if context budget allows.
+- **0.3** — Convenience resources (prompt-xml). Optional.
+- **0.2** — Supporting files (template). Load on demand only.
+
+## Answers to Open Question #12
+
+> "Why not just use resources?"
+
+This implementation shows that resources **do work** for skill delivery, and that combining them with a `load_skill` tool creates a more practical system. Key findings for evaluation:
+
+- **Discovery**: Skills appear in `resources/list` as `skill://*/SKILL.md`, making them immediately visible to any MCP-aware client. The `load_skill` tool description also lists available skills for model discovery.
+- **Progressive disclosure**: The URI hierarchy (`SKILL.md` → `_manifest` → `{path}`) provides layered loading. The `load_skill` tool provides an alternative on-demand loading path.
+- **System prompt injection**: `skill://prompt-xml` provides a clean mechanism for hosts to inject skill awareness
+- **Control model**: The hybrid approach gives both the host (via resources) and the model (via `load_skill` tool) agency over when skill content gets loaded
+- **Interoperability**: The `skill://` URI convention is shared with skillsdotnet, enabling cross-implementation discovery
+
+## Relationship to Other Approaches
+
+| Approach | How it differs |
+| :--- | :--- |
+| **1. Skills as Primitives** (SEP-2076) | Uses dedicated `skills/list` and `skills/get` protocol methods instead of resources |
+| **3. Skills as Tools** (sibling example) | Uses MCP tools only (model-controlled) instead of the hybrid resources + tool approach |
+| **5. Server Instructions** | Uses server instructions to point to resources instead of exposing resources directly |
+| **6. Convention** | This example could become part of a documented convention pattern |
+
+## Borrowing From SkillsDotNet
+
+The URI scheme in this implementation is aligned with [SkillsDotNet](https://github.com/pederhp/skillsdotnet), a C# implementation of the same pattern. Both implementations use:
+
+- `skill://{name}/SKILL.md` — listed resource for skill content
+- `skill://{name}/_manifest` — listed resource for file inventory (with SHA256 hashes)
+- `skill://{name}/{+path}` — resource template for supporting files
+
+1. Scan `resources/list` for URIs matching `skill://*/SKILL.md`
+2. Read each SKILL.md to extract frontmatter (name + description)
+3. Build compact context summaries for the system prompt (~50-100 tokens per skill)
+4. Expose a `load_skill` tool/function for on-demand full content loading
+
+## Comparison to FastMCP Implementation
+
+[FastMCP](https://github.com/jlowin/fastmcp) includes support for the `skill://` URI scheme through its [Skills Provider](https://gofastmcp.com/servers/providers/skills). Both FastMCP and this implementation converge on:
+
+- Same three-tier resource model: listed `SKILL.md` + listed `_manifest` + template for supporting files
+- Same manifest format: `{ skill, files: [{ path, size, hash }] }` with `sha256:<hex>` hashes
+- Same discovery model: scan for `SKILL.md` frontmatter, enumerate supporting files, pre-compute hashes
+- Same security model: path traversal prevention, symlink resolution, MIME type detection
+
+Key architectural differences:
+
+| Aspect | This implementation | FastMCP |
+| :--- | :--- | :--- |
+| Reactivity | Push-based (file watching + subscriptions) | Poll-based (optional re-scan on request) |
+| Access model | Hybrid: Resources + `load_skill` server tool | Resources + client utilities |
+| Architecture | Flat, single-server | Layered provider hierarchy with vendor presets (Claude, Cursor, Codex, Gemini, etc.) |
+| Client utilities | Server-only | Includes `list_skills`, `download_skill`, `sync_skills` for skill distribution |
+| System prompt injection | Optional `skill://prompt-xml` resource + tool description embedding | Not implemented (relies on client) |
+| Resource annotations | `audience`, `priority`, `lastModified` on all resources | Not set (uses internal metadata) |
+
+## Inspirations and Attribution
+
+This reference implementation derives from:
+
+- **[skills-over-mcp](https://github.com/keithagroves/skills-over-mcp)** by [Keith Groves](https://github.com/keithagroves) — Resource-based skill exposure, `skill://` URI scheme, JSON index, XML prompt injection, document templates
+- **[skilljack-mcp](https://github.com/olaservo/skilljack-mcp)** by [Ola Hungerford](https://github.com/olaservo) — Resource template patterns, subscription architecture, path security
+- **[skillsdotnet](https://github.com/PederHP/skillsdotnet)** by [Peder HP](https://github.com/PederHP) — `_manifest` resource with file hashes, `load_skill` tool, `SkillCatalog` client-side pattern, URI scheme conventions