From 0fda74df471fb27176bca89b08503bf9ef5b7fd6 Mon Sep 17 00:00:00 2001 From: Mohamed Ragab Date: Thu, 13 Aug 2026 18:43:45 +0300 Subject: [PATCH 1/2] Document asking an AI agent to install the skill as the easiest path Verified on both Codex (installs via $skill-installer to ~/.codex/skills/) and Claude Code (installs as a personal skill plus the slash commands in ~/.claude/commands/). Becomes item 1 and takes the "easiest, recommended" badge from the AGENTS.md item; items renumber to 1-7. The documented prompt carries the /tree/main/skills/paymob-integration subdirectory rather than the bare repo root. Codex resolved the subdirectory unaided, but only after searching the web and inspecting the layout, and an agent that guesses wrong installs the multi-agent plugin package as though it were a standalone skill. States the two limits this path has, both found by testing rather than reading: it does not register the MCP server, so there is no live account access, and it does not namespace the skill, so installing it alongside the plugin yields two identically-described skills. Also documents that a fresh session is required, which is the most common reason the install looks like it failed. Separately: the Claude Code plugin block now notes that a shell "claude plugin install" needs /reload-plugins or a restart to take effect, and marketplace.json gains the description that "claude plugin validate --strict" requires; validate.py now enforces it. --- .claude-plugin/marketplace.json | 1 + README.md | 52 ++++++++++++++++++++++++++++----- scripts/validate.py | 5 ++++ 3 files changed, 51 insertions(+), 7 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3b5444a..97bd077 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,5 +1,6 @@ { "name": "paymob", + "description": "Paymob's official marketplace for AI agent integration tooling — build and verify secure Paymob payment flows across Egypt, UAE, KSA, and Oman.", "owner": { "name": "Paymob", "email": "mohamedragab@paymob.com", diff --git a/README.md b/README.md index 22b2915..f14fdbd 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,31 @@ It's all plain Markdown — any AI assistant can use it. Find your tool below; m > **Using an “Upload skill” screen?** Do not upload GitHub's full repository ZIP. Build or download the dedicated `paymob-integration.zip` described under [Skill upload](#skill-upload-claudeai--chatgpt--lovable); it contains one top-level skill folder and leaves every plugin/editor entry point unchanged. -### 1. OpenAI Codex → install the standalone skill +### 1. Any AI agent → just ask it to install the skill (easiest, recommended) + +No CLI, no downloads, no config files. Paste this to your agent: + +```text +Install the Paymob integration skill from https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration +``` + +The agent fetches the skill and puts it wherever its own convention expects. Tested on both: + +| Agent | What you get | +|---|---| +| **OpenAI Codex** | Uses its `$skill-installer`; installs to `~/.codex/skills/paymob-integration` | +| **Claude Code** | Installs as a personal skill in `~/.claude/skills/paymob-integration/`, plus the three slash commands in `~/.claude/commands/` | + +**Keep the `/tree/main/skills/paymob-integration` part of the URL.** The repository root is a multi-agent plugin package, not a standalone skill directory — an agent pointed at the bare root can install the wrong tree. + +**Then start a fresh session.** Skills and commands are read at session start, so they won't show up in the session that installed them. This is the most common reason people think the install failed. + +Two things this path deliberately does *not* do: + +- **It doesn't register the Paymob MCP server**, so there's no live account access (payment links, transactions, balances, settlements). Agents leave it out on purpose — it's a persistent config change pointing at a live financial service. To get it, use the Claude Code plugin install (item 7 below), which bundles it, or add it yourself per [Live access](#live-access--paymob-mcp-server). +- **It doesn't namespace the skill.** Install it this way *and* as a plugin and you'll have two `paymob-integration` skills with identical descriptions; disable one to clear the ambiguity. + +### 2. OpenAI Codex → install the standalone skill Ask Codex: @@ -30,7 +54,7 @@ Use $skill-installer to install https://github.com/PaymobAccept/Paymob-AI-Integr Targeting the `skills/paymob-integration` subdirectory is required; the repository root is a multi-agent plugin package, not a standalone skill directory. The standalone skill includes all references. Add the optional live Paymob server separately with `codex mcp add paymob --url https://mcp.paymob.com/mcp`. -### 2. Lovable → import the tested workspace skill +### 3. Lovable → import the tested workspace skill Lovable **Tested successfully with Lovable Workspace Skills.** @@ -42,7 +66,7 @@ Targeting the `skills/paymob-integration` subdirectory is required; the reposito You need a workspace owner, admin, or editor role to import a custom skill. Although Lovable also supports public GitHub imports, use the release ZIP for this repository: Lovable accepts `SKILL.md` only at the repository root or inside one wrapping folder, while this multi-agent plugin intentionally keeps it at `skills/paymob-integration/SKILL.md`. -### 3. Coding agents → drop in `AGENTS.md` (easiest, recommended) +### 4. Coding agents → drop in `AGENTS.md` [`AGENTS.md`](https://agents.md) is an open standard that coding agents read **automatically** from your project's root folder. Natively supported by **OpenAI Codex, Cursor, GitHub Copilot, Windsurf, Gemini CLI, Aider, Zed, Jules, Devin, Factory, Amp, RooCode, Warp, JetBrains Junie**, and more. @@ -56,13 +80,13 @@ curl -O https://raw.githubusercontent.com/PaymobAccept/Paymob-AI-Integration-Ski - Already have an `AGENTS.md`? Just paste this one's contents into it under a `## Paymob` heading. - Now ask your agent in plain English — *"Add Paymob card payments to my checkout"* — and it follows the Paymob rules automatically. -### 4. Chat assistants (ChatGPT · Gemini · Claude.ai · Copilot Chat …) → paste `universal-prompt.md` +### 5. Chat assistants (ChatGPT · Gemini · Claude.ai · Copilot Chat …) → paste `universal-prompt.md` 1. Open [`universal-prompt.md`](universal-prompt.md) and **copy the whole file**. 2. Paste it into the assistant's **system prompt** / **custom instructions** (ChatGPT: *Settings → Personalization → Custom instructions*; Gemini: a *Gem*; Claude.ai: a *Project*'s instructions). 3. Describe what you're building. It's fully self-contained — no other files needed. -### 5. Prefer a pinned editor rules file? (optional) +### 6. Prefer a pinned editor rules file? (optional) If you'd rather use your editor's native rules file instead of `AGENTS.md`, save [`universal-prompt.md`](universal-prompt.md) as: @@ -73,15 +97,17 @@ If you'd rather use your editor's native rules file instead of `AGENTS.md`, save | GitHub Copilot | `.github/copilot-instructions.md` | | Cline · Continue · Roo | the tool's rules / context file | -### 6. Claude Code / Cowork → install the full plugin +### 7. Claude Code / Cowork → install the full plugin -Add this repository as a marketplace, then install the plugin. The plugin auto-registers the bundled live Paymob MCP server (see [below](#live-access--paymob-mcp-server)): +Pick this over item 1 when you want the **bundled live Paymob MCP server** (see [below](#live-access--paymob-mcp-server)) and namespaced plugin commands. Add this repository as a marketplace, then install the plugin: ```bash claude plugin marketplace add PaymobAccept/Paymob-AI-Integration-Skill claude plugin install paymob-integration@paymob ``` +A shell `claude plugin install` doesn't take effect in a session that's already running — run `/reload-plugins` in that session, or restart, before the skill and its commands appear. + Cowork and local-development options are under [Installation](#installation). > **One source of truth, no drift:** the full skill lives in `skills/paymob-integration/`; `universal-prompt.md` is its self-contained portable copy; `AGENTS.md` is a short router to it. @@ -184,6 +210,18 @@ This packaging step only copies the canonical skill into an ignored `dist/` arch A root-level copy, symlink, or shortcut to `SKILL.md` is intentionally not used: upload services may not follow links, while a copied file would create a second source of truth that can drift. +### Ask your AI agent (any agent, no CLI) + +Paste this to the agent you already use: + +```text +Install the Paymob integration skill from https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration +``` + +Verified on OpenAI Codex (installs via `$skill-installer` to `~/.codex/skills/paymob-integration`) and Claude Code (installs as a personal skill in `~/.claude/skills/paymob-integration/` plus the slash commands in `~/.claude/commands/`). Start a fresh session afterwards — skills and commands are read at session start. + +Keep the `/tree/main/skills/paymob-integration` subdirectory in the URL; the repository root is a multi-agent plugin package, not a standalone skill directory. This path installs the skill only — it does not register the Paymob MCP server, so use the plugin install below if you want live account access. + ### OpenAI Codex (standalone skill) In a Codex task, ask: diff --git a/scripts/validate.py b/scripts/validate.py index 82212eb..dbba28c 100644 --- a/scripts/validate.py +++ b/scripts/validate.py @@ -256,6 +256,11 @@ def validate_manifests(skill_name: str, errors: list[str]) -> str: if marketplace.get("name") != "paymob": errors.append("Claude marketplace name must be 'paymob'") + # `claude plugin validate --strict` treats a missing marketplace description + # as an error, and directory listings surface it. + marketplace_description = marketplace.get("description") + if not isinstance(marketplace_description, str) or not marketplace_description.strip(): + errors.append("Claude marketplace must declare a non-empty description") if not isinstance(marketplace.get("owner"), dict): errors.append("Claude marketplace must declare an owner object") plugins = marketplace.get("plugins") From 0f04f233c885aae47127b7ed53671022c5d8d444 Mon Sep 17 00:00:00 2001 From: Mohamed Ragab Date: Thu, 13 Aug 2026 19:25:08 +0300 Subject: [PATCH 2/2] Say plainly that no vendor marketplace lists this yet The intro reads as though the plugin ships through Codex, Claude, and Lovable marketplaces. It does not: this repository is the only distribution channel today, and the Paymob MCP server is in no vendor connector registry either. A user who searches a marketplace for "Paymob", finds nothing, and concludes the install is broken is the failure this note prevents. The Claude Code path registers this repo as a custom marketplace, which needs no vendor listing, so every documented method works as written. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f14fdbd..eba679f 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ Give any AI coding agent expert, **workflow-driven** knowledge of the [Paymob](h Ships as a native **Codex/ChatGPT plugin**, a **Claude Code/Cowork plugin**, a tested **Lovable workspace skill**, and a portable prompt (`universal-prompt.md`) + `AGENTS.md` for Cursor, Windsurf, GitHub Copilot, Gemini, and other agents. +> **This repository is the distribution channel.** Paymob has no listing yet in Anthropic's plugin directory, OpenAI's, or Lovable's marketplace, and the Paymob MCP server is not in any vendor connector registry. If you search a vendor marketplace for "Paymob" and find nothing, that's expected — not a mistake on your end. Every method below installs straight from this repo (or its release ZIP) and works today; the Claude Code path registers this repo as a *custom* marketplace, which needs no vendor listing. Vendor listings are something we hope to add later. + --- ## Works with any AI agent