feat: agent-specific skill loading instructions#44
Merged
RichardHightower merged 2 commits intomainfrom Jan 21, 2026
Merged
Conversation
- Add _generate_usage_template() for dynamic invocation commands
- Claude gets no --agent flag, all others include --agent {name}
- Agents with native_skill_support='none' get extended step-by-step guidance
- Add fallback directory search when --agent not specified
- Create LOAD_SKILLS.md reference document
- Add comprehensive tests for all new functionality (15 new tests)
The usage template in config files now dynamically generates the correct
invocation command based on the agent type:
- Claude (native_skill_support='all'): skilz read <skill-name>
- Other agents: skilz read <skill-name> --agent {agent_name}
Agents with native_skill_support='none' (Gemini, QWEN, Aider, etc.) also
receive extended step-by-step instructions to help them use skills.
The read command now implements fallback search across multiple agent
directories when --agent is not specified, searching in order:
claude -> universal -> gemini -> opencode -> codex
When --force-config is used, the usage template now includes extended step-by-step instructions regardless of the agent's native_skill_support setting. This is useful when: - Writing to config files for agents that don't natively understand skills - Using custom setups where extended guidance is helpful Also updated gemini_agent fixture to reflect current production config (native_skill_support='all') and added gemini_agent_no_native for testing. Added 4 new tests for force_extended behavior.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements agent-specific skill loading instructions in config files. The usage template now dynamically generates the correct invocation command based on the agent type.
Changes
config_sync.py_generate_usage_template()function for dynamic templatesconfig_sync.py_build_skills_section()and_merge_skill_into_section()with agent paramsconfig_sync.pyforce_extendedparameter for--force-configsupportinstaller.pyforce_configto sync functions for extended instructionsread_cmd.py--agentnot specifiedLOAD_SKILLS.mdAgent-Specific Behavior
skilz read <skill-name>(no --agent flag)skilz read <skill-name> --agent codexskilz read <skill-name> --agent opencodeskilz read <skill-name> --agent geminiskilz read <skill-name> --agent aider+ extended instructionsskilz read <skill-name> --agent qwen+ extended instructionsRule: Claude with
native_skill_support="all"gets no--agentflag. All others include--agent {name}.Extended Instructions: Agents with
native_skill_support="none"automatically get step-by-step guidance.Force Extended Instructions (--force-config)
When
--force-configis used, extended step-by-step instructions are included regardless of the agent'snative_skill_supportsetting. This is useful for:Example:
skilz install my-skill --agent gemini --force-config # GEMINI.md will include extended step-by-step instructionsFallback Search Order
When
skilz read <skill-name>is called without--agent:.claude/skills/first.skilz/skills/(universal).gemini/skills/.opencode/skills/.codex/skills/Test Plan