tomkrikorian/visionosagents/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

1. Apply this repo's preferred structure:

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

1. 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

1. 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

1. 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

1. Follow consistent formatting:

• Use markdown links for file references
• Keep tables readable and scannable
• Provide clear, actionable descriptions

Information About the Skill

Skill Structure Template

Every SKILL.md must satisfy the official minimum format. In this repo, the preferred structure is the three-section layout below:

skill-name/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── assets/
│   └── logo.svg
└── references/
    └── reference.md

---
name: skill-name
description: Brief description of what the skill does and when to use it.
---
 
# Skill Name
 
## Description and Goals
 
[Description of the skill, its purpose, and goals]
 
### Goals
 
-Goal 1
-Goal 2
-Goal 3
 
## What This Skill Should Do
 
[Clear explanation of what the skill accomplishes and how it should be used]
 
## Information About the Skill
 
### Core Concepts
 
[Important concepts and principles]
 
### Reference Tables
 
[Tables organizing references with clickable links and "When to Use" descriptions]
 
### Implementation Patterns
 
[Code examples and patterns]
 
### Pitfalls and Checks
 
[Common mistakes and things to watch for]

File Reference Guidelines

• Use relative paths from the skill root directory
• Keep references one level deep: references/filename.md
• Avoid nested chains: Don't create references that point to other references that point to more references
• Use markdown links: [ComponentName](references/componentname.md)

Optional Metadata

Codex supports optional skill metadata in agents/openai.yaml. Use it when the skill benefits from a polished display name, icon, short description, brand color, invocation policy, or declared tool dependencies.

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "../assets/small-logo.svg"
  icon_large: "../assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"
 
policy:
  allow_implicit_invocation: false
 
dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

Use policy and dependencies only when they materially improve the skill. Do not add them by default just because the fields exist.

Table Format

Reference tables should use this format:

| Component | When to Use |
|-----------|-------------|
| [`ComponentName`](references/componentname.md) | Clear description of when to use this component. |

Reference File Naming

• Component files: {name}component.md (e.g., modelcomponent.md)
• System files: system.md (consolidate all system info in one file)
• Other references: Use descriptive, lowercase names with hyphens

Best Practices

• Keep "When to Use" descriptions concise but informative
• Group related components/systems into logical categories
• Provide code examples in implementation patterns sections
• Document common pitfalls and how to avoid them
• Update the skill description in the frontmatter to match the content
• Keep each skill focused on one job
• Prefer instructions over scripts unless deterministic tooling is required
• Write imperative steps with explicit inputs and outputs
• Test prompts against the skill description to confirm the trigger behavior is correct
• Use $skill-creator first when you want a starting point from the official Codex workflow
• Treat repo-specific layout rules as conventions, not as requirements imposed by Codex itself