tkr-skill-writer

TKR Skill Writer

Description and Goals

This skill provides guidelines and templates for creating well-structured skills that follow consistent patterns in this repository while staying aligned with the current Codex skill guide. Skills should be clear, discoverable, and provide actionable guidance for developers.

Goals

• Standardize skill structure across all skills in the repository
• Ensure skills are discoverable and easy to navigate
• Provide clear "when to use" guidance for each skill
• Maintain consistent reference file organization
• Keep repo conventions separate from actual Codex requirements
• Include optional Codex metadata when it improves discovery and presentation
• Enable efficient skill creation and maintenance

What This Skill Should Do

When creating or updating a skill, this skill guides you to:

1. Start from the official minimum:

   • A skill folder with a SKILL.md file
   • Frontmatter with name and description
   • Instructions that explain exactly when the skill should trigger

2. Apply this repo's preferred structure:

   • Description and Goals
   • What This Skill Should Do
   • Information About the Skill (with subcategories)

3. Create reference files that are:

   • One level deep from SKILL.md (e.g., references/filename.md)
   • Use relative paths from the skill root
   • Avoid deeply nested reference chains

4. Organize component/system references in tables with:

   • Component/System name as a clickable link: [ComponentName](references/componentname.md)
   • "When to Use" descriptions that clearly explain when to load each reference

5. Add optional metadata when useful:

   • Create agents/openai.yaml for UI metadata in the Codex app
   • Set interface.display_name, short_description, icon_small, icon_large, and brand_color
   • Add interface.default_prompt only when a starter prompt will improve skill discoverability or invocation clarity
   • Add policy or dependencies only when the skill genuinely needs them