modified the description of the cursor and list_files contracts as implemented

Author: vijaydeepsinha

docs/advanced/skills.md

@@ -254,8 +254,10 @@ Each response then holds at most 50 entries and carries a `nextCursor` while mor
 `SkillsClient.list_skills()` and `read_directory()` follow it for you. A skill entry is never split
 across pages.
 
-The cursor is opaque. A cursor the catalog would not issue is rejected with Invalid params
-(`-32602`), and so is any cursor when `page_size` isn't set. A `page_size` below 1 raises `ValueError`.
+The cursor is opaque, and the catalog keeps no record of the cursors it has handed out. It accepts
+a cursor that marks a page boundary of its listing. A cursor that is malformed, out of range, or
+not on a page boundary is rejected with Invalid params (`-32602`), and so is any cursor when
+`page_size` isn't set. A `page_size` below 1 raises `ValueError`.
 
 ### Invalid skills
 
@@ -300,7 +302,8 @@ class SkillProvider(Protocol):
     async def read_file(self, path: str) -> bytes: ...
 ```
 
-`list_files()` returns the path of every file, recursively and without directories. `read_file()`
+`list_files()` returns the path of every file it serves, recursively and without directories. It
+may leave files out; `FilesystemSkillProvider` omits any name that starts with `.`. `read_file()`
 returns the raw bytes of one file. Paths use `/` as the separator and are relative to the root of
 the provider. A provider can therefore be backed by any storage, such as an archive, a database,
 or object storage.

src/mcp/server/skills/catalog.py

@@ -278,8 +278,9 @@ def _encode_cursor(offset: int) -> str:
 def _paginate(items: Sequence[_T], cursor: str | None, page_size: int | None) -> tuple[list[_T], str | None]:
     """Return one page of `items` and the cursor for the next page, if any.
 
-    The catalog is immutable, so a cursor is just an offset into `items`. Only the offsets this
-    function issues are valid; anything else is Invalid params.
+    The catalog is immutable, so a cursor is just an offset into `items`, and no state is kept
+    about which cursors were issued. Only an offset on a page boundary, in canonical form, is
+    accepted; anything else is Invalid params.
     """
     if page_size is None:
         if cursor is not None: