Skip to main content

Skill System

Overview​

Skill is a CRD (Custom Resource Definition) that provides on-demand capabilities and tools to AI Agents. Instead of loading all instructions into the system prompt, Skills are loaded dynamically when the LLM determines they are needed.

Why Skills?​

  • Token Efficiency: Only load detailed instructions when needed, reducing context window usage
  • Modularity: Package related prompts and tools together as reusable units
  • Extensibility: Add new capabilities without modifying core agents

Skill Relationship with Other CRDs​

Ghost.spec.skills[] β†’ references Skill names
     ↓
Bot (ghostRef) β†’ inherits skills from Ghost
     ↓
Team (members[]) β†’ Bot skills available in tasks
     ↓
Task execution β†’ LLM calls load_skill() on demand

Key Points:

  • Skills are referenced by name in Ghost.spec.skills[]
  • A Ghost can have multiple skills
  • Skills can be user-private or public
  • Lookup priority: user-private Skills first, then public Skills

Skill Package Structure​

Skills are uploaded as ZIP packages containing:

skill-package.zip
β”œβ”€β”€ SKILL.md          # Required: Metadata + prompt content
└── *.py              # Optional: Additional tool modules

SKILL.md Format​

The SKILL.md file uses YAML frontmatter for metadata and markdown body for the prompt content:

---
description: "Brief description - used by LLM to decide when to load"
displayName: "Human-readable name"
version: "1.0.0"
author: "Author Name"
tags: ["tag1", "tag2"]
bindShells: ["Chat", "ClaudeCode"]  # Compatible shell types
---

# Skill Prompt Content

Detailed instructions that will be injected into system prompt
when the skill is loaded by the LLM...

Metadata Fields​

FieldRequiredDescription
descriptionYesBrief description for LLM to decide when to load
displayNameNoHuman-readable name for UI display
versionNoSemantic version number
authorNoAuthor name
tagsNoTags for categorization
bindShellsNoCompatible Shell types (e.g., "Chat", "ClaudeCode")

Skill Workflow​

  1. Create Skill: User uploads a ZIP package containing SKILL.md
  2. Configure Association: Add skill name to Ghost.spec.skills[]
  3. Runtime Loading:
    • When task starts, skill metadata (name and description) is injected into system prompt
    • LLM decides whether to load a skill based on user request
    • Calls load_skill() tool to load the full skill prompt
  4. Update/Delete: Upload new version or delete (must remove Ghost references first)

Best Practices​

Creating Skills​

  1. Write clear descriptions - The description is used by LLM to decide when to load, should be concise and clear
  2. Keep prompts focused - Each skill should have a single, well-defined purpose
  3. Use appropriate bindShells - Specify which Shell types are compatible
  4. Version your skills - Use semantic versioning for tracking changes

For more information, see the AGENTS.md development guide.