Agent Skills Investigation

[wenjin272]

Agent Skills Investigation

Introduction

Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently.

example

Take the Brave Search Skill as an example:：https://clawhub.ai/steipete/brave-search, It includes the following files:

• SKILL.md describes the skill’s name, purpose, and usage.

• search.js and content.js are Node.js scripts used for web search and content extraction, respectively.

Why Agent Skills

• For skill authors: Build capabilities once and deploy them across multiple agent products.

• For compatible agents: Support for skills lets end users give agents new capabilities out of the box.

• For teams and enterprises: Capture organizational knowledge in portable, version-controlled packages.

My understanding is:

•  Dynamically expand knowledge and capability boundaries—similar to RAG retrieving SOPs or domain-specific knowledge.

• Increase determinism and reliability in task execution—akin to explicitly defining workflows.

• Share skills across any agent that supports the agent skill—similar to how MCP servers work.

How skills work

Skills use progressive disclosure to manage context efficiently:

1. Discovery: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.

2. Activation: When a task matches a skill’s description, the agent reads the full SKILL.md instructions into context.

3. Execution: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed.

In terms of implementation in agent framework:

1. During initialization, the agent loads the name and description of all skills from a specified directory and injects them into the system prompt.

2. A "load skill" tool is provided; when the LLM decides a skill is needed, it generates a tool call to fetch the skill’s full content.

3. A shell command execution tool is provided; when the LLM determines that a script or command from the skill should be run in the shell, it generates a tool call to execute it.

agentscope-java implementation

We evaluated three repositories: LangChain, AgentScope, and AgentScope-Java. Among them, AgentScope-Java provides the most complete support for Agent Skills: agentscope-ai/agentscope-java#92.

It mainly includes three components:

• Implement basic skill registration, loading, and integration

• Support sandboxed execution of scripts within skills

• Improve ecosystem compatibility and maintainability

[qingfei1994]

@wenjin272 I think integrating with skills is a fantastic idea, but I do have a question. Skills are typically triggered by prompts. For an event-driven agent framework, how does it work with various types of skills when the agents are predefined with specific workflows?

[wenjin272]

Skills are typically triggered by prompts

Yes. To use skills, the framework must provide a system prompt to the chat model, like:

## Available Skills

<usage>
Skills provide specialized capabilities and domain knowledge. Use them when they match your current task.

How to use skills:
- Load skill: load_skill_through_path(skillId="<skill-id>", path="SKILL.md")
- The skill will be activated and its documentation loaded with detailed instructions
- Additional resources (scripts, assets, references) can be loaded using the same tool with different paths

Path Information:
When you load a skill, the response will include:
- Exact paths to all skill resources
- Code examples for accessing skill files
- Usage instructions specific to that skill

Template fields explanation:
- <name>: The skill's display name
- <description>: When and how to use this skill
</usage>

<available_skills>
...

and after the available_skills will be the name and description of each skill.

I think the main difference is, for conversation agents, user could dynamic add or remove skills, but for event-driven agents, user must register all the skills may be used when define the agents and can't add new skills during the runtime.

But, in the future, I think we could also achieve dynamic adding or removing agent skills by retrieving them from an MCP server. Because FASTMCP now supports skills provider: https://gofastmcp.com/servers/providers/skills. And we plan to support dynamic loading tools and prompts from mcp server: #543.

[wenjin272]

Besides, I am currently preparing the design document for the agent skills integration, which is expected to be released this week. You are welcome to participate in the review once it's available.

[qingfei1994]

sure, looking forward to that

[wenjin272]

Hi, @qingfei1994, I have posted the design for agent skills integration #565.