Skills Module

This page is divided into two parts:

  • Research Skills: research workflow modules under agentsociety2.skills.

  • Agent Skills: PersonAgent skill registration and runtime mechanisms under agentsociety2.agent.skills.

Research Skills

Top-level Entry

analysis

experiment

hypothesis

literature

Note

The publicly documented research skill modules in this repository are analysis, experiment, hypothesis, and literature. The web_research directory does not currently retain readable source code, so it is not included in the documented API surface.

Agent Skills

Skill infrastructure (discovery, visibility / activation, script execution, and lifecycle hooks) has moved from agent/skills/ down into agentsociety2.agent.base. The agent/skills/ directory now only contains skill content, such as the built-in daily-guidance/. For design notes, see Agent Skills.

SkillRegistry

class agentsociety2.agent.base.skill_registry.SkillRegistry[source]

Bases: object

Tool metadata.

Parameters:

None.

__init__()[source]

Initialize an empty registry.

Parameters:

None.

Returns:

None.

Return type:

None

scan_builtin(root=None)[source]

Scan built-in skills from the agent/skills directory.

Parameters:

root (Path | None) – Optional built-in skill root override.

Returns:

Agent Skills

Return type:

list[str]

scan_custom(skills_root, namespace='custom')[source]

Scan custom skills from a workspace directory.

Parameters:

  • skills_root (Path) – Directory containing skill subdirectories with SKILL.md files.

  • namespace (str) – Namespace assigned to discovered skills.

Returns:

Agent Skills

Return type:

list[str]

scan_env(skills_dir, env_name)[source]

Scan skills from an environment module’s skill directory.

Parameters:

  • skills_dir (Path) – Directory containing skill subdirectories with SKILL.md files.

  • env_name (str) – List of environment module types

Returns:

Agent Skills

Return type:

list[str]

list_all()[source]

List all registered skills.

Parameters:

None.

Returns:

Get standard status descriptions.

Return type:

list[SkillDescriptor]

get(skill_id)[source]

Return one skill descriptor by id.

Parameters:

skill_id (str) – Registry Module

Returns:

Matching descriptor, or None.

Return type:

SkillDescriptor | None

find_by_name(name)[source]

Find skill descriptors by display name.

Parameters:

name (str) – Skill display name.

Returns:

Matching descriptors.

Return type:

list[SkillDescriptor]

read_skill_doc(skill_id)[source]

Read one skill’s SKILL.md.

Parameters:

skill_id (str) – Registry Module

Returns:

Skill document text, or an empty string.

Return type:

str

read_skill_file(skill_id, relative_path)[source]

Read one file inside a skill directory.

Parameters:

  • skill_id (str) – Registry Module

  • relative_path (str) – Path relative to the skill root.

Returns:

File text, or an empty string.

Return type:

str

list_hooks(hook_type)[source]

List skills declaring one hook.

Parameters:

hook_type (str) – Lifecycle hook name.

Returns:

Skill descriptors that declare the hook.

Return type:

list[SkillDescriptor]

copy()[source]

source registry.

Parameters:

None.

Returns:

SkillRegistry

Return type:

SkillRegistry

SkillRegistry

class agentsociety2.agent.base.skill_registry.SkillDescriptor(skill_id, name, namespace, description, root, source, source_label, script, hooks)[source]

Tool metadata.

Parameters:

  • skill_id (str) – Stable registry skill id.

  • name (str) – Display name from SKILL.md.

  • namespace (str) – Skill namespace.

  • description (str) – Hypothesis description

  • root (Path) – Skill root directory.

  • source (str) – Source category.

  • source_label (str) – Human-readable source label.

  • script (str | None) – Optional default script path.

  • hooks (dict[str, str]) – Lifecycle hook script map.

skill_id: str
name: str
namespace: str
description: str
root: Path
source: str
source_label: str
script: str | None
hooks: dict[str, str]
resource_files()[source]

List files shipped under this skill root.

Parameters:

None.

Returns:

Relative resource file paths under the skill root.

Return type:

list[str]

__init__(skill_id, name, namespace, description, root, source, source_label, script, hooks)

Agent Skills

class agentsociety2.agent.base.skill_runtime.AgentSkillRuntime(agent_id, registry)[source]

Bases: object

Registry for skill discovery, management, and execution.

__init__(agent_id, registry)[source]

Initialize the skill runtime.

Parameters:

  • agent_id (int) – Experiment ID

  • registry (SkillRegistryLike) – Skill registry facade used by this runtime.

Returns:

None.

Return type:

None

bind_workspace(*, workspace_root, fs, trace_writer)[source]

Bind this runtime to an agent-owned workspace.

Parameters:

  • workspace_root (Path) – Agent workspace root created by the agent.

  • fs (WorkspaceFS) – Agent-owned workspace filesystem facade.

  • trace_writer (JsonlTraceWriter) – Agent-owned trace writer.

Returns:

None.

Return type:

None

workspace_root()[source]

Return the workspace root.

Parameters:

None.

Returns:

Absolute workspace root path.

Return type:

Path

property is_initialized: bool

Return whether the workspace is initialized.

Parameters:

None.

Returns:

True when the workspace has been initialized.

property fs: WorkspaceFS

Return the workspace filesystem facade.

Parameters:

None.

Returns:

Workspace filesystem facade.

set_visible_skills(tokens)[source]

Set visible skills for this agent.

Each entry may be a registry skill id (namespace@name) or a display name; both forms resolve against the whole registry.

Parameters:

tokens (Iterable[str]) – Candidate skill ids or display names.

Returns:

None.

Return type:

None

add_visible_skill(token)[source]

Add one visible skill by id or display name.

Parameters:

token (str) – Skill id (namespace@name) or display name.

Returns:

True when the skill exists and was made visible.

Return type:

bool

remove_visible_skill(token)[source]

Remove one visible skill by id or display name.

Parameters:

token (str) – Skill id (namespace@name) or display name.

Returns:

True when the skill was visible and removed.

Return type:

bool

visible_skill_ids()[source]

Return visible skill ids.

Parameters:

None.

Returns:

Copy of the visible skill id set.

Return type:

set[str]

visible_skill_count()[source]

Return the visible skill count.

Parameters:

None.

Returns:

Number of API calls made.

Return type:

int

list_visible_skills()[source]

List visible skill descriptors.

Parameters:

None.

Returns:

Visible skill descriptors.

Return type:

list[SkillDescriptor]

skill_catalog()[source]

Build a compact visible skill catalog.

Parameters:

None.

Returns:

Get the world description.

Return type:

list[dict[str, str]]

set_activated_skills(tokens)[source]

Set activated skills from visible skills.

Each entry may be a skill id (namespace@name) or a display name; both forms resolve against visible skills.

Parameters:

tokens (Iterable[str]) – Candidate skill ids or display names to activate.

Returns:

None.

Return type:

None

add_default_activated_skills(tokens)[source]

Activate configured default skills when they are visible.

Each entry may be a skill id or a display name.

Parameters:

tokens (Iterable[str]) – Skill ids or display names requested by outer agent config.

Returns:

None.

Return type:

None

activated_skill_ids()[source]

Return activated skill ids.

Parameters:

None.

Returns:

Copy of the activated skill id set.

Return type:

set[str]

activated_skill_count()[source]

Return activated skill count.

Parameters:

None.

Returns:

Number of API calls made.

Return type:

int

infer_single_script_skill_id()[source]

Infer a visible activated skill when exactly one has a default script.

Parameters:

None.

Returns:

Skill id for the only active scripted skill, or an empty string.

Return type:

str

resolve_skill_id(token, *, visible_only=True)[source]

Resolve a skill id or display name to a registry skill id.

Accepts either a registry skill id (namespace@name) or a bare display name — every public skill API in this runtime takes the same token and tolerates both forms. When visible_only is True (the default) resolution is restricted to visible skills; when False the whole registry is searched (use this for skills that are not yet visible, e.g. in add_visible_skill()).

Ambiguous display names (more than one match) resolve only when exactly one candidate is currently activated.

Parameters:

  • token (str) – Skill id (namespace@name) or display name from tool arguments / agent config.

  • visible_only (bool) – Restrict resolution to visible skills.

Returns:

Matching skill id, or an empty string when not found or ambiguous.

Return type:

str

resolve_skill_id_by_name(skill_name)[source]

Deprecated alias for resolve_skill_id().

Parameters:

skill_name (str) – Skill id or display name.

Returns:

Matching visible skill id, or an empty string.

Return type:

str

activate_skill(token)[source]

Activate a visible skill by id or display name.

Parameters:

token (str) – Skill id (namespace@name) or display name.

Returns:

Tuple of (activated, skill_id, skill_doc).

Return type:

tuple[bool, str, str]

activate_skill_by_name(skill_name)[source]

Deprecated alias for activate_skill().

Parameters:

skill_name (str) – Skill id or display name.

Returns:

Tuple of (activated, skill_id, skill_doc).

Return type:

tuple[bool, str, str]

deactivate_skill(token)[source]

Deactivate a visible skill by id or display name.

Parameters:

token (str) – Skill id (namespace@name) or display name.

Returns:

Tuple of (removed, skill_id).

Return type:

tuple[bool, str]

deactivate_skill_by_name(skill_name)[source]

Deprecated alias for deactivate_skill().

Parameters:

skill_name (str) – Skill id or display name.

Returns:

Tuple of (removed, skill_id).

Return type:

tuple[bool, str]

activated_skill_content_xml()[source]

Render docs and resource hints for activated skills.

Parameters:

None.

Returns:

XML-like skill content blocks for active skills.

Return type:

str

active_hook_skills(hook_type)[source]

List visible activated skills that declare one hook.

Parameters:

hook_type (str) – Lifecycle hook name.

Returns:

Skill descriptors eligible to run the hook.

Return type:

list[SkillDescriptor]

load_skill_doc(skill_id)[source]

Read a visible skill document.

Parameters:

skill_id (str) – Registry Module

Returns:

SKILL.md text, or an empty string.

Return type:

str

read_skill_file(skill_id, relative_path)[source]

Read one file inside a visible skill.

Parameters:

  • skill_id (str) – Registry Module

  • relative_path (str) – Path relative to the skill root.

Returns:

File text, or an empty string.

Return type:

str

resolve_skill_path(path)[source]

Map a path to a (skill_id, relative_path) inside a visible skill.

Used to recover when an agent tries to read a skill-bundled file (e.g. references/examples.md) via the generic workspace read tool, which only sees the agent workspace and rejects such paths as “escaping” it. Returning a mapping lets the caller transparently delegate to read_skill_file() instead of failing.

Two matching strategies, in order:

  1. Direct containment — the resolved absolute path is inside a visible skill root.

  2. Skill-name segment — some path component equals a visible skill’s skill_id or name (e.g. the model-emitted .../skills/daily-guidance/references/examples.md). The components after that segment are taken as the skill-relative path and must resolve to an existing file under the skill root.

Parameters:

path (str | Path) – Path to test (absolute, or relative to be matched by segment).

Returns:

(skill_id, posix_relative_path) if a visible skill file matches, else None.

Return type:

tuple[str, str] | None

async run_skill_script(skill_id, script_path, argv, *, timeout_sec=30)[source]

Run a script inside a visible skill.

Parameters:

  • skill_id (str) – Registry Module

  • script_path (str) – Path relative to the skill root, or empty to use the default script.

  • argv (list[str]) – Command-line arguments.

  • timeout_sec (int) – Execution timeout in seconds.

Returns:

Tool execution result.

Return type:

ScriptRunResult

async run_skill_hook(skill_id, hook_type, argv, *, timeout_sec=30)[source]

Run a lifecycle hook for a visible skill.

Parameters:

  • skill_id (str) – Registry Module

  • hook_type (str) – Lifecycle hook name.

  • argv (list[str]) – Command-line arguments.

  • timeout_sec (int) – Execution timeout in seconds.

Returns:

Tool execution result.

Return type:

ScriptRunResult

SkillScriptContext

class agentsociety2.agent.base.skill_runtime.SkillScriptContext(workspace_root, skill_dir, skill_id, skill_name, env=<factory>)[source]

Per-call context handed to an in-process skill entrypoint.

Replaces the process-global env vars (AGENT_WORK_DIR etc.) that the subprocess path relied on, so 50 agents can run their hooks in-process in parallel without racing on os.environ / cwd / sys.stdout.

Parameters:

  • workspace_root (Path) – This agent’s workspace root (was AGENT_WORK_DIR).

  • skill_dir (Path) – The skill package root (was SKILL_DIR).

  • skill_id (str) – Registry skill id (was SKILL_ID).

  • skill_name (str) – Display name (was SKILL_NAME).

  • env (dict[str, str]) – Snapshot of the env-var dict the subprocess path would have set.

workspace_root: Path
skill_dir: Path
skill_id: str
skill_name: str
env: dict[str, str]
__init__(workspace_root, skill_dir, skill_id, skill_name, env=<factory>)

SKILL.md Frontmatter

The SKILL.md file uses YAML frontmatter to declare skill metainformation:

---
name: my-skill
description: 触发条件 + 输出结果，选择阶段 LLM 唯一可见的文本
script: scripts/my_skill.py
hooks:
  pre_step: scripts/my_skill.py
---

Recognized frontmatter fields are name, description (the only text visible during selection and what determines activation), optional script (default relative script path), and hooks (lifecycle script mapping with keys such as pre_step / post_step). Skill registration ids look like namespace@name (built-in built-in@, custom custom@). Scripts execute by default in the agent process through entrypoint(argv, ctx) (see Agent Skills); skill ids starting with env: are redirected to ask_env and go through environment routing rather than script execution.