Skill

This docs was updated at: 2026-03-21

com.paragon.skills.Skill  ·  Class

---

Represents a modular expertise that augments an agent's capabilities.

A Skill packages instructions and resources that the agent can access on demand via the SkillReaderTool. When skills are added to an agent, a concise catalog (name + description) appears in the system prompt, and a read_skill tool is registered so the agent can load full instructions when it decides a skill is relevant.

Unlike sub-agents, skills share the main agent's context window. They extend the agent's capabilities without creating separate execution contexts.

Usage Examples

Via Code

Skill pdfSkill = Skill.builder()
    .name("pdf-processor")
    .description("Process PDF files, extract text, fill forms")
    .instructions("""
        You are a PDF processing expert. When working with PDFs:
        1. Analyze the document structure
        2. Extract or modify content as requested
        3. Return well-formatted results
        """)
    .build();

Simple Factory

Skill skill = Skill.of(
    "greeting",
    "Generate personalized greetings",
    "You create warm, personalized greetings..."
);

Integration with Agents

Agent agent = Agent.builder()
    .name("DocumentAssistant")
    .instructions("You help users with document tasks.")
    .addSkill(pdfSkill)  // Skill instructions are added to agent's prompt
    .responder(responder)
    .build();

See Also

• SkillProvider
• SkillStore

Since: 1.0

Methods

builder

public static @NonNull Builder builder()

Creates a new Skill builder.

Returns

a new builder instance

---

of

public static @NonNull Skill of(
      @NonNull String name, @NonNull String description, @NonNull String instructions)

Creates a simple Skill with name, description, and instructions.

Parameters

Name	Description
name	the skill name (lowercase, numbers, hyphens)
description	when to use this skill
instructions	the skill's instructions

Returns

a new Skill instance

---

of

public static @NonNull Skill of(
      @NonNull String name, @NonNull String description, @NonNull Prompt instructions)

Creates a simple Skill with name, description, and instructions.

Parameters

Name	Description
name	the skill name (lowercase, numbers, hyphens)
description	when to use this skill
instructions	the skill's instructions as a Prompt

Returns

a new Skill instance

---

name

public @NonNull String name()

Returns the skill's unique name.

Returns

the skill name

---

description

public @NonNull String description()

Returns the skill's description.

This description helps the LLM understand when to apply this skill's expertise.

Returns

the skill description

---

instructions

public @NonNull Prompt instructions()

Returns the skill's instructions.

These instructions are injected into the agent's system prompt.

Returns

the skill instructions

---

resources

public @NonNull Map<String, Prompt> resources()

Returns additional resources (context files) for this skill.

Resources are named Prompts that provide supplementary context. For example, a PDF skill might have a "FORMS.md" resource with form-filling guidance.

Returns

unmodifiable map of resource name to content

---

hasResources

public boolean hasResources()

Returns whether this skill has any additional resources.

Returns

true if the skill has resources

---

toPromptSection

public @NonNull String toPromptSection()

Generates the prompt section for this skill.

This produces a formatted text block that can be appended to an agent's system prompt. The format includes the skill name, description, instructions, and any resources.

Returns

the formatted skill prompt section

---

toCatalogEntry

public @NonNull String toCatalogEntry()

Generates a concise catalog entry for this skill.

This produces a single-line summary suitable for listing in the agent's system prompt. The agent can then call the read_skill tool to load full instructions when needed.

Returns

a concise catalog line (e.g., "- **pdf-processor**: Process PDF files\n")

---

name

public @NonNull Builder name(@NonNull String name)

Sets the skill's unique name.

Must contain only lowercase letters, numbers, and hyphens. Maximum 64 characters.

Parameters

Name	Description
name	the skill name

Returns

this builder

---

description

public @NonNull Builder description(@NonNull String description)

Sets the skill's description.

This should explain what the skill does and when to use it. Maximum 1024 characters.

Parameters

Name	Description
description	the skill description

Returns

this builder

---

instructions

public @NonNull Builder instructions(@NonNull Prompt instructions)

Sets the skill's instructions.

Parameters

Name	Description
instructions	the instructions as a Prompt

Returns

this builder

---

instructions

public @NonNull Builder instructions(@NonNull String instructions)

Sets the skill's instructions.

Parameters

Name	Description
instructions	the instructions as a string

Returns

this builder

---

addResource

public @NonNull Builder addResource(@NonNull String name, @NonNull Prompt content)

Adds a resource (additional context file) to the skill.

Parameters

Name	Description
name	the resource name (e.g., "FORMS.md")
content	the resource content

Returns

this builder

---

addResource

public @NonNull Builder addResource(@NonNull String name, @NonNull String content)

Adds a resource (additional context file) to the skill.

Parameters

Name	Description
name	the resource name (e.g., "FORMS.md")
content	the resource content as a string

Returns

this builder

---

build

public @NonNull Skill build()

Builds the Skill instance.

Returns

the configured Skill

Throws

Type	Condition
NullPointerException	if required fields are missing
IllegalArgumentException	if validation fails