Add Feishu Document API Guide Skill

[rogerhorsley]

Add Feishu Document API Guide Skill

Description

Practical guide for working directly with Feishu Document HTTP APIs, based on real-world debugging and validation.

What this skill provides

• Battle-tested Python scripts for document operations (FeishuDocWriter class with automatic token and revision_id management)
• Comprehensive guide to common API pitfalls with detailed solutions for each
• Critical gotchas documented: required document_revision_id parameter, block_type field mappings, style field requirements
• Production-ready code examples verified through actual implementation

Key features

✅ Verified through real implementation (successfully created and populated a full document)
✅ Documents 8 common pitfalls with root causes and solutions
✅ Includes production-ready Python class with helper functions
✅ Covers authentication, document creation, and content manipulation
✅ Provides debugging checklist and troubleshooting guide

Skill structure

• SKILL.md - Quick start guide, critical gotchas, common tasks, troubleshooting
• scripts/feishu_doc_writer.py - Production-ready Python class with token management
• references/common-pitfalls.md - Detailed documentation of 8 common issues

Use cases

• Implementing custom Feishu integrations via HTTP API
• Debugging "invalid param" errors (error code 1770001)
• Learning Feishu API best practices from real-world experience
• Working around MCP tool limitations with direct API access

Verification

All code has been tested and verified:

• ✅ Successfully authenticated with Feishu API
• ✅ Created documents programmatically
• ✅ Added text content with formatting (bold, mixed styles)
• ✅ Handled batch content additions with proper revision tracking

This skill fills a gap for developers who need to work directly with Feishu's HTTP API and want to avoid the common pitfalls discovered through real implementation.