Add TypeScript SDK and examples for the Skills Extension SEP

.gitignore

@@ -1 +1,3 @@
 .claude/settings.local.json
+node_modules/
+dist/

examples/README.md

@@ -0,0 +1,147 @@
+# Skills Extension SEP — Architecture
+
+## How It All Fits Together
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                              HOST                                   │
+│                                                                     │
+│  ┌───────────────┐    Exposes to model:                             │
+│  │  read_resource │◄── { server, uri }                              │
+│  │     (tool)     │    "Read an MCP resource from a connected       │
+│  └───────┬───────┘     server."                                     │
+│          │                                                          │
+│          │  Routes by server name                                   │
+│          ▼                                                          │
+│  ┌───────────────┐         ┌───────────────┐                        │
+│  │  MCP Client A  │         │  MCP Client B  │   ...                │
+│  └───────┬───────┘         └───────────────┘                        │
+└──────────┼──────────────────────────────────────────────────────────┘
+           │ stdio / SSE
+           ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                         MCP SERVER                                   │
+│                                                                      │
+│  capabilities.extensions: { "io.modelcontextprotocol/skills": {} }   │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐   │
+│  │                    Skills Extension SDK                        │   │
+│  │                                                                │   │
+│  │  discoverSkills(skillsDir)                                     │   │
+│  │    ├── Recursively finds SKILL.md files                        │   │
+│  │    ├── Parses YAML frontmatter (name, description)             │   │
+│  │    ├── Validates: final path segment == frontmatter name       │   │
+│  │    ├── Enforces no-nesting constraint                          │   │
+│  │    └── Returns Map<skillPath, SkillMetadata>                   │   │
+│  │                                                                │   │
+│  │  registerSkillResources(server, skillMap, skillsDir)           │   │
+│  │    ├── skill://{path}/SKILL.md     (listed, per skill)         │   │
+│  │    ├── skill://{path}/_manifest    (listed, per skill)         │   │
+│  │    ├── skill://{+filePath}         (template, supporting)      │   │
+│  │    └── skill://prompt-xml          (optional, XML summary)     │   │
+│  │                                                                │   │
+│  │  SEP-2093 shims (resource-extensions.ts)                       │   │
+│  │    ├── resources/metadata          (metadata without content)  │   │
+│  │    ├── resources/list + uri param  (scoped enumeration)        │   │
+│  │    └── _meta capabilities          (per-resource capabilities) │   │
+│  └────────────────────────────────────────────────────────────────┘   │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐   │
+│  │                      Skills Directory                          │   │
+│  │                                                                │   │
+│  │  sample-skills/                                                │   │
+│  │  ├── code-review/                                              │   │
+│  │  │   ├── SKILL.md          ──► skill://code-review/SKILL.md    │   │
+│  │  │   └── references/                                           │   │
+│  │  │       └── REFERENCE.md  ──► skill://code-review/ref...md    │   │
+│  │  ├── git-commit-review/                                        │   │
+│  │  │   └── SKILL.md          ──► skill://git-commit-review/...   │   │
+│  │  └── acme/                      ◄── organizational prefix      │   │
+│  │      ├── billing/                                              │   │
+│  │      │   └── refunds/           ◄── name = "refunds"           │   │
+│  │      │       ├── SKILL.md  ──► skill://acme/billing/refunds/.. │   │
+│  │      │       └── templates/                                    │   │
+│  │      │           └── email ──► skill://acme/billing/refunds/.. │   │
+│  │      └── onboarding/            ◄── name = "onboarding"        │   │
+│  │          └── SKILL.md      ──► skill://acme/onboarding/...     │   │
+│  └────────────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Skill URI Structure
+
+```
+skill://<skill-path>/SKILL.md
+        ├──────────┘ └──────┘
+        │                │
+        │                └── file-path (always explicit)
+        │
+        └── locator: prefix + name
+            ├── prefix: server-chosen (e.g., "acme/billing")
+            └── name:   final segment = frontmatter name (e.g., "refunds")
+```
+
+## Discovery Flow
+
+```
+Host                           Server
+ │                               │
+ │  initialize ──────────────►   │
+ │  ◄──── capabilities:          │
+ │        extensions:             │
+ │          io.modelcontextprotocol/skills: {}
+ │                               │
+ │  resources/list ──────────►   │  Returns all resources
+ │  ◄──── skill://*/SKILL.md     │  (client filters for skill://)
+ │        entries                 │
+ │                               │
+ │  resources/list ──────────►   │  SEP-2093: scoped
+ │    { uri: "skill://" }        │  Returns only SKILL.md entries
+ │  ◄──── filtered list          │
+ │                               │
+ │  resources/metadata ──────►   │  SEP-2093: metadata only
+ │    { uri: "skill://..." }     │  No content transferred
+ │  ◄──── { resource: { name,   │
+ │         description, caps } } │
+ │                               │
+ │  resources/read ──────────►   │  Load skill content
+ │    { uri: "skill://..." }     │
+ │  ◄──── { contents: [{ text:  │
+ │         "---\nname: ...\n..." │
+ │         }] }                  │
+ │                               │
+```
+
+## SDK Wrapper Mapping
+
+```
+SEP Concept                  SDK Function               Protocol Call
+─────────────────────────────────────────────────────────────────────
+Host tool for model          READ_RESOURCE_TOOL          (tool schema)
+Discover skills              listSkills()                resources/list
+Scoped discovery             listSkillsScoped(uri)       resources/list + uri
+Read any skill URI           readSkillUri(uri)           resources/read
+Read by path                 readSkillContent(path)      resources/read
+Metadata without content     fetchSkillMetadata(uri)     resources/metadata
+File manifest                readSkillManifest(path)     resources/read
+Supporting files             readSkillDocument(path,f)   resources/read
+```
+
+## What's a Shim vs What's the SEP
+
+```
+┌──────────────────────────────┬────────────────────────────────────┐
+│        SEP (permanent)       │     SDK Shims (temporary)          │
+├──────────────────────────────┼────────────────────────────────────┤
+│ skill:// URI convention      │ _requestHandlers override          │
+│ SKILL.md explicit in URI     │ capabilities in _meta              │
+│ Final segment = name         │                                    │
+│ No-nesting constraint        │ Tracking PRs:                      │
+│ resources/read for loading   │  - SEP-2093 (uri param, metadata,  │
+│ resources/list for discovery │    per-resource capabilities)      │
+│ resources/metadata (2093)    │                                    │
+│ read_resource host tool      │ Resolved (SDK v1.29.0):            │
+│ Extension declaration        │  - typescript-sdk#1630 (extensions)│
+│ listSkills / readSkillUri    │  - typescript-sdk#1575 (size field)│
+└──────────────────────────────┴────────────────────────────────────┘
+```

examples/sample-skills/acme/billing/refunds/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: refunds
+description: Process customer refund requests following Acme Corp billing policies. Guides agents through eligibility checks, approval workflows, and customer communication.
+metadata:
+  author: acme-billing-team
+  version: "1.0"
+---
+
+# Billing Refunds
+
+Process customer refund requests following Acme Corp billing policies.
+
+## When to Use
+
+- Customer requests a refund for a product or service
+- Agent needs to evaluate refund eligibility
+- Escalation is needed for refunds above threshold
+
+## Process
+
+1. **Verify the customer** — confirm identity and locate the original transaction
+2. **Check eligibility** — verify the request falls within the refund window (30 days for products, 14 days for services)
+3. **Assess the reason** — categorize as: defective, not as described, changed mind, duplicate charge, or unauthorized
+4. **Apply policy rules**:
+   - Defective/unauthorized: full refund, no questions
+   - Not as described: full refund with return required
+   - Changed mind: refund minus 15% restocking fee
+   - Duplicate charge: full refund automatically
+5. **Check approval thresholds**:
+   - Under $100: auto-approve
+   - $100–$500: team lead approval
+   - Over $500: manager approval
+6. **Process and communicate** — issue the refund and send confirmation using the email template
+
+## Templates
+
+See `templates/refund-email-template.md` for the customer communication template.
+
+## Important Notes
+
+- Always log the refund reason for analytics
+- Never promise a specific timeline — say "within 5-10 business days"
+- If the customer is upset, escalate to a human agent

examples/sample-skills/acme/billing/refunds/templates/refund-email-template.md

@@ -0,0 +1,32 @@
+# Refund Confirmation Email Template
+
+## Subject Line
+
+Refund Processed — Order #{ORDER_ID}
+
+## Body
+
+Dear {CUSTOMER_NAME},
+
+We've processed your refund request for order #{ORDER_ID}.
+
+**Refund Details:**
+- Original amount: ${ORIGINAL_AMOUNT}
+- Refund amount: ${REFUND_AMOUNT}
+- Reason: {REFUND_REASON}
+- Reference number: {REFUND_REFERENCE}
+
+The refund will appear on your original payment method within 5-10 business days.
+
+If you have any questions, please don't hesitate to reach out to our support team.
+
+Best regards,
+Acme Corp Billing Team
+
+---
+
+## Usage Notes
+
+- Replace all `{PLACEHOLDER}` values with actual data
+- For partial refunds, include a line explaining the difference
+- For restocking fee deductions, add: "A 15% restocking fee of ${FEE_AMOUNT} has been applied per our return policy."

examples/sample-skills/acme/onboarding/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: onboarding
+description: Guide new employee onboarding process for Acme Corp. Covers IT setup, team introductions, and first-week checklist.
+metadata:
+  author: acme-hr-team
+  version: "1.0"
+---
+
+# Employee Onboarding
+
+Guide the new employee onboarding process for Acme Corp.
+
+## When to Use
+
+- A new employee is joining the team
+- HR or a manager needs help with onboarding steps
+- New hire asks about their first-week tasks
+
+## Pre-Start Checklist
+
+1. **IT Setup** — request laptop, email account, and VPN access
+2. **Access provisioning** — add to relevant Slack channels, GitHub org, and internal tools
+3. **Workspace** — assign desk/office or ship remote work equipment
+4. **Documentation** — prepare offer letter, NDA, and benefits enrollment forms
+
+## First Day
+
+1. Welcome meeting with manager (30 min)
+2. IT setup walkthrough — verify all accounts and access
+3. Team introduction — brief round of introductions
+4. Buddy assignment — pair with an experienced team member
+5. Company overview — mission, values, org structure
+
+## First Week
+
+1. Complete all compliance training modules
+2. Attend department orientation
+3. Set up development environment (engineering roles)
+4. Schedule 1:1s with key stakeholders
+5. Review team documentation and README files
+6. First small task or PR (engineering roles)
+
+## 30-60-90 Day Goals
+
+- **30 days**: Understand team processes, complete initial training, ship first contribution
+- **60 days**: Own a small project or feature independently
+- **90 days**: Full velocity, participate in on-call rotation (if applicable)

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`.
+
+## 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)