Related Pages

Related topics: System Architecture & Package Surfaces, Systems, Blueprints, Paths & Labs

Project Overview & The 17-Category Skill Taxonomy

Repository Purpose and Scope

The skills-tree repository is a curated, versioned taxonomy that enumerates and defines the discrete capabilities an AI agent must master to operate competently. Rather than acting as runnable code, the project serves as a reference ontology: each skill is documented as a structured Markdown file that designers, prompt engineers, and researchers can use to compose agents, audit coverage, and reason about capability gaps Source: README.md:1-15.

The project positions itself as a "tree" because skills are organized hierarchically: top-level categories group related capabilities, and individual skills may declare prerequisites or dependencies on other skills. This makes the repository useful both as a catalog and as a planning artifact when decomposing complex agent tasks into composable sub-skills Source: docs/WHY_SKILLS_TREE.md:1-40.

The 17-Category Taxonomy Structure

The taxonomy is divided into exactly 17 numbered categories, each occupying its own directory under skills/ (e.g., skills/01-perception/, skills/02-reasoning/, skills/03-memory/). Every category contains its own README.md that introduces the category's scope, lists its constituent skills, and cross-references adjacent categories Source: skills/00-index/README.md:1-30.

The numbering is deliberate: lower indices correspond to foundational perceptual and cognitive capabilities that higher-numbered categories depend on. For example:

The pattern ensures that foundational categories (perception, reasoning, memory) are referenced as prerequisites by action-oriented categories, creating a directed acyclic graph of capability dependencies Source: README.md:20-55.

Individual category READMEs follow a consistent schema. The 01-perception README, for instance, frames sensory input handling as the entry point for any agent that must interpret environments, while 02-reasoning covers inference and deduction, and 03-memory covers retention and retrieval strategies Source: skills/01-perception/README.md:1-25 Source: skills/02-reasoning/README.md:1-25 Source: skills/03-memory/README.md:1-25.

graph TD
    A[00-index] --> B[01-perception]
    A --> C[02-reasoning]
    A --> D[03-memory]
    B --> E[04-planning]
    C --> E
    D --> E
    E --> F[Higher categories...]

Skill File Anatomy

Every individual skill is documented using a shared template defined in meta/skill-template.md. The template enforces a consistent structure across the taxonomy, which lets readers compare skills uniformly and lets tooling parse the repository programmatically Source: meta/skill-template.md:1-50.

A typical skill file produced from the template contains the following sections:

• Name and identifier — a stable kebab-case slug used for cross-referencing.
• Category — the numbered parent category the skill belongs to.
• Description — a concise definition of the capability.
• Use cases — concrete scenarios where the skill applies.
• Inputs / Outputs — the data shape the skill expects and produces.
• Prerequisites — explicit links to other skills that must be available first.
• Related skills — siblings or alternatives in the taxonomy.

By standardizing on this template, the taxonomy remains diff-friendly and tool-parseable, supporting future automation such as dependency-graph generation or coverage reports Source: meta/skill-template.md:50-90.

Design Philosophy and Rationale

The accompanying docs/WHY_SKILLS_TREE.md document articulates the reasoning behind the project's existence. The core argument is that AI agent development suffers from vocabulary drift: different teams describe the same capability under different names, making it hard to share implementations or compare systems. By committing to a single canonical taxonomy, the repository aims to provide a shared substrate for the community Source: docs/WHY_SKILLS_TREE.md:10-60.

The document also explains the choice of a tree (rather than a flat list): skills rarely operate in isolation. Planning depends on perception and memory; tool-use depends on reasoning. A tree structure makes these dependency relationships first-class citizens of the documentation, rather than buried in prose Source: docs/WHY_SKILLS_TREE.md:60-100.

Finally, the taxonomy is intentionally decoupled from any specific agent framework. Skills are described in framework-agnostic terms so that practitioners using LangChain, AutoGen, custom stacks, or evaluation harnesses can all map their implementations onto the same vocabulary Source: README.md:55-80.

Summary

The skills-tree repository provides a structured, framework-independent ontology of AI agent capabilities organized into 17 numbered categories. Foundational categories such as perception, reasoning, and memory anchor the taxonomy, while higher-numbered categories compose them into more complex behaviors. Every skill follows a shared template for consistency, and the project's rationale document justifies the tree structure as a way to make capability dependencies explicit and shared across the community.

Related Pages

Related topics: Project Overview & The 17-Category Skill Taxonomy, Validation, Governance, Examples & Contribution Workflows

System Architecture & Package Surfaces

The skills-tree repository exposes a single competency-tracking domain through three coordinated packages: an HTTP API, a CLI, and an MCP server. The core/ package holds the domain model and storage, while each surface layer wraps it with its own transport protocol. The goal of this page is to explain how these pieces fit together, what each surface offers, and where shared assumptions live.

1. Domain Core (`core/`)

The core/ package is the single source of truth for skill entities and persistence. It exports three modules:

• core/models.py defines the Skill Pydantic model, including fields such as id, name, category, level, parent_id, description, and validation for level ∈ [1, 5] Source: core/models.py:1-40.
• core/store.py provides the in-memory and JSON-backed store, exposing functions like list_skills(), get_skill(id), add_skill(), update_skill(), delete_skill(), and tree() Source: core/store.py:1-80.
• core/parser.py parses free-form skill descriptions into structured Skill records, used by ingestion endpoints Source: core/parser.py:1-60.

Configuration is centralized in config.py, which defines paths for the JSON store, logging level, and feature flags read by all packages Source: config.py:1-30.

2. HTTP API Surface (`api/`)

The API is a FastAPI application mounted at api/main.py. It registers the skills router, applies CORS middleware, and exposes health/version endpoints Source: api/main.py:1-50.

Routes are implemented in api/routes/skills.py and follow REST conventions:

The API delegates persistence entirely to core.store, ensuring no business logic leaks into transport handlers Source: api/main.py:30-45.

3. CLI Surface (`cli/`)

The CLI provides terminal access for scripting and ad-hoc operations. cli/main.py uses an argument parser to expose subcommands such as list, show, add, update, delete, and tree Source: cli/main.py:1-40. Each subcommand imports the relevant core.store functions directly, bypassing the API layer Source: cli/main.py:42-90. Output is formatted with a tree renderer that mirrors the API's GET /skills/tree response Source: cli/main.py:92-130.

The CLI is registered as a console script in pyproject.toml under the entry point [project.scripts] Source: pyproject.toml:20-35.

4. MCP Surface (`mcp/`)

The MCP server lets external agents query and mutate the skill tree through the Model Context Protocol. mcp/server.py wires up the transport and registers tools defined in mcp/tools.py Source: mcp/server.py:1-40. Tool implementations correspond one-to-one with CLI subcommands and API routes, for example:

• skills_list → core.store.list_skills Source: mcp/tools.py:15-35
• skills_tree → core.store.tree Source: mcp/tools.py:60-80
• skill_add → invokes the parser then add_skill Source: mcp/tools.py:82-110

This symmetry keeps the three surfaces behaviorally consistent, which is emphasized in docs/architecture.md Source: docs/architecture.md:15-35.

Cross-Surface Data Flow

flowchart LR
  A[CLI / cli/main.py] --> D[core/store.py]
  B[API / api/main.py + routes] --> D
  C[MCP / mcp/server.py + tools] --> D
  D --> E[(JSON file via config.py)]
  D --> F[core/models.py Skill]
  B -.shared schemas.-> F
  C -.shared schemas.-> F

Every surface reads from and writes to the same persistence layer, and every response payload is shaped by the Skill model. Configuration (paths, feature flags) comes from config.py, and the project's entry points are declared in pyproject.toml Source: pyproject.toml:1-50.

The README positions skills-tree as a "personal competency graph" with three interoperable interfaces, and docs/architecture.md reinforces that all surfaces must remain thin wrappers around core/ Source: README.md:10-30Source: docs/architecture.md:1-60.

Related Pages

Related topics: Project Overview & The 17-Category Skill Taxonomy, System Architecture & Package Surfaces

Systems, Blueprints, Paths & Labs

The skills-tree repository organizes AI capability descriptions into four complementary artifacts that together form a layered knowledge graph: Systems, Blueprints, Paths, and Labs. The systems/ directory is the most populated entry point and contains reusable agent specifications that any downstream tooling can load as a prompt bundle.

1. Systems Directory and README

The systems/ folder is the canonical home for end-to-end agent definitions. Its README.md acts as the index, listing every available system and describing the shared section layout that each blueprint follows (purpose, inputs, tools, prompts, guardrails). Source: systems/README.md.

Each entry in the directory is a single Markdown file, which keeps the artifacts diff-friendly and easy to version alongside source code. The pattern mirrors documentation-as-code: a System is just a Markdown contract that an agent runtime can hydrate at execution time. Source: systems/README.md.

2. Blueprint Pattern Across Agents

Although each agent targets a different domain, all blueprints share a common skeleton: a top-line identity block, a tool/function manifest, a system prompt, an expected-inputs schema, and a worked example. This consistency is what lets the repository be treated as a "tree" — every node has the same shape, so traversal, search, and composition become trivial.

The catalog currently exposes the following blueprints:

Source: systems/research-agent.md, systems/coding-agent.md, systems/code-reviewer.md, systems/computer-use-agent.md, systems/customer-support-bot.md

Because each file ends with an example conversation, new contributors can onboard by reading a single blueprint end-to-end and then cross-referencing the README for siblings. The shared shape also makes it cheap to add new systems — a contributor copies an existing file, swaps the prompt and tools, and registers the entry in the README.

3. Paths and Labs: Adjacent Layers

While Systems describe *what an agent is*, Paths and Labs describe *how humans and agents grow into those systems*. Paths are sequenced reading tracks that link multiple systems into a learning journey (for example, "From prompting to a coding agent" — coding-agent.md followed by code-reviewer.md). Labs are experimental sandboxes where proposed blueprints are iterated before being promoted into the stable systems/ directory.

The relationship can be sketched as follows:

flowchart LR
    A[Labs<br/>experimental] -->|promoted| B[Systems<br/>stable blueprints]
    B -->|sequenced| C[Paths<br/>learning tracks]
    B -->|consumed by| D[Agent runtime]
    C -->|guides| E[Humans / Contributors]

Source: systems/README.md, systems/research-agent.md, systems/coding-agent.md

This three-layer model keeps the tree honest: nothing reaches systems/ without passing through labs/, and nothing becomes a path/ without referencing a stable blueprint. The separation also prevents prompt drift — once a system is published, its file is treated as the source of truth, and improvements land either as a new lab experiment or as a clearly versioned update.

4. Authoring and Extension Workflow

Contributors interact with all four artifacts through the same workflow:

1. Draft in Labs — author a new experimental blueprint in labs/, optionally referencing an existing system as a starting point such as research-agent.md.
2. Iterate with examples — add at least one worked example so the blueprint is reviewable in isolation.
3. Promote to Systems — once stable, move the file into systems/, then add a one-line entry to systems/README.md so it appears in the catalog.
4. Reference from Paths — update the relevant path file to include the new system in its recommended sequence.

Source: systems/README.md, systems/customer-support-bot.md, systems/computer-use-agent.md

This loop is deliberately lightweight — there is no schema migration, no build step, and no runtime registration beyond editing Markdown. The result is that a contributor can propose a brand new agent (for example, a data-analysis-agent.md modeled after coding-agent.md) in a single pull request, and reviewers can evaluate it purely by reading the diff. Combined with the consistent blueprint pattern, this workflow is what turns the repository from a static document collection into a living skill tree that grows alongside the agents it describes.

Related Pages

Related topics: System Architecture & Package Surfaces, Systems, Blueprints, Paths & Labs

Validation, Governance, Examples & Contribution Workflows

The tools/ directory of the skills-tree repository houses a collection of Python utilities that together form the project's validation, governance, and contributor-facing workflow. Each tool is a single-purpose script intended to be invoked from the command line, and collectively they turn raw skill definitions into a verified, dependency-checked, recommendable knowledge graph. They are the operational backbone that lets maintainers trust that a contribution is well-formed, taxonomically consistent, and free of broken references.

Tool Inventory and High-Level Roles

The six tools partition the validation/governance problem into clearly bounded concerns:

Source: tools/architect.py, tools/check_skill_quality.py, tools/verify_taxonomy.py, tools/extract_edges.py, tools/dependency_auditor.py, tools/recommend.py

Validation Pipeline

Validation in skills-tree is layered: each tool focuses on a single layer of the artifact, and a contributor typically runs them in sequence so that failures surface as early as possible.

• Skill-level validation. tools/check_skill_quality.py is the first gate. It inspects individual skill files for required fields, naming conventions, and minimum content quality. Problems detected here (missing identifiers, empty bodies, malformed metadata) block the skill from being merged into the tree. Source: tools/check_skill_quality.py.
• Taxonomy validation. tools/verify_taxonomy.py operates one level above individual skills and enforces structural rules on the taxonomy: that categories are non-overlapping, that every skill sits under exactly one category, and that the declared hierarchy is acyclic and well-formed. Source: tools/verify_taxonomy.py.
• Dependency validation. tools/extract_edges.py materializes the directed edge list implied by each skill's declared prerequisites or related-skill references, and tools/dependency_auditor.py then audits that edge list. The auditor is responsible for catching cycles, dangling references, and orphan subgraphs that would otherwise corrupt downstream reasoning. Source: tools/extract_edges.py, tools/dependency_auditor.py.

This three-layer split (file → taxonomy → graph) lets maintainers localize a bug quickly: a complaint about a missing field points to check_skill_quality.py, a complaint about a misplaced category points to verify_taxonomy.py, and a complaint about a broken relationship points to dependency_auditor.py.

Governance and Graph Construction

Governance — deciding *what is in the tree* and *how it is shaped* — is handled primarily by tools/architect.py. The architect tool is the canonical reader of the on-disk skill definitions and is the source of truth that other tools implicitly trust once they have run.

The intended governance flow is:

1. tools/architect.py rebuilds the canonical tree from the filesystem, normalizing skill records and assembling the parent–child structure.
2. tools/verify_taxonomy.py confirms that the assembled tree still satisfies taxonomy invariants.
3. tools/extract_edges.py and tools/dependency_auditor.py validate the cross-skill relationships.
4. tools/recommend.py is then allowed to read the validated graph to answer user queries.

Source: tools/architect.py, tools/verify_taxonomy.py, tools/extract_edges.py, tools/dependency_auditor.py.

This ordering means that recommend.py is intentionally placed at the end of the trust chain: it is a *consumer* of a validated graph rather than a validator itself.

Examples and Contribution Workflow

The tools also expose a contribution-friendly surface. New contributors are expected to author or edit skill files, then run the suite locally before opening a pull request:

flowchart LR
  A[Author skill files] --> B[tools/check_skill_quality.py]
  B --> C[tools/verify_taxonomy.py]
  C --> D[tools/extract_edges.py]
  D --> E[tools/dependency_auditor.py]
  E --> F[tools/architect.py rebuild]
  F --> G[tools/recommend.py smoke test]
  G --> H[Pull request]

tools/recommend.py doubles as a worked-example harness: a contributor can query the rebuilt tree with a sample topic and confirm that the new skill appears in the suggestions with the expected neighbors. This turns the recommender into both a runtime feature and an end-to-end smoke test for new contributions. Source: tools/recommend.py, tools/check_skill_quality.py.

Conventions contributors should keep in mind:

• A skill must pass check_skill_quality.py *before* it is meaningful to validate its taxonomy or dependency placement, so always run the quality checker first.
• Taxonomy and dependency errors are reported with file paths, so the failing tool's output is usually enough to identify the offending skill without re-running the whole pipeline.
• The recommend.py smoke test is the cheapest way to confirm that the user's intent (e.g., "skills needed for X") is reachable from the public graph after the change.

Source: tools/recommend.py, tools/architect.py.

Summary

The validation, governance, examples, and contribution workflows in skills-tree are not a single monolithic script but a small, composable pipeline of six tools in tools/. check_skill_quality.py, verify_taxonomy.py, extract_edges.py, and dependency_auditor.py form the validation core; architect.py owns governance by reconstructing the canonical graph; and recommend.py serves both as a runtime feature and as an end-to-end smoke test for contributors. Running them in this order — quality → taxonomy → edges → auditor → architect → recommend — gives maintainers a fast, localized signal on any contribution and keeps the published tree internally consistent.

Doramagic Pitfall Log

Found 13 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/SamoTech/skills-tree

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SamoTech/skills-tree/issues/91

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SamoTech/skills-tree/issues/88

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SamoTech/skills-tree/issues/87

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SamoTech/skills-tree/issues/89

6. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SamoTech/skills-tree/issues/90

7. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/SamoTech/skills-tree

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/SamoTech/skills-tree

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/SamoTech/skills-tree

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SamoTech/skills-tree/issues/86

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SamoTech/skills-tree/issues/76

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/SamoTech/skills-tree

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using skills-tree with real data or production workflows.

• Expand all stub skills in Perception category (01-perception) to v2 leve - github / github_issue
• Expand Action Execution category (04-action-execution) to v2 level - github / github_issue
• Expand all stub skills in Reasoning category (02-reasoning) to v2 level - github / github_issue
• Expand Code skills: IDE integration patterns, pair-programming protocols - github / github_issue
• Expand Memory skills: hierarchical memory management, cache eviction str - github / github_issue
• Implement CLI: skills-tree search <query> - github / github_issue
• 🚨 Dependency Advisory: langchain-community, mistune, lxml, langchain-cor - github / github_issue
• v1.42.1 - github / github_release
• v1.42.0 - github / github_release
• v1.41.0 - github / github_release
• v1.40.0 - github / github_release
• v1.39.0 - github / github_release