Skills

When to use this

Use skills to give an agent specialised instructions that it loads only when a task needs them. For a step-by-step walkthrough, see How to give an agent skills. 10xGraph implements the Agent Skills specification, so a skill written for Claude Code, Codex, GitHub Copilot or any other compatible client works in 10xGraph unchanged, and the other way round.

Import path

from tenxgraph.core.skills import (
    SkillConfig,
    SkillDiagnostic,
    SkillMeta,
    SkillResourceError,
    SkillsRegistry,
    validate_skill,
)

How skills work

A skill is a directory with a SKILL.md file and, optionally, bundled files:

.agents/skills/
└── pdf-processing/
    ├── SKILL.md          # required: frontmatter + instructions
    ├── scripts/          # optional: executable code
    │   └── extract.py
    ├── references/       # optional: documentation loaded on demand
    │   └── REFERENCE.md
    └── assets/           # optional: templates, data files

Skills load in three steps, so an agent with many skills only pays for the ones it uses:

1. Catalog. At startup the agent adds each skill’s name and description to the system prompt as an <available_skills> block.
2. Instructions. When a task matches a description, the model calls activate_skill(skill_name). The tool returns the SKILL.md body wrapped in <skill_content name="..."> tags, together with a <skill_resources> list of the bundled files.
3. Resources. When the instructions point to a bundled file, the model calls read_skill_resource(skill_name, path) to read it.

activate_skill and read_skill_resource are added to the agent’s ToolNode automatically. read_skill_resource is only registered when at least one skill bundles files, and no tool or catalog is added when no skill is found.

SkillConfig

Configuration passed to the Agent constructor via the skills= parameter.

from tenxgraph.core.graph import Agent, ToolNode
from tenxgraph.core.skills import SkillConfig

agent = Agent(
    model="gpt-4o",
    tool_node=ToolNode([]),
    skills=SkillConfig(
        skills_dir=["./.agents/skills", "./shared-skills"],
        hot_reload=True,
    ),
)

Fields

The skill_dirs property returns skills_dir as a list.

Activation modes

mode="on-demand" is the default. The catalog is added to the system prompt, and the model calls activate_skill() when it decides a skill applies.

mode="session" pins one skill per call. The framework reads state.<preload_from> at the start of every call and injects that skill as a system message. No catalog and no activate_skill tool are added, which suits multi-tenant agents where each session has a fixed persona or domain. read_skill_resource is still registered when the skill bundles files and the agent has a ToolNode.

from tenxgraph.core.state import AgentState
from tenxgraph.core.skills import SkillConfig

class FashionState(AgentState):
    SKILL_NAME: str = ""

agent = Agent(
    model="gpt-4o",
    skills=SkillConfig(
        skills_dir="./skills/",
        mode="session",
        preload_from="SKILL_NAME",
    ),
)

Keeping skills in context

Each activation is recorded in state.execution_meta.internal_data["active_skills"]. If context trimming or summarisation later removes the tool result that carried a skill’s instructions, the agent re-injects them as a system message on the next call, so the model never silently loses a skill it activated. If the model activates a skill whose instructions are still in the conversation, activate_skill says so instead of repeating them.

The tools

activate_skill(skill_name)

skill_name is an enum of the discovered skill names, so the model cannot request a skill that does not exist. The result looks like this:

<skill_content name="pdf-processing">
# PDF Processing
...instructions from SKILL.md...

Compatibility: Requires python3 and pypdf
Relative paths in this skill are relative to the skill directory. Read a bundled file with read_skill_resource(skill_name="pdf-processing", path="<relative path>").

<skill_resources>
  <file>references/REFERENCE.md</file>
  <file>scripts/extract.py</file>
</skill_resources>
</skill_content>

read_skill_resource(skill_name, path)

Reads any file inside the skill directory as text: markdown, Python and shell scripts, extension-less executables, JSON, CSV and so on. Nothing is executed.

• Text that is not valid UTF-8 is decoded with replacement characters.
• Binary files are described (name and size) instead of dumped.
• A directory path returns a listing of its files.
• Absolute paths, .. segments and symlinks that leave the skill directory are rejected.
• Hidden files, __pycache__ and node_modules are not listed.

Callbacks

Calls to activate_skill and read_skill_resource fire InvocationType.SKILL callbacks (not TOOL), with context.function_name set to the tool name:

from tenxgraph.utils import CallbackManager, InvocationType

callbacks = CallbackManager()
callbacks.register_before_invoke(
    InvocationType.SKILL,
    lambda context, data: print(context.function_name, data) or data,
)
app = graph.compile(callback_manager=callbacks)

Session-mode preloading is not a tool call, so it fires no callback. tenxgraph.core.skills.activation.get_active_skills(state) returns the skills activated in a thread.

SkillMeta

Parsed metadata for a single skill.

SkillsRegistry

The registry holds discovered skills. Agent creates one for you; use it directly to inspect skills or build your own tools.

from tenxgraph.core.skills import SkillsRegistry

registry = SkillsRegistry()
registry.discover(["./.agents/skills", "./shared-skills"])

for diagnostic in registry.diagnostics:
    print(diagnostic)

catalog = registry.build_catalog()
script = registry.read_file("pdf-processing", "scripts/extract.py", max_bytes=100_000)

SkillsRegistry also supports len(registry) and name in registry.

Writing a SKILL.md file

---
name: sql-query-helper
description: >-
  Write and debug SQL queries. Use when the user asks for a query, a JOIN,
  or help with a database error.
license: MIT
metadata:
  triggers: "write a sql query; fix this join; why is my query slow"
  tags: "database, sql"
  priority: "10"
---

# SQL Query Helper

- Use fully qualified column references (table.column).
- Prefer CTEs for readability.
- Explain each JOIN type chosen.

The table definitions are in [references/schema.sql](references/schema.sql).

Frontmatter rules

Other top-level fields are not allowed by the specification. 10xGraph’s triggers, tags and priority go inside metadata. triggers is separated by ; or newlines, and tags by commas or spaces.

Refer to bundled files with paths relative to the skill directory, and keep SKILL.md under 500 lines by moving detail into references/.

Lenient loading

10xGraph loads skills written for other clients even when they bend the rules, and records a diagnostic instead of failing:

• A name that breaks the naming rules or does not match its directory still loads.
• A description over 1024 characters still loads.
• A value containing : that makes the YAML invalid (for example description: Use when: ...) is quoted and loaded.
• A skill is skipped only when its frontmatter cannot be parsed, it has no description, or its name contains whitespace or path separators.

Diagnostics are logged as warnings on the tenxgraph.skills.registry logger and are available from registry.diagnostics.

Validating skills

Check skills against the specification before shipping them:

agentflow skills --validate ./.agents/skills

from tenxgraph.core.skills import validate_skill

for issue in validate_skill("./.agents/skills/sql-query-helper"):
    print(issue)   # e.g. "error: .../SKILL.md: Skill name 'SQL' must be lowercase"

error diagnostics are specification violations. warning diagnostics are recommendations that are not followed, such as a body over 500 lines or a references/... path that does not exist.

Example: coding assistant with multiple skills

from tenxgraph.core.graph import Agent, StateGraph, ToolNode
from tenxgraph.core.skills import SkillConfig
from tenxgraph.core.state import AgentState
from tenxgraph.utils.constants import END

tool_node = ToolNode([])

agent = Agent(
    model="gpt-4o",
    system_prompt=[{"role": "system", "content": "You are a software engineering assistant."}],
    tool_node="TOOL",
    skills=SkillConfig(skills_dir="./.agents/skills", hot_reload=False),
)

def route(state: AgentState) -> str:
    last = state.context[-1]
    return "TOOL" if getattr(last, "tools_calls", None) else END

graph = StateGraph()
graph.add_node("MAIN", agent)
graph.add_node("TOOL", tool_node)
graph.add_conditional_edges("MAIN", route, {"TOOL": "TOOL", END: END})
graph.add_edge("TOOL", "MAIN")
graph.set_entry_point("MAIN")

app = graph.compile()

When a user asks “Help me write a SQL join”, the model sees sql-query-helper in the catalog, calls activate_skill("sql-query-helper"), and then reads references/schema.sql with read_skill_resource if it needs the table definitions.

Migrating from earlier versions

Common errors