Skill Guide

Package reusable instructions and optional executors as skills to keep agents fast, deterministic, and auditable. Use this guide to register, inspect, refine, and attach custom skills with the Python SDK (CLI support is coming soon).

What Are Skills?

Skills are self-contained instruction bundles that can optionally run executor code. They wrap clear guidance (in SKILL.md) plus any supporting templates or scripts so an agent can load, activate, and follow them deterministically, consistent with the Agent Skills spec.

Skill definition (per the Agent Skills spec):

• A SKILL.md with YAML frontmatter (id, name, description, optional executor_path) and clear Markdown instructions the model can follow.

• Optional supporting assets: templates, references, and (when present) executor code that the platform runs on your behalf.

• Activated by skill name (frontmatter id) provided at agent creation or per run.

Skill coverage is tracked in the AIP capability matrix. The Python SDK exposes first-class helpers and uses the platform API under the hood so you don't have to call REST directly.

Skill bundles are ZIP files that contain a SKILL.md manifest and any supporting templates or executors. The skill name defaults to the folder name unless you set id in the frontmatter—keep names lowercase and hyphenated for consistency.

Skill Basics and Examples

• Instruction-only template — mirrors the Anthropic skills pattern with a SKILL.md manifest plus a Markdown template read via read_skill_file (see the greeting examples in anthropics/skills).

• Template + executor — pairs SKILL.md with scripts/..._executor.py to run code through run_skill_executor, as described in the Agent Skills spec.

• Domain kits — multi-file packs (similar to the Anthropic plugin-dev skills) that combine manifests, templates, and references to keep long-form guidance organized.

Skills vs. Tools (Side-by-Side)

Aspect	Skills	Tools
Purpose	Instructional bundles that guide the model; may include optional executor code.	Code-first capabilities for actions (API calls, data fetches, mutations).
Activation	By skill name from SKILL.md (frontmatter id).	By tool name; exposed as callable functions.
Best for	Templated outputs, domain guardrails, embedded playbooks.	Performing work: queries, mutations, integrations.
Composition	Instructions + optional executor_path; can reference templates.	Code + schema; may return data for the model to use.
Spec	Agent Skills spec.	Platform tool schema (see Tools guide).

Flow of control:

User request → Agent → (choose skill) → inject instructions → optional executor
            → (use tools as needed) → respond

Skill Package Layout

Each skill ships as a folder with SKILL.md plus optional templates or executors. Zip the folder before registering it. Follow the structure in the Agent Skills spec: YAML frontmatter (id, name, description, optional executor_path) plus clear Markdown instructions the model can follow.

skills/
  datetime/
    SKILL.md
    scripts/datetime_executor.py
    templates/response_template.md

Example SKILL.md:

---
id: datetime
name: Datetime (UTC)
description: Return an ISO 8601 UTC timestamp and date math for offsets.
executor_path: scripts/datetime_executor.py
metadata:
  owner: platform-team
---

# Datetime Skill
- Always call `run_skill_executor` with `days_offset` instead of guessing times.
- Echo the executor output directly in your response.

Package the bundle:

zip -r datetime.zip skills/datetime/

Create Skills

When to use: add a new templated instruction set or executor that agents can activate by skill name.

Python SDK

from glaip_sdk import Client

client = Client()

# Register a ZIP that contains SKILL.md and supporting files
skill = client.skills.create_skill_from_file("skills/datetime.zip")
print(skill.id, skill.name)

CLI

List and Inspect Skills

Python SDK

from glaip_sdk import Client

client = Client()

for skill in client.skills.list_skills(limit=50, page=1):
    print(skill.id, skill.name)

detail = client.skills.get_skill_by_id("datetime")
print(detail.id, detail.name, detail.manifest)

CLI

Retrieve or Refresh Skills

Python SDK

from glaip_sdk import Client

client = Client()

# Save the stored bundle to disk
client.skills.download_skill_zip("datetime", output_path="datetime.zip")

# Re-register after edits (skill name must match SKILL.md frontmatter)
client.skills.update_skill_from_file("datetime", "skills/datetime.zip")

CLI

Delete Skills

Python SDK

from glaip_sdk import Client

client = Client()
client.skills.delete_skill("datetime")

CLI

Attach Skills to Agents

Skills are activated when you include skill names (as defined in SKILL.md) on the agent definition or the per-run payload. The runner fetches missing skills as needed and injects a use_skill pseudo-tool plus run_skill_executor when an executor is present.

Python SDK

from glaip_sdk import Client

client = Client()

# Create or update the agent to include skills
agent = client.agents.create_agent(
    name="faq-with-skills",
    instruction="Prefer skills for templated answers; fall back to tools otherwise.",
    framework="langchain",
    type="config",
    language_model_id="gpt-4o-mini",
    skills=["greeting", "datetime"],
)

# Activate skills for a specific run
result = agent.run(
    "Say hello and include today's timestamp.",
    skills=["greeting", "datetime"],
    token_streaming=True,
)
print(result)

CLI

Runs fail with 422 ValidationError if the referenced skill names are unknown. Ensure each skill is registered and the name matches the SKILL.md frontmatter/folder name.

Troubleshooting

Issue	Symptoms	Resolution
Missing SKILL.md or bad ZIP	400 ValidationError during registration	Ensure SKILL.md exists at the bundle root and zip the skill folder, not individual files.
ZIP too large	400 ValidationError with size message	Keep bundles under 50MB; prune artifacts and rebuild the zip.
Name mismatch on update	400 ValidationError about skill identity	Ensure the name you pass matches the id in SKILL.md and the folder name.
Unknown skill on run	422 ValidationError	Confirm the skill is registered and the names in the run request match the skill name.

Limitations and Safety

• Bundle size: ZIPs up to 50MB; individual extracted files must be under 10MB; no symlinks or path traversal in archives.

• Executors: Provide Python scripts referenced via executor_path; these run in the platform sandbox via run_skill_executor.

• Assets: Include only what the skill needs (templates, small reference files). Large binaries or opaque archives are rejected.

• Naming: Skill names are drawn from SKILL.md frontmatter (id); keep them lowercase and hyphenated for portability.

Related Documentation

• Agents guide — attach skills to agents and run them alongside tools.

• Tools guide — complement skills with tool calls.

• Automation & scripting — script skill registrations and agent runs for CI/CD.