THETA Agent Workflow Skill

English | 中文

Portable agent workflow skill for running safe THETA topic-modeling workflows.

This repository publishes the standalone copy of the THETA workflow skill. The same skill is also mirrored inside the main CodeSoul-co/THETA repository at skills/theta-workflow/.

What It Does

theta-workflow guides an agent through the full THETA workflow:

• Check whether a usable THETA repository exists before doing anything else.
• Confirm cloning if the repository is missing.
• Inspect environment, .env, model paths, and datasets read-only.
• Choose embedding behavior safely: cloud only for zero_shot; local models for supervised, unsupervised, or finetune-capable workflows.
• Recommend models and parameters.
• Generate commands without executing them.
• Require explicit confirmation before writing files, installing dependencies, calling cloud APIs, downloading models, training, overwriting, deleting, or changing git state.
• Read and explain model outputs, tuning needs, and report options.

The skill is plain Markdown plus a read-only Python helper. It does not require a Codex-specific API and can be used by any agent runtime that can read local files and follow skill-style instructions.

Repository Layout

theta-workflow/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── commands.md
│   ├── confirmation-flow.en.md
│   ├── confirmation-flow.zh.md
│   ├── result-analysis.md
│   ├── user-questions.md
│   └── workflow.md
└── scripts/
    └── inspect_theta_env.py

Generic Installation

Copy the skill folder into your agent runtime's skill directory:

mkdir -p "<AGENT_SKILLS_DIR>"
cp -R theta-workflow "<AGENT_SKILLS_DIR>/theta-workflow"

If your runtime does not have a skill directory, point the agent directly at:

theta-workflow/SKILL.md

Example prompt:

Use the THETA Workflow skill in theta-workflow to help me run THETA topic modeling on a policy-text dataset.

If your runtime supports named skill invocation, $theta-workflow can be used as the skill name.

Skill Usage

OpenClaw

OpenClaw skills are discovered from skill roots such as workspace skills/, workspace .agents/skills/, personal ~/.agents/skills/, and managed ~/.openclaw/skills/. OpenClaw's CLI local install expects the source directory itself to contain SKILL.md, so install the theta-workflow/ subdirectory rather than the repository root.

Workspace install:

git clone https://github.com/CodeSoul-co/theta-skill.git
cd theta-skill
openclaw skills install ./theta-workflow --as theta-workflow
openclaw skills list

Global install:

git clone https://github.com/CodeSoul-co/theta-skill.git
cd theta-skill
openclaw skills install ./theta-workflow --as theta-workflow --global
openclaw skills info theta-workflow

Example prompt:

Use theta-workflow to help me run THETA topic modeling on a policy-text dataset.

Codex

Codex can load skills from repository or user skill folders. For a project-specific install, copy the skill into .agents/skills/; for a user-wide install, copy it into ~/.agents/skills/.

Project install:

git clone https://github.com/CodeSoul-co/theta-skill.git
mkdir -p .agents/skills
cp -R theta-skill/theta-workflow .agents/skills/theta-workflow

User install:

git clone https://github.com/CodeSoul-co/theta-skill.git
mkdir -p ~/.agents/skills
cp -R theta-skill/theta-workflow ~/.agents/skills/theta-workflow

Invoke explicitly with a skill mention, or let Codex select it when the prompt matches the SKILL.md description:

Use $theta-workflow to help me run THETA topic modeling on a policy-text dataset.

Codex-compatible runtimes that still use $CODEX_HOME/skills can also install with:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R theta-workflow "${CODEX_HOME:-$HOME/.codex}/skills/theta-workflow"

Restart or reload the runtime if it caches available skills.

Claude Code

Claude Code skills can be installed globally under ~/.claude/skills/ or per project under .claude/skills/. Claude Code uses the directory name as the slash command, so keep the folder name theta-workflow.

Personal install:

git clone https://github.com/CodeSoul-co/theta-skill.git
mkdir -p ~/.claude/skills
cp -R theta-skill/theta-workflow ~/.claude/skills/theta-workflow

Project install:

git clone https://github.com/CodeSoul-co/theta-skill.git
mkdir -p .claude/skills
cp -R theta-skill/theta-workflow .claude/skills/theta-workflow

Invoke directly:

/theta-workflow Help me run THETA topic modeling on a policy-text dataset.

Claude can also load the skill automatically when the user request matches its description.

Platform References

• OpenClaw Skills: https://docs.openclaw.ai/tools/skills
• OpenClaw skills CLI: https://docs.openclaw.ai/cli/skills
• Codex Agent Skills: https://developers.openai.com/codex/skills
• Claude Code Skills: https://code.claude.com/docs/en/skills

Read-Only Preflight

From a THETA checkout, run:

python theta-workflow/scripts/inspect_theta_env.py \
  --repo /path/to/THETA \
  --dataset data/example \
  --mode zero_shot

The helper never writes files, installs dependencies, calls APIs, starts training, or prints secret values.

Sync With THETA

This standalone repository mirrors the skill stored in the main CodeSoul-co/THETA repository. The THETA README also links back to this standalone skill repository.

Pull the latest skill from a THETA checkout:

bash scripts/sync_from_theta.sh /path/to/THETA

Push local standalone edits back into a THETA checkout:

bash scripts/sync_to_theta.sh /path/to/THETA

After syncing in either direction, run:

python /path/to/skill-creator/scripts/quick_validate.py theta-workflow
python theta-workflow/scripts/inspect_theta_env.py --repo /path/to/THETA --json