How Skills Integrate with AI Agents Like OpenClaw and Codex in social-auto-upload

Skills integrate with AI agents through self-contained SKILL.md definitions that declare CLI contracts, enabling agents like OpenClaw and Codex to discover and invoke platform-specific automation via the sau command-line interface.

The social-auto-upload repository provides a framework for AI agents to automate social media uploads through a structured skill system. By packaging automation capabilities as discoverable skills with standardized CLI interfaces, the project enables seamless integration with agent frameworks like OpenClaw, Codex, and Claude Code without requiring agents to parse complex source code.

Skill Structure and the SKILL.md Contract

A skill in this repository is a self-contained directory describing a concrete capability for an AI agent. The heart of every skill is a SKILL.md file that declares the skill name, description, and the concrete CLI commands the agent should invoke.

For example, the Douyin upload skill lives in skills/douyin-upload/SKILL.md and instructs the agent to prefer the sau command-line interface for login, cookie checks, video, and note uploads. This file acts as the stable contract between the agent and the underlying automation, abstracting away the Playwright implementation details found in utils/base_social_media.py.

Packaging and Discovery Mechanism

The project distributes skills via the Python package manager. After installing the social-auto-upload package via pip, the wheel contains embedded copies of each skill directory.

To activate skills for agent use, run:

pip install social-auto-upload
sau skill install

The sau skill install command copies the embedded skill directories from the package into the agent's skill folder (e.g., ~/.codex/skills/). As documented in docs/skill-distribution.md, this package-plus-skill model ensures version consistency between the CLI tool and the skill definitions agents rely upon.

Agent Bootstrap Process

Both OpenClaw and Codex require a bootstrap prompt that configures the repository before task execution. The repository provides this prompt in docs/agent-bootstrap.md, which instructs the agent to:

1. Install the Python environment using uv or pip.
2. Verify CLI availability with sau --help and platform-specific help commands (e.g., sau douyin --help).
3. Install skills via sau skill install.

Only after completing these steps does the agent gain access to skill definitions and the ability to issue platform-specific commands. This bootstrap sequence ensures the agent operates within a verified environment with all necessary CLI contracts in place.

Command Execution Flow

When an agent receives a request such as "upload a Douyin video," the integration follows a deterministic execution path:

1. Skill Lookup: The agent locates the douyin-upload skill in its skill directory.
2. Command Construction: The agent reads skills/douyin-upload/SKILL.md to identify the exact CLI command structure (sau douyin upload-video ...).
3. Parameter Injection: The agent constructs the command line with required arguments (--account, --file, --title, --desc, --tags, --schedule, --headless).
4. CLI Execution: The sau CLI (implemented in sau_cli.py) parses arguments through build_parser and routes to the upload-video sub-command.
5. Automation: The CLI calls upload_video(request), which drives Playwright browser automation via utils/base_social_media.py.
6. Response: The CLI returns a success or failure message that the agent forwards to the user.

This flow demonstrates how skills serve as the contract layer, allowing agents to invoke complex browser automation without understanding Playwright internals.

Agent-Specific Implementation Strategies

Different AI agents require specific handling for optimal integration with the skill system.

OpenClaw functions best when the repository is mounted and the full bootstrap prompt from docs/agent-bootstrap.md is pasted directly. OpenClaw can display QR-code images generated during the login skill action, making the authentication flow seamless.

Codex requires the bootstrap sequence to run first (install, sau skill install) before accepting platform actions. After initialization, Codex uses the skill-defined CLI contracts to build and execute commands.

Claude Code follows the same pattern as Codex: set the repository as the current workspace, send the bootstrap prompt, then proceed through the "install → verify → login → upload" workflow.

Summary

• Skills are self-contained directories with SKILL.md files that define CLI contracts for AI agents.
• The sau skill install command bridges the packaged Python distribution to the agent's skill directory (e.g., ~/.codex/skills/).
• Agents require bootstrap prompts from docs/agent-bootstrap.md to initialize the environment and verify CLI availability.
• Execution flows from skill discovery → command construction → sau_cli.py parsing → Playwright automation in utils/base_social_media.py.
• OpenClaw, Codex, and Claude Code each follow specific initialization patterns documented in the bootstrap configuration.

Frequently Asked Questions

How does an AI agent discover available skills in social-auto-upload?

The agent discovers skills through the sau skill install command, which copies embedded skill directories from the installed Python package into the agent's local skill folder (such as ~/.codex/skills/). Each skill contains a SKILL.md file that the agent reads to understand available commands and parameters.

What is the role of the SKILL.md file in agent integration?

The SKILL.md file serves as the contract between the AI agent and the automation layer. It declares the skill name, description, and exact CLI commands (like sau douyin upload-video) that the agent should construct. This abstraction allows agents to invoke complex browser automation without reading the underlying Python source code in utils/base_social_media.py.

How do OpenClaw and Codex differ in their skill integration approach?

OpenClaw excels at handling interactive elements like QR-code login displays directly within its interface, making it ideal for the authentication flows defined in skills. Codex requires strict adherence to the bootstrap sequence—installing the package and running sau skill install before accepting task commands—but otherwise follows the same CLI contract pattern defined in the skill files.

Where is the command-line interface implemented that agents invoke?

The CLI is implemented in sau_cli.py at the repository root. This file contains the build_parser logic that handles sub-commands like upload-video, validates arguments such as --account and --file, and routes execution to platform-specific upload functions that utilize Playwright for browser automation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}