Skip to content

[pull] main from Kilo-Org:main #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pull merged 2 commits into from
Jan 24, 2026
Merged

[pull] main from Kilo-Org:main #131

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a2272c9
docs: clarify how skills are loaded and used
markijbema Jan 22, 2026
e7ee725
Merge pull request #5320 from Kilo-Org/mark/docs-skills-clarification
lambertjosh Jan 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 23 additions & 9 deletions apps/kilocode-docs/docs/agent-behavior/skills.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,19 @@ Skills can be:

The workflow is:

1. **Discovery**: Skills are scanned from designated directories when Kilo Code initializes
2. **Activation**: When a mode is active, relevant skills are included in the system prompt
3. **Execution**: The AI agent follows the skill's instructions for applicable tasks
1. **Discovery**: Skills are scanned from designated directories when Kilo Code initializes. Only the metadata (name, description, and file path) is read at this stage—not the full instructions.
2. **Prompt inclusion**: When a mode is active, the metadata for relevant skills is included in the system prompt. The agent sees a list of available skills with their descriptions.
3. **On-demand loading**: When the agent determines that a task matches a skill's description, it reads the full `SKILL.md` file into context and follows the instructions.

### How the Agent Decides to Use a Skill

The agent (LLM) decides whether to use a skill based on the skill's `description` field. There's no keyword matching or semantic search—the agent evaluates your request against all available skill descriptions and determines if one "clearly and unambiguously applies."

This means:

- **Description wording matters**: Write descriptions that match how users phrase requests
- **Explicit invocation always works**: Saying "use the api-design skill" will trigger it since the agent sees the skill name
- **Vague descriptions lead to uncertain matching**: Be specific about when the skill should be used

## Skill Locations

Expand Down Expand Up @@ -125,10 +135,8 @@ description: A brief description of what this skill does and when to use it

Your detailed instructions for the AI agent go here.

These instructions will be included in the system prompt when:

1. The skill is discovered in a valid location
2. The current mode matches (or the skill is generic)
The agent will read this content when it decides to use the skill based on
your request matching the description above.

## Example Usage

Expand Down Expand Up @@ -264,18 +272,24 @@ You can discover and install community-created skills through:

4. **Check file location**: Ensure `SKILL.md` is directly inside the skill directory, not nested further.

### Verifying a Skill is Activated
### Verifying a Skill is Available

To confirm a skill is properly loaded and available to the agent, you can ask the agent directly. Simply send a message like:

- "Do you have access to skill X?"
- "Is the skill called X loaded?"
- "What skills do you have available?"

The agent will respond with information about whether the skill is loaded and accessible. This is the most reliable way to verify that a skill has been activated after adding it or reloading VSCode.
The agent will respond with information about whether the skill is loaded and accessible. This is the most reliable way to verify that a skill is available after adding it or reloading VSCode.

If the agent confirms the skill is available, you're ready to use it. If not, check the troubleshooting steps above to identify and resolve the issue.

### Checking if a Skill Was Used

To see if a skill was actually used during a conversation, look for a `read_file` tool call in the chat that targets a `SKILL.md` file. When the agent decides to use a skill, it reads the full skill file into context—this appears as a file read operation in the conversation.

There's currently no dedicated UI indicator showing "Skill X was activated." The `read_file` call is the most reliable way to confirm a skill was used.

### Common Errors

| Error | Cause | Solution |
Expand Down