Skills

Load more instructions, depending on the goal (Progressive Prompt Enhancement)

Skills are reusable instructions that your agents can load on-demand. Unlike prompts which are always included in your agent's context, skills are only retrieved when the agent decides they're needed. This makes skills perfect for specialized knowledge, detailed procedures, or domain expertise that you don't want cluttering every single run.

Creating Skills

Skills are created at the project level, and can be used by any task within that project.

To create a new skill, navigate to the "Skills" page in your project sidebar and click "New Skill".

You'll be prompted to provide:

• Name: An identifier for the skill. Only allows lower case letters, numbers and hyphens.

• Description: A clear explanation of what the skill does and when to use it

• Instructions: The markdown-formatted instructions that will be loaded when the agent calls this skill.

Write Clear Descriptions

The skill description is what the model sees when deciding whether to use a skill. Make it specific and actionable:

• Poor: "SQL help"

• Better: "Write and optimize SQL queries for PostgreSQL"

• Best: "Generates SQL queries for PostgreSQL with proper joins, filtering, and performance optimization. Use when user requests data retrieval, filtering, or analysis from a database."

Using Skills

Once you've created skills, you can make them available to your agents through run configurations.

Adding Skills to Run Configurations

On the "Run" screen, under the "Skills" section in Advanced, you'll see all available skills in your project. Select the skills you want to make available to the agent for this run.

How Agents Use Skills

When you make skills available to an agent, here's what happens:

1. Discovery: The agent sees all available skill names and descriptions at the end of its system prompt.

2. Decision: The agent decides which skills (if any) are relevant to the current task.

3. Loading: When the agent needs a skill, it calls the skill() tool with the skill's name.

4. Execution: The skill's full instructions are loaded into the conversation, and the agent proceeds with the task.

This lazy-loading approach means your agent's context stays clean and focused. Specialized instructions are only retrieved when actually needed.

Model Behavior

The model may or may not choose to use the skills you provide. If you find the model is not using a skill when you feel it should, try:

1. Making the skill description more specific and actionable

2. Updating your prompt to explicitly mention when certain skills should be used

3. Ensuring the skill name clearly indicates its purpose

4. Using a more modern model: models that came out before Agent Skills were released have not seen skills in their training data, and are less likely to leverage them.

Viewing Skill Usage

When viewing a run trace, you can see which skills the agent loaded in the "All Messages" section. Skill calls appear as tool invocations, showing when and how the agent used each skill.

Reference Files

Skills can include reference files—additional markdown documents that provide supporting information, which are also only retrieved when the agent decides they're needed. References are useful for:

• Detailed technical specifications

• Code examples or templates

• Domain knowledge or terminology

• Style guides or formatting rules

Adding References

Currently, references are managed through the file system. To add references to a skill:

1. Navigate to your project's skills directory

2. Find the skill's folder (named after the skill ID)

3. Create a references folder if it doesn't exist

4. Add markdown files (.md) to the references folder

5. Reference the new file from your main SKILL.md file (see details below).

Your skill structure should look like:

skills/
  <skill_id>/
    skill.kiln           # Metadata (name, description, etc.)
    SKILL.md             # Main skill instructions
    references/          # Additional reference files
      API_RESPONSE_FORMAT.md
      STYLE_GUIDE.md
      ...

Referencing from SKILL.md

Within your skill instructions (in SKILL.md), you should reference files using markdown link syntax. This is how the agent can discover reference files. Example:

## Instructions

Follow our company's coding standards. See our [style guide](references/STYLE_GUIDE.md) for details.

When generating API responses, use the format specified in this [API format guide](references/API_RESPONSE_FORMAT.md).

Skills vs Tools vs Subtasks

Kiln offers three ways to extend your agent's capabilities. Here's how to choose:

Feature	Skills	Tools	Subtasks
Primary Use	Instructions & knowledge	External actions	Complex workflows
Context Impact	Details loaded only when needed. Only description injected into prompt.	Tool definitions often much more verbose than skills descriptions	Isolated per subtask
Progressive Disclosure	Yes - can link to reference files, forming a nested hierarchy of knowledge	No	No
Best For	Guidelines, procedures, rules	APIs, databases	Multi-agent patterns
Setup Complexity	Low	Medium	High

Skills vs Search Tools (RAG)

Skills can also be compared to RAG. Both have pros and cons for adding knowledge to a system:

Feature	Skills	RAG
Max Documents	Typically <50	Unlimited
Context Impact	Low: ~100 tokens per document for name and description.	Very Low: 1 tool definition for all documents.
Chunking	Manually create skills and reference files.	Automatic chunking of larger docs.
Control	High: define the exact skill and reference file content. Descriptions can prompt the agent exactly when to load each skill.	Low: documents are automatically chunked (split) and indexed. The agent needs to guess search terms to find relevant information.
Deployment Complexity	Low: no additional effort if your toolchain supports it (like Kiln SDK).	High: requires vector database hosting, and jobs to process and index documents.
Progressive Disclosure	Yes - can link to reference files, forming a nested hierarchy of knowledge	Yes - can muli-hop.

Best Practices

Write Specific, Actionable Descriptions

Your skill descriptions are the primary signal the model uses to decide when to use a skill. Make them clear and specific:

• ✅ "Validates JSON schemas against the OpenAPI 3.0 specification and reports errors"

• ❌ "JSON validator"

Keep Skills Focused

Each skill should have a single, clear purpose. If you find a skill becoming too broad, consider splitting it into multiple focused skills, or splitting the skill into reference files.

Test Your Skills

After creating a skill, test it by:

1. Creating a run configuration with the skill enabled

2. Running your task with inputs that should trigger the skill

3. Checking the trace to verify the skill was loaded and used correctly

Managing Skills

Editing / Cloning Skills

We don't allow editing skills, as historical eval scores and dataset runs become would become misleading if edited, with no versioning to tell you what changed.

Instead, Kiln lets you clone a skill, giving you a fresh copy to modify while keeping the original intact so existing results stay valid.

Archiving Skills

If you have skills you no longer use but want to keep for reference, you can archive them. Archived skills won't appear in the skills dropdown and won't be available to agents. Unarchiving restores them to active use.