Skills Configuration

Overview

Skills let a Digital Employee follow a reusable operating guide for a specific task or domain.

Each skill is a directory containing a SKILL.md file. The Digital Employee reads these instructions at runtime and uses them to shape its behavior for matching requests.

In this repository, two usage patterns are demonstrated by the examples:

• Remote GitHub-based skills

• Local path-based skills

Use remote skills when you want a deployable Digital Employee that references skills stored in GitHub. Use local skills when you want to develop and test skill behavior locally without deploying.

Key Concepts

What is a skill?

A skill is an instruction package that gives the Digital Employee a narrowly scoped behavior. It is represented by a Skill object (from glaip_sdk.skills) and must point to a directory containing a SKILL.md file.

You can provide skills as:

• A GitHub URL string pointing to a skill directory in a GitHub repository

• A Skill object loaded from a local filesystem path using Skill.from_path(...)

• A list combining any of the above

How skills are attached

Skills are attached to a DigitalEmployeeAgentBuilder before building the pipeline:

from digital_employee_core.digital_employee.builders.agent_builder import DigitalEmployeeAgentBuilder
from digital_employee_core.digital_employee.builders.builder import DigitalEmployeeBuilder
from digital_employee_core.digital_employee.builders.pipeline_builder import DigitalEmployeePipelineBuilder

agent_builder = DigitalEmployeeAgentBuilder().add_skills(skills)
pipeline_builder = DigitalEmployeePipelineBuilder().add_step(agent_builder)

digital_employee = (
    DigitalEmployeeBuilder()
    .set_name("my_assistant")
    .set_email("[e-mail]")
    .set_job(
        title="My Assistant",
        description="A digital employee with skills",
        instruction="You are a helpful assistant.",
    )
    .set_pipeline(pipeline_builder)
    .build()
)

You can also add and remove skills on a built agent:

agent.add_skills("https://github.com/org/repo/tree/main/skills/my-skill")
agent.remove_skills(skill_object)

Multiple add_skills() calls accumulate — they do not replace previously added skills. Passing None or an empty list is a no-op.

Skill source types

Remote GitHub skills

Pass a GitHub tree URL string directly:

skills = ["https://github.com/coreyhaines31/marketingskills/tree/main/skills/copywriting"]

agent_builder = DigitalEmployeeAgentBuilder().add_skills(skills)

This is the right choice when:

• You want skills stored in a versioned repository

• You want to share the same skill source across environments

• You want the Digital Employee to fetch the latest skill on first invocation

Local path-based skills

Load a Skill object from a local directory:

from glaip_sdk.skills import Skill

local_skill = Skill.from_path(str(skill_path))
agent_builder = DigitalEmployeeAgentBuilder().add_skills([local_skill])

This is the right choice when:

• You are developing a skill locally

• You want deterministic testing during development

• You do not want to push the skill to GitHub first

Skill Directory Structure

A skill is a directory. The directory name becomes the skill's identifier and must match the name field in SKILL.md.

.agents/skills/
└── haiku-standup/
    ├── SKILL.md          ← required
    └── references/       ← optional supporting files
        └── ...

SKILL.md format

SKILL.md uses YAML frontmatter followed by a markdown body:

---
name: haiku-standup
description: >
  Format daily standup updates into the team's custom standup template.
  Use when the user mentions "standup", "daily update", "what I did yesterday",
  or asks to format their work status.
metadata:
  version: 1.0.0
allowed-tools: read_file
---

# Haiku Standup Formatter

Format every standup update using the exact structure below...

Frontmatter fields

Field	Required	Description
name	Yes	Skill identifier. Must match directory name. Lowercase alphanumeric and hyphens only, max 64 characters.
description	Yes	Used in the system prompt to tell the model when to apply this skill. Max 1024 characters.
metadata.version	No	Optional version string for your own tracking.
allowed-tools	No	Space-separated list of tools the model may use when this skill is active.
license	No	Optional license identifier.
compatibility	No	Optional version compatibility constraint.

Name rules

• Lowercase alphanumeric characters only, separated by single hyphens

• Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$

• Maximum 64 characters

• Must exactly match the directory name

Remote GitHub Skills Example

The file examples/skills_example.py demonstrates the remote workflow.

1) Add the GitHub skill URL

skills = ["https://github.com/coreyhaines31/marketingskills/tree/main/skills/copywriting"]

agent_builder = DigitalEmployeeAgentBuilder().add_skills(skills)

2) Build the pipeline and Digital Employee

from digital_employee_core.digital_employee.builders.builder import DigitalEmployeeBuilder
from digital_employee_core.digital_employee.builders.pipeline_builder import DigitalEmployeePipelineBuilder

pipeline_builder = DigitalEmployeePipelineBuilder().add_step(agent_builder)

digital_employee = (
    DigitalEmployeeBuilder()
    .set_name("skills_github_assistant")
    .set_email("[e-mail]")
    .set_job(
        title="Skills-enabled Assistant - Example",
        description="A digital employee using remote skills from GitHub",
        instruction="You are a helpful assistant.",
    )
    .set_pipeline(pipeline_builder)
    .build()
)

3) Invoke the Digital Employee

import asyncio

message = "Write landing page copy for PulsePath."
result = asyncio.run(digital_employee.invoke(message=message, local=True))

Private GitHub repositories

For private repositories, provide one of these environment variables before running:

• GITHUB_PERSONAL_ACCESS_TOKEN

• GITHUB_TOKEN

• GH_TOKEN

The token is resolved in the order listed above.

Local Skills Example

The directory examples/local_skills/ demonstrates the local workflow.

1) Define the skill directory

Create a directory at .agents/skills/haiku-standup/ containing a SKILL.md:

---
name: haiku-standup
description: >
  Format daily standup updates into the team's custom standup template.
  Use when the user mentions "standup", "daily update", "what I did yesterday",
  or asks to format their work status.
---

# Haiku Standup Formatter

Format every standup update using the exact structure below. Never skip sections.
Never reorder them. Always generate the haiku — do not ask the user to write one.

## Output Template

```text
📋 STANDUP — [TODAY'S DATE in YYYY-MM-DD]

🎋 [A haiku summarizing the update — must be valid 5-7-5 syllable structure]

🔥 BLOCKER [PRIORITY-CODE]
[Blocker description — what it is and what it's blocking]
(If no blockers, write: "☁️ ALL CLEAR — No blockers today")

✅ DONE
- [Completed item 1]
- [Completed item 2]

🎯 TODAY
- [Planned item 1]
- [Planned item 2]

Vibe Check: [MOON-RATING] ([N]/5)
```

2) Load the local skill

from pathlib import Path
from glaip_sdk.skills import Skill

skill_path = Path(__file__).parent / ".agents/skills/haiku-standup"
local_skill = Skill.from_path(str(skill_path))

3) Build the agent and pipeline

from digital_employee_core.digital_employee.builders.agent_builder import DigitalEmployeeAgentBuilder
from digital_employee_core.digital_employee.builders.pipeline_builder import DigitalEmployeePipelineBuilder

agent_builder = DigitalEmployeeAgentBuilder().add_skills([local_skill])
pipeline_builder = DigitalEmployeePipelineBuilder().add_step(agent_builder)

4) Build the Digital Employee

from digital_employee_core.digital_employee.builders.builder import DigitalEmployeeBuilder

digital_employee = (
    DigitalEmployeeBuilder()
    .set_name("skills_local_assistant")
    .set_email("[e-mail]")
    .set_job(
        title="Local Skills Assistant",
        description="A digital employee using local skills for deterministic development",
        instruction="You are a helpful assistant that formats standup updates.",
    )
    .set_pipeline(pipeline_builder)
    .build()
)

5) Ivoke the Digital Employee

import asyncio

message = (
    "Standup: Yesterday I migrated the database schema and fixed the authentication bug. "
    "Today I'll work on the API documentation and start the performance optimization. "
    "No blockers right now, feeling pretty good about progress."
)

result = asyncio.run(digital_employee.invoke(message, local=True))
print(result["agent_response"])

What this example shows

• A local skill is loaded from a filesystem path using Skill.from_path(...)

• The skill folder must exist and contain SKILL.md before execution

• Local skills are run with invoke(..., local=True) — no deployment step required

Managing Skills at Runtime

After building a DigitalEmployeeAgent, you can modify its skills list:

# Add a single GitHub URL
agent.add_skills("https://github.com/org/repo/tree/main/skills/my-skill")

# Add multiple skills at once
agent.add_skills(["url-a", "url-b"])

# Add a local Skill object
agent.add_skills(local_skill)

# Remove a skill (matches by name or source)
agent.remove_skills(local_skill)
agent.remove_skills(["url-a", "url-b"])

add_skills() accumulates — it never replaces the existing list. remove_skills() with None or a non-existent skill is a no-op.

When to Use Which Approach

Use remote GitHub skills when

• Your skill definitions are stored in a GitHub repository

• You want centralized version control for skill content

• You want to share the same skill across multiple Digital Employees or environments

Use local skills when

• You are iterating on skill content locally

• You want quick testing without pushing to GitHub

• You need deterministic development loops or local-only experimentation

• You already have a local skill folder with a valid SKILL.md

Best Practices

1. Keep skills narrowly scoped

Write each skill for a specific job, such as copywriting or standup formatting, rather than combining many unrelated behaviors in one skill.

2. Write a precise description

The description field in SKILL.md is injected directly into the system prompt. The model uses it to decide when to activate the skill. Make it specific about the triggers that should activate the skill:

description: >
  Format daily standup updates into the team's custom standup template.
  Use when the user mentions "standup", "daily update", "what I did yesterday",
  or asks to format their work status.

3. Match the job instruction to the skill

Pair a general assistant instruction with an explicit hint when using local skills:

instruction="You are a helpful assistant that formats standup updates."

This helps the Digital Employee treat the skill as the primary behavior guide.

4. Validate the local path before running

Check that the skill path exists before loading it:

if not skill_path.exists():
    raise FileNotFoundError(f"Skill directory not found: {skill_path}")

local_skill = Skill.from_path(str(skill_path))

5. Keep SKILL.md instructions explicit

A strong skill file should clearly define:

• When the skill applies (the description field)

• The expected output structure

• Rules and constraints the model must follow

• What the model must infer versus what it must ask about

Troubleshooting

Local skill is not being found

Problem: Skill.from_path(...) raises an error or the skill is not loaded.

Solution:

• Verify the directory path is correct and exists

• Verify SKILL.md exists at the root of the skill directory (not in a subdirectory)

• Verify you are passing a string path: Skill.from_path(str(skill_path))

Skill name validation error

Problem: Skill fails to load with a name validation error.

Solution:

• Ensure the name field in SKILL.md frontmatter exactly matches the directory name

• The name must be lowercase alphanumeric with hyphens only: ^[a-z0-9]+(-[a-z0-9]+)*$

• Maximum 64 characters

Local skill does not behave as expected

Problem: The output ignores the intended format.

Solution:

• Make the instructions in SKILL.md more explicit

• Add stricter output templates and rules

• Ensure the description field contains the exact triggers that should activate this skill

• Ensure the employee instruction does not conflict with the skill behavior

Remote GitHub skill cannot be accessed

Problem: The Digital Employee cannot download the GitHub-based skill.

Solution:

• Verify the GitHub URL points to the correct skill directory (it should be a GitHub tree URL)

• If the repository is private, set GITHUB_PERSONAL_ACCESS_TOKEN, GITHUB_TOKEN, or GH_TOKEN

• Confirm your network can reach github.com