# ecomdly docs

Every skill on ecomdly is a plain .md file with a stable URL. Install one into Claude Code, or connect the whole catalog over MCP.

## Quickstart

```bash
# install one skill into ./skills
npx @ecomdly/cli add cartlift/product-feed-optimizer

# or connect the catalog to Claude Code
claude mcp add --transport http ecomdly https://ecomdly.com/mcp
```

## Raw endpoints

Each document serves raw Markdown at a predictable path. Unversioned URLs always return the latest; pin a version when exact wording matters.

- `GET https://ecomdly.com/raw/{owner}/{skill}.md` → latest approved version
- `GET https://ecomdly.com/raw/{owner}/{skill}@v12.md` → pinned version
- `GET https://ecomdly.com/raw/{owner}/{skill}/SKILL.md` (or `…@v12/SKILL.md`) → the same file in Agent Skills format with `name`/`description`/`version` front matter guaranteed — what `hermes skills install <url>` and Claude Code expect
- Response: `200 OK`, `content-type: text/markdown; charset=utf-8`, `X-Ecomdly-Version`, `X-Ecomdly-Safety` (clean | review)
- Add `?download=1` for a `Content-Disposition: attachment` response.

## REST API

Reads are public; writes take a bearer token from your agent’s configuration (My agent → Configuration).

- `GET /v1/skills?category=code-review&sort=trending&q=…` — list (paginated)
- `GET /v1/skills/{owner}/{skill}` — one skill, including its Markdown body
- `POST /v1/skills` `{name, category, body}` — submit for review (202)
- `PUT /v1/skills/{owner}/{skill}` `{body, note}` — new version through the same pipeline

## MCP server

`https://ecomdly.com/mcp` exposes the catalog as tools, so agents can find and load skills themselves:

- `search_skills(query, category?)` → ranked results
- `get_skill(owner/skill, version?)` → the Markdown body
- `install_skill(owner/skill, target?, scope?)` → the complete skill file plus step-by-step install instructions the agent follows: in Claude Code it writes `~/.claude/skills/<name>/SKILL.md` (so the skill is available as `/<name>` in every project; `scope=project` → `.claude/skills/…` in the current project only), other agents get `./skills/<name>.md` with `target=generic`. `get_skill` only reads.
- `submit_skill(name, body, category?, note?)` → signed in: creates the skill (or a new version) under your account, runs the checks and the safety scan, and queues it for human review — never publishes directly
- `brain_list(brain?, folder?)`, `brain_search(query, brain?)`, `brain_get(name, brain?)`, `brain_write(name, body, mode?, folder?, brain?)`, `brain_create(name)` → private Brain memory: named brains, optionally shared with other users as viewer/editor — read and written by the agent itself (signed in — browser sign-in or MCP token, see below; writes are versioned; credentials are refused). Details: https://ecomdly.com/docs/brain.md · skills in depth: https://ecomdly.com/docs/skills.md

## Connect to Claude

One URL for every client: `https://ecomdly.com/mcp`. Searching, reading and installing skills works without an account. The first time Claude touches your private Brain or submits a skill, ecomdly answers "sign in" (HTTP 401 with OAuth discovery) and Claude opens the browser — sign in with Google or GitHub, approve the app, done. The connection renews itself; disconnect it under Settings → Connected apps (https://ecomdly.com/settings).

**What the sign-in looks like**: Claude calls a tool that needs you (`brain_*`, `submit_skill`) → ecomdly answers 401 with OAuth discovery → Claude registers as an OAuth client and opens `https://ecomdly.com/oauth/authorize` → you sign in with Google or GitHub and approve the `mcp:use` scope → the browser sends Claude back with a code, Claude exchanges it for a token and retries the tool. Next time it just works.

**Claude Desktop & claude.ai**: Settings → Connectors → *Add custom connector*. Name `ecomdly`, URL `https://ecomdly.com/mcp`, Authentication *Required when the server asks* (or *Always required* to sign in right away). The sign-in pops up the first time you ask Claude about your Brain.

**Claude Code**

```bash
claude mcp add --transport http ecomdly https://ecomdly.com/mcp
# inside Claude Code: /mcp → ecomdly → Authenticate opens the browser (needed once)
# then e.g. "submit this file as a skill to ecomdly" — it goes to the review queue, not the catalog
```

Add `--scope user` to have the server in every project. Or let the CLI do it: `npx @ecomdly/cli setup` adds the server (user scope) and writes `~/.claude/rules/ecomdly.md` — search the catalog before planning a task, search the Brain before answering about your own context — because instructions the MCP server sends compete with your own CLAUDE.md and lose, while a rule file does not.

**Without a browser — personal token**: for CI, a server-side agent or a client without OAuth support, create a token under Settings → MCP token (shown once) and send it as a bearer header instead: `claude mcp add --transport http ecomdly https://ecomdly.com/mcp --header "Authorization: Bearer <token>"`, or in Claude Desktop: Add custom connector → Authentication *None* → Request headers `Authorization: Bearer <token>`. Treat the token like a password; revoke it in Settings if it leaks.

**Hermes Agent**: speaks MCP over streamable HTTP and can run the browser sign-in itself (`auth: oauth`, first use), so catalog, `submit_skill` and Brain work without copying a token. In `~/.hermes/config.yaml`, then `/reload-mcp` inside a session:

```yaml
mcp_servers:
  ecomdly:
    url: "https://ecomdly.com/mcp"
    auth: oauth            # or drop `auth` and set headers: {Authorization: "Bearer ${env:ECOMDLY_MCP_TOKEN}"}
    tools:
      include: [search_skills, get_skill, install_skill, submit_skill, "brain_*"]
```

Tools appear prefixed with the server name (`mcp_ecomdly_search_skills`, …). `install_skill` with `target=hermes` returns the file and Hermes' own path, `~/.hermes/skills/<category>/<name>/SKILL.md`. Every skill is also served as a ready-made SKILL.md (Agent Skills format, `name`/`description`/`version` front matter guaranteed), so `hermes skills install https://ecomdly.com/raw/cartlift/product-feed-optimizer/SKILL.md` (or `…@v3/SKILL.md`) works without MCP.

**OpenClaw**: remote MCP over streamable HTTP with your own headers, so the personal token is the whole setup — no browser involved. Keep the token in the gateway's environment, then:

```bash
export ECOMDLY_MCP_TOKEN=<token>   # from Settings → MCP token
openclaw mcp add ecomdly --url https://ecomdly.com/mcp --transport streamable-http --header "Authorization: Bearer ${ECOMDLY_MCP_TOKEN}"
openclaw mcp doctor --probe      # lists search_skills, get_skill, install_skill, brain_*
```

Or in `~/.openclaw/openclaw.json` (values are expanded from the environment at runtime, so the placeholder stays on disk):

```json
{
  "mcp": {
    "servers": {
      "ecomdly": {
        "url": "https://ecomdly.com/mcp",
        "transport": "streamable-http",
        "headers": { "Authorization": "Bearer ${ECOMDLY_MCP_TOKEN}" },
        "requestTimeoutMs": 20000,
        "toolFilter": { "include": ["search_skills", "get_skill", "install_skill", "brain_*"] }
      }
    }
  }
}
```

Without `headers` the agent still gets the catalog tools; the Brain tools then answer 401. `toolFilter` is optional. Any other client that speaks streamable HTTP and can send a header works the same way.

**Protocol details** (for other MCP clients): OAuth 2.1 with PKCE (S256), dynamic client registration at `https://ecomdly.com/oauth/register`, discovery at `https://ecomdly.com/.well-known/oauth-protected-resource/mcp` and `https://ecomdly.com/.well-known/oauth-authorization-server`, scope `mcp:use`, refresh tokens supported. Redirect URIs are limited to claude.ai, claude.com and localhost.

## Publishing & review

Submitted skills run automated checks (Markdown lint, license, prompt-injection scan) and an AI safety scan, then queue for human review. A blocked scan or a failed check auto-rejects with a reason. Approved skills are published with a version history; every update goes through the same pipeline. Skills whose current version passed everything with a clean scan carry the "Security checked" badge.

## Frequently asked

**What is an agent skill?** A Markdown file that tells an AI agent how to do one job: when to use it, the rules, and the exact output format. Skills say how to work; your private Brain files say what is true in your context.

**Is it free?** Browsing, installing and publishing skills is free.

**Do I need an account to install?** No. Raw URLs, the CLI and the MCP catalog tools work without signing in. Upvoting, publishing and your Brain need a Google or GitHub sign-in — or a personal token (Settings → MCP token) for headless agents.

**Can I pin a version?** Yes — `@v12` in the raw URL or `version` in `get_skill`.

**Machine-readable versions of this site:** `https://ecomdly.com/llms.txt`, `https://ecomdly.com/llms-full.txt`, and any page with `.md` appended or `Accept: text/markdown`.