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..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 @@ -20,7 +22,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 +56,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 +68,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 +82,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 +99,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 +212,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")