Skip to content
AgentScope Skills Architecture: Single-Source SKILL.md, Progressive Disclosure & Fault-Tolerant Loading

AgentScope Skills Architecture: Single-Source SKILL.md, Progressive Disclosure & Fault-Tolerant Loading

This article dissects AgentScope's industrial-grade skill system design, covering SKILL.md as single source of truth, progressive disclosure via lightweight manifests, on-demand markdown fetching through SkillViewer, group-based activation filtering, two-layer caching with mtime invalidation, async loading with utf-8-sig BOM handling, OrderedDict deduplication, Jinja2 template rendering, dual-phase filtering (assembly-time and call-time), and a nine-stage execution pipeline that injects skill content into context only for the next reasoning turn.

Tech Freedom Circle
Tech Freedom Circle
Tech Freedom Circle

One: Core Positioning — Skills as Versioned Capability Packages

The problem: 200 skills × ~3,000 characters each = ~600k characters / 400k+ tokens if fully injected. This blows context budgets, increases latency, and dilutes model attention. Vector retrieval alone fails because it doesn't solve fallback on retrieval failure, conflict resolution for same-name skills, or when to load full skill bodies.

AgentScope's answer: manifest resident, body on-demand . The prompt receives only a structured manifest (name, description, dir) — tiny overhead proportional to skill count. Full markdown bodies are fetched via the SkillViewer tool only when the model actually needs them. Cost structure becomes: prompt cost ∝ skills × summary length; body cost ∝ skills actually invoked this turn.

Two: Three Core Concepts

Skill — Manual (markdown). Side effects: none. Permission: not needed.

Tool — Weapon (executable function). Side effects: yes. Permission: required.

SkillViewer — Tool that reads the manual. Side effects: none. Permission: self ALLOW, downstream re-evaluated.

Three: Source Code Map — Five Layers, One Data Flow

Data Model — Entity: Skill. Source anchor: skill/_base.py:7-29. Responsibility: name / description / dir / markdown / updated_at.

Loading — Entity: LocalSkillLoader. Source anchor: skill/_local_loader.py:16-175. Responsibility: parse SKILL.md, mtime cache, concurrency & fault tolerance.

Grouping — Entity: ToolGroup.list_skills. Source anchor: tool/_tool_group.py:81-99. Responsibility: one group per loader, string paths auto-converted to instances.

Aggregation — Entity: _get_available_skills / get_skill_instructions. Source anchor: tool/_toolkit.py:394-471. Responsibility: group filtering, same-name override, Jinja2 rendering.

Consumption — Entity: SkillViewer. Source anchor: tool/_builtin/_skill.py:18-127. Responsibility: query by group, return body.

Provisioning — Entity: Workspace partition. Source anchor: workspace/_base.py:454-493,1580-1616. Responsibility: assemble copies, prevent rollback, maintain index.

Library — Entity: Skill library routing & service. Source anchor: app/_router/_skill.py:46-56, app/_service/_workspace.py:351,412-444. Responsibility: install, validity check, library vs copy semantics.

Directory layout: skill/ holds resources (data model, loaders); tool/ holds integration logic (aggregation, rendering, consumption). This reflects true responsibility separation.

Skill Model — Five Fields

class Skill:
    name: str        # Unique primary key; aggregation/override/lookup all rely on it
    description: str # Only field that enters the prompt; quality decides model selection
    dir: Path        # Tells model where the resource lives
    markdown: str    # Returned only on on-demand view
    updated_at: float # File mtime; used to judge cache validity

No version, enabled, owner — versioning and enablement are delegated to group and provisioning layers, so the same skill can have different visibility in different groups/agents without embedding governance fields that would bind it to a dynamic context.

Four: Load & Parse — SKILL.md Single Source + Encoding Fault Tolerance

Skills must be version-controlled (git diff/rollback), migratable (copy directory), auditable (human opens file). A single file makes "one directory = one skill" with all info self-contained. This mirrors the Schema SSOT idea: one authoritative source per entity, everything else derived.

Engineering detail in _local_loader.py:

async with aiofiles.open(skill_md_path, "r", encoding="utf-8-sig") as f:
    content_str = await f.read()
    content = frontmatter.loads(content_str)
utf-8-sig is a Python built-in UTF-8 alias with BOM awareness, specifically for Windows-ecosystem UTF-8 files that carry a BOM.

Windows editors often prepend a BOM (three bytes ). Plain utf-8 reads it as ---, breaking the front-matter delimiter; metadata becomes body, skill is marked "missing fields" and skipped. The file looks fine in the editor; the bug only reproduces on Windows-edited files — extremely hard to debug. utf-8-sig auto-detects and strips the BOM, handling both BOM and non-BOM files with one encoding parameter — platform-grade maturity shows in anticipating such dirty data.

Five: _load_single_skill — Two-Layer Cache + Threefold Fault Tolerance

Three key designs:

Fully async: isfile, getmtime, read all via aiofiles — non-blocking event loop is a correctness requirement in platform frameworks, not an optimization.

Stat before read: getmtime is a lightweight syscall, far cheaper than reading the whole file; used for cache invalidation so invalidation cost stays below reload cost.

Two caches, each owning a segment:

In-process mtime cache — Criterion: SKILL.md mtime. Problem solved: same-turn repeated reads of same skill batch — skip file reads.

On-disk .index index — Criterion: directory mtime comparison. Problem solved: new session startup — skip full skill-library traversal.

In-process cache handles "no duplicate file reads within the same turn"; hit returns object directly, miss triggers SKILL.md read. Disk .index handles "new session doesn't scan entire library"; directory mtime comparison decides whether to rebuild index — if not, skip scan; if yes, run scan and backfill into in-process cache.

def load_with_cache(skill_md_path, cache, index):
    mtime = os.path.getmtime(skill_md_path)
    if mtime == cache.get(skill_md_path):
        return cache[skill_md_path]
    skill = parse_and_build(skill_md_path)
    cache[skill_md_path] = (mtime, skill)
    return skill

Six: list_skills — Directory Validation + to_thread Scan + gather Exception Collection

list_skills

is the loader's only batch entry point. Design principle: all failure paths converge to return [], letting upstream callers iterate unconditionally.

Directory missing → return []. scan_subdir defaults to False: scan only current directory, avoiding misidentifying examples, backups, .git history as skills, and preventing recursive reads into other agent partitions — plugin loader's default should return minimal visible set, not maximal discovery. os.walk offloaded to thread pool via asyncio.to_thread — sync blocking I/O moved off event loop; awaiting many stat calls individually is more expensive, single thread-pool hand-off yields better throughput. gather(return_exceptions=True): single skill load failure doesn't abort the whole batch; exceptions become identifiable result elements — default behavior would immediately propagate exception and discard completed results; enabling this gives batch resilience.

Always returns []: upstream can for skill in await group.list_skills(): without None checks or try blocks.

async def list_skills(self, roots, scan_subdir=False):
    if not roots or not any(Path(r).exists() for r in roots):
        return []
    dirs = await asyncio.to_thread(walk_roots, roots, scan_subdir)
    results = await asyncio.gather(*[self._load_single(d) for d in dirs], return_exceptions=True)
    return [r for r in results if isinstance(r, Skill)]

Seven: Group Aggregation — _get_available_skills — basic Mandatory + Same-Name Override + OrderedDict Ordering

groups_filter = ["basic"] + (groups or [])

— basic always in filter set. Platform guarantees every agent has a minimum capability set in any scenario: visibility can narrow, but capability set cannot go to zero; narrowing is policy, zero is accident — this constraint encoded in code, not just docs, to prevent human assembly mistakes.

Filtering happens before calling list_skills; inactive groups never trigger the loader, yielding two gains: (1) performance — no scan/load for inactive groups; (2) isolation — inactive skills never enter the dictionary, so manifest rendering and SkillViewer never see them.

Same-name handling: later registration overrides earlier, warning only, no error. name is the primary key; order = priority; no extra priority field needed. This supports "basic generic + business-group same-name customization" layering. OrderedDict is the determinism anchor: neutralizes os.walk 's unstable order, making manifest order reproducible, cacheable, auditable. Returns dict[str, Skill] keyed by name, directly consumable by SkillViewer lookup.

def _get_available_skills(self, groups):
    groups_filter = ["basic"] + (groups or [])
    result = OrderedDict()
    for g in self.tool_groups:
        if g.name not in groups_filter:
            continue
        for skill in await g.list_skills():
            if skill.name in result:
                log.warning(f"override: {skill.name}")
            result[skill.name] = skill
    return result

Eight: Aggregation & Rendering — get_skill_instructions — Jinja2 Rendering + Prompt Hard Guardrails

Manifest rendering is not serializing skill objects into the prompt; it's a strict three-field projection through a Jinja2 template. get_skill_instructions ( tool/_toolkit.py:431-471) renders aggregation result into a prompt fragment in four steps, each mapping to an explicit contract: determine active groups → aggregate → return None if no skills → Jinja2 render.

async def get_skill_instructions(self, activated_groups=None) -> str | None:
    if activated_groups is None:
        activated_groups = [g.name for g in self.tool_groups]
    skills = await self._get_available_skills(activated_groups)
    if len(skills) == 0:
        return None
    template = Template(self.skill_instruction_template)
    return template.render(
        skills=skills.values(),
        skill_viewer=self.builtin_skill_viewer.tool.name,
    )

Why only three fields? Template receives only name/description/dir; code-level constraint prevents body from accidentally leaking into prompt. Injecting skill_viewer tool name ensures manifest auto-syncs if tool is renamed — no "prompt says A, actual is B".

Jinja2 is Python's mainstream template engine: write a template with placeholders, fill data at runtime, generate final text automatically.

Nine: On-Demand View — SkillViewer — Metadata Front-Loaded + Progressive Disclosure Loop Closed

SkillViewer isn't just "read file, return"; it bridges assembly-time manifest and call-time authorization, closing the progressive disclosure loop. Every field design serves "let the model use skills correctly": description writes behavioral instruction — "on receiving task, first cross-check manifest" — not mere feature description; this is the model's behavioral contract. input_schema accepts only exact name, no fuzzy match: filtering delegated to model (semantic strength), exact lookup to system (determinism).

Six metadata fields simultaneously serve permissions, scheduling, telemetry; is_concurrency_safe=True and is_state_injected=True opposite directions but not contradictory: former governs scheduling, latter governs data. check_permissions returns ALLOW, but visible scope still constrained by real-time group re-filter inside call — action permitted, not data access scope. call operation four key points: _agent_state type mismatch → throw DeveloperOrientedException (assembly defect must surface to developer, not masked by degradation).

Use real-time activated_groups for query, not assembly-time snapshot.

Not found → return SkillNotFoundError text block, no exception thrown .

Hit → return ToolChunk(markdown); body enters context for the first time at this moment.

Two filters, neither dispensable: assembly-time controls "what model sees in manifest" (discovery); call-time uses real-time groups to control "what model reads" (authorization). Keep only assembly-time → snapshot stale after group switch, model reads disabled content via old manifest. Keep only call-time → prompt either full-body or blind guess.

async def call(self, name, _agent_state):
    groups = _agent_state.tool_context.activated_groups
    skills = await self._get_available_skills(["basic"] + groups)
    if name not in skills:
        return SkillNotFoundError(name)
    return ToolChunk(skills[name].markdown)

Ten: Execution Pipeline — Nine Stages + Read-Only Fast Path + Body Injection

Skill body does not enter model the moment SkillViewer returns; it must pass through reinjection stage (truncate, unload, write to context) and only becomes visible to the model in the next reasoning turn.

Stage 1 Assembly Injection — Recompute prompt each turn, read real-time groups. Rationale: manifest is computed result, not startup config; recompute every turn.

Stage 2 Scheduling Batching — Batch by concurrency-safe / read-only. Rationale: write ops isolated into sequential batches; read-only can run concurrently.

Stage 3 Availability Check — Check existence & activation first, then validate params. Rationale: availability before params lets model self-correct.

Stage 4 Read-Only Fast Path — is_read_only=True pre-approves. Rationale: fast path is the normal route; check_permissions is double insurance.

Stage 5 State Injection — Register only if skills available; inject _agent_state. Rationale: if all skills deleted, calling Skill yields ToolNotFoundError.

Stage 6 Onion Chain — Middleware recursively wraps, normalize to AsyncGenerator. Rationale: SkillViewer has no middleware → shortest path.

Stage 7 Secondary Filter — Re-filter with real-time groups (basic + active). Rationale: assembly manifest and call-time auth may diverge.

Stage 8 Reinjection — Truncate/unload, write to context, emit FINISHED. Rationale: next-turn model then "sees" just-read content.

Stage 9 Convergence — Model acts as interpreter, consumes Bash/Read/MCP tools. Rationale: no dedicated interpreter; execution = model as interpreter + general tools.

async def execute_skill_call(tool_call, agent_state):
    check_availability(tool_call)  # Stage 3
    if tool_call.is_read_only:
        pass  # Stage 4 fast path
    inject_state(tool_call, agent_state)  # Stage 5
    result = await skill_viewer(tool_call.name, agent_state)
    write_to_context(result)  # Stage 8
    return result

Model emits ToolCallBlock(Skill, args); scheduler batches by concurrency-safety and read-only flags; pre-execution availability check — tool missing or group inactive → hard error; param errors degraded to error text for model self-correction. Read-only fast path pre-approves at permission engine layer; check_permissions as double insurance. Then call_tool recomputes available tools with real-time groups, registers Skill only if any available, injects _agent_state into call args. After onion-chain normalization to AsyncGenerator, SkillViewer.call re-filters with real-time groups; hit returns body, miss returns SkillNotFoundError. Body accumulated as ToolResponse, truncated/unloaded, written to state.context, advanced to FINISHED, emits ToolResultEndEvent. Current reasoning turn already ended; skill body enters model view only at next _prepare_model_input. Model reads body, then invokes Bash, Read, MCP tools per markdown manual — all "write" ops with their own permission checks, possibly user confirmation. Skill system has no interpreter; execution fully converges to general tool layer. Skills only "teach model how to use tools", not "execute for model" — crisp responsibility boundary.

Eleven: Provisioning Partition & Copy Cleanup — Agent Partition + Library/Copy Semantic Separation

10.1 Partition: Each Agent Owns a Skill Directory

Partitioning isn't code logic deciding "who owns this skill"; it's filesystem-level physical isolation naturally preventing cross-talk. Each agent instance exclusively owns a skill copy directory, e.g.:

.agentscope/agents/A/skills/  ← only Agent A reads
.agentscope/agents/B/skills/  ← only Agent B reads

Loader A only scans A's directory; OS-level file permissions isolate — no runtime branches like "check if skill belongs to current agent".

10.2 Group: Directory Name = Group Name

Groups aren't declared in config; they're carried by directory structure itself — first-level subdirectory name is group name, zero-config. Skills placed under skills/frontend/ belong to frontend group. Runtime activates groups via reset_tools; framework scans only activated directories; inactive directories never even scanned.

def discover_groups(skills_root):
    return [d.name for d in skills_root.iterdir()
            if d.is_dir() and not d.name.startswith(".")]

10.3 Partition vs Group: Two-Layer Stacking

Partition — Question answered: which copy belongs to whom. Split basis: agent instance, one plot each. Effective layer: filesystem, physical isolation.

Group — Question answered: which skills visible this turn. Split basis: directory name. Effective layer: prompt manifest, logical filter.

Partition governs "exists or not": what's not in A's directory, A never reads.

Group governs "visible or not": even if in directory, inactive group → model never sees in manifest.

Stacking isn't simple "partition then group"; it's defense-in-depth: physical isolation bottom, logical filter top. Partition first guarantees no cross-agent leakage; group then controls visibility scope.

def get_visible_skills(agent_id, activated_groups):
    partition = get_partition(agent_id)  # Partition: physical isolation
    skills = partition.list_skills()      # Only sees own agent's
    return filter_by_groups(skills, activated_groups)  # Group: logical filter

10.4 Library vs Copy Semantic Separation: Why Delete Library Doesn't Clear Copy

Deleting library record without clearing copy is not a bug — it's deliberate decoupling of library and copy lifecycles. Library governs "eligible to install"; copy governs "installed on this machine"; each manages its own.

Skill Library — Essence: global registry record. Lifecycle: follows system/user account. After delete: cannot reinstall afterward.

Copy — Essence: actual skill files in agent directory. Lifecycle: follows agent instance. After delete: reclaimed by purge_agent.

Library = app store: delist an app → future downloads blocked. Copy = already installed on phone: store delist doesn't affect installed copy. Package manager analogy:

Repo delists a package → delete library record → future installs blocked.

Locally installed package still works → agent copy directory skills still usable.

Manually uninstall local package → purge_agent clears copy directory.

Platform must provide UI notice ("skill delisted but still usable in this agent"), sync-clean entry (delete both library and copy), lifecycle reclamation ( purge_agent auto-clean).

class SkillLibrary:
    records: dict[str, SkillRecord]  # Global: delete → cannot reinstall

class AgentPartition:
    copies: dict[str, SkillCopy]     # Local: purge_agent reclaims

def delete_library_record(name):
    del library.records[name]  # Future installs blocked
    # partition.copies untouched  # Already installed keeps working

10.5 Group Activation: Three Write Paths for activated_groups

Groups aren't "visible because they exist"; they must be explicitly activated for model to see them in manifest. Activation state lives in session-level state, not Toolkit or disk:

agent.state.tool_context.activated_groups  # list[str]

Simplest method: application-side preset — write at startup:

state = AgentState()
state.tool_context.activated_groups = ["basic", "frontend", "devops"]
agent = ReActAgent(..., state=state)

Next prompt assembly, _get_available_skills reads only these groups; get_tool_schemas also exposes only these groups' tool schemas.

Original Source

Signed-in readers can open the original source through BestHub's protected redirect.

Sign in to view source
Republication Notice

This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactadmin@besthub.devand we will review it promptly.

fault toleranceAgent ArchitectureOn-Demand LoadingContext ManagementProgressive DisclosureAgentScopeSkill SystemTool Orchestration
Reader feedback

How this landed with the community

Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.