Do this with AI
Install the cms-taxonomy skill from Contentstack agent skills and connect the Taxonomy Librarian profile in MCP Profile Hub. Then ask your agent:
Audit the taxonomies in my stack and list terms with no entries, duplicate term names, and content types that still classify content with tags instead.
New to this? Set up your AI workbench first.
Taxonomies are your query layer
Taxonomies are usually treated as a tagging feature for editors. On developers.contentstack.com they became the thing every listing, filter, card, markdown file and agent index reads from. If I had to name the one modeling decision that made the learning restructure possible, it is this one.
The short version
We tag every blog post, guide, kickstart and live stream with four taxonomies: subjects, technology, intent and level.
level and intent are tiny closed sets. Every entry gets exactly one term from each, and those two facets do more work than all the subjects combined.
On top of the taxonomies we added two fields (prerequisites and outcome) and one content type (path). That was enough to build /paths, level and intent filters, and markdown that agents can reason about.
Taxonomies beat tags, select fields and reference fields for classification because they live at the stack level and you query them the same way everywhere.
What was wrong before
The site had plenty of content: multi-chapter guides, kickstarts, live streams, blog posts. What it did not have was order. A developer landing on a guide from search had no idea whether it assumed a week of Contentstack experience or none. There was no "start here" and no "what next".
The site already had two taxonomies. subjects covered topics like ai, headless and personalization. technology covered frameworks like next and nuxt. Both answer "what is this about?" Neither answers the question a developer actually has: "is this page for me, right now?"
We also noticed that a big share of readers are agents, or developers working through one in Cursor, Claude Code or Codex. They read the .md routes and llms.txt. An agent has the same problem as a person, only worse: it cannot skim a page and guess the level from the tone.
Four taxonomies, two of them small
I added two taxonomies to the stack:
level: beginner, intermediate, advanced
intent: learn, build, fix, ship
Because taxonomies are stack-level, I defined them once and attached them to the Taxonomy field on blog posts, guides, kickstarts and live streams. Every entry gets exactly one term from each.
The code that reads them is boring, which is what you want:
type Taxonomy = { taxonomy_uid: string; term_uid: string };
const LEVELS = new Set(["beginner", "intermediate", "advanced"]);
const INTENTS = new Set(["learn", "build", "fix", "ship"]);
export function extractLearningMeta(taxonomies: Taxonomy[] = []) {
const term = (uid: string) => taxonomies.find((t) => t.taxonomy_uid === uid)?.term_uid;
const level = term("level");
const intent = term("intent");
return {
level: level && LEVELS.has(level) ? level : undefined,
intent: intent && INTENTS.has(intent) ? intent : undefined,
};
}One detail that took a few commits to get right: level and intent are not topic tags. The first version rendered "beginner" and "build" next to "ai" and "graphql" in the tag row on every card, and it looked like noise. Now the card shows the content type and level above the title, the detail page shows level and intent in the meta row, and the topic tags only show subjects and technology.
Prerequisites, outcome and paths
Taxonomies tell you what kind of page something is. They do not tell you what you need before you start or what you have when you finish. For that, guides and blog posts got two plain fields:
prerequisites: a list of short noun phrases, like "A Contentstack stack with a delivery token"
outcome: one sentence about what the reader has or can do afterwards
The original plan made prerequisites a reference field pointing at other entries. I went with text. Most real prerequisites are not pages on this site ("Node.js 20", "a Launch project"), and a reference field would have forced editors to create entries for things that are not content.
Then the path content type. A path has a title, URL, description, outcome, the same taxonomies, and an ordered group of steps. Each step references one guide, blog post, kickstart or live stream, plus a checkpoint: what you should have working after that step. The Your first Contentstack site path is the beginner route, from first fetch to Live Preview running locally.
The /paths index is a regular CMS page. Its List block queries the path content type and renders the cards, sorted beginner to advanced.
The same metadata, rendered for agents
None of this needed separate agent copy. Every blog, guide, kickstart, live stream and path has a .md version, and each one starts with frontmatter built from the taxonomies and the two fields:
---
title: "Querying content by taxonomy"
url: "https://developers.contentstack.com/guides/querying-content-by-taxonomy"
type: "guide"
level: "intermediate"
intent: "build"
outcome: "You can filter entries by taxonomy terms through the Delivery API..."
prerequisites:
- "A Contentstack stack with at least one taxonomy applied to a content type"
next:
- "https://developers.contentstack.com/blog/taxonomies-are-your-query-layer"
tags:
- "taxonomy"
- "api"
- "sdk"
---Paths go one step further. /paths/{slug}.md lists the steps in order with their checkpoints, and /paths/{slug}/full.md concatenates the markdown of every step into one document. An agent can load everything a beginner needs in one fetch.
llms.txt is now organized the same way. It opens with the learning paths, then lists content by task: learn, build, fix, ship. Each line carries the level. An agent asked to "help me fix a broken preview" can go straight to the fix section and pick a beginner or advanced page based on the conversation.
Taxonomies, tags, select fields or references
Contentstack gives you four ways to classify an entry. For a label like level or intent, I think three of them are the wrong default.
Tags are free text on the entry. They are fast to add and impossible to govern. One editor writes "Next.js", another "nextjs", a third "next". Nothing stops it, and nothing groups them. Fine for internal notes, bad as a query layer.
Select fields are controlled, which is better, but they belong to one content type. If guides, blog posts and kickstarts all need a level, you define the same three options three times. Add "expert" and you change three schemas. And there is no hierarchy.
Reference fields to a "category" content type are the classic headless answer. They make sense when the category has real content: a description, an image, its own landing page. For a label like "beginner" they are overhead. Each category is an entry that needs publishing, you need includeReference() to read its name, and filtering by a referenced value is more work than filtering by a field on the entry.
Taxonomies are defined once at the stack level, attached to any content type, hierarchical when you need it, and managed by editors without a schema change. Every content type uses the same query syntax, and /v3/taxonomies/entries queries all of them at once. The taxonomy querying guide covers the operators. For the wider modeling question, see modular blocks, references or global fields.
Why intent and level beat subjects
subjects keeps growing. Every new feature adds a term, and the list on /search gets longer. That is fine for browsing, but a long list of topics is not how developers decide what to read.
Developers arrive in a mode. They want to understand something, build something, fix something that broke, or get something into production. That is intent. And they want to know if the page matches what they already know. That is level. Two questions, seven terms, one term per entry.
Small closed sets make reliable facets. Editors cannot get them wrong in creative ways. Counts stay meaningful. An agent can rely on level: beginner meaning the same thing on every page. And the combination is where it gets useful: "intermediate fix" is a short list, and probably the page you need.
What I would do differently
I would add level and intent before writing the content, not after. Tagging every existing entry after the fact is slow, and some older multi-chapter guides honestly span two levels, so you end up making judgment calls per entry.
I would also keep the filter logic close to the data shape from day one. Our /search page counts terms in memory because a taxonomy query returns entries, not facet counts. That works for a site of this size. On a large catalog I would put a search index in front.
Conclusion
Taxonomies are cheap to add, shared across content types, and queryable everywhere. Pick the few facets that answer "is this for me, and does it help with what I am doing?" and make them required. Everything else on the site (cards, filters, paths, frontmatter, llms.txt) can read from that one layer.
Frequently asked questions
Which four taxonomies does developers.contentstack.com use?
subjects, technology, intent (learn, build, fix, ship) and level (beginner, intermediate, advanced). They are applied to blog posts, guides, kickstarts and live streams.
Why not use a select field for level?
A select field belongs to one content type, so the same list would be duplicated in every schema. A taxonomy is defined once at the stack level and queried the same way everywhere.
When is a reference field the better choice?
When the category carries its own content, like a description, an image or its own landing page. A taxonomy term is a label, not an entry.
How do agents use the taxonomies?
Every markdown version of a page starts with YAML frontmatter that includes level and intent, and llms.txt groups content by intent and by learning path.