AffinityBots LogoAffinityBots
Agents

Agent Skills

Create custom capabilities for your AI agents. Build skills with AI, import from packages, or use community skills.

March 10, 2025
6 min read

Agent Skills are reusable capability packages you attach to your agents. Each skill adds instructions, behaviors, and optional tool requirements—letting you extend agents without rewriting prompts or reconfiguring tools for every agent.

What Are Agent Skills?

A skill is a packaged set of:

  • Instructions – Markdown instructions that define how the agent should behave when the skill is active
  • Metadata – Name, description, and compatibility info
  • Optional requirements – Tools, knowledge, or other resources the skill needs

Skills sit between raw prompts and raw tools: they bundle behavior and requirements into reusable units you can attach to multiple agents.

Plan Limits

PlanSkill builds per month
Free3
Starter25
ProUnlimited

A skill build is one AI-assisted creation in the Skill Builder. Importing existing skills (folder/zip) does not count as a build. Skills require a Starter or Pro plan to access the Skills page and builder.

Creating Skills

With the AI Skill Builder

  1. Go to Skills in the sidebar
  2. Click Build Skill
  3. Describe what you want the skill to do (e.g., "Build a support triage skill that classifies tickets and drafts responses")
  4. The builder opens with an AI-generated skill structure
  5. Edit the SKILL.md and other files as needed
  6. Save and publish

The Skill Builder uses AI to generate the initial skill from your description. You can refine the instructions, add required tools, and adjust the structure before saving.

By import

  1. Go to Skills → Import
  2. Upload a skill folder (as a zip) or provide a path
  3. The skill must follow the standard format: a SKILL.md file with frontmatter and markdown instructions
  4. Imported skills appear in My Skills

Importing does not consume skill builds. Use this for skills you've created elsewhere or downloaded from the community.

My Skills vs Community

  • My Skills – Skills you own (created or imported). You can edit, archive, and assign them to agents.
  • Community – Public skills shared by others. You can browse and clone them to add a copy to My Skills, then assign to your agents.

Cloning a community skill creates your own copy. Updates to the original community skill do not affect your clone.

Assigning Skills to Agents

  1. Open your agent in the Agent Builder
  2. Go to the Skills tab (or Config panel → Skills)
  3. Click Add skill and choose from your skills
  4. Reorder skills if needed (order can affect which skills are activated first)
  5. Save

An agent can have multiple skills. At runtime, the agent receives metadata for all attached skills and activates relevant ones based on the user's request.

How Skills Work at Runtime

When a user sends a message:

  1. The agent receives metadata (name, description) for all attached skills
  2. Based on the message, the agent selects which skills to activate
  3. For activated skills, the full instructions are loaded into context
  4. The agent follows those instructions while responding
  5. Required tools (if any) are checked against the agent's enabled tools

Skills are loaded progressively—only activated skills get their full instructions loaded, which keeps token usage efficient.

Skill Package Format

Skills follow a standard package structure:

my-skill/
  SKILL.md          # Required: frontmatter + markdown instructions
  scripts/          # Optional: executable helpers
  references/      # Optional: reference docs
  assets/           # Optional: templates, resources

The SKILL.md file has YAML frontmatter for metadata and markdown for instructions. Example:

---
name: "Support Triage"
description: "Classifies support tickets and drafts responses"
---
# Instructions
When the user asks about a support ticket...

Best Practices

Writing skill instructions

  • Be specific – Clear instructions produce more consistent behavior
  • Keep it focused – One main capability per skill
  • Reference tools – If the skill needs tools, list them in metadata so they can be enabled

Organizing skills

  • Reuse across agents – Create skills for common behaviors (e.g., "Email drafting", "Research summarization") and attach to multiple agents
  • Combine with tools – Skills that need Gmail, Slack, etc. should declare required tools so you can enable them when assigning the skill

Skill builds

  • Use builds wisely on Free – You get 3 per month; consider importing or cloning community skills to extend your library
  • Refine before saving – Edit the AI-generated skill in the builder before publishing to avoid wasting builds

Troubleshooting

"Skills require Starter or Pro"

The Skills page and Skill Builder are available on Starter and Pro plans. Free users can still use agents that have skills assigned (if the agent was configured by someone on a paid plan), but cannot create or manage skills.

"Skill build limit reached"

Free: 3 builds/month; Starter: 25 builds/month. The limit resets each calendar month. Importing skills does not count toward the limit.

Agent not using a skill

  • Ensure the skill is assigned to the agent
  • Check that the user's message relates to the skill's purpose—skills are activated based on relevance
  • Verify required tools are enabled for the agent if the skill declares them

Import failed

  • Ensure the package has a SKILL.md file at the root
  • Check that the zip contains the skill folder (not loose files)
  • Validate frontmatter format (name, description)

Related Guides