Skill Best Practices

General Best Practices

Single Responsibility

A skill should do one thing well. If a skill requires multiple distinct steps, consider splitting it into smaller skills that can be composed together. A good skill reads like a focused recipe, not a manual.

Write a Clear Description

The description is how agents and users discover your skill. Write in third person, lead with what it does, then explain when to use it. Front-load the key use case.

Define Clear Inputs and Outputs

• Document what variables the skill expects, their types, and which are required.
• Specify the output format explicitly — JSON, plain text, or structured sections.
• Provide default values for optional inputs to prevent empty context reaching the LLM.

Design for Composability

Good skills work standalone but compose well with others. Keep inputs and outputs generic enough that other prompts or workflows can use them without transformation.

Naming Conventions

• Use kebab-case: extract-email-data, classify-ticket
• Use action-oriented names that describe the outcome: summarize-document, not document-helper
• Avoid vague names like utils, helper, or tools

Handle Edge Cases Gracefully

Tell the model what to do when input is missing, ambiguous, or unexpected. A skill should return a useful response even with imperfect input, rather than failing silently.

Common Mistakes to Avoid

• Mega-skills — Encoding all behavior in one monolithic skill instead of composing focused ones.
• Vague descriptions — Descriptions that don't help agents decide when to use the skill.
• Missing defaults — Not providing defaults for optional variables, causing empty sections in the rendered output.
• Untested with real data — Skills that work with clean demo inputs but break with actual user inputs.

PDK Best Practices

Use the Flat Editor Effectively

Skills use a single-input editor (no roles). Write the complete instruction as one coherent block. Structure it with clear sections using headings or markers.

You are an email classifier.

Given the following email, return a JSON object with:
- category: one of "support", "sales", "billing", "other"
- sentiment: one of "positive", "neutral", "negative"
- urgency: one of "low", "medium", "high"

Email:
{{email_body}}

Use Typed Variables with Defaults

Every variable should have a type and a sensible default. This makes the skill robust when used in pipelines where some inputs may not be provided.

{{email_body:text}}
{{output_format:text ?? "json"}}
{{language:text ?? "English"}}

Use Conditionals for Flexibility

Use [#IF] blocks to adapt skill behavior based on input without creating separate skills for each variation.

Classify the following text.

[#IF {{include_reasoning}} #equals(true)]
First explain your reasoning step by step, then provide the classification.
[ELSE]
Return only the classification, no explanation.
[END IF]

Text: {{input_text}}

Extract Reusable Sections

If multiple skills share common instructions (output format rules, tone guidelines), extract them into [#SECTION] blocks.

[#SECTION name="json_output_rules"]
Return valid JSON only. No markdown fences. No explanation outside the JSON object.
[END SECTION]

Classify this email:
{{email_body}}

[#INCLUDE json_output_rules]

Set Appropriate Model Configuration

Skills often need specific model settings. Use the Meta tab to pin the model and temperature so the skill behaves consistently regardless of who calls it.

provider: openai
model: gpt-4o-mini
temperature: 0.1
maxTokens: 512

Test with Edge Cases

Test your skill with empty inputs, very long text, special characters, and unexpected formats. Use the Eval system to create a regression test suite so changes don't break existing behavior.