Cinch

A Python CLI for adapting local skills, agents, and commands to supported AI coding tools.

Illustration of local inventory discovery and translation to several target formats.

---

💡 Why Cinch?

AI coding tools use different instruction formats. Cinch's adapters write to layouts such as:

• Claude Code: .claude/skills/<n>/SKILL.md
• Cursor & Codex: .agents/skills/<n>/SKILL.md
• GitHub Copilot: .github/instructions/<n>.instructions.md with YAML applyTo
• Gemini CLI: .gemini/commands/<n>.toml with prompt blocks
• Windsurf: .devin/rules/<n>.md with an adapter size limit
• Cline: .clinerules/<n>.md
• Aider: Markdown files plus read entries in .aider.conf.yml
• Continue: .continue/prompts/<n>.prompt files and optional customCommands in an existing config.json

Moving a workflow between tools can require changes to paths, frontmatter, and configuration.

Cinch automates those file transformations for its registered adapters. It scans local skills, agents, and commands, previews the generated files, and writes them into a project workspace. This is an experimental interoperability tool: output depends on the source format, adapter, and client version. Unsupported metadata may be omitted, and hooks are preserved only when source and target match. File translation does not guarantee equivalent agent behavior.

---

⚡ Quickstart

Claude Code + Cursor + Codex

Cinch's Cursor and Codex adapters share the same output layout (.agents/skills/). Selecting both writes that destination once; Claude Code gets a separate .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

Harness	Where the skill lands	Invocation example (client-dependent)
Claude Code	.claude/skills/humanizer/SKILL.md	/humanizer
Cursor	.agents/skills/humanizer/SKILL.md	/humanizer
Codex	same .agents/skills/… path as Cursor	$humanizer

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.

---

🔄 Example Translations

Author a workflow in Markdown with frontmatter. Cinch maps the supported fields and body into the selected adapter's output format.

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.

Translations Generated by Cinch:

Cursor & Codex (.agents/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.

GitHub Copilot (.github/instructions/humanizer.instructions.md)

---
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.

Gemini CLI (.gemini/commands/humanizer.toml)

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.
"""

Windsurf / Devin (.devin/rules/humanizer.md)

---
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.

Aider (.aider/humanizer.md + .aider.conf.yml merge)

File .aider/humanizer.md:

# humanizer

> Convert robotic AI prose into punchy engineering writing

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

Merged safely into .aider.conf.yml:

read:
  - ".aider/humanizer.md"

Continue (.continue/prompts/humanizer.prompt)

---
name: "humanizer"
description: "Convert robotic AI prose into punchy engineering writing"
invokable: true
---

{{{ input }}}

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

<!-- cinch paths: **/*.md -->

---

🤝 Target Adapter Matrix

The current adapter registry contains these 12 targets. The conformance fixtures record vendor references, and local tests check generated files. These checks do not establish live-client discovery, execution, or compatibility with every client version.

Harness	Skill Destination	Frontmatter Schema	Notes / Standards
Claude Code	.claude/skills/<n>/SKILL.md	name, description, paths, source metadata	Skill frontmatter is re-rendered
Cursor	.agents/skills/<n>/SKILL.md	name, description, paths	Shared with Codex (one write covers both)
Codex	.agents/skills/<n>/SKILL.md	name, description, paths	Same path as Cursor; supports disable-model-invocation
GitHub Copilot	.github/instructions/<n>.instructions.md	applyTo, description	Native Copilot instruction rules
Gemini CLI	.gemini/commands/<n>.toml	description, prompt (TOML)	Validated TOML prompt command schema
Windsurf	.devin/rules/<n>.md	trigger, description, globs	12,000 character limit pointer fallback
Cline	.clinerules/<n>.md	paths	Clean markdown rule injection
OpenCode	.opencode/commands/<n>.md	description	Native command configuration
Aider	.aider/<n>.md	None (Markdown body)	Automatically merges read: in .aider.conf.yml
Zed	.agents/skills/<n>/SKILL.md	name, description, disable-model-invocation	Shared with Cursor/Codex; commands disable model invocation
Continue	.continue/prompts/<n>.prompt	name, description, invokable	Slash commands; merges customCommands into existing .continue/config.json
Grok	.grok/skills/<n>/SKILL.md	name, description, paths, when-to-use, allowed-tools	xAI Grok Build/CLI; unsupported source frontmatter stripped

Continue

Cinch's Continue adapter writes each skill, agent, or command to .continue/prompts/ as <name>.prompt with invokable: true, intended for slash-command use in compatible clients.

The prompt body preserves Handlebars context variables ({{{ input }}}, {{{ current_file }}}, …), upgrades bare {{ var }} tokens to the triple-brace form, and records Cinch paths as an HTML comment. When a project already has .continue/config.json, Cinch also merges a matching customCommands entry for older Continue installs that still read slash commands from config.

uvx cinch-init --from-harness claude --harness continue --skills humanizer --yes

Zed

Cinch's Zed adapter targets the Agent Skills layout also used by its Cursor and Codex adapters:

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

A skill folder may also contain scripts/, references/, and assets/; Cinch copies those alongside SKILL.md when the source ships them. Check the linked Zed documentation for client discovery, invocation, and workspace trust requirements.

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.

Grok

Cinch's Grok adapter targets .grok/skills/:

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

Each skill is a folder with SKILL.md YAML frontmatter. Cinch emits name, description, optional paths, and Grok-native extras (when-to-use, allowed-tools, argument-hint, user-invocable, disable-model-invocation) when present on the source. Unsupported Claude keys such as hooks are stripped. Commands become slash-only skills via disable-model-invocation: true. Support scripts and references copy into the skill folder.

Wire with cinch init --harness grok (or cinch init --from-harness claude --harness grok).

---

🛠️ 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

Flag	Description
--from-harness <id>	Source harness to read skills from (auto-detected if only one is on disk).
--harness <list>	Target harness(es) to wire (comma-separated list, e.g. cursor,copilot,gemini).
--starter	Include curated starter skills (humanizer, security-auditor, test-writer, git-commit).
--skills <list>	Comma-separated list of skill names to attach.
--agents <list>	Comma-separated list of agent names to attach.
--commands <list>	Comma-separated list of commands/prompts to attach.
--hooks <list>	Comma-separated list of hooks (preserved only when target matches source).
--purpose <catalog>	Filter inventory by category: python, ml, data, web, docs, security, agents.
--from-dir <path>	Extra local root directory containing skills or agents to inventory.
--dry-run	Preview the exact files and paths without writing anything to disk.
--yes	Non-interactive execution (accept defaults or provided flags).

---

⚡ Local Performance Benchmark

The included benchmark measures frontmatter parsing, rendering across registered adapters, and plan resolution plus disk writes using sets of 10, 50, and 100 synthetic skills:

uv run python benchmark/run.py

Results depend on hardware, filesystem, and skill contents. These measurements cover local file processing, not model inference or end-to-end client performance.

---

🧱 Architecture: The 3-Stage Pipeline

Cinch parses source documents, renders target files, and applies a write plan. Some formats pass through unchanged; support files and same-harness hooks are copied.

┌─────────────────────────┐
│  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()
             ▼
┌─────────────────────────┐
│ Generated Project Files│ + .cinch.json write-outcome manifest
└─────────────────────────┘

The Inline vs. Pointer Rule

• Inline by default: The skill body is written into the target file with the adapter's frontmatter mapping.
• Support files and pointers: Native skill-folder adapters copy support files alongside SKILL.md. Other adapters can place supporting content under .cinch/skills/<name>/ and emit a pointer, including when the Windsurf adapter's 12,000-character threshold is exceeded.

---

🔐 Trust Policy & Provenance Audit

Cinch features a trust policy and provenance framework configured via .cinchpolicy.yml:

# Audit a local folder or remote skill statically
cinch audit ./my-skills

# Output machine-readable JSON for CI pipelines
cinch audit gh:my-org/skills@v1.0.0 --json

# Enforce policies on installation
cinch install gh:my-org/skills@v1.0.0 --enforce-policy

• Inspects licenses, executable scripts, and unsafe path/symlink escapes without executing repository code.
• Supports source allow/deny lists, ref requirements (a SemVer tag or commit SHA), and human review gates for scripts (--reviewed). Tags can move; use a commit SHA when pinning source content.
• Read the full Trust Policy Guide.

---

🛡️ File Handling and Network Use

• Local translation: Inventory, preview, and init can work with local files. Remote-source audit, install, and update operations can clone or fetch repositories; package installation also requires network access unless cached.
• Existing files: Normal init skips differing existing files (outcome: "exists"). Adapter-specific configuration merges and explicit update/watch operations can change files; review the generated plan and diff.
• Write manifest: Applying a plan outside dry-run mode writes .cinch.json with the latest file outcomes and skipped items. It is a write record, not a record of agent execution.

---

🌟 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

If Cinch saves you time wiring AI workflows, please consider giving it a ⭐ on GitHub!