refactor(skills): enhance descriptions and improve clarity in usage documentation

Author: Michael-Obele

skills/docshark/SKILL.md

@@ -1,60 +1,44 @@
 ---
 name: docshark
-description: Use when answering framework, library, SDK, or API documentation questions with DocShark MCP tools. Use for indexed-doc lookup, full-page retrieval, and library lifecycle operations.
+description: Use when answering framework, library, SDK, or API documentation questions with DocShark MCP tools, especially for indexed-doc search, full-page retrieval, and library lifecycle tasks.
 ---
 
 # DocShark MCP Usage
 
-## Overview
+Use DocShark in this exact order:
 
-Use DocShark as a tool-first docs workflow. Keep answers grounded in tool output, not model memory.
+1. `list_libraries` if coverage is unknown.
+2. `search_docs` for primary lookup (natural language queries).
+3. `get_doc_page` only when snippet context is not enough.
+4. `manage_library` for lifecycle operations.
 
-## Use These Tools
+## Current Tool Contract
 
-- `list_libraries` - discover what is indexed.
-- `search_docs` - primary natural-language search.
-- `search_docs_batch` - multiple related queries in one call.
-- `get_doc_page` - fetch full markdown for one page.
-- `manage_library` - lifecycle actions: `add`, `rename`, `refresh`, `remove`, `info`.
+- Read/search:
+  - `list_libraries`
+  - `search_docs`
+  - `search_docs_batch`
+  - `get_doc_page`
+- Lifecycle:
+  - `manage_library` with `action` in `add | rename | refresh | remove | info`
 
-Important: do not call `add_library`, `refresh_library`, or `remove_library`; those are not current tool names.
+Do not call deprecated/nonexistent tool names such as `add_library`, `refresh_library`, or `remove_library`.
 
-## Default Flow
+## manage_library Required Inputs
 
-1. Call `list_libraries` if library coverage is unknown.
-2. Call `search_docs` with a natural-language query.
-3. Call `get_doc_page` only when snippet context is insufficient.
-4. If docs are missing or stale, call `manage_library` with the correct `action`.
+- `add`: `url` (optional `name`, `version`, `max_depth`)
+- `refresh`: `library`
+- `remove`: `library`
+- `info`: `library`
+- `rename`: `current_name`, `new_name`
 
-## manage_library Quick Guide
+## Query Style
 
-- Add docs:
-  - `action: "add"`
-  - required: `url`
-  - optional: `name`, `version`, `max_depth`
-- Refresh docs:
-  - `action: "refresh"`
-  - required: `library`
-- Remove docs:
-  - `action: "remove"`
-  - required: `library`
-- Inspect one library:
-  - `action: "info"`
-  - required: `library`
-- Rename library:
-  - `action: "rename"`
-  - required: `current_name`, `new_name`
+- Use natural language: `SvelteKit form actions redirect after submit`
+- Avoid keyword fragments: `sveltekit form redirect`
 
-## Query Patterns
+## Output Rules
 
-Use natural language, not keyword fragments.
-
-- Good: `SvelteKit form actions redirect after submit`
-- Good: `TanStack Query cache invalidation guidance`
-- Weak: `sveltekit form redirect`
-
-## Response Rules
-
-- Cite what DocShark returned.
-- If no results, say so and refine query or library scope.
-- If library is missing, state that and use `manage_library` `action: "add"`.
+- Ground answers in tool output.
+- If nothing is found, say so and refine query/filter.
+- If a library is missing, use `manage_library` with `action: "add"`.

skills/using-docshark/SKILL.md

@@ -1,17 +1,13 @@
 ---
 name: using-docshark
-description: Use when installing, running, and troubleshooting DocShark as an MCP server, or when configuring clients to connect through STDIO or HTTP MCP endpoints.
+description: Use when installing, running, and troubleshooting DocShark as an MCP server, including client setup for STDIO mode and endpoint checks for HTTP mode.
 ---
 
 # Operating DocShark
 
-## Overview
-
-This skill covers accurate runtime setup and troubleshooting for the current DocShark codebase.
-
 ## Start Modes
 
-### STDIO mode (for MCP clients)
+### STDIO mode (MCP clients)
 
 ```bash
 docshark --stdio
@@ -23,17 +19,17 @@ or
 npx docshark --stdio
 ```
 
-Use this when a client launches DocShark as a subprocess MCP server.
+Use STDIO when a client launches DocShark as a subprocess MCP server.
 
 ### HTTP mode
 
 ```bash
 docshark
 ```
 
-Default HTTP port is `6380` unless `--port` is provided.
+Default HTTP port is `6380` (override with `--port`).
 
-When running in HTTP mode, key endpoints are:
+HTTP endpoints:
 
 - `/mcp`
 - `/sse`
@@ -47,7 +43,7 @@ When running in HTTP mode, key endpoints are:
   - CLI: `--data-dir <path>`
   - Env: `DOCSHARK_DATA_DIR`
 
-## Reliable CLI Operations
+## Core CLI Operations
 
 - `docshark add <url>`
 - `docshark list`
@@ -60,13 +56,13 @@ When running in HTTP mode, key endpoints are:
 ## Troubleshooting
 
 - No search results:
-  1. Run `docshark list` to verify library exists.
-  2. Run `docshark refresh <library>` for stale index.
-  3. Re-run search with a more explicit natural-language query.
+  1. Verify with `docshark list`.
+  2. Refresh with `docshark refresh <library>`.
+  3. Re-run with a clearer natural-language query.
 - Client cannot connect in STDIO mode:
-  1. Verify client command uses `docshark --stdio` (or `npx docshark --stdio`).
-  2. Check that `docshark` is on PATH if not using `npx`.
+  1. Verify startup command is `docshark --stdio` or `npx docshark --stdio`.
+  2. Ensure `docshark` is on PATH if not using `npx`.
 - HTTP mode not reachable:
-  1. Verify process is running.
+  1. Confirm process is running.
   2. Check `/api/health`.
-  3. Confirm selected `--port` is not occupied.
+  3. Confirm chosen `--port` is available.