Skills

Skills

Tangly ships two skills under skills/ in the repo. They follow the agent-skills convention: Markdown files with frontmatter that any skill-aware agent (Claude Code, Codex, …) 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 your agent 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 both globally with one command:

npx skills add tanglydocs/tangly -g

This drops the skill files into your global skills directory (~/.claude/skills/ for Claude Code; the equivalent global path for Codex and other skill-aware agents). Drop the -g to install into the current project’s skills dir instead. The agent 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

Re-run the install command to pull the latest:

npx skills add tanglydocs/tangly -g

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

Use them

After installation, no further setup. Open a Tangly project in your skill-aware agent (Claude Code, Codex, …). 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?”

The agent 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/ (or the equivalent path for your agent) with the same frontmatter format. Skill-aware agents merge project skills with global ones.

Source

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