Douyin Skills

[!IMPORTANT] This repository implements Douyin workflows today. Support for other Agent clients and social platforms is a direction, not a shipped compatibility claim. It is not an official Douyin product, and it does not provide bulk engagement or platform-control bypasses.

Why this project exists

Agents can plan a multi-step task, but the social web is where plans meet stateful logins, changing pages, risk checks, and buttons with real consequences. A publishing click cannot be treated like a harmless text-generation step, and an uncertain result should not be reported as success.

douyin-skills is a concrete attempt to make that boundary easier to inspect and reuse. It packages intent as versioned Skills, exposes browser actions through a structured JSON CLI, keeps account sessions in local Chrome, and stops for human review when the page or outcome is uncertain.

Douyin is the current proving ground: a major social platform with real creator workflows and enough operational friction to test whether an agent integration is actually dependable. The project is intentionally narrower than a social-media management suite; it focuses on small, verifiable actions that can become reliable building blocks.

What works today

Everyday Douyin web tasks are not inherently complicated, but browser startup, login state, page transitions, and publish review can interrupt your flow. douyin-skills turns those steps into five composable Skills: your agent understands the intent, then acts through Chrome on your computer.

What makes it different:

• Built for everyday users: install it, then describe the task instead of learning CDP or selectors.
• Agent-readable contract: Skill instructions and JSON results make the workflow reviewable instead of hiding behavior in prompts.
• Local-first: Chrome and account profiles stay on your computer; the debug endpoint only listens on 127.0.0.1.
• Fails safely: publishing requires validation and explicit confirmation; risk pages and uncertain outcomes stop for human review.
• Composable: authentication, environment, discovery, publishing, and interactions work independently or as a workflow.
• Drift-aware: sanitized fixtures lock down how login, risk, search, detail, and publish states are interpreted without storing account data.
• Maintainable: one JSON CLI, focused regression tests, cross-platform CI, and Skills that document the real runtime contract.

See the guarded workflow

This 40-second walkthrough is entirely synthetic: it makes no network requests and contains no real Douyin page, account, cookie, QR code, phone number, profile path, or user content. It demonstrates the control flow and deliberately ends at Prepared · not published. It is not evidence that a live page version or account passed end-to-end validation.

The source is assets/demo/index.html. Maintainers with Chrome and FFmpeg can reproduce the GIF with npm run render:demo.

Start in three minutes

OpenClaw: full bundled experience (recommended)

openclaw skills install git:zJay26/douyin-skills@main

Then tell your agent:

Use douyin-env to install dependencies and run the environment checks.

This installation command and nested Skill discovery model follow the official OpenClaw documentation.

Manual runtime setup

git clone https://github.com/zJay26/douyin-skills.git
cd douyin-skills
npm install
python scripts/cli.py doctor

You can also choose Code → Download ZIP on GitHub, extract the complete directory, and run the same npm install and doctor commands. Replace python with python3 if needed.

The environment is ready when the JSON from doctor contains "success": true and an empty required_failures list.

Stable release download

For a versioned, checksum-verifiable install, download douyin-skills-v1.1.0.zip and SHA256SUMS from the v1.1.0 Release. Verify the ZIP before extracting it:

# Linux / macOS
sha256sum -c SHA256SUMS

# Windows PowerShell: compare this value with the matching SHA256SUMS line
Get-FileHash .\douyin-skills-v1.1.0.zip -Algorithm SHA256

The named ZIP contains the complete repository under one versioned directory, including the privacy-safe Demo. GitHub's automatic source archives are separate and are not covered by the published checksum.

Your first workflow

1. Check the environment

   Use douyin-env to configure and verify this Skill.

2. Sign in

   Check Douyin login with the default account. If I am signed out, show me the QR code.

3. Describe the task

   Search for “city night photography” and return five titles, authors, content types, and links.

   With my work account, fill the photo-publishing form with these three images and this caption. Pick suitable music, but stop before publishing.

4. Confirm publishing separately

   I reviewed the page. Publish once, and do not retry if the result is not explicitly confirmed.

The first login creates an isolated local Chrome profile. If Douyin later presents a captcha, identity check, or risk page, the CLI switches to a visible browser and waits for you to complete it manually.

Why this matters to the Agent ecosystem

The larger contribution is not a claim that one repository has solved every social platform. It is a working separation between what an agent decides and what a real browser is allowed to do.

The root SKILL.md follows the open Agent Skills specification, which is designed for portable, version-controlled agent knowledge. OpenClaw follows that specification and currently provides the documented installation path for this repository. Execution on other Agent Skills clients is not part of CI yet, so treat cross-client use as integration work rather than plug-and-play support.

This distinction matters: the repository offers a reusable pattern today, not a universal compatibility badge.

Who may find the pattern useful

• Operators who want useful automation without handing browser sessions to a hosted control service.
• Agent builders looking for a concrete contract between model intent and stateful browser actions.
• Tool and client maintainers exploring how Agent Skills, CLIs, or tool protocols can share one execution core.
• Researchers and reviewers interested in human checkpoints, uncertainty, and honest completion semantics.

Starting with Douyin, not ending there

The current implementation is specific to Douyin. Its URLs, selectors, login pages, creator forms, and content types must not be presented as portable code. The surrounding architecture is more general:

flowchart LR
    A["User intent"] --> B["Agent Skill"]
    B --> C["Structured JSON CLI"]
    C --> D["Local browser runtime"]
    D --> E["Human checkpoint"]
    D --> F["Platform adapter"]
    F --> G["Douyin · implemented today"]
    F -. "future adapter work" .-> H["Other social / creator platforms"]

A future adapter for another social or creator platform could reuse the Skill-to-CLI boundary, browser lifecycle, local profiles, timeouts, validation states, and human-review policy. It would still need its own authorized login flow, URLs, selectors, domain rules, tests, and platform-policy review.

No other platform adapter ships in this repository today. See the Agent ecosystem design note for the portability boundary and ROADMAP.md for the staged plan.

Five composable Skills

The root SKILL.md routes multi-step requests. Child Skills address scripts with OpenClaw's recommended {baseDir} convention, so execution does not depend on the agent's current working directory.

Safety model and scope

What it does

• Operates public pages on Douyin Web and Creator Center Web.
• Keeps login state in loopback-only Chrome and supports named, isolated profiles.
• Shows the browser and waits when captcha or identity verification is required.
• Checks title, body, images, music, and button state before publishing.
• Returns explicit states for uncertain page outcomes and asks for human verification.

What it deliberately does not do

• Bypass captchas, identity checks, risk controls, or platform rate limits.
• Comment, reply, send direct messages, publish videos, save drafts, or schedule posts.
• Farm accounts, inflate engagement, scrape entire profiles, or run bulk operating pipelines.
• Retry when publishing is uncertain, or click like/favorite again when the final state is unknown.

[!WARNING] Web interfaces change and automation may be restricted by the platform. Use a reasonable frequency and verify important actions on the actual page. You remain responsible for applicable law, platform rules, and content permissions.

Implementation architecture

flowchart LR
    A["User intent"] --> B["Agent"]
    B --> C["5 Skills"]
    C --> D["Python JSON CLI"]
    D --> E["Node.js CDP bridge"]
    E --> F["Chrome · 127.0.0.1"]
    F --> G["Douyin Web"]
    D -. "config and profiles" .-> H["~/.douyin-skills/"]

• scripts/cli.py is the only public command entry point and always produces JSON.
• Python uses only the standard library; the Node.js side only depends on the lockfile-pinned ws package.
• The Chrome launcher handles cross-platform browser discovery, port checks, profile isolation, and headless/headed transitions.
• The CDP bridge drives pages through timeout-bounded HTTP/WebSocket calls without exposing the debug port to LAN or public networks.
• Page logic is split into authentication, discovery, publishing, and interaction modules, with shared URL, wait, and error handling.
• The platform-facing code is not generic yet; the ecosystem design note identifies the boundary that should be extracted before another adapter is attempted.

Requirements

The CLI searches PATH and common browser locations on Windows, macOS, Linux, and WSL. You can also specify an executable explicitly:

CHROME_BIN=/absolute/path/to/chrome python scripts/cli.py doctor

When a Linux container runs as root, the launcher adds Chrome's required --no-sandbox flag. It does not disable the browser sandbox for regular users.

CLI reference

Every command returns JSON. Put global account options before the subcommand:

python scripts/cli.py --account work check-login

Discover the installed runtime and result-contract versions without launching Chrome:

python scripts/cli.py version

Agent integrations should follow the stable minimum fields and certainty rules in the JSON result contract.

Run python scripts/cli.py --help or a subcommand's --help for every option.

Publishing states are not interchangeable

Likes and favorites may similarly return state_verified: false. That proves a click occurred, not the final state; the agent should say so and avoid repeating the action.

Local data

The default data directory is ~/.douyin-skills/; set DOUYIN_SKILLS_HOME to use another local path. It may contain named-account configuration, runtime state, and Chrome profiles:

• Do not commit it to Git.
• Do not upload it to cloud drives, issues, or third-party services.
• remove-account unregisters the account but does not promise to delete profile data.
• Back up and report corrupt configuration instead of rebuilding or overwriting it automatically.

Repository layout

.
├── SKILL.md                  # Multi-step entry point and shared guardrails
├── skills/                   # Five composable child Skills
├── scripts/
│   ├── cli.py                # Unified JSON CLI
│   ├── doctor.py             # Environment diagnostics
│   ├── chrome_launcher.py    # Chrome lifecycle and profiles
│   ├── cdp_client.mjs        # Node.js CDP bridge
│   └── douyin/               # Auth, discovery, publish, interaction modules
├── tests/                    # Python unit tests and Node.js bridge test
├── fixtures/page_states/     # Synthetic state-contract regression fixtures
├── assets/                   # README and social-preview artwork
├── docs/                     # Agent ecosystem and adapter design notes
├── ROADMAP.md                # Evidence-led project direction
└── .github/                  # CI, dependency updates, collaboration templates

Development and verification

npm ci
python -m compileall -q scripts tests/python
python -m unittest discover -s tests/python -v
python scripts/validate_fixtures.py
python scripts/validate_repository.py
npm run check
npm test

python -m pip install ruff==0.16.2
ruff check scripts tests/python
ruff format --check scripts tests/python

CI tests Windows (Python 3.13 / Node.js 24) and Ubuntu (Python 3.9 / Node.js 18), with a separate Ruff check. It also validates the synthetic page-state fixtures, including their expected certainty semantics and privacy rules. CI does not perform real account login, captcha, or publishing; those end-to-end outcomes still depend on the account, page version, and platform policy at that moment. The exact release gate and non-goals are recorded in Validation and support boundaries; versioned changes are listed in the changelog, and maintainer steps live in the release process.

Read CONTRIBUTING.md before sending changes. Use GitHub Discussions for open-ended workflow and adapter ideas, and Issues for reproducible defects or scoped work. Report security problems privately through SECURITY.md, and never paste account or session data into a public issue.

FAQ

The project has no remote-control service. It talks to Chrome on 127.0.0.1, and account configuration and profiles stay local by default. Chrome still communicates with Douyin normally when you visit the website.

The CLI detected a captcha, identity check, or risk page and switched to headed mode for manual completion. It does not attempt to bypass the check.

If the state is publish_clicked_unconfirmed, check Creator Center first. Do not click again because that may create a duplicate post.

No. The project intentionally focuses on small, clear local workflows: login, discovery, photo publishing, and one-at-a-time basic interactions.

Contributing, license, and trademarks

Focused, tested contributions that preserve the safety model are welcome. Useful starting points include reproducible page-compatibility reports, selector fixtures, clearer result semantics, documentation for another Agent Skills client, and design work toward a clean platform-adapter boundary. Start with CONTRIBUTING.md and the roadmap.

This project is available under the MIT License. douyin-skills is not affiliated with, authorized by, or officially connected to Douyin, ByteDance, or OpenClaw. Product names are used only to identify compatibility.