cinch

Universal skills and agents for every AI harness. Author once, wire anywhere.

See Cinch inspect local inventory and wire skills across harnesses in milliseconds.

💡 Why Cinch?

The AI coding assistant ecosystem is deeply fragmented. Every developer and team uses different tools:

• Claude Code stores skills in .claude/skills/<n>/SKILL.md
• Cursor & Codex standardize on .agents/skills/<n>/SKILL.md
• GitHub Copilot expects .github/instructions/<n>.instructions.md with YAML applyTo
• Gemini CLI requires commands in .gemini/commands/<n>.toml with raw prompt blocks
• Windsurf / Devin parses .devin/rules/<n>.md with strict character limits
• Cline reads .clinerules/<n>.md
• Aider ignores unconfigured files and requires entries appended to .aider.conf.yml

Whenever you switch harnesses, try a new AI tool, or share custom workflows with your team, you're forced to manually rewrite prompt files, reformat frontmatter, and hunt down obscure config paths.

Cinch is the universal translation bridge. It scans your existing local skills and agents, translates them through native dialect adapters, and attaches them directly into any project workspace. No proprietary marketplaces, no redundant skill libraries—just one CLI to bring your favorite skills everywhere.

⚡ Quickstart

Claude Code + Cursor + Codex (most common)

Cursor and Codex share the same on-disk layout (.agents/skills/). Wire once and both read the skill; Claude Code gets its own .claude/skills/ copy.

# From a checkout that has example skills (or point --from-dir at your own):
uvx cinch-init \
  --from-dir examples/skills \
  --harness claude,cursor,codex \
  --skills humanizer \
  --yes

No Claude skills on disk yet? Use the bundled starters instead:

uvx cinch-init --starter --harness claude,cursor,codex --yes

Interactive or other harnesses

# Interactive wizard: discover skills and pick target harnesses
uvx cinch-init

# Also wire Copilot / Gemini / etc. in the same run
uvx cinch-init --from-harness claude --harness cursor,copilot,gemini --skills humanizer --yes

Install globally with pipx install cinch-init or pip install cinch-init.

🔄 One Skill, Every Dialect (The Rosetta Stone)

Author your workflow once in standard Markdown. Cinch translates it into each harness's native format on the fly.

Source: ~/.claude/skills/humanizer/SKILL.md

---
name: humanizer
description: Convert robotic AI prose into punchy engineering writing
paths:
  - "**/*.md"
---
# Humanizer Guidelines
- Cut throat-clearing openers ("Certainly! Here is...").
- Use active voice and concrete verbs.

Native Translations Generated by Cinch:

---
name: "humanizer"
description: "Convert robotic AI prose into punchy engineering writing"
paths:
  - "**/*.md"
---

# Humanizer Guidelines
- Cut throat-clearing openers ("Certainly! Here is...").
- Use active voice and concrete verbs.

---
applyTo:
  - "**/*.md"
description: "Convert robotic AI prose into punchy engineering writing"
---

# Humanizer Guidelines
- Cut throat-clearing openers ("Certainly! Here is...").
- Use active voice and concrete verbs.

description = "Convert robotic AI prose into punchy engineering writing"
prompt = """
# Humanizer Guidelines
- Cut throat-clearing openers ("Certainly! Here is...").
- Use active voice and concrete verbs.
"""

---
trigger: "manual"
description: "Convert robotic AI prose into punchy engineering writing"
globs:
  - "**/*.md"
---

# Humanizer Guidelines
- Cut throat-clearing openers ("Certainly! Here is...").
- Use active voice and concrete verbs.

# humanizer

> Convert robotic AI prose into punchy engineering writing

# Humanizer Guidelines
- Cut throat-clearing openers ("Certainly! Here is...").
- Use active voice and concrete verbs.

read:
  - ".aider/humanizer.md"

🤝 Supported Harness Matrix

Every mapping is backed by vendor documentation and verified through automated conformance tests.

Planned Harnesses: Grok CLI, Continue.

Zed

Zed's agent reads Agent Skills from the same cross-vendor .agents/skills/ layout Cinch already writes for Cursor and Codex:

• Global: ~/.agents/skills/<name>/SKILL.md
• Project-local: <worktree>/.agents/skills/<name>/SKILL.md

Type / in the agent panel and pick the skill, or load it with an @<skill> mention. The Skills Manager opens with cmd-alt-l (macOS) / ctrl-alt-l (Linux/Windows). Project-local skills load only from a trusted worktree. A skill folder may also contain scripts/, references/, and assets/; Cinch copies those alongside the SKILL.md when the source ships them.

Because Zed shares .agents/skills/ with Cursor and Codex, a --harness cursor,zed run writes the file once (as Cursor's rendering, which includes paths) and reports Zed as shared. Wire --harness zed on its own for Zed's minimal name/description frontmatter.

🛠️ Command Reference

# 1. Discover harnesses detected on your machine
cinch harnesses

# 2. Inspect available skills, agents, commands, and hooks on disk
cinch inventory --harness claude
cinch inventory --harness cursor --purpose security

# 3. Preview how a skill translates without writing any files
cinch preview humanizer --target copilot
cinch preview security-auditor --from-dir examples/skills --target gemini

# 4. Interactive init wizard (prompts for starter skills if none on disk)
cinch init

# 5. Wire curated starters into Claude Code + Cursor/Codex
cinch init --starter --harness claude,cursor,codex --yes

# 6. Multi-target cross-harness wiring (non-interactive)
cinch init \
  --from-harness claude \
  --harness cursor,copilot,gemini,windsurf \
  --skills humanizer,security-auditor \
  --yes

# 7. Check workspace sync & wired file integrity
cinch status

# 8. Inspect workspace drift with syntax-highlighted unified diffs
cinch diff

# 9. Validate & lint SKILL.md files against dialect best practices
cinch check
cinch check examples/skills/docker-deploy

# 10. Attach from an external skills repository or checkout
cinch init --from-dir examples/skills --harness cursor,copilot --yes

CLI Flags

⚡ Blistering Performance

Cinch is written in pure, dependency-light Python and designed for microsecond-scale execution. Running the included benchmark suite (benchmark/run.py):

Zero perceptible lag in your CLI or agent loops.

🧱 Architecture: The 3-Stage Pipeline

Cinch never performs direct, naive file copying between disparate tools. Instead, it processes assets through a clean, verifiable translation pipeline:

┌─────────────────────────┐
│  Source Item on Disk    │ (e.g. ~/.claude/skills/humanizer/SKILL.md)
└────────────┬────────────┘
             │ parse_doc()
             ▼
┌─────────────────────────┐
│     Canonical Doc       │ (Unified AST: name, description, body, paths, support)
└────────────┬────────────┘
             │ Adapter.render()
             ▼
┌─────────────────────────┐
│      RenderedFiles      │ (Tailored to each target dialect + merge rules)
└────────────┬────────────┘
             │ apply_plan()
             ▼
┌─────────────────────────┐
│  Verified Project Files │ + .cinch.json execution audit manifest
└─────────────────────────┘

The Inline vs. Pointer Rule

• Inline by default: The skill body is written directly into the target's native file with correctly translated frontmatter.
• Pointer when limits or assets require it: If a skill exceeds documented per-file limit (e.g., Windsurf's 12,000 character rule threshold) or bundles supporting scripts (scripts/, references/), Cinch copies the support directory to .cinch/skills/<name>/ and creates a native adapter file pointing to it.

🛡️ Trust & Safety Guarantees

• 🔒 100% Local-First: Runs entirely on your local machine. No telemetry, no cloud dependencies, no network requests.
• 🛡️ Zero Destructive Overwrites: Existing hand-crafted rule files are never silently replaced (outcome: "exists").
• 📝 Verifiable Manifest: Every run updates .cinch.json with an exact audit trail of files written, merged, or skipped.

🌟 Community & Contributing

Contributions are warmly welcome! Whether adding an adapter for a new harness, refining prompts, or improving test fixtures:

• Read our Contributing Guide
• Check our Security Policy
• License: MIT