[Feature Request] Chatagent support Skill

[fengju0213]

Required prerequisites

• I have searched the Issue Tracker and Discussions that this hasn't already been reported. (+1 or comment there if it has.)
• Consider asking first in a Discussion.

Motivation

CAMEL Skills Design (Phase 1)

Goal: add a skills system that mirrors Codex/Claude-style SKILL.md usage, with
an extensible provider layer.

Requirements

• Support external skills (loaded from configured filesystem roots).
• Do not persist injected skill messages in memory.
• Keep skill format compatible with Claude skills repo (SKILL.md + YAML frontmatter).
• Keep progressive disclosure: load metadata first, load full content on demand.

SkillSpec (format protocol)

SKILL.md with YAML frontmatter:

• Required:
  • name
  • description
• Optional:
  • metadata.short-description (kept for compatibility with Codex-style metadata)

Example:

---

name: pdf-processing
description: Extract tables and forms from PDFs.
metadata:
short-description: PDF parsing and extraction

PDF Processing

[Instructions...]

Data model

SkillMetadata

• name: str
• description: str
• short_description: Optional[str]

SkillDocument

• meta: SkillMetadata
• body: str

SkillLoadOutcome

• skills: list[SkillMetadata]
• errors: list[SkillError]

SkillError

• source: str
• message: str

SkillLoader (progressive disclosure)

Purpose: load only metadata during listing, and load full content only when a
skill is explicitly mentioned.

• list(cwd) -> SkillLoadOutcome (metadata only)
• read(meta) -> SkillDocument (full body)

Provider abstraction

Phase 1: only FilesystemSkillProvider is implemented.

SkillProvider (interface)

• list(cwd) -> list[SkillMetadata]
• read(meta) -> SkillDocument
• refresh(cwd) -> None

FilesystemSkillProvider

• Roots (ordered):
  • repo: /.camel/skills
  • user: ~/.camel/skills
  • system: /etc/camel/skills
• Recursively scan for SKILL.md files.
• Skip hidden dirs and symlinks.
• Parse frontmatter and validate length limits.
• Dedupe by name with priority: repo > user > system > external.

SkillManager

• Aggregates providers (Phase 1 only filesystem).
• Caches per cwd.
• Resolves explicit mentions in user input.
• Builds injection messages.

Injection strategy

• Injected messages are not written to memory.
• Injected payload is a user message with a stable wrapper:

skill-name /path/to/SKILL.md ...contents...

Skill creator

It is a skill in itself.

reference: SKILL.md

ChatAgent integration

• Before calling the model in ChatAgent.step:

  1. skills = SkillManager.list(cwd)
  2. mentions = SkillManager.resolve_mentions(user_text, skills)
  3. injection_msgs = SkillManager.build_messages(mentions)
  4. prepend injection_msgs to the message list for this turn

• Memory filtering:

  • Mark injected messages with meta_dict {"skill": true} and skip these on write.

Error handling

• Invalid SKILL.md is recorded as a warning (not fatal) and skipped.
• System-scope errors are suppressed (optional, matches Codex behavior).
• Read failures during injection create warnings but do not fail the turn.

Directory structure (proposal)

camel/
skills/
init.py
spec.py # SkillSpec parsing/validation
model.py # SkillMetadata, SkillDocument, SkillLoadOutcome, SkillError
loader.py # SkillLoader (list/read)
provider.py # SkillProvider interface
provider_fs.py # FilesystemSkillProvider (phase 1)
manager.py # SkillManager
injection.py # build injection messages

Solution

No response

Alternatives

No response

Additional context

No response

[lightaime]

Thanks @fengju0213. Why not use give the skill directory to agent and ask the agent to use terminal toolkit to use the skills? We only support skills for agents that have access to terminal. Maybe add a skill toolkit that has access to the skill folder to list, load and offload skills to agent’s context

[fengju0213]

Thanks @fengju0213. Why not use give the skill directory to agent and ask the agent to use terminal toolkit to use the skills? We only support skills for agents that have access to terminal. Maybe add a skill toolkit that has access to the skill folder to list, load and offload skills to agent’s context

yeah, our skill needs to be used in conjunction with a terminal.

[fengju0213]

Thanks @fengju0213. Why not use give the skill directory to agent and ask the agent to use terminal toolkit to use the skills? We only support skills for agents that have access to terminal. Maybe add a skill toolkit that has access to the skill folder to list, load and offload skills to agent’s context

The current design is only for formatting specifications. For skill generation, I plan to provide a skill that the agent can use the terminal to generate.

[lightaime]

Thanks @fengju0213. Why not use give the skill directory to agent and ask the agent to use terminal toolkit to use the skills? We only support skills for agents that have access to terminal. Maybe add a skill toolkit that has access to the skill folder to list, load and offload skills to agent’s context

The current design is only for formatting specifications. For skill generation, I plan to provide a skill that the agent can use the terminal to generate.

Can you design the interface of skill toolkit and how does agent use it?

[fengju0213]

Thanks @fengju0213. Why not use give the skill directory to agent and ask the agent to use terminal toolkit to use the skills? We only support skills for agents that have access to terminal. Maybe add a skill toolkit that has access to the skill folder to list, load and offload skills to agent’s context

The current design is only for formatting specifications. For skill generation, I plan to provide a skill that the agent can use the terminal to generate.

Can you design the interface of skill toolkit and how does agent use it?

One option is to design a dedicated skill toolkit with a small set of clear, high-level functions exposed to the agent, for example:

• list_skills()
  Returns only summary / metadata of skills (e.g. name, description, tags, version), without loading full content.

• get_skill(skill_name)
  Retrieves the full definition of a specific skill (e.g. the underlying markdown / YAML).

• create_skill(spec)
  Generates and persists a new skill based on a given specification.

That said, I’m also questioning whether a separate toolkit is strictly necessary. Since skills are essentially just structured markdown files, we could potentially rely on prompting + the terminal toolkit to guide the agent to:

• list files in the skill directory,
• read skill definitions,
• generate and write new skill files when needed.

I’d be interested to hear your thoughts on which direction makes more sense here.

[fengju0213]

I think the core issue is how to elegantly load skills into the agent’s context.
Whether this is done via a dedicated skill toolkit or through the terminal toolkit may actually be less important.

[bytecii]

@fengju0213
I think make a toolkit for skills should be interesting, for example make agent to load/get some skills which don't need to be exposed as files in the file system? but we can make the terminal agent use skill at first
and then we can do the toolkit later maybe need more detailed planning

• list skills design maybe we can follow this https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart
  maybe some extra arguments like the user's skills folder to be listed or use skills from anthropic?
• for elegant loading skills we can either explicit invocation (such as list chosen skill details to agent) or modify the prompt tell the agents which skills are activated https://developers.openai.com/codex/skills/
• generate the new skill maybe quite tricky, we can support this later