Organize skill reference files: separate examples and criteria
Translated from Korean. View original
As terminology lists and examples accumulate in a skill, its workflow can become hard to find. Keep the steps to follow in SKILL.md and move long reference tables and output examples into separate files. After splitting them, say both where they are and when they should be read.
What should I separate first?
Start with material that serves a different purpose from the workflow, such as multi-paragraph terminology tables, long examples or output templates. Splitting even two-line rules into separate files can create more places to search.
For a customer-notice editing skill, keep the editing sequence in the main file, put terminology in references/terms.md and output examples in examples/notice.md. These folder names are examples.
How should I arrange the folders?
Start with one instruction file and one reference file. Add examples or templates folders when you actually have material you revisit; there is no need to create every empty folder in advance.
- notice-edit
- SKILL.mdWorkflow and which material to read
- references
- terms.mdService terminology
- examples
- notice.mdBefore-and-after editing example
How should the body refer to files?
‘Reference material available’ does not say when to read it. Connect each reference to a step. Paths relative to the skill folder are easier to manage when moving it to another computer.
Example: ‘Before editing, read references/terms.md to check service and feature names. If you need an output format, consult examples/notice.md. Do not copy example dates or names into the new result.’
What belongs in an example?
Include both input and output so the change is visible. If the rule is to fix translated phrasing while preserving dates, a short example containing a date can demonstrate it.
Label it as an example and explain its role, such as ‘format reference only; do not reuse content,’ so fictional company names or numbers are not mixed into real work.
What should I check before moving or sharing?
Copying only SKILL.md may leave reference files behind. Check the whole skill folder and open the files it references. Also inspect paths containing your computer username and inaccessible internal links.
After splitting files, run a task in a new conversation. Check whether it identifies missing material and avoids copying example values into the new result.
- Relative paths in the body match actual files.
- All required reference files are included.
- Examples and real work material are distinguished.
- No information that cannot be shared is included.
Frequently asked questions
Q. Is the folder name references required? A. It is used here to distinguish reference material. Follow your tool or skill format's requirements if there are any.
Q. Does splitting files automatically reduce reading? A. You also need to specify when and under what conditions to read them. Requiring every reference file on every task reduces the benefit.