Creating Agent Skills#

Agent Skills are packaged capabilities that give Agents pre-built expertise. This guide walks through how to create a skill — from writing the SKILL.md file to packaging and publishing to the platform.

For the full format specification, see agentskills.io/specification.

Prerequisites#

Before you begin, you'll need:

• A running server in Agent Studio
• Familiarity with how Agents use context and tools
• An understanding of how skills work

Skill directory structure#

A skill is a directory containing, at minimum, a SKILL.md file:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: additional documentation
├── assets/           # Optional: templates, schemas, resources
└── ...               # Any additional files or directories

The SKILL.md file is the only required file. Everything else is optional.

Writing SKILL.md#

The SKILL.md file must contain YAML frontmatter followed by Markdown content. The frontmatter defines metadata, and the Markdown body contains the instructions the Agent follows when the skill is activated.

Frontmatter fields#

Minimal example#

---
name: code-review
description: Reviews code changes for quality, security, and best practices. Use when the user asks for a code review or submits a pull request.
---

# Code Review

You are performing a code review. Follow these steps:

1. Identify the changes in the current branch compared to the base branch
2. Review each changed file for:
   - Code quality and readability
   - Potential bugs or edge cases
   - Security vulnerabilities
   - Adherence to project conventions
3. Provide a summary with:
   - **Blockers** — Issues that must be fixed before merging
   - **Suggestions** — Improvements that would be nice but aren't blocking
   - **Highlights** — Things done well worth calling out

Example with optional fields#

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
compatibility: Requires Python 3.14+ and uv
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(python:*) Read
---

Name field rules#

The name field must:

• Be 1–64 characters
• Contain only lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)
• Not start or end with a hyphen
• Not contain consecutive hyphens (--)
• Match the parent directory name

Writing effective descriptions#

The description field is what Agents use to decide whether to activate the skill. Include specific keywords that help Agents identify relevant tasks.

Good: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction."

Poor: "Helps with PDFs."

Body content#

The Markdown body after the frontmatter contains the skill's instructions. Write whatever helps Agents perform the task effectively.

Recommended sections:

• Step-by-step instructions
• Examples of inputs and outputs
• Common edge cases

Tips for effective instructions#

• Be direct — Write instructions as clear, imperative statements. The Agent will follow them literally.
• Define the output format — If you want structured output (a checklist, a table, specific sections), show the format in the instructions.
• Include guardrails — Tell the Agent what not to do. If the skill should only read files and never modify them, say so explicitly.
• Use headings for structure — The Agent uses heading hierarchy to understand which instructions are primary vs. supplementary.
• Reference supporting files — If your skill includes templates or documentation in subdirectories, reference them by relative path. The Agent can read them at runtime.
• Keep it focused — A skill that tries to do everything will do nothing well. Prefer multiple small, focused skills over one large one.
• Keep it under 500 lines — Move detailed reference material to files in the references/ directory.

Optional directories#

scripts/#

Contains executable code that Agents can run. Scripts should:

• Be self-contained or clearly document dependencies
• Include helpful error messages
• Handle edge cases gracefully

Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.

references/#

Contains additional documentation that Agents can read when needed. Keep individual reference files focused — Agents load these on demand, so smaller files mean less context usage.

Example files:

• REFERENCE.md — Detailed technical reference
• FORMS.md — Form templates or structured data formats
• Domain-specific files (finance.md, legal.md, etc.)

assets/#

Contains static resources:

• Templates (document templates, configuration templates)
• Images (diagrams, examples)
• Data files (lookup tables, schemas)

Progressive disclosure#

Skills should be structured for efficient use of context:

1. Metadata (~100 tokens) — The name and description fields are loaded at startup for all skills
2. Instructions (< 5000 tokens recommended) — The full SKILL.md body is loaded when the skill is activated
3. Resources (as needed) — Files in scripts/, references/, or assets/ are loaded only when required

Testing skills#

Before publishing, test your skill locally on a server:

1. Review the SKILL.md — Read through the frontmatter and instructions, verifying they are clear and complete
2. Validate the structure — Ensure the name matches the directory name and all referenced files exist
3. Simulate activation — Provide the skill's instructions to the Agent and verify the output matches your expectations
4. Iterate — Refine the instructions based on the Agent's behavior. Common adjustments:
   • Adding guardrails when the Agent does something unexpected
   • Clarifying ambiguous instructions
   • Adding examples for complex output formats

Packaging and uploading#

Once your skill is tested, package and upload it:

# From the parent directory containing your skill
tar -czf my-skill.tar.gz my-skill/

Then upload through the platform:

1. Navigate to the Agent Skills page
2. Click Add and select the appropriate scope (Organization, User, or Workspace)
3. Upload the .tar.gz or .zip file
4. Review the extracted metadata and confirm

The skill is immediately available to attach to servers within its scope.

Versioning and updates#

When updating a published skill, use the metadata field to track versions:

metadata:
  version: "1.1.0"

Follow semantic versioning:

• Patch (1.0.0 → 1.0.1) — Bug fixes, minor instruction tweaks
• Minor (1.0.0 → 1.1.0) — New capabilities, additional scripts
• Major (1.0.0 → 2.0.0) — Breaking changes to behavior or output format

Upload the new package and servers will pick up the update automatically via the Rendered.ai Extension.

Best practices#

• One skill, one job — Each skill should do one thing well. A "code-review" skill and a "deploy" skill are better than an "everything" skill.
• Write clear descriptions — The description field is what Agents and users see. Make it specific enough to understand at a glance, and include keywords that help Agents match it to relevant tasks.
• Keep instructions under 500 lines — Long instructions dilute the Agent's attention. Move detailed reference material to the references/ directory.
• Include examples in assets — Rather than putting long examples directly in the instructions, store them in assets/ and reference them. This keeps SKILL.md readable.
• Version your skills — Even for internal skills, versioning via metadata helps you track changes and coordinate rollouts.

Agent Skills vs. Rules#

Agent Skills and Rules both influence Agent behavior, but they serve different purposes:

A good rule of thumb: if you find yourself writing the same complex instructions repeatedly, package them as a skill. If you want behavior that should always apply, use a rule.