Add TypeScript SDK for the Skills Extension SEP

.gitignore

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

examples/README.md

@@ -0,0 +1,76 @@
+# Skills Extension SEP — Reference Examples
+
+End-to-end TypeScript reference for [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) (Skills Extension), exercising every normative surface in the SEP against the bundled SDK.
+
+## Layout
+
+```
+examples/
+├── sample-skills/                  ← individually-served skills (4 skill-md entries)
+│   ├── code-review/
+│   │   ├── SKILL.md
+│   │   └── references/REFERENCE.md
+│   ├── git-commit-review/SKILL.md
+│   └── acme/
+│       ├── onboarding/SKILL.md
+│       └── billing/refunds/
+│           ├── SKILL.md
+│           └── templates/refund-email-template.md
+│
+├── sample-archive-source/          ← packed at server startup → archive entry
+│   └── pdf-processing/
+│       ├── SKILL.md
+│       └── references/FORMS.md
+│
+├── skills-server/typescript/       ← MCP server using @modelcontextprotocol/experimental-ext-skills/server
+│   ├── package.json
+│   ├── tsconfig.json
+│   └── src/
+│       ├── index.ts                ← discovers, registers, declares capability
+│       └── pack-archive.ts         ← in-memory tar.gz packer (example-only)
+│
+└── skills-client/typescript/       ← MCP client using @modelcontextprotocol/experimental-ext-skills/client
+    ├── package.json
+    ├── tsconfig.json
+    └── src/index.ts                ← walks every client-side surface
+```
+
+## What it demonstrates
+
+| SEP feature | Server | Client |
+|---|---|---|
+| Capability declaration `io.modelcontextprotocol/skills` (`directoryRead: true`) | `declareSkillsExtension(server, { directoryRead: true })` | observed in `initialize` response |
+| `skill://` scheme + multi-segment paths | 4 file skills, 1 multi-segment (`acme/billing/refunds`) | parses each URI |
+| `skill://index.json` enumeration (verbatim frontmatter, `url`+`digest`, `archives`) | generated by `registerSkillResources()` | `listSkillsFromIndex()` |
+| File-skill entries (`url` + `digest`) | each discovered SKILL.md | resolved as `uri`, digest carried on the summary |
+| Archive entries (`.tar.gz`, in `archives[]`) | `pdf-processing` packed at startup | `readSkillArchive()` fetches + unpacks |
+| `resources/directory/read` (`inode/directory`) | handler installed via `directoryRead: true` | `readDirectory()` / `walkDirectory()` |
+| Digest verification | `sha256:` digests emitted in the index | `verifyDigest()` against the read |
+| Supporting-file flow | catch-all template `skill://{+skillFilePath}` | `readSkillDocument()` |
+| `read_resource` tool schema | n/a (host concern) | `READ_RESOURCE_TOOL` exported |
+
+## Run it
+
+```bash
+# Build the SDK first (workspace dep)
+cd typescript/sdk
+npm install
+npm run build
+
+# Build the example server
+cd ../../examples/skills-server/typescript
+npm install
+npm run build
+
+# Build and run the example client (it spawns the server via stdio)
+cd ../../skills-client/typescript
+npm install
+npm run build
+npm start
+```
+
+The client output walks through its sections, each demonstrating one SEP surface — index discovery, `resources/directory/read` enumeration, fallback enumeration, skill-md reads, archive fetch+unpack, digest verification, and the supporting-file flow.
+
+## Archive safety
+
+The pdf-processing archive demo exercises the SEP's archive-safety requirements end-to-end: the SDK rejects path-traversal segments, absolute paths, drive-letter prefixes, and out-of-tree symlinks at unpack time, with bounded total size, per-file size, and entry count to defend against decompression bombs. See [`typescript/sdk/src/archive.test.ts`](../typescript/sdk/src/archive.test.ts) for the full safety suite.

examples/sample-archive-source/pdf-processing/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pdf-processing
+description: Extract text and form data from PDFs, fill PDF forms, and merge multi-page documents. Use whenever the user asks to read, fill, or assemble PDFs.
+---
+
+# PDF Processing
+
+Workflow for extracting structured data from PDFs and assembling new ones from
+templates and form input.
+
+This skill is distributed as an **archive** (`skill://pdf-processing.tar.gz`)
+to demonstrate SEP-2640 archive distribution. The host fetches the archive,
+unpacks it with archive-safety checks, and presents files at
+`skill://pdf-processing/<file-path>` exactly as if they were served as
+individual MCP resources.
+
+## When to use
+
+- **Extract text** — pull plain text from a PDF, preserving page boundaries.
+- **Read form fields** — list a PDF's interactive form fields and current values.
+- **Fill forms** — given field/value pairs, produce a filled PDF.
+- **Merge** — concatenate or interleave pages from multiple PDFs.
+
+## How to use
+
+1. Identify the operation (extract, read-fields, fill, merge).
+2. For extract/read-fields: open the input PDF and use the operation's tooling
+   to produce the structured output.
+3. For fill: validate that all required fields are provided, then write the
+   filled PDF.
+4. For merge: confirm page ordering and total page count before writing.
+5. Always report the output location and any per-page warnings (low OCR
+   confidence, missing fields, etc.).
+
+## References
+
+See [`references/FORMS.md`](references/FORMS.md) for the field-naming
+conventions used by this skill's tooling.

examples/sample-archive-source/pdf-processing/references/FORMS.md

@@ -0,0 +1,16 @@
+# PDF Form Field Conventions
+
+The pdf-processing skill expects field names to follow these conventions:
+
+- **snake_case** for field identifiers (`first_name`, `policy_number`).
+- **Type prefixes** for non-text fields:
+  - `chk_` — checkboxes (boolean values: "Yes"/"No" or true/false)
+  - `dt_` — dates (ISO 8601: YYYY-MM-DD)
+  - `sel_` — single-select dropdowns (string matching one of the field's options)
+  - `num_` — numeric fields (integers or decimals; locale-neutral)
+- **Required fields** are flagged with a trailing `*` in the source PDF's tooltip but
+  appear without it in the field name returned by `read-fields`.
+
+When filling a form, missing required fields produce a warning per field; the
+operation still succeeds with whatever was provided. Use the warnings to decide
+whether to surface a follow-up to the user.

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)

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