didactyl/plans/remove_role_markers_from_skills.md

Remove Role Markers from Skill Content

Summary

Skill content should always be system-role instructions — pure markdown. The system:, user:, and assistant: role markers should not appear in skill content authored by users or the LLM agent.

The runtime already handles user: injection internally (appending the DM message or trigger event as the user message). Skill authors writing user: in their content is either redundant or creates conflicts (double user: markers).

What Changes

Principle

• Skill content = system instructions. Always. No role markers.
• The runtime owns role assignment. It injects user: before the actual input (DM, trigger event).
• context_roles_split() stays — the runtime still uses it internally to split the assembled markdown (which includes the runtime-injected user: marker) into API messages.

Files to Change

Documentation

File	Change
docs/SKILLS.md	Remove role markers from skill content spec and examples. Clarify that skill content is always system instructions.
docs/CONTEXT.md	Clarify that user: is injected by the runtime, not by skill authors. Update examples.
docs/TOOLS.md	Remove role marker references from skill_create and skill_edit descriptions.

Source Code

File	Change
src/tools/tools_schema.c	Remove role marker references from skill_create and skill_edit tool descriptions and parameter descriptions.
src/context_roles.c	No change — still needed for runtime-level user: splitting.
src/context_roles.h	No change.
src/agent.c	No change — already injects user: correctly.

Web Pages

File	Change
~/lt/client-ndk/www/skills-edit.html	Remove system:/user:/assistant: syntax highlighting from the editor overlay. Update placeholder text.

Plans (historical docs, lower priority)

File	Change
plans/skills_edit_page.md	Remove role marker references from content description and highlighting spec.
plans/markdown_context_window.md	Update role marker section to clarify runtime-only usage.
plans/example_context.md	Update examples to show skill content without role markers.
plans/example_context_v2.md	Update examples to show skill content without role markers.
plans/skills_demo_page.md	Update template examples to remove system:/user: from skill templates.

What Does NOT Change

• context_roles_split() — The runtime still assembles a full markdown string with user: injected at the boundary, then splits it. This is an internal runtime mechanism, not a skill authoring concern.
• skills-tv.html — This is a separate client-side execution model that builds its own messages array. It can keep its system:/user: template format since it is not going through the Didactyl agent. However, it could be simplified later.
• DM history — Already uses proper role assignment in the messages array, not role markers.

Detailed Changes

docs/SKILLS.md

Before:

{
  "content": "system:\n## Spelling and Grammar Checker\n\nYou are a spelling and grammar checker.\n\n### Rules\n...\n\nuser:\n{{message}}"
}

After:

{
  "content": "## Spelling and Grammar Checker\n\nYou are a spelling and grammar checker.\n\n### Rules\n..."
}

Remove the bullet points about role markers. Add a note:

Skill content is always system-role instructions. The runtime handles user message injection (DM content, trigger events) automatically. Do not include system:, user:, or assistant: markers in skill content.

src/tools/tools_schema.c

skill_create description — Remove "use role markers (system:/user:/assistant:) at line start when needed; unmarked content defaults to system."

Replace with: "Write content as markdown system instructions. The runtime handles user message injection. Prefer ## for top-level sections."

skill_create content param — Remove "May include role markers at line start (system:/user:/assistant:)"

Replace with: "Markdown system instructions for the skill. May include markdown headings/lists/code fences and template variables."

Same pattern for skill_edit.

skills-edit.html

Remove the .hl-role CSS class and the regex that highlights system:, user:, assistant: in the editor overlay. Update the textarea placeholder from system:\nYou are...\n\nuser:\n{{message}} to just ## My Skill\n\nYou are a helpful assistant.\n\nRespond to {{message}} with....