contact (v1)

The "contact (v1)" Skill for Happycapy Skills

What Is This

The contact (v1) skill, identified as lark-contact, is a user and organization directory integration designed for the Happycapy Skills platform. It provides programmatic access to organizational contact data through the Feishu (Lark Suite) communication and collaboration platform. Specifically, this skill enables developers and users to search for users, retrieve user information, and explore organizational structure data (such as departments and members), all via CLI commands. The contact (v1) skill is packaged with shortcuts for the most common operations, which are exposed through the Happycapy Skills interface.

This skill is primarily powered by the lark-cli tool. It acts as a bridge between the Happycapy Skills environment and Feishu’s organizational API endpoints, enabling querying of user profiles, searching for colleagues by keyword, and exploring department details. The key features are accessible via high-level shortcut commands, making it straightforward to integrate personnel search and lookup into workflows or other automations.

Why Use It

Organizations using Feishu (Lark) as their communication backbone often need to programmatically fetch user details or search for colleagues based on varied criteria such as name, email, or phone number. Typical use cases include:

• Automating onboarding or offboarding workflows with up-to-date user data
• Building custom dashboards that display team or company contact information
• Implementing chatbots or integrations that reference user profiles or department structures
• Quickly searching for colleagues or retrieving contact details for collaboration

Instead of building custom integrations from scratch, the contact (v1) skill provides a robust, tested interface tailored for these scenarios. It abstracts away the complexity of handling authentication, permissions, and direct API calls, allowing users to focus on their core business logic.

How to Use It

Prerequisites

• Authentication and Permissions: Before using the contact (v1) skill, you must ensure that authentication and permissions are set up as described in the shared SKILL.md file (../lark-shared/SKILL.md). This step is critical for accessing user data securely.
• Tooling Dependency: The skill requires the lark-cli binary to be available in your environment.

Shortcuts

The skill exposes high-level shortcut commands that encapsulate the most common tasks. These shortcuts are recommended for use due to their simplicity and reliability.

Search Users: +search-user

This shortcut allows you to search for users based on keywords such as name, email address, or phone number. The results are sorted by relevance.

Example Usage:

lark-cli contact +search-user --keyword="Alice"

Expected Output:

A list of users whose profiles match the keyword "Alice", sorted by relevance. Each result includes key details such as user ID, name, email, and department.

Get User Info: +get-user

This shortcut retrieves detailed information for a specific user. If no user_id is provided, it returns the current user's information.

Example Usage:

lark-cli contact +get-user --user_id="ou_123abc"

If you want your own info:

lark-cli contact +get-user

Expected Output:

The full profile for the given user, or for yourself if the --user_id flag is omitted. This typically includes name, open_id, email, phone, department, and possibly additional metadata.

CLI Help

You can access the full CLI help for contact-related commands by running:

lark-cli contact --help

This provides comprehensive documentation of available flags, parameters, and usage patterns.

When to Use It

Use the contact (v1) skill in any scenario where you need to:

• Search for users within your organization by name, email, or phone number
• Retrieve detailed information about a specific user or about yourself
• Query department structure or obtain lists of users in a department (if supported by the skill version)
• Enable custom scripts, automation, or integrations that rely on up-to-date directory data

Examples include HR applications, onboarding/offboarding automation, employee self-service tools, and chatbot integrations.

Important Notes

• Authentication Is Mandatory: You must follow the authentication and permissions setup in the shared SKILL.md (../lark-shared/SKILL.md). Failing to do so will prevent API access and may cause authorization errors.
• Use Shortcuts First: If a shortcut exists for an operation, always use it instead of lower-level or legacy commands. Shortcuts are better maintained and encapsulate best practices.
• Data Freshness: The skill queries live data from the Feishu platform, so user and department information is always up-to-date.
• Privacy and Permissions: User data access is governed by organization policies and Feishu’s API permissions. Make sure your app or script has the necessary scopes and approvals.
• CLI Dependency: The lark-cli binary must be installed and accessible in your environment. Refer to the official source repository for installation and setup instructions.

By leveraging the contact (v1) skill, you can seamlessly integrate Feishu organizational directory features into your own workflows, scripts, or applications, ensuring access to reliable and current user information.