Skip to main content

Skills

A skill is a folder of instructions, scripts and reference files that an agent loads on demand when a task matches it.

Use a skill for know-how you want to reuse across agents, such as a house writing format or a checklist. The agent sees only the skill's description until a task needs it, so skills keep the agent's context small.

Try it​

This example writes a one-file skill, uploads it, and attaches it to an agent.

from pathlib import Path
from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

folder = Path("release-notes")
folder.mkdir(exist_ok=True)
(folder / "SKILL.md").write_text("""---
name: release-notes
description: Writes release notes in the house format from a list of changes.
---
# Release notes
Write three sections: New, Improved, Fixed. One bullet per change, past tense.
End with the line "Thanks to everyone who reported issues."
""")

skill = aix.Skill(file_path="release-notes").save()

agent = aix.Agent(
    name="Release writer",
    description="Writes release notes for product updates.",
    instructions="Use your skills when they match the task.",
    skills=[skill],
).save()

result = agent.run("Write release notes for: added CSV export; fixed login timeout; faster search.")
print(result.data.output)
Show output

Write a skill​

A skill is a folder with a SKILL.md file at its root. Add scripts/ and resources/ subfolders for helper code and reference files; the whole tree is uploaded as one asset. A single .md file also works, and is stored as SKILL.md.

The frontmatter of SKILL.md sets the skill's metadata. The body is the instructions the agent reads when it loads the skill.

FieldRequiredDescription
nameNoSkill name. Defaults to the folder name.
descriptionYesWhat the skill does and when to use it. The agent routes on this text, so make it specific.
requiresNoAsset paths of tools the skill expects, for example tavily/tavily-web-search/tavily.

aix.Skill(file_path=...) reads the folder without any network call. Check what it parsed before you save.

print(skill.name, "|", skill.description, "|", skill.status)
Show output

Find skills​

Get a skill by ID or path, or search your skills by name.

same = aix.Skill.get(skill.id)
print(same.name)

page = aix.Skill.search("release", page_size=5)
for item in page.results:
    print(item.name, item.status)
Show output

Pass a Skill object or a skill ID in skills=[...] when you create an agent.

Update a skill​

update() replaces or adds one file in the skill. Agents that use the skill get the new content on their next run.

(folder / "SKILL.md").write_text("""---
name: release-notes
description: Writes release notes in the house format from a list of changes.
---
# Release notes
Write three sections: New, Improved, Fixed. One bullet per change, past tense.
End with the line "Questions? Reply to this email."
""")

skill.update(str(folder / "SKILL.md"))
print(skill.list_files())

result = agent.run("Write release notes for: added dark mode.")
print(result.data.output)
Show output

Download, copy and delete​

print(skill.download("release-notes.zip"))

copy = skill.clone(name="release-notes-copy").save()
print(copy.name)

copy.delete()
agent.delete()
skill.delete()
Show output

Reference​

ParameterTypeDefaultDescription
file_pathstrrequiredA folder with SKILL.md at its root, or a single .md file.
namestrfrom SKILL.mdOverrides the frontmatter name.
descriptionstrfrom SKILL.mdOverrides the frontmatter description.
tagslist[str][]Labels to organize and filter skills.
MethodWhat it does
aix.Skill(file_path=...).save()Upload a skill.
aix.Skill.get(id), aix.Skill.search(query)Find skills.
skill.update(path, name=None)Replace or add one file or subfolder.
skill.list_files()List the files in the skill.
skill.download(path)Save the skill as a ZIP file.
skill.clone(name=...), skill.delete()Copy or remove a skill.

Next steps​