# Feishu Doc

> Use when creating, reading, or editing Feishu/Lark cloud documents (docx/wiki), especially inserting or batch-updating native tables, callouts, whiteboards, or other rich blocks, or converting markdown ↔ Feishu docs. Also use for Feishu spreadsheets (sheets) and multi-dimensional tables (bitable/base). Cortex drives all Feishu rich-text work through the official lark-cli — NOT through MCP tools (…

- **Type:** Skill
- **Install:** `agentstack add skill-fangxm233-cortex-agent-feishu-doc`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fangxm233](https://agentstack.voostack.com/s/fangxm233)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fangxm233](https://github.com/fangxm233)
- **Source:** https://github.com/fangxm233/cortex-agent/tree/main/agent-server/defaults/plugins/cortex-feishu/skills/feishu-doc

## Install

```sh
agentstack add skill-fangxm233-cortex-agent-feishu-doc
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# feishu-doc — Feishu rich-text via the official lark-cli

## Why this skill exists

Feishu cloud documents are a block tree; native tables are a strict block type.
Cortex previously exposed `feishu_docx_*` MCP tools whose table support was
structurally weak, so they were removed. The reliable channel is now the **official
`lark-cli`** (`@larksuite/cli`), which ships its own version-matched agent skills
covering the exact XML/block workflow.

> The old MCP's limitations do **not** apply to lark-cli. In particular, with the
> current CLI both of these work fine (verified on v1.0.56): markdown tables import
> as **native** `` blocks (they do not degrade to text), and `block_replace`
> can replace **across types** (e.g. a text paragraph → a table). Do not carry the
> retired MCP's table caveats into lark-cli guidance.

This Cortex skill is a thin **integration + delegation** layer: it gets `lark-cli`
installed and authenticated, surfaces the Cortex-environment gotchas below, then hands
you off to the official embedded skills. Do not re-document or freeze the lark-cli
content/XML/table workflow here — read it live (Step 3) so it stays in sync with the
installed CLI.

`feishu_send_file` (uploading a file to a Feishu chat) still lives in the cortex-feishu
MCP and is unrelated to this skill. Feishu IM messaging runs through the platform
adapter, not MCP — none of that is affected.

## Step 1 — Preflight (install + config)

Run the bundled preflight (idempotent: installs only if missing, configures the app
from Cortex's `FEISHU_APP_ID` / `FEISHU_APP_SECRET`, prints auth status):

```bash
bash plugins/cortex-feishu/skills/feishu-doc/scripts/ensure-lark-cli.sh
```

If the script path is unavailable, the essential check inline:

```bash
command -v lark-cli >/dev/null 2>&1 || npm install -g @larksuite/cli
lark-cli auth status
```

Notes:
- Cortex runs on **lab2**; install/run there. `lark-cli` stores credentials in the
  OS keychain (falls back to a local file on headless Linux).
- `config init` is non-interactive via `--app-id  --app-secret-stdin` and refuses
  only inside OpenClaw/Hermes agent workspaces (Cortex is neither).

## Step 2 — Authenticate (one-time, may need the user)

Document editing defaults to the **user** identity (`--as user`). `auth status` shows
two identities:
- `bot` (tenant): ready as soon as `config init` ran — enough for many tenant API calls.
- `user`: requires a one-time **device-flow** login the bot cannot complete alone.

If the user identity is missing and you need it, do NOT block silently. Use the
non-interactive flow:

```bash
lark-cli auth login --no-wait --json --domain docs,drive,sheets,base
```

Surface the returned verification URL (or `lark-cli auth qrcode`) to the user as your
turn's final message, end the turn, and after they confirm, resume with:

```bash
lark-cli auth login --device-code 
```

## Step 3 — Delegate to the official lark-cli skills (authoritative)

Before running any `docs` / `sheets` / `base` command, read the matching embedded
skill — it is version-matched to the installed CLI and is the source of truth for
flags, XML syntax, block selectors, and table handling. Read it via the CLI (do NOT
grep local SKILL.md files):

```bash
lark-cli skills read lark-doc            # documents / blocks / tables / whiteboards
lark-cli skills read lark-doc      # a referenced sub-file, e.g. references/lark-doc-update.md
lark-cli skills read lark-sheets         # spreadsheets
lark-cli skills read lark-base           # bitable / multi-dimensional tables
```

Key facts the official skill expands on (read it for the exact commands):
- Docs use **v2 API**: pass `--api-version v2` to `docs +create/+fetch/+update`.
- Create / full-section import: XML or Markdown both work
  (`docs +create --api-version v2 --content '....'`).
- Precise edits (insert/replace/delete a block): prefer XML (`--doc-format xml`, the
  default) and the `+update` commands (`str_replace`, `block_insert_after`,
  `block_replace`, `block_delete`, `block_move_after`).
- **Native tables work both ways**: an XML `` (via `+create`,
  `block_insert_after`, or `block_replace` — cross-type text→table is fine) and a
  markdown table (via `append`/`overwrite --doc-format markdown`) both produce a real
  native table block. The `lark-doc` references document the exact `` XML and
  styling (`colgroup`, header `background-color`, `colspan`/`rowspan`).
- Embedded `` / `` tags: extract the token and switch to the
  `lark-sheets` / `lark-base` skill to operate the data inside.

## Step 4 — Programmatic / batch table updates

The motivating use case (update a doc table from data) is what the CLI is for. Pattern:

1. Read the target doc to locate the table block id:
   `lark-cli docs +fetch --api-version v2 --doc "" --detail with-ids`.
2. Generate the new `` XML from your data (CSV/dict) in a small script.
3. Apply it with `docs +update --api-version v2 --doc "" --command block_replace`
   on the table block (cross-type is fine), or `block_insert_after` + `block_delete` the
   stale block (per the `lark-doc` reference).

Keep generation in a script under the project so the update is repeatable; this is the
right home for data-driven table maintenance, not one-off MCP calls.

## Step 5 — Cortex-environment gotchas (read before driving the CLI)

These are integration-layer facts specific to running lark-cli inside Cortex. They are
NOT in the official lark-cli skills — check them here, then defer everything about
content/XML/blocks to Step 3.

- **Pass content via stdin, not `@file`.** lark-cli's `@file` only accepts a path
  *relative to the current directory*, but each Cortex bash call resets `cwd` to
  `~/.cortex`, so an absolute `@/path` fails ("--file must be a relative path"). Use
  `--content -` and pipe the body in (`--content -                     # raw OAPI when no shortcut fits
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fangxm233](https://github.com/fangxm233)
- **Source:** [fangxm233/cortex-agent](https://github.com/fangxm233/cortex-agent)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fangxm233-cortex-agent-feishu-doc
- Seller: https://agentstack.voostack.com/s/fangxm233
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.