Skill: cced3000/mdshare-agent (version 1.0.0)

--- name: mdshare-agent description: Create, read, unlock, update, and delete temporary Markdown shares through the MDShare service. Use when an agent needs to publish Markdown as a short-lived share link, fetch shared Markdown, access password-protected or burn-after-read content, continue editing with a manage or edit token, or hand back public/edit/manage links for collaboration. Triggers include “share this markdown”, “generate a temporary link”, “publish notes”, “read an MDShare link”, “update an existing share”, and “delete a temporary share”. --- # MDShare Agent Use MDShare as a lightweight anonymous Markdown publishing backend. ## Service - Default base URL: `https://share.yekyos.com` - If the caller provides another deployment, use that instead. - Keep public links and token-bearing links separate: - Public link: `/s/{slug}` - Edit/manage page: `/e/{slug}#edit={token}` or `/e/{slug}#manage={token}` - Never expose `ownerToken` or `editorToken` unless the user explicitly wants those links. ## Core Workflows ### Create a share Send `POST /api/shares` with JSON: ```json { "markdownContent": "# Title\n\nBody", "expiresInHours": 24, "password": "", "burnMode": "OFF", "editableMode": "READ_ONLY" } ``` Rules: - `expiresInHours` should normally be one of `1`, `24`, `168`, `720`. - `burnMode` values: - `OFF` - `AFTER_FIRST_VIEW_GRACE` - `AFTER_FIRST_VIEW_INSTANT` - `editableMode` values: - `READ_ONLY` - `EDIT_LINK` Return these links to the user: - Public: `{baseUrl}/s/{slug}` - Manage: `{baseUrl}/e/{slug}#manage={ownerToken}` - Edit: only if `editorToken` exists, `{baseUrl}/e/{slug}#edit={editorToken}` Example using the default deployment: - Public: `https://share.yekyos.com/s/abc123xy` - Manage: `https://share.yekyos.com/e/abc123xy#manage=<ownerToken>` - Edit: `https://share.yekyos.com/e/abc123xy#edit=<editorToken>` ### Read a public share Call `GET /api/shares/{slug}/public`. Possible states: - `available`: content is returned - `gated`: password and/or confirm-view is required - `expired` - `burned` - `deleted` - `not_found` If the state is `gated`, ask for the password only when needed and explain burn-after-read before confirming access. ### Unlock a gated share Send `POST /api/shares/{slug}/public` with JSON: ```json { "password": "optional-password", "confirmView": true } ``` Use `confirmView: true` when the service says burn confirmation is required. ### Read or edit through a token Use header: ```text x-share-[REDACTED_SECRET] ``` Call `GET /api/shares/{slug}/manage` to inspect the current share and role. ### Save content Send `PATCH /api/shares/{slug}/manage` with header `x-share-token` and JSON: ```json { "markdownContent": "# Updated\n\nContent", "lastKnownUpdatedAt": "2026-03-12T00:00:00.000Z", "force": false } ``` If the API returns `409` with `conflict: true`, do not overwrite silently. Summarize the conflict and ask whether to force-save. ### Update settings Owner token only. Send `PATCH /api/shares/{slug}/settings` with JSON: ```json { "expiresInHours": 168, "password": "", "burnMode": "OFF", "editableMode": "READ_ONLY" } ``` If the response includes a new `editorToken`, regenerate the edit link. ### Delete a share Owner token only. Call `DELETE /api/shares/{slug}/manage` with `x-share-token`. ## Behavior Guidance - Prefer simple defaults: - `expiresInHours: 168` - `burnMode: OFF` - `editableMode: READ_ONLY` - Treat password as optional. Empty string means no password. - Preserve user Markdown exactly unless they explicitly ask for formatting or cleanup. - When the user only wants a formatting preview, do not create a share link unless they ask. - For sensitive content, remind the user that anyone with a manage link can modify or delete the share. ## Reference - For endpoint details and payload shapes, read [references/api.md](references/api.md). - For end-to-end agent flows, read [references/workflows.md](references/workflows.md). - For install and invocation examples, read [references/install-examples.md](references/install-examples.md).

path: references/api.md
content: # MDShare API Reference

Base URL example: `https://share.yekyos.com`

## `POST /api/shares`

Create a share.

Request body:

```json
{
  "markdownContent": "string, required",
  "expiresInHours": "number, optional",
  "password": "string, optional",
  "burnMode": "OFF | AFTER_FIRST_VIEW_GRACE | AFTER_FIRST_VIEW_INSTANT",
  "editableMode": "READ_ONLY | EDIT_LINK"
}
```

Success response:

```json
{
  "share": {
    "slug": "string",
    "markdownContent": "string",
    "expiresAt": "ISO string",
    "createdAt": "ISO string",
    "updatedAt": "ISO string",
    "editableMode": "READ_ONLY | EDIT_LINK",
    "burnMode": "OFF | AFTER_FIRST_VIEW_GRACE | AFTER_FIRST_VIEW_INSTANT",
    "firstViewedAt": "ISO string | null",
    "burnDeadline": "ISO string | null",
    "deletedAt": "ISO string | null",
    "burnedAt": "ISO string | null",
    "statusLabel": "string",
    "expiresAtLabel": "string"
  },
  "ownerToken": "string",
  "editorToken": "string | null"
}
```

## `GET /api/shares/{slug}/public`

Read public state.

Response states:

- `available`
- `gated`
- `expired`
- `burned`
- `deleted`
- `not_found`

`available` response includes `share.markdownContent`.

`gated` response shape:

```json
{
  "state": "gated",
  "passwordRequired": true,
  "burnConfirmationRequired": false,
  "share": {
    "expiresAt": "ISO string",
    "burnMode": "string"
  }
}
```

## `POST /api/shares/{slug}/public`

Unlock gated content.

Request body:

```json
{
  "password": "string, optional",
  "confirmView": "boolean, optional"
}
```

Response:

- `200` for `available`
- `404` for `not_found`
- `410` for `expired`, `burned`, or `deleted`
- `400` for wrong password or invalid request

## `GET /api/shares/{slug}/manage`

Read manage/edit payload.

Required header:

```text
x-share-[REDACTED_SECRET]
```

Success response:

```json
{
  "role": "owner | editor",
  "share": {
    "slug": "string",
    "markdownContent": "string",
    "expiresAt": "ISO string",
    "createdAt": "ISO string",
    "updatedAt": "ISO string",
    "editableMode": "READ_ONLY | EDIT_LINK",
    "burnMode": "OFF | AFTER_FIRST_VIEW_GRACE | AFTER_FIRST_VIEW_INSTANT",
    "firstViewedAt": "ISO string | null",
    "burnDeadline": "ISO string | null",
    "deletedAt": "ISO string | null",
    "burnedAt": "ISO string | null",
    "statusLabel": "string",
    "expiresAtLabel": "string"
  }
}
```

## `PATCH /api/shares/{slug}/manage`

Save Markdown content.

Required header:

```text
x-share-[REDACTED_SECRET]
```

Request body:

```json
{
  "markdownContent": "string, required",
  "lastKnownUpdatedAt": "ISO string | null",
  "force": false
}
```

Conflict response:

```json
{
  "conflict": true,
  "role": "owner | editor",
  "share": {
    "...": "latest remote share payload"
  }
}
```

## `PATCH /api/shares/{slug}/settings`

Owner token only.

Required header:

```text
x-share-[REDACTED_SECRET]
```

Request body:

```json
{
  "expiresInHours": 168,
  "password": "",
  "burnMode": "OFF",
  "editableMode": "READ_ONLY"
}
```

Response may include:

```json
{
  "role": "owner",
  "share": {
    "...": "updated share payload"
  },
  "editorToken": "string | null"
}
```

## `DELETE /api/shares/{slug}/manage`

Owner token only.

Required header:

```text
x-share-[REDACTED_SECRET]
```

Success response:

```json
{
  "success": true
}
```


path: references/install-examples.md
content: # MDShare Agent Install Examples

Use this reference when wiring the packaged skill into OpenClaw or another skill-based agent runtime.

## Packaged file

Use the packaged artifact:

```text
D:\project\mdshare\dist\mdshare-agent.skill
```

## Example 1: Install into a skill-based runtime

Typical pattern:

1. Import or install `mdshare-agent.skill` into the runtime's skill directory.
2. Enable the skill.
3. Let the runtime load `SKILL.md` and bundled `references/`.

If the runtime expects an unpacked folder instead of a `.skill` file, use:

```text
D:\project\mdshare\skills\mdshare-agent
```

## Example 2: Trigger phrases

These user requests should trigger the skill:

- “帮我把这段 markdown 生成临时链接”
- “share this markdown note”
- “read this MDShare link”
- “update this temporary share”
- “delete this MDShare document”

## Example 3: Agent tool call shape

If the agent can call HTTP directly, the skill should guide it toward requests like:

```http
POST https://share.yekyos.com/api/shares
Content-Type: application/json
```

```json
{
  "markdownContent": "# Hello\n\nFrom agent",
  "expiresInHours": 168,
  "password": "",
  "burnMode": "OFF",
  "editableMode": "READ_ONLY"
}
```

## Example 4: Returned output style

Recommended agent reply after creating a share:

```text
分享已创建。
公开访问：https://share.yekyos.com/s/{slug}
管理链接：https://share.yekyos.com/e/{slug}#manage={ownerToken}
```

Only include the edit link when edit mode is enabled.

## Example 5: Safe behavior

When integrating this skill into a general-purpose agent:

- Do not expose manage or edit links unless the user asks for them or needs them.
- Do not auto-confirm burn-after-read access without user intent.
- Do not create a share when the task is only local Markdown formatting or preview.


path: references/workflows.md
content: # MDShare Agent Workflows

Use these flows when the caller wants the agent to operate MDShare directly instead of just describing the API.

## Workflow 1: Create a temporary share and return links

Use when the user says things like:

- “帮我把这份 Markdown 发成临时链接”
- “share this note”
- “generate a temporary markdown link”

Steps:

1. Collect the Markdown exactly as provided.
2. Unless the user specifies otherwise, use:
   - `expiresInHours: 168`
   - `burnMode: OFF`
   - `editableMode: READ_ONLY`
   - empty password
3. Call `POST /api/shares`.
4. Return:
   - public link
   - manage link
   - edit link only if `editorToken` exists
5. Briefly explain the difference between public and manage links.

Suggested reply shape:

```text
分享已创建。
公开访问：https://share.yekyos.com/s/{slug}
管理链接：https://share.yekyos.com/e/{slug}#manage={ownerToken}
```

Only include the edit link when editing is enabled.

## Workflow 2: Read a protected share

Use when the user gives an MDShare public link and asks to read or summarize it.

Steps:

1. Extract `{slug}` from `/s/{slug}`.
2. Call `GET /api/shares/{slug}/public`.
3. If state is `available`, use the content directly.
4. If state is `gated`:
   - ask for a password only when `passwordRequired` is true
   - mention burn-after-read before using `confirmView: true`
5. Call `POST /api/shares/{slug}/public` with the required fields.
6. Continue only after the API returns `available`.

Guardrails:

- Do not assume a password.
- Do not auto-confirm burn-after-read unless the user clearly wants to proceed.
- If the API returns `expired`, `burned`, `deleted`, or `not_found`, report that state plainly.

## Workflow 3: Update an existing share through a token

Use when the user provides a manage link or edit link and wants to continue editing.

Steps:

1. Extract:
   - `slug` from `/e/{slug}`
   - token from `#manage=...` or `#edit=...`
2. Call `GET /api/shares/{slug}/manage` with `x-share-token`.
3. Present the current role:
   - `owner`
   - `editor`
4. When saving new Markdown, send `PATCH /api/shares/{slug}/manage` with:
   - `markdownContent`
   - `lastKnownUpdatedAt`
   - `force: false`
5. If the API returns `409` and `conflict: true`, summarize the remote update and ask whether to force overwrite.
6. Only use `force: true` after explicit confirmation.

Guardrails:

- `editor` can edit content but not settings.
- `owner` can edit content, change settings, and delete the share.

## Workflow 4: Change expiry, password, or editability

Use when the user provides a manage link and asks to:

- extend expiry
- add/remove password
- enable/disable edit link
- change burn-after-read behavior

Steps:

1. Extract `slug` and owner token.
2. Call `PATCH /api/shares/{slug}/settings`.
3. Preserve unspecified settings when possible by reading current state first.
4. If a new `editorToken` is returned, regenerate the edit link and return it.

## Workflow 5: Delete a share

Use when the user wants a share permanently disabled.

Steps:

1. Require the manage link or owner token.
2. Confirm intent when the user has not already been explicit.
3. Call `DELETE /api/shares/{slug}/manage`.
4. Report success only after `{ "success": true }`.

## Workflow 6: Use MDShare as a formatting helper

Use when the user wants formatted Markdown output but does not necessarily want a share link.

Steps:

1. Do not call the API by default.
2. Render or transform Markdown locally when the task is just formatting, preview, or conversion.
3. Only create a share if the user explicitly asks to publish or share it.

This keeps MDShare positioned as a lightweight sharing backend rather than forcing publication for every Markdown task.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)