Documentation / Agent skills / Setup

Skills setup guide

Step-by-step guidance for creating a skill directory, authoring SKILL.md, testing locally, and shipping to production.

← Documentation overviewAgent skills hub

This guide walks through how to create, configure, and deploy skills for the Agentic Hosting platform.

Creating a new skill

Step 1: Choose a location

Skills are stored in the skills/ directory. Choose the appropriate location:

skills/
├── core/           # Core platform skills (built-in)
├── community/      # Community-contributed skills
├── private/        # Private/organizational skills
└── your-skill/     # Your custom skill

Step 2: Create the skill directory

mkdir -p skills/my-awesome-skill

Step 3: Create SKILL.md

Create the main skill definition file:

touch skills/my-awesome-skill/SKILL.md

Step 4: Add frontmatter

Add the required YAML frontmatter:

---
title: "My Awesome Skill"
slug: my-awesome-skill
description: "Does something useful for your agent."
version: "1.0.0"
author: "Your Name"
tags: ["automation", "useful"]
category: "automation"
status: "active"
requirements: []
---

Step 5: Add content

Fill in the skill content following the skills format specification.

Skill structure best practices

Naming conventions

  • Slug: lowercase, hyphens, no spaces (my-awesome-skill).
  • Title: Human-readable, title case (“My Awesome Skill”).
  • Files: Use descriptive names (extract_data.md, api_integration.md).

Versioning

Follow Semantic Versioning:

  • Major (1.0.0 → 2.0.0): Breaking changes.
  • Minor (1.0.0 → 1.1.0): New features, backward compatible.
  • Patch (1.0.0 → 1.0.1): Bug fixes.

Categories

CategoryDescription
coreBuilt-in and foundational platform skills.
automationTask automation and workflow skills.
researchInformation gathering and analysis.
opsOperational and system tasks.
integrationExternal API and service integrations.
dataData processing and transformation.
securitySecurity-related skills.

Tags

Use relevant tags for discovery:

  • Action tags: extract, transform, load, analyze, notify.
  • Domain tags: finance, hr, marketing, engineering.
  • Tech tags: api, database, aws, stripe.

Testing your skill

Local validation

  1. Check frontmatter — Ensure valid YAML.
  2. Verify structure — All required sections present.
  3. Test examples — Run example code snippets.

Integration testing

  1. Load skill — Ensure the skill can be loaded by the agent.
  2. Test execution — Run with sample inputs.
  3. Verify output — Check outputs match expectations.
  4. Error handling — Test edge cases and error conditions.

Deploying skills

Development environment

Skills in skills/ are loaded automatically in development.

Production deployment

  1. Version bump — Update version in frontmatter.
  2. Test thoroughly — Run full test suite.
  3. Document changes — Update changelog.
  4. Deploy — Push to production environment.
  5. Verify — Confirm skill loads correctly.

Common issues

Frontmatter parse errors

Problem: YAML frontmatter will not parse.

Solution: Check for consistent indentation (2 spaces), no tabs, valid YAML syntax, and proper quoting of special characters.

Skill not loading

Problem: Skill does not appear in the skill list.

Solution: Check status is set to active, verify slug is unique, and ensure SKILL.md is at the skill root.

Invalid examples

Problem: Example code does not work.

Solution: Verify syntax is correct, check all required parameters are provided, and test with actual execution.

Next steps