Skills

Tangly ships two skills under skills/ in the repo. They’re Claude Code skills — Markdown files with frontmatter that Claude Code loads on demand and uses to scope its behavior.

What you get

tanglify

Build, customize, and ship documentation sites with Tangly — a self-hosted, open-source documentation framework that renders Mintlify projects unmodified. Covers initializing a documentation project, validating with tangly check, authoring docs.json + MDX content, porting an existing Mintlify docs site via tangly migrate, and deploying static output to Vercel, Cloudflare Pages, Netlify, or any CDN (including subpath hosting via —base).

The skill activates whenever Claude Code sees a Tangly project (cwd has tangly.toml, docs.json, or you mention any of the trigger keywords). It carries:

• Every CLI command’s flags + when to use each.
• The docs.json schema with field-by-field guidance.
• Frontmatter conventions.
• Migration patterns from Mintlify.
• Deployment recipes for Vercel, Cloudflare, Netlify, static.

tech-documentation

A general technical-writing skill. Diátaxis-grounded — picks the right document type (tutorial, how-to, reference, explanation), enforces plain active voice, structures top-down, grounds claims in runnable examples. Not Tangly-specific; ships in this repo because it pairs well with tanglify for an end-to-end docs workflow.

Install them

The skills follow the agent-skills convention. Install via:

npx skills add tanglydocs/tangly/skills/tanglify
npx skills add tanglydocs/tangly/skills/tech-documentation

This drops the skill files into your local skills directory (~/.claude/skills/ for Claude Code’s CLI, or your project-local skills dir if you’ve configured one). Claude Code picks them up at session start.

Version locking

Each SKILL.md carries a version: field that matches the tangly npm package version. The repo runs scripts/sync-skill-versions.ts as part of every release — bun run version (which wraps changeset version) updates packages/tangly/package.json and every skills/*/SKILL.md in the same commit.

The version reflects “what version of the Tangly CLI did this skill describe.” When the CLI gets a new flag or a flag’s behavior changes, the skill’s version bumps with it. If the skill knows about something the CLI doesn’t, that’s a bug — open an issue.

Updating

npx skills update tanglydocs/tangly/skills/tanglify

Or, if you’d rather pin to a specific version:

npx skills add tanglydocs/tangly/skills/[email protected]

The skill’s metadata.version field shows which version is live.

Use them

After installation, no further setup. Open a Tangly project in Claude Code. Ask it to:

• “Add a new guide page for auth.mdx.”
• “Migrate this mint.json to docs.json.”
• “Switch the theme to geist and update the brand colors.”
• “Build for Cloudflare Pages with the /docs subpath.”
• “What’s in tangly check’s strict mode?”

Claude Code reads the skill, picks the right CLI commands and config patterns, edits files, runs commands. The skill keeps it from inventing flags that don’t exist.

Authoring your own

If you’d rather write a project-specific skill — your team has conventions Tangly’s bundled skill doesn’t know about — see Conventions. The short version: drop a Markdown file in .claude/skills/ with the same frontmatter format. Claude Code merges project skills with global ones.

Source

• skills/tanglify/SKILL.md
• skills/tech-documentation/SKILL.md
• scripts/sync-skill-versions.ts — version sync logic