Agent Skills Framework Overview

Relevant source files

The following files were used as context for generating this wiki page:

• ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md
• ai-docs/003-AI/006-多智能体/002-Multica智能体模板与小队编排skills调研/index.md
• ai-docs/003-AI/006-多智能体/001-Multica-agent协作与上下文机制/index.md
• blog/2026/10/07/01-AI代码质量.md
• ai-docs/003-AI/003-Agent-Harness/DSH/003-DSH预设提示词全解/preset-explorer.html
• ai-docs/003-AI/004-记忆/001-对话记忆与知识库增量沉淀/index.md

The Agent Skills Framework defines a standardized architecture for equipping AI agents with reusable capabilities, specialized workflows, and engineering constraints. It focuses on progressive disclosure of information through a tiered context budget to prevent context window exhaustion while ensuring high trigger reliability. The framework organizes skills as "reusable skills" that can be searched, evaluated, and bound to specific agents or squads within platforms like Multica.

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:27-35, ai-docs/003-AI/006-多智能体/002-Multica智能体模板与小队编排skills调研/index.md:32-35

Skill Architecture and Tiered Context

The framework utilizes a three-level loading mechanism to balance immediate availability with context resource conservation. Information is disclosed progressively based on the agent's current task requirements.

Level	Content Component	Loading Trigger	Budget Constraints	Binding Constraint
Level 1	name + description	Preloaded at startup for all installed skills	~100 words	High compression required
Level 2	SKILL.md body	Entirely loaded upon skill trigger	< 5000 tokens / < 500 lines	Hard constraint
Level 3	references/, scripts/, assets/	Loaded on-demand by the agent	Virtually unlimited	No limit

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:73-82

Tiered Loading Flow

The following diagram illustrates how the system manages context by only loading Level 2 and Level 3 data when specific conditions are met.

The system preloads Level 1 for all skills to enable the model to decide which skill to invoke. Level 2 is only loaded once the model identifies a match, and Level 3 is accessed only when the agent explicitly calls for supplemental files.
Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:83-108

Trigger Engineering

Skill triggering relies exclusively on the name and description fields provided in the skill's frontmatter. The agent is unaware of the SKILL.md body until the trigger occurs; therefore, "When to Use" instructions must reside in the description.

Effective Description Formula

A functional description must combine two elements:

1. What it does: A list of specific capabilities containing key nouns.
2. When to use it: Specific scenarios and potential user phrases (triggering keywords).

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:144-150

Naming Conventions

Skills must follow strict naming rules to prevent silent loading failures:

• Maximum 64 characters.
• Only lowercase letters, numbers, and hyphens allowed.
• No consecutive hyphens (e.g., my--skill is invalid).
• The name field must exactly match the parent directory name.

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:214-220

Content Organization and File System

The framework separates "how to do" from "what to use" to maintain a clean context. Level 3 resources are categorized by their role in the agent's workflow.

Directory	Purpose	Context Behavior	Typical Content
scripts/	Executable code	Not loaded into context	Deterministic steps, reliable logic
references/	Technical documentation	Loaded on-demand	Schemas, API docs, long examples
assets/	Production resources	Not loaded into context	Templates, icons, boilerplate

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:178-185

Content Stratification by Freedom

The choice between writing instructions (Level 2) or scripts (Level 3) depends on the required degree of freedom:

• High Freedom (Text): Used for heuristic tasks or decisions dependent on context.
• Low Freedom (Scripts): Used for fragile, error-prone operations that must remain consistent.

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:167-175

Skill Governance and Implementation

In multi-agent environments like Multica, skills serve as the primary mechanism for defining agent capabilities. Governance involves searching, evaluating, and managing the lifecycle of these skills.

Skill-Based Agent Composition

Agents are defined by their instructions and the set of skills bound to them. The framework advocates for "curated skills" where sources are evaluated for reliability before import.

The hx-skill-curator manages the allowlist of skills, recording source URLs, tags, and reliability metrics.
Sources: ai-docs/003-AI/006-多智能体/002-Multica智能体模板与小队编排skills调研/index.md:130-135, ai-docs/003-AI/006-多智能体/002-Multica智能体模板与小队编排skills调研/index.md:183-195

Quality Control (Guardrails)

The framework includes specialized skills like hx-project-guardrails to install project-level constraints, including:

• Code Quality: Linting, formatting (120 character limit, 4-space indentation), and architecture checks.
• Documentation: Requirement for AGENTS.md and README.md to be present in all directories.
• Context Constraints: Total context (AGENTS + Skills) must not exceed 64KB.

Sources: blog/2026/10/07/01-AI代码质量.md:100-115, blog/2026/10/07/01-AI代码质量.md:148-155

Verification and Falsifiability

Skill effectiveness must be verified using "forward-testing," where a fresh agent is tasked with a real objective without knowing it is being tested. Verification is considered successful only if the agent succeeds without "leaked" context or meta-knowledge about the test.

Automated Validation Checklist

Since skill loading failures are often silent, the framework requires automated validation scripts covering:

1. Naming consistency with directory names.
2. Presence of trigger information in the description.
3. Context budget adherence (Level 2 < 500 lines).
4. Reference integrity (all Level 3 files must be cited in SKILL.md).
5. Nesting limits (references must only be one level deep from SKILL.md).

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:225-235, ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:255-265

Summary

The Agent Skills Framework provides a technical standard for building modular AI capabilities. By enforcing a tiered context structure and strict trigger engineering, it ensures that agents can access vast amounts of specialized knowledge without overwhelming the model's primary context window. The framework's emphasis on executable validation and on-demand resource loading facilitates a scalable multi-agent ecosystem where skills are treated as verifiable engineering assets.