How to use the Hyphens in URLs agent skill

What the hyphens skill makes the agent do

Agent skills are folders of instructions that an AI agent loads when a task matches the skill's description. The hyphens skill is for URL structure work. Its description covers three jobs: auditing URL structures for word separator format, generating slugs from titles, and planning a URL migration from underscores or spaces to hyphens with appropriate redirects.

When the skill is active, the agent can review a site's URL structure, flag underscore or encoded-space URLs, suggest hyphenated replacements, write a slug-generation function, and outline how to redirect old links to new ones.

• Audit: flag URL paths that use underscores between words, spaces encoded as %20 or +, or mixed separators such as /best-practices_guide
• Fix: generate the hyphenated equivalent of each flagged path
• Slugs: write a function that turns a title into a lowercase, hyphenated slug
• Migration: outline 301 redirects, internal link updates, sitemap changes and re-indexing

Why hyphens instead of underscores

The skill is built on the rule that Google treats hyphens in URLs as word separators, while underscores join words into one token. The source gives the example that /seo_practices is read as one word, 'seopractices', rather than 'seo' and 'practices'. Its reasoning is that a URL with underscores matches fewer individual keyword queries.

• Preferred: /best-seo-practices
• Discouraged: /best_seo_practices or /bestseopractices

Install the hyphens skill

Download the ZIP for the hyphens skill from the directory page. You can install it in one of two ways.

For Claude Code, unzip the download into ~/.claude/skills/ to make it available across your projects, or into a project's .claude/skills/ folder to limit it to that project.

For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

Trigger the skill with natural requests

You do not need a special command. The skill loads when your request matches its description, so describe the job in plain words. Mention URLs, slugs, underscores, spaces or redirects so the match is clear.

Include the material the agent needs, such as a list of URLs, a sitemap, router file or CMS slug field, so it can check real paths rather than guessing.

• Audit my URLs for underscores or %20 spaces and count them by section
• Write a slug function that turns blog post titles into lowercase hyphenated slugs
• Plan a migration of /docs/api_reference paths to hyphens with 301 redirects

Check and fix a URL structure

The audit flags three problem patterns: underscores used as word separators, spaces encoded as %20 or +, and mixed separators in one URL. The skill reports the count of non-hyphenated URLs by category.

For fixes, the source's steps are: find the affected pages, generate hyphenated equivalents, set up 301 redirects from old to new URLs, update internal links, submit the new URLs to Google Search Console for re-indexing, and update sitemap.xml so it lists only the new URLs. Going forward, enforce hyphens in your CMS or slug function.

Safety, requirements and when not to use it

The skill lists no required tools. It does not run scripts and does not use the network, so it works by reading and writing text. The skill does not itself create redirects or change your site; you or your team apply the changes.

Do not use it on sites whose URLs are already consistent and stable, because changing them adds redirect risk for little gain. Also avoid changing URLs that bookmarks, API consumers or external links depend on unless proper 301 redirects are in place first.

• Requires: nothing listed
• Runs scripts: no
• Uses network: no

Tips for getting good results

Give the agent the real URL list or router file rather than a description, and ask it to report counts before it proposes changes. Review every proposed redirect map before deploying, since a wrong target loses the search value you are trying to keep.

The skill is rated intermediate difficulty and roughly 10 minutes for the rule itself, but a full migration takes longer because of redirects and re-indexing.

• Ask for a count by category first, then a mapping table
• Check that slug output is lowercase and contains only letters, numbers and hyphens
• Test redirects on a staging copy before going live