URL: /guides/ai-agents/skills

---
title: Skills
description: Tangly ships two Claude Code skills — `tanglify` for using Tangly, `tech-documentation` for writing the docs that go in it. Version-locked to the CLI.
icon: "hammer"
---

# Skills

Tangly ships two skills under [`skills/`](https://github.com/tanglydocs/tangly/tree/main/skills) in the repo. They're [Claude Code skills](https://docs.claude.com/en/docs/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](https://github.com/anthropics/agent-skills). Install via:

```bash
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`](https://github.com/tanglydocs/tangly/blob/main/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

```bash
npx skills update tanglydocs/tangly/skills/tanglify
```

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

```bash
npx skills add tanglydocs/tangly/skills/tanglify@0.0.7
```

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](/guides/ai-agents/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`](https://github.com/tanglydocs/tangly/blob/main/skills/tanglify/SKILL.md)
- [`skills/tech-documentation/SKILL.md`](https://github.com/tanglydocs/tangly/blob/main/skills/tech-documentation/SKILL.md)
- [`scripts/sync-skill-versions.ts`](https://github.com/tanglydocs/tangly/blob/main/scripts/sync-skill-versions.ts) — version sync logic