Skill Creator

Skill Creator

Create skills that give CAMEL agents useful, non-obvious guidance without constraining unrelated work.

Core principles

• Assume the agent is capable. Include only context that changes its decisions or makes repeated work more reliable. Remove generic advice, duplicated explanations, and speculative edge cases.
• Preserve user intent and authority. A skill supports the requested task; it does not broaden the task, select a different product, or grant permission for external or destructive actions.
• Match specificity to risk. Use flexible instructions when several approaches are valid. Use exact sequences or deterministic scripts when an operation is fragile, safety-sensitive, or must be repeatable.
• Keep discovery precise. The description is visible before the body and is the primary trigger. State the job, likely trigger terms, and any boundary needed to prevent common false matches.
• Disclose details progressively. Keep the shared workflow in SKILL.md. Put conditional details in directly linked references and load only the resources needed for the current request.
• Prefer the smallest useful bundle. Start instruction-only. Add a script, reference, or asset only when it has a concrete, recurring purpose.

CAMEL skill contract

A skill is a directory with one required file and optional resources:

skill-name/
|-- SKILL.md          Required frontmatter and instructions
|-- scripts/          Optional deterministic helpers
|-- references/       Optional guidance loaded only when relevant
`-- assets/           Optional templates or files used in output

For repository-scoped CAMEL skills, prefer <repo-root>/.camel/skills/<skill-name>/. SkillToolkit also discovers repository skills under .agents/skills, user skills under ~/.camel/skills and ~/.config/camel/skills, and system skills under /etc/camel/skills.

Design for these runtime behaviors:

• SkillToolkit initially exposes each skill's name, description, path, scope, and direct child entries. It loads the body only after the agent calls load_skill.
• Loaded content includes the skill's base directory. Use paths relative to that directory when referring to bundled resources.
• Repository skills take precedence over user and system skills with the same name. Keep names unique and make the directory name match the frontmatter name.
• Skill discovery is cached. Call clear_cache() or recreate the toolkit when testing changes in a running process.
• SkillToolkit loads instructions but does not execute scripts. Give the agent TerminalToolkit or another appropriate execution tool when a skill requires runnable helpers.
• Product-specific metadata is optional. Do not add files such as agents/openai.yaml unless a target host actually consumes them; CAMEL's SkillToolkit does not require them.

Create or update a skill

Adapt the workflow to the request. Skip steps that add no value, but verify the finished skill against realistic use.

1. Define the job and trigger boundary

Identify:

• the outcome the skill should help produce;
• two or three realistic requests that should trigger it;
• nearby requests that should not trigger it;
• non-obvious constraints, tools, data, or output requirements.

Ask the user only for missing information that would materially change the skill. For an existing skill, inspect its current files and callers before removing or renaming anything.

2. Plan the minimum bundle

Use SKILL.md alone when instructions are sufficient. Add resources only for these reasons:

• scripts/: logic that would otherwise be rewritten, or operations needing deterministic behavior;
• references/: maintained schemas, policies, APIs, or substantial guidance needed only in some modes;
• assets/: templates, fonts, images, boilerplate, or other files copied or adapted into the result.

Do not add placeholder directories, README files, changelogs, installation guides, or duplicated quick references without a concrete requirement.

3. Initialize or edit

For a new skill, either create the directory and SKILL.md directly or use the bundled initializer when its scaffold is useful:

python <skill-creator-base>/scripts/init_skill.py \
  <skill-name> --path <repo-root>/.camel/skills

The current initializer creates example resource directories. Delete every placeholder and directory the finished skill does not need. Do not initialize an existing skill again.

Use lowercase letters, digits, and single hyphens for names, with a maximum of 64 characters.

4. Write for progressive disclosure

In frontmatter:

• Keep name equal to the skill directory name.
• Write a concise, discriminating description that says what the skill does and when it applies. Front-load the main use case because hosts may shorten long descriptions.
• Keep required metadata to name and description. Add supported optional fields only when the target environment needs them.

In the body:

• Use direct instructions and decision criteria, not background the agent already knows.
• State inputs, outputs, important invariants, and stopping conditions where they affect correctness.
• Link every supporting reference where it becomes relevant and explain when to read it. Avoid deep chains of references.
• Reuse scripts and assets explicitly rather than asking the agent to recreate them.
• Preserve real compatibility and authorization boundaries. Do not turn one observed failure into a universal rule without evidence.

For conditional patterns, read only the applicable bundled guide:

• For sequential or branching procedures, read references/workflows.md.
• For strict output structures or examples, read references/output-patterns.md.

5. Validate implementation

Run the bundled validator from any working directory:

python <skill-creator-base>/scripts/quick_validate.py <skill-directory>

Then verify the behavior that validation cannot prove:

• Run every new or changed helper script with representative inputs.
• Instantiate SkillToolkit with the intended repository root as working_directory and confirm the skill appears in list_skills().
• Confirm list_skill_files() exposes the intended resources and load_skill() returns the body with the correct base directory.
• If scripts are required, test the agent with both SkillToolkit and the execution toolkit the workflow expects.

6. Evaluate and iterate

Test trigger quality and execution quality separately:

1. Try the realistic should-trigger and should-not-trigger requests from step
   1. Include paraphrases rather than matching only the description's wording.
2. Run a small set of representative tasks with the skill loaded. When useful, compare against the same tasks without the skill to check that it adds value.
3. Inspect the actual decisions and outputs, collect user feedback when output quality is subjective, and identify the smallest supported correction.
4. Re-run the affected cases and retain changes only when they improve the intended behavior without broadening false triggers.

Use the CAMEL model and agent configuration already chosen for the task. Do not introduce a provider-specific CLI merely to evaluate a CAMEL skill. Independent or parallel agent evaluation is optional when available and justified; it is not a prerequisite for creating a useful skill.

7. Package only when needed

If the user needs a distributable .skill archive, run:

python <skill-creator-base>/scripts/package_skill.py \
  <skill-directory> [output-directory]

The packager validates first and excludes common local, credential, cache, and build artifacts. Inspect the archive contents before delivery. Do not package an intermediate skill when repository-local use is the requested outcome.

Completion criteria

A skill is complete when:

• its trigger boundary is clear and tested with positive and negative cases;
• its instructions preserve task scope and contain only useful guidance;
• every bundled resource is necessary, discoverable, and verified;
• CAMEL can discover and load it from the intended root;
• no scaffold placeholders or local artifacts remain;
• packaging succeeds when distribution was requested.