Everyone is discussing AI agent skills, but almost no one is talking about how to organize these skills.

The current mainstream approach is simple: one skill file corresponds to one capability. Summarization skills, code review skills, test writing skills—one file, one task. It works, indeed.

But recently, an idea made me completely rethink this problem. What if skills aren't flat files, but graphs?

Imagine how a senior engineer would walk you through a large codebase. They wouldn't hand you a thick document and say 'read this'; instead, they would give you a map. They point to the correct modules, explain how the parts connect, and then let you dive into specific areas only when necessary.

This is the mental model behind the Skill Graph.

## From Manual to Map

Someone online compared flat skill files to a 200-page manual that no one reads, while the skill graph is like a senior engineer's onboarding guide. This analogy is spot on.

A skill graph is a network of small, composable skill files connected via wiki links. Each file captures a complete idea, technique, or concept, and the links tell the agent when and why to follow them.

The shift with this method is: the agent doesn't load all content at once. It scans the index, reads short descriptions, follows relevant links, and only reads the full content when truly necessary. Most decisions are made before reading any complete file.

## Practical Use Cases

Consider these scenarios:

- **Trading Skill Graph**: Risk management, market psychology, position sizing, technical analysis—each concept links to related concepts, allowing context to flow between them.

- **Legal Skill Graph**: Contract patterns, compliance requirements, jurisdiction specifics, chains of precedent—everything can be traversed from a single entry point.

- **Company Skill Graph**: Organizational structure, product knowledge, processes, onboarding context, culture, competitive landscape.

These scenarios cannot be stuffed into a single file, but they all work perfectly as graphs.

## Building Tools

Ars Contexta is a Claude Code plugin that generates a complete knowledge system through conversation. You describe your thinking and working style, and the engine infers a cognitive architecture suited to your domain.

The tool is based on 249 interconnected research statements involving thinking tools, knowledge management, and agent-native cognitive architectures. Every configuration decision can be traced back to specific research backing.

The installation process takes about 20 minutes and is a one-time, token-intensive investment. Once installed, your agent remembers the system.

## Technical Implementation

The building blocks of a skill graph are surprisingly simple: wiki links embedded in prose (carrying meaning rather than just citations), YAML frontmatter (allowing the agent to scan nodes without reading the full file), and content maps (organizing clusters into navigable sub-topics).

It's just Markdown files linking to Markdown files, that's all.

Someone online pointed out that flat skills work for one-off tasks, while graphs are for domains. This is the difference between a lookup table and a mental model. Skill graphs don't just store knowledge; they encode relationships, which is exactly where agent reasoning starts to feel more like understanding and less like automation.

## Scaling Thoughts

For enterprise use cases, someone online suggested that when you have thousands of skills, loading 1,000 skills directly into the context might not work well. They considered grouping skills into categories or knowledge domains, using about 100 core skills, treating the rest as MOCs and resources, and letting the agent crawl via wiki links.

This architectural thinking is important because when the number of skills reaches 1k, 10k, or even 100k, the flat approach will fail completely.

Skill graphs represent a mental model shift from 'skill as file' to 'skill as graph'. Most teams just dump everything into Markdown files and then wonder why their agents can't figure out the relevant content.

Real builders are building graphs that connect them.

---

*Reference: Akshay Pachaar's tweet discussion and Ars Contexta project documentation*