tangled-skill
Small Codex skill for working with Tangled
Star
Fork
Watch
2 1 0
Files
skills
.gitignore
README.md
README.md

Tangled Codex Skill #

A Codex skill for working with Tangled repositories, CI, Sites, webhooks, Jujutsu stacked PRs, and self-hosted knots or spindles.

The skill gives Codex Tangled-specific operating guidance: when to use local Git or Jujutsu, when to rely on the Tangled UI, what to inspect before pushing, and which rough edges differ from GitHub-style hosting.

What It Covers #

  • Publishing or mirroring repositories to Tangled without disturbing existing remotes.
  • Diagnosing Tangled SSH remote and key configuration issues.
  • Writing or repairing .tangled/workflows Spindle pipeline files.
  • Checking static site readiness for Tangled Sites.
  • Working with Tangled pull requests, review rounds, and issue surfaces.
  • Handling Jujutsu (jj) workspaces and Tangled stacked PR submission.
  • Troubleshooting commit attribution, SSH commit verification, and DCO signoff for Tangled core contributions.
  • Reasoning about self-hosted knots, spindles, migration, XRPC compatibility, and service configuration.

Skill Layout #

skills/tangled/
|-- SKILL.md
|-- agents/
|   `-- openai.yaml
|-- evals/
|   `-- eval-cases.md
|-- references/
|   |-- problem-patterns.md
|   `-- surfaces.md
`-- scripts/
    `-- inspect_tangled_repo.py

SKILL.md is the main skill entry point. It keeps the core workflow compact and points Codex to reference files only when a task needs more detail.

scripts/inspect_tangled_repo.py is a read-only diagnostic helper for local repositories. It checks Git remotes, Tangled-looking URLs, SSH config resolution, workflow files, candidate Sites directories, commit signing hints, DCO status, and Jujutsu readiness.

The reference files hold the longer Tangled notes:

  • references/surfaces.md: platform surfaces, source anchors, workflow syntax, Sites, webhooks, Jujutsu, and self-hosting details.
  • references/problem-patterns.md: recurring failure modes and guardrails for SSH, punchcards, pipelines, PRs, private code assumptions, and migrations.

Installation #

Copy the skill folder into your Codex skills directory:

mkdir -p "$CODEX_HOME/skills"
cp -R skills/tangled "$CODEX_HOME/skills/tangled"

If CODEX_HOME is not set, use the skills directory for your Codex installation.

After installation, start a new Codex session or reload skills so $tangled appears in the available skill list.

Usage #

Invoke the skill explicitly:

Use $tangled to publish this repo to Tangled and diagnose any SSH or workflow issues.

Or ask for a Tangled-specific task, such as:

Help me mirror this repository to Tangled without changing my GitHub remote.

My Tangled pipeline is not running. Can you inspect the workflow?

I am using Jujutsu and want to submit this stack as Tangled PRs.

For local repository diagnostics, run:

python skills/tangled/scripts/inspect_tangled_repo.py --repo .

For structured output:

python skills/tangled/scripts/inspect_tangled_repo.py --repo . --json

JSON output is redacted by default for shareable reports: local repository paths are shown as <repo> and SSH identity file names as <ssh-identity>. For local/private diagnostics with exact paths, use:

python skills/tangled/scripts/inspect_tangled_repo.py --repo . --json --full-details

To redact human-readable output too, use:

python skills/tangled/scripts/inspect_tangled_repo.py --repo . --redact

For Tangled core contribution checks:

python skills/tangled/scripts/inspect_tangled_repo.py --repo . --core-contribution

Safety Model #

The skill is intentionally conservative.

  • It treats the Tangled web UI as the source of truth for account setup, repository creation, Sites settings, webhooks, collaborators, and final PR submission steps.
  • It inspects local repository state before changing remotes or pushing.
  • It avoids assuming GitHub APIs, GitHub Actions syntax, GitHub-style PR metadata, or a gh-style Tangled CLI.
  • It warns before secrets are placed in workflow files, because workflow YAML and logs should be treated as public unless current Tangled docs or UI prove otherwise.
  • It may edit ordinary repo files, such as .tangled/workflows/*.yml, after inspection when the user asks for a fix.
  • It asks before pushes, remote rewrites, global SSH config edits, actual SSH connection tests, force pushes, destructive Jujutsu operations, or self-hosted service/database changes.

Development Notes #

Keep the skill body concise. Put task-specific details in references/ and keep deterministic checks in scripts/.

When updating Tangled behavior, re-check the live Tangled docs or relevant Tangled core issues first. Some service behavior is young enough that remembered details can go stale.

Run the eval cases manually after meaningful changes:

skills/tangled/evals/eval-cases.md

The evals focus on behavior that matters for agent safety: preserving existing remotes, asking before network-changing operations, avoiding GitHub assumptions, keeping secrets out of public workflow YAML, and treating Jujutsu stacked PR submission as a push plus Tangled UI step.