Feishu Skill - AI Tool Extension for Feishu API

A progressively extensible skill designed for AI tools to leverage Feishu capabilities. The core philosophy is implement only what you need, when you need it.

⚠️ CRITICAL: After Creating New Scripts

You MUST update scripts/script_index.json immediately after creating any new script.

Failure to update the index will cause:

• Future AI lookup cannot find the newly created script
• Duplicate implementation of the same functionality
• Confusion for other AI tools using this skill

Action required: Add an entry to scripts/script_index.json with fields: name, description, usage_hint, added_date, tags

Design Philosophy

This skill is designed specifically for AI tools, not for human manual use.

When an AI tool receives a task involving Feishu:

1. Check existing scripts first - Search scripts/script_index.json for already-implemented APIs
2. Implement only if needed - If no match exists, use Context7 to query Feishu OpenAPI documentation
3. Add to index - Once implemented, update the index to avoid future re-implementation

This approach ensures:

• No wasted effort - Only implement APIs when actually needed
• Progressive expansion - The skill grows based on real usage patterns
• Efficient lookup - AI tools can quickly find what's already available

Quick Start

This skill works out of the box once authentication is configured:

# Configure authentication (one-time setup)
cd scripts/env
echo '{"app_id": "your_app_id", "app_secret": "your_app_secret"}' > app.json

AI Workflow

Decision Logic

When AI encounters a Feishu-related task, follow this decision tree:

Step 1: Check index file

Read scripts/script_index.json
Search by: description, tags

If match found:

• Run python3 script.py --help to understand parameters
• Execute the script
• Return result

If NO match found:

• Use Context7 to query Feishu API documentation:

  Library: open.feishu.cn / larksuite
  Query: "[specific requirement, e.g., 如何获取群组成员列表]"
  

• Implement new Python script based on documentation
• Execute and test
• IMPORTANT: Update scripts/script_index.json to add the new script

If execution fails:

• Check API error messages
• Use Context7 or references/doc_urls.txt to consult documentation
• Fix the script
• Re-test

Critical Decision Points

When deciding between "use existing" vs "implement new", consider:

• Is there a semantic match? Even if parameter names differ, if the functionality is equivalent, use existing script
• What's the cost of implementing? Simple single-call APIs → implement immediately. Complex multi-call workflows → consider reusing existing scripts
• Can this compose from existing scripts? Sometimes new features can be achieved by combining multiple existing scripts

Technical Reference

Script Index Format

scripts/script_index.json structure:

{
  "version": "1.0",
  "last_updated": "2026-02-12T12:00:00Z",
  "scripts": [
    {
      "name": "get_group_members",
      "description": "获取指定群组的人员列表",
      "usage_hint": "python3 get_group_members.py <open_chat_id>",
      "added_date": "2026-02-12",
      "tags": ["group", "member", "user"]
    }
  ]
}

Key fields for AI search:

• description: Human-readable explanation of functionality
• tags: Array of keywords for matching (prioritize these for fuzzy matching)

Authentication

Configuration file: scripts/env/app.json

{
  "app_id": "cli_xxxxxxxxxxxxxxxx",
  "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

To obtain credentials:

1. Login to Feishu Open Platform
2. Create or select an application
3. Get App ID and App Secret from application details

Token management: get_token.py handles token lifecycle:

• Automatic caching during validity period
• Auto-refresh 5 minutes before expiration
• Cache file: scripts/env/token_cache.json

Script Template

When implementing new APIs, use this template:

#!/usr/bin/env python3
"""
[Complete functional description]

Usage:
    python3 script.py <param1> <param2> [options]

Parameters:
    param1: Parameter description
    param2: Parameter description

Options:
    --page-size: Page size (default: 20)
    --page-token: Pagination token

Output:
    JSON format output:
    {
      "code": 0,
      "msg": "success",
      "data": { ... }
    }

References:
    Feishu API: https://open.feishu.cn/document/...
"""

import sys
import json
import subprocess
from pathlib import Path
import requests

# Configuration
TOKEN_SCRIPT = Path(__file__).parent / "get_token.py"
BASE_URL = "https://open.feishu.cn"

def get_token():
    """Get Feishu access token"""
    result = subprocess.run(
        [sys.executable, str(TOKEN_SCRIPT)],
        capture_output=True,
        text=True,
        check=True
    )
    return result.stdout.strip()

def api_function(param1, param2, token, **kwargs):
    """API call function"""
    headers = {"Authorization": f"Bearer {token}"}
    # ... implement API call
    pass

def main():
    # Handle --help
    if "--help" in sys.argv or "-h" in sys.argv:
        print(__doc__)
        return

    # Parse required parameters
    if len(sys.argv) < 3:
        print(__doc__, file=sys.stderr)
        sys.exit(1)

    param1 = sys.argv[1]
    param2 = sys.argv[2]
    kwargs = {}

    # Parse optional parameters
    for i in range(3, len(sys.argv)):
        if sys.argv[i].startswith("--"):
            key = sys.argv[i][2:].replace("-", "_")
            i += 1
            if i < len(sys.argv):
                kwargs[key] = sys.argv[i]

    # Get token
    token = get_token()

    # Call API
    result = api_function(param1, param2, token, **kwargs)

    # Output JSON
    print(json.dumps(result, indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()

Development standards:

1. ⚠️ CRITICAL: After creating any new script, you MUST update scripts/script_index.json immediately
2. Complete docstring with Usage, Parameters, Options, Output sections
3. Support --help parameter
4. Use get_token.py for authentication
5. Output standard JSON format
6. Proper error handling with friendly messages

📋 New Script Creation Checklist

When implementing a new API, you MUST complete ALL steps:

• Query Context7 for API documentation
• Create the Python script following the template
• Test the script execution (verify it returns correct JSON)
• ⚠️ UPDATE scripts/script_index.json ← Don't forget this!
• Save the API documentation URL to references/doc_urls.txt

Using Context7 for Feishu API

When implementing new APIs, query Feishu documentation via Context7:

Library ID: open.feishu.cn / larksuite
Query examples:
- "如何获取群组成员列表"
- "发送消息到飞书群组的 API 使用方法"
- "飞书文档操作的 OpenAPI"

Why Context7?

• Provides up-to-date API documentation
• Includes code examples and parameters
• Faster than searching the web manually
• Reduces trial-and-error

Examples

AI Task Example 1: Get Group Members

User request: "Get the member list for group oc_xxxxxxxxxxxxx"

AI decision process:

1. Search scripts/script_index.json → Found match: get_group_members
2. Execute: python3 scripts/get_group_members.py oc_xxxxxxxxxxxxx
3. Return result

AI Task Example 2: Add New API Capability

User request: "Delete a message from the group"

AI decision process:

1. Search scripts/script_index.json → No match
2. Context7 query: "飞书删除消息 API"
3. Get documentation showing message/delete endpoint
4. Implement delete_message.py script
5. Test execution
6. ⛔ CRITICAL STEP: Update scripts/script_index.json with new entry - DO NOT skip this!
7. Return result

Why step 6 is critical:

• If you skip it, next AI will NOT find delete_message.py in the index
• This causes duplicate work: same functionality will be re-implemented
• The progressive expansion philosophy breaks down

References

• Feishu Open Platform
• Feishu API Documentation
• DEVELOPMENT.md - Detailed development guidelines