agentleFS
gaznilgaznil/seo-skills-by-gaznil/skills/blog-taxonomy/SKILL.md

blog-taxonomy

Skill0 starsChanged 3 months agoMITView on GitHub

Extract, suggest, and sync tags and categories for blog posts across all major CMS platforms. Supports WordPress REST API, Shopify GraphQL, Ghost Content API, Strapi REST/GraphQL, and Sanity GROQ. Generates tag suggestions from content analysis (keyword frequency, heading extraction, semantic grouping), enforces minimum post-count thresholds to prevent thin tag archives, and syncs taxonomy via authenticated API calls. Use when user says "tags", "categories", "taxonomy", "tag suggestions", "sync tags", "WordPress tags", "Shopify tags".

  • Reads credentials

3 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the target file and extract:

    line 32
  2. Distinctive:

    All H2 and H3 headings (primary topic signals)

    line 33
  3. Distinctive:

    Use consistent slug format: lowercase, hyphen-separated

    line 243
  4. Distinctive:

    Every post needs exactly 1 primary category

    line 244
  5. Very specific:

    Missing environment variables: If CMS_TYPE, CMS_URL, or CMS_API_KEY is unset, report which variable is missing and provide the expected …

    line 261
  6. Very specific:

    Invalid credentials: If the CMS API returns 401/403, report "Authentication failed - check CMS_API_KEY" and do not retry

    line 262
  7. Very specific:

    Connection timeouts: If the CMS endpoint is unreachable after 10 seconds, report the timeout and suggest checking CMS_URL

    line 263
  8. Distinctive:

    Duplicate tag slugs: If a tag already exists on the CMS, skip creation and note "Tag already exists: [name]"

    line 264
  9. Distinctive:

    Rate limits: If the CMS API returns 429, wait and retry once.

    line 265
  10. Very specific:

    Unsupported CMS: If CMS_TYPE is not one of the 5 supported platforms, list the valid options and exit

    line 266

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Blog Taxonomy

Manage tags, categories, and topic clusters across CMS platforms.

Commands

CommandPurpose
/blog taxonomy suggest <file>Extract candidate tags and categories from content
/blog taxonomy sync <cms>Push taxonomy to CMS via authenticated API
/blog taxonomy audit [directory]Check for thin tags, orphan tags, taxonomy bloat

Tag Suggestion Workflow

Step 1: Parse Content Structure

Read the target file and extract:

  • All H2 and H3 headings (primary topic signals)
  • Bold and italic phrases (emphasis signals)
  • Existing frontmatter tags/categories if present

Step 2: Frequency Analysis

Scan the body text for high-frequency phrases:

  • 1-word terms: minimum 4 occurrences (excluding stop words)
  • 2-word phrases: minimum 3 occurrences
  • 3-word phrases: minimum 2 occurrences

Exclude common non-tag words: articles, prepositions, conjunctions, pronouns.

Step 3: Semantic Grouping

Group related candidates into clusters:

  • Merge singular/plural variants (keep the more common form)
  • Merge hyphenated and non-hyphenated forms
  • Group synonyms under the highest-frequency term

Step 4: Deduplicate and Rank

  • Fuzzy match on slugified names (Levenshtein distance <= 2)
  • Score each candidate: (frequency * 2) + (heading_presence * 5) + (emphasis * 1)
  • Return top 5-10 ranked suggestions

Output Format

## Tag Suggestions: [Post Title]

| Rank | Tag | Score | Source |
|------|-----|-------|--------|
| 1 | content-marketing | 18 | H2 + 6 mentions |
| 2 | seo-strategy | 14 | H3 + 4 mentions |
| 3 | keyword-research | 11 | 5 mentions + bold |

### Suggested Categories
- Primary: [best-fit category]
- Secondary: [optional second category]

CMS Adapters

Adapter Overview

CMSAPI TypeAuth MethodTags Model
WordPressRESTApplication Passwords (base64)First-class entities with IDs
ShopifyGraphQL (Admin API)Admin API access tokenString array on Article
GhostREST (Admin API)API key with JWT signingFirst-class entities
StrapiREST or GraphQLAPI token (Bearer)User-defined content type
SanityGROQ / MutationsProject token (Bearer)Document type

WordPress Adapter

List tags:

GET {CMS_URL}/wp-json/wp/v2/tags?per_page=100&search={keyword}
Authorization: Basic {base64(username:app_password)}

Create tag:

POST {CMS_URL}/wp-json/wp/v2/tags
Body: {"name": "Tag Name", "slug": "tag-name", "description": "Optional"}

List categories (hierarchical, supports parent field):

GET {CMS_URL}/wp-json/wp/v2/categories?per_page=100

Create category:

POST {CMS_URL}/wp-json/wp/v2/categories
Body: {"name": "Category", "slug": "category", "parent": 0}

Assign tags to post:

POST {CMS_URL}/wp-json/wp/v2/posts/{id}
Body: {"tags": [1, 2, 3], "categories": [4]}

Pagination: follow X-WP-TotalPages header for full listing.

Shopify Adapter

Tags on Shopify are string arrays on the Article object, not first-class entities.

Update article tags (GraphQL Admin API):

mutation {
  articleUpdate(id: "gid://shopify/Article/123", article: {
    tags: ["tag-one", "tag-two", "tag-three"]
  }) {
    article { id tags }
    userErrors { field message }
  }
}

List all tags in use (GraphQL):

{
  articles(first: 250) {
    edges {
      node { id title tags }
    }
  }
}

Auth header: X-Shopify-Access-Token: {token}

Note: REST API marked legacy Oct 2024. GraphQL required for new apps since Apr 2025.

Ghost Adapter

List tags:

GET {CMS_URL}/ghost/api/admin/tags/?limit=all
Authorization: Ghost {jwt_token}

Create tag:

POST {CMS_URL}/ghost/api/admin/tags/
Body: {"tags": [{"name": "Tag Name", "slug": "tag-name"}]}

JWT generation: sign with admin API key (id:secret format), iat = now, exp = 5 min, audience = /admin/.

Strapi Adapter

Endpoint auto-generated from content types. Typical setup:

GET {CMS_URL}/api/tags?pagination[pageSize]=100
POST {CMS_URL}/api/tags
Body: {"data": {"name": "Tag Name", "slug": "tag-name"}}
Authorization: Bearer {api_token}

Strapi v4+ uses the data wrapper. Check your content type schema for field names.

Sanity Adapter

Query tags (GROQ):

*[_type == "tag"] { _id, name, slug }

Create tag (Mutations API):

POST https://{project_id}.api.sanity.io/v2024-01-01/data/mutate/{dataset}
Body: {"mutations": [{"create": {"_type": "tag", "name": "Tag", "slug": {"current": "tag"}}}]}
Authorization: Bearer {token}

Taxonomy Audit Workflow

Step 1: Inventory

Scan all posts in the target directory (or fetch from CMS). Build a map:

  • tag_name -> [list of post files/IDs using this tag]
  • category_name -> [list of post files/IDs]

Step 2: Health Checks

CheckThresholdAction
Thin tag archives< 5 posts per tagRecommend noindex or merge
Orphan tags0 postsRecommend deletion
Tag bloat> 50 total tagsRecommend consolidation
Category depth> 3 levelsRecommend flattening
Uncategorized postsNo category assignedAssign to appropriate category
Duplicate slugsSame slug, different nameMerge into canonical version

Step 3: Recommendations

Group findings by priority:

  • Critical: orphan tags creating empty archive pages (crawl waste)
  • High: thin tags with < 3 posts (poor user experience, weak SEO signal)
  • Medium: tag bloat over 50 (diluted taxonomy, harder to navigate)
  • Low: naming inconsistencies (mixed case, hyphen vs space)

Output Format

## Taxonomy Audit: [Site/Directory]

**Total tags**: [n] | **Total categories**: [n]
**Healthy**: [n] | **Thin**: [n] | **Orphan**: [n]

### Critical Issues
- [orphan tags list]

### Recommendations
1. Merge [tag-a] and [tag-b] (same topic, [n] combined posts)
2. Delete orphan tags: [list]
3. Add noindex to tag archives with < 5 posts

Site-Wide Guidelines

  • Aim for 5-10 main categories per site (broad topics)
  • Tags should have at least 5 posts before creating an archive page
  • Use consistent slug format: lowercase, hyphen-separated
  • Every post needs exactly 1 primary category
  • Tags per post: 3-8 recommended, never exceed 15

Environment Variables

VariablePurposeExample
CMS_TYPEPlatform identifierwordpress, shopify, ghost, strapi, sanity
CMS_URLBase URL of the CMShttps://example.com
CMS_API_KEYAuthentication credentialApplication password, API token, or key

These must be set in the shell environment. Never store credentials in files or commit them to version control. The skill reads them via $CMS_TYPE, $CMS_URL, and $CMS_API_KEY at runtime.

Error Handling

  • Missing environment variables: If CMS_TYPE, CMS_URL, or CMS_API_KEY is unset, report which variable is missing and provide the expected format
  • Invalid credentials: If the CMS API returns 401/403, report "Authentication failed - check CMS_API_KEY" and do not retry
  • Connection timeouts: If the CMS endpoint is unreachable after 10 seconds, report the timeout and suggest checking CMS_URL
  • Duplicate tag slugs: If a tag already exists on the CMS, skip creation and note "Tag already exists: [name]"
  • Rate limits: If the CMS API returns 429, wait and retry once. Report if the limit persists
  • Unsupported CMS: If CMS_TYPE is not one of the 5 supported platforms, list the valid options and exit

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.