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

> Learn how skills integrate with AI agents like OpenClaw and Codex in social-auto-upload. Discover how SKILL.md definitions enable CLI automation via the sau command.

- Repository: [Alleria/social-auto-upload](https://github.com/dreammis/social-auto-upload)
- Tags: deep-dive
- Published: 2026-05-31

---

**Skills integrate with AI agents through self-contained [`SKILL.md`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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:

```bash
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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/docs/agent-bootstrap.md) to initialize the environment and verify CLI availability.
- Execution flows from skill discovery → command construction → [`sau_cli.py`](https://github.com/dreammis/social-auto-upload/blob/main/sau_cli.py) parsing → Playwright automation in [`utils/base_social_media.py`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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`](https://github.com/dreammis/social-auto-upload/blob/main/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.