diff --git a/pinrag/README.md b/pinrag/README.md
new file mode 100644
index 0000000..2c387bd
--- /dev/null
+++ b/pinrag/README.md
@@ -0,0 +1,9 @@
+This folder is a **ready-to-contribute** copy of the PinRAG skill for [block/agent-skills](https://github.com/block/agent-skills).
+
+**To submit to the Goose Skills Marketplace:**
+
+1. Fork [block/agent-skills](https://github.com/block/agent-skills).
+2. Copy this `pinrag` directory to the **root** of your fork (next to `code-review/`, `api-setup/`, etc.).
+3. Open a pull request using the repository’s “Submit a Skill” template.
+
+Validation runs in CI; `name` in `SKILL.md` frontmatter must match the folder name `pinrag`.
diff --git a/pinrag/SKILL.md b/pinrag/SKILL.md
new file mode 100644
index 0000000..c7d836e
--- /dev/null
+++ b/pinrag/SKILL.md
@@ -0,0 +1,55 @@
+---
+name: pinrag
+description: Use the PinRAG MCP server for retrieval-augmented QA over indexed documents with citations.
+author: ndjordjevic
+version: "1.0"
+tags:
+  - rag
+  - mcp
+  - pdf
+  - citations
+  - langchain
+  - chromadb
+  - youtube
+  - github
+---
+
+# PinRAG MCP tools
+
+Use this skill when the **PinRAG** MCP server is running (stdio process from `pinrag-mcp`). The server is typically started with **`uvx --from pinrag pinrag-mcp`** or after `pipx install pinrag` / `uv tool install pinrag` so `pinrag-mcp` is on `PATH`.
+
+## Prerequisites
+
+- **API keys:** Set `ANTHROPIC_API_KEY` and/or `OPENAI_API_KEY` in the MCP `env` block (or your environment). See the [PinRAG README](https://github.com/ndjordjevic/pinrag#installation).
+- **uv:** If using `uvx`, install [uv](https://docs.astral.sh/uv/) and ensure it is on `PATH`.
+
+## Tools (invoke via your host’s MCP integration)
+
+| Tool | When to use | Parameters |
+|------|-------------|------------|
+| `query_tool` | Answer questions over the index with citations | Required: `query`. Optional: `document_id`, `page_min`, `page_max`, `tag`, `document_type`, `response_style`, GitHub `file_path`, etc. |
+| `add_document_tool` | Index local files, directories, or URLs (YouTube, GitHub) in one call | Required: `paths` (list of strings). Optional: `tags`. |
+| `add_url_tool` | Index a **single** YouTube or GitHub URL | Required: `url`. |
+| `list_documents_tool` | List indexed documents and chunk counts | Optional: `tag` to filter. |
+| `remove_document_tool` | Remove a document from the index | Required: `document_id`. |
+
+## Resources and prompt
+
+- **Resources:** `pinrag://documents` (indexed docs), `pinrag://server-config` (effective config), if your client lists MCP resources.
+- **Prompt:** `use_pinrag` with parameter `request` for combined indexing/query/list/remove flows when supported.
+
+## Workflow
+
+1. Map the user’s request to a tool (questions → `query_tool`; “add/index …” → `add_document_tool` or `add_url_tool`; “list docs” → `list_documents_tool`; “remove …” → `remove_document_tool`).
+2. Call the tool through the host’s MCP layer using the exact tool names above.
+3. Return answers with citations as provided by the server.
+
+## Examples
+
+- “What does the PDF say about X?” → `query_tool` with `{"query": "What does the PDF say about X?"}`
+- “Index `~/papers` with tag `amiga`” → `add_document_tool` with `{"paths": ["~/papers"], "tags": ["amiga"]}`
+- “Add this YouTube video” (single URL) → `add_url_tool` with `{"url": "<url>"}` or `add_document_tool` with `{"paths": ["<url>"]}`
+- “List indexed documents” → `list_documents_tool` with `{}`
+- “Search only in document X” → `query_tool` with `query` plus `document_id` set to that document’s id
+
+If the user has not configured the PinRAG MCP server, point them to [PinRAG installation](https://github.com/ndjordjevic/pinrag).