Deep Dive
Skills System
Skills are persistent, named instruction sets that the agent advertises at startup and fetches on demand. They survive across sessions, can be imported and exported as Markdown, and stack with project-specific overrides from AGENTS.md.
How Skills Work
Skills are named, persistent instruction sets stored in Raggie's SQLite database. They let the agent learn and retain knowledge across sessions without bloating the system prompt. Each role can have multiple skills, and the agent fetches the full content of a skill only when it needs it.
Startup Loading
When the agent starts, all skills for the current role are loaded from the database. But instead of dumping the full content into the system prompt, only brief one-line summaries are included:
# Available Skills (use GetSkill to fetch full content)
code/testing: Always write tests after implementing. Use pytest fixtures.
code/refactoring: When refactoring, preserve behavior. Extract small methods.
code/git-workflow: Write conventional commits. Branch naming: feat/, fix/, chore/. This approach means the system prompt stays lean. The LLM sees what skills are available without consuming thousands of tokens on instructions it may never need.
On-Demand Fetching
When the LLM decides a skill is relevant to the current task, it calls GetSkill with the skill name. The full markdown content of the skill is returned as a tool response, giving the agent detailed instructions for the task at hand.
The lifecycle of a skill
Advertise
At startup, skill summaries are injected into the system prompt. The LLM can see what's available without consuming the full content.
Recognize
The LLM encounters a task matching a skill's summary (e.g. writing tests triggers the testing skill).
Fetch
The LLM calls GetSkill("testing"). Raggie returns the full markdown content from the database.
Apply
The LLM follows the detailed skill instructions for the remainder of the task. The full skill content is now in its context.
The skill only needs to be fetched once per session. On subsequent prompts, the full content is already in the conversation history (as a tool call + tool response pair), so the LLM continues to have access to it.
Key Characteristics
The skills system is designed around a few core principles that make it lightweight, flexible, and safe.
Persistent
Skills survive across sessions. They are stored in the SQLite database alongside chat history, todo lists, and session state. Close the terminal, come back tomorrow, and all skills are still there.
Multiple per role
Each role can have many named skills. For example, the code role might have testing, refactoring, and git-workflow.
On-demand loading
Only summaries go into the system prompt. The full skill content is fetched via GetSkill only when the LLM decides it needs it. This saves tokens.
User-controlled
The SetSkill tool always asks for user consent before creating or modifying a skill. The agent cannot silently change its own instructions.
Override with AGENTS.md
Project-specific instructions in AGENTS.md are appended after skills in the system prompt. This means AGENTS.md can override skill instructions for project-specific conventions .; no need to create a skill just for one project.
Managing Skills
Skills are managed through the raggie skill CLI command. You can use an interactive menu for day-to-day management or CLI flags for scripting and automation.
CLI Flags for Scripting
For automation, CI/CD, or batch operations, use these flags instead of the interactive menu:
| Flag | Description |
|---|---|
--show |
Display all skills for the role. Use with --name to view a specific skill's full content |
--name <name> |
Specify the skill name. Required for --import-skill, --export-skill, and --delete |
--import-skill <file> |
Import a skill from a Markdown file into the database. Requires --name |
--export-skill <file> |
Export a skill from the database to a Markdown file. Requires --name |
--delete |
Delete a skill permanently. Requires --name |
--list-all |
List all skills across all roles. The role argument is not required with this flag |
Usage Examples
raggie skill code # interactive menu for role 'code'
raggie skill # interactive menu (all roles)
raggie skill code --show --name testing # show full content of 'testing' skill
raggie skill code --import-skill my-skills.md --name testing # import from file
raggie skill code --export-skill backup.md --name testing # export to file
raggie skill code --delete --name testing # delete a skill
raggie skill --list-all # list all skills across all rolesImport and Export Workflow
Skills are stored as Markdown in the database and can be imported from or exported to .md files. This makes skills portable: back them up, share them with your team, or version-control them alongside your code.
Export a Skill
Save a skill to a Markdown file. The file contains the full skill content as-is, ready to be shared or version-controlled.
raggie skill code --export-skill testing.md --name testingProduces a testing.md file with the skill's full content.
Import a Skill
Load a skill from a Markdown file into the database. If a skill with the same name already exists, it is overwritten.
raggie skill code --import-skill testing.md --name testingReads testing.md and stores it as a code/testing skill.
What a skill file looks like
A skill is just a Markdown file. The first line of the content is used as the summary shown in the system prompt. Here is an example:
# testing
Always write tests after implementing features. Use pytest with fixtures and parametrize.
## Requirements
- Every new function must have at least one test
- Use pytest fixtures for shared setup
- Use parametrize for edge cases
- Test files go in a tests/ directory mirroring the source tree
## Example
```python
import pytest
from src.users import get_user_by_id
def test_get_user_by_id():
user = get_user_by_id(1)
assert user.name == "Alice"
```How Skills Stack
At startup, the agent builds its system prompt by assembling several layers in a fixed order. Understanding this order helps you predict how instructions will interact.
Role System Prompt
The base system prompt file (e.g. coder_system_prompt.md). This defines the agent's core identity, tool usage rules, coding philosophy, and guardrails. This is the foundation .; everything else is layered on top.
Environment Context
Current date, working directory, and host system information (OS, kernel version, architecture). This gives the agent awareness of its runtime environment without hardcoding assumptions.
Skill Summaries
All skills for the current role, listed as role/name: one-line summary. These are brief advertisements .; the full content is only loaded when the LLM calls GetSkill. Multiple skills are listed in no guaranteed order.
AGENTS.md Override
If an AGENTS.md file exists in the project root, its contents are appended after everything else. Since LLMs typically give more weight to later instructions, AGENTS.md acts as a project-specific override. It can refine, extend, or contradict skill instructions for one-off project needs without modifying the skill itself.
Why this order matters
Skills are general; AGENTS.md is specific. A code/testing skill might say "always use pytest." But a specific project might use unittest. Rather than creating a one-off skill, drop an AGENTS.md with "Use unittest, not pytest for this project." The later position of AGENTS.md means it takes precedence.
Skill summaries are cheap. Each skill summary is a single line in the system prompt. Even with 10 skills, the overhead is negligible. The full content is only loaded when needed, keeping your token usage lean.
You can share skills across projects. Export a skill from one project, import it into another. The AGENTS.md in each project can customize behavior without altering the shared skill definition.
Token Impact
Here is how skills affect token usage at each stage:
| Stage | What's in context | Token cost |
|---|---|---|
| Startup | One-line summary per skill | ~10-20 tokens per skill. Negligible even with dozens of skills |
On GetSkill call |
Full skill content as tool response | As many tokens as the skill is long. Typical skills are 200-800 tokens |
| Subsequent prompts | Full skill content in conversation history | No additional cost. It's already in the context window |
SetSkill and GetSkill Tools
The agent interacts with skills through two dedicated tools. GetSkill fetches skill content on demand, and SetSkill lets the agent create or update skills .; with your explicit consent.
GetSkill
Fetches the full markdown content of a skill by name. If a description exists in the code index, it is prepended. Supports fuzzy search when an exact name match is not found.
GetSkill("testing") # fetch code/testing
GetSkill("git-workflow") # fetch code/git-workflowNo user consent required. This is a read-only operation.
SetSkill
Creates or updates a named skill for the agent's own role. The content is markdown-formatted instructions that extend the agent's behavior.
SetSkill("testing", "# testing\n\nAlways write tests...")Always requires user consent. A prompt is shown before the skill is applied.
The SetSkill Consent Flow
When the agent calls SetSkill, the tool halts execution and asks for your approval. This is a safety measure: the agent cannot silently modify its own instruction set.
The agent wants to create/update a skill:
Role: code
Name: testing
Content:
# testing
Always write tests after implementing features. Use pytest with fixtures.
============================================================
Allow this skill change? (y/n):If you approve, the skill is written to the database and immediately available (the system prompt is rebuilt on the next message). If you decline, the tool call fails and the agent must proceed without the skill.