Skip to content

Commit 1887784

Browse files
authored
new skill em-dash (#2042)
* new skill em-dash * codespell: resolve error * codespell: resolve error * manually apply suggestions from code review
1 parent 348732b commit 1887784

2 files changed

Lines changed: 235 additions & 0 deletions

File tree

docs/README.skills.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
153153
| [editorconfig](../skills/editorconfig/SKILL.md)<br />`gh skills install github/awesome-copilot editorconfig` | Generates a comprehensive and best-practice-oriented .editorconfig file based on project analysis and user preferences. | None |
154154
| [ef-core](../skills/ef-core/SKILL.md)<br />`gh skills install github/awesome-copilot ef-core` | Get best practices for Entity Framework Core | None |
155155
| [efcore-d2-db-diagram](../skills/efcore-d2-db-diagram/SKILL.md)<br />`gh skills install github/awesome-copilot efcore-d2-db-diagram` | Generate D2 database diagrams from Entity Framework Core models. USE FOR: EF Core database diagram, Entity Framework Core ERD, DbContext diagram, C# entity relationship diagram, PostgreSQL schema visualization, generate .d2 file from EF Core entities, Fluent API mapping diagram, migrations-based database diagram, table relationships, owned types, many-to-many join tables, indexes and constraints. DO NOT USE FOR: runtime debugging, database migration execution, schema deployment, SQL performance tuning, or draw.io diagrams. | `references/d2-erd-style.md`<br />`references/efcore-model-extraction.md`<br />`references/grouping-modes.md`<br />`references/quality-gate.md`<br />`references/relationship-rules.md` |
156+
| [em-dash](../skills/em-dash/SKILL.md)<br />`gh skills install github/awesome-copilot em-dash` | Expert on the history, origin, and correct use of the em dash. Use when writing or reviewing code, comments, or data files to avoid em and en dashes, defaulting to never using them and replacing any found with a hyphen (-). Includes strong knowledge of punctuation marks and the proper usage of punctuation characters when writing comments. | None |
156157
| [email-drafter](../skills/email-drafter/SKILL.md)<br />`gh skills install github/awesome-copilot email-drafter` | Draft and review professional emails that match your personal writing style. Analyzes your sent emails for tone, greeting, structure, and sign-off patterns via WorkIQ, then generates context-aware drafts for any recipient. USE FOR: draft email, write email, compose email, reply email, follow-up email, analyze email tone, email style. | None |
157158
| [entra-agent-user](../skills/entra-agent-user/SKILL.md)<br />`gh skills install github/awesome-copilot entra-agent-user` | Create Agent Users in Microsoft Entra ID from Agent Identities, enabling AI agents to act as digital workers with user identity capabilities in Microsoft 365 and Azure environments. | None |
158159
| [eval-driven-dev](../skills/eval-driven-dev/SKILL.md)<br />`gh skills install github/awesome-copilot eval-driven-dev` | Improve AI application with evaluation-driven development. Define eval criteria, instrument the application, build golden datasets, observe and evaluate application runs, analyze results, and produce a concrete action plan for improvements. ALWAYS USE THIS SKILL when the user asks to set up QA, add tests, add evals, evaluate, benchmark, fix wrong behaviors, improve quality, or do quality assurance for any Python project that calls an LLM model. | `references/1-a-project-analysis.md`<br />`references/1-b-entry-point.md`<br />`references/1-c-eval-criteria.md`<br />`references/2a-instrumentation.md`<br />`references/2b-implement-runnable.md`<br />`references/2c-capture-and-verify-trace.md`<br />`references/3-define-evaluators.md`<br />`references/4-build-dataset.md`<br />`references/5-run-tests.md`<br />`references/6-analyze-outcomes.md`<br />`references/evaluators.md`<br />`references/runnable-examples`<br />`references/testing-api.md`<br />`references/wrap-api.md`<br />`resources` |

skills/em-dash/SKILL.md

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
---
2+
name: em-dash
3+
description: 'Expert on the history, origin, and correct use of the em dash. Use when writing or reviewing code, comments, or data files to avoid em and en dashes, defaulting to never using them and replacing any found with a hyphen (-). Includes strong knowledge of punctuation marks and the proper usage of punctuation characters when writing comments.'
4+
---
5+
6+
# em dash
7+
8+
The **em dash** (U+2014, `\u2014`; not the hyphen-minus `-`) is the longest
9+
of the standard dashes, and is the Swiss Army knife of punctuation. Its history
10+
is a fascinating journey from handwritten manuscripts to mechanical
11+
constraints, literary rebellion, and modern digital dominance.
12+
13+
Here is a breakdown of how the em dash evolved:
14+
15+
## History of the em dash
16+
17+
### Early Beginnings (15th-18th Century)
18+
19+
- The First Dashes: Early appearances of the dash in English literature date
20+
back to 1580 in private letters and 1588 in English drama. They were often
21+
used to indicate pauses, self-interruption, or an unfinished thought
22+
- Gutenberg and Early Printing: The em dash officially emerged as a standardized
23+
typesetting mark during the 15th-century printing revolution
24+
25+
#### The Etymology
26+
27+
- The "M" Width: The em dash is named because its standard length is equal to
28+
the width of the capital letter "M" in the specific typeface being used
29+
(Similarly, the slightly shorter en dash is the width of the letter "N")
30+
31+
### Literary Popularity (17th-19th Century)
32+
33+
- The Author's Tool: By the 17th and 18th centuries, it became a beloved tool
34+
for writers mimicking the natural lurches, stutters, and rhythms of speech
35+
- Dickinson Dashes: In the 19th century, poets like Emily Dickinson famously
36+
used the em dash for emotional weight, rhythm, and to invite reader
37+
interpretation. This became so synonymous with her work that they are often
38+
informally called "Dickinson Dashes"
39+
40+
### The Typewriter Era (19th-20th Century)
41+
42+
- The Double-Hyphen Compromise: When typewriters were introduced, they lacked
43+
a dedicated key for the em dash. To compensate, typists began using two
44+
consecutive hyphens (--)
45+
- The No-Space Rule: Because of this mechanical compromise, a stylistic
46+
convention of typing the mark without surrounding spaces emerged and remains
47+
48+
### The Digital Age (Present Day)
49+
50+
- Return to Form: Modern digital typesetting and word processing programs have
51+
restored the true, unbroken em dash
52+
- **Modern Renaissance**: The em dash is experiencing a resurgence of popularity
53+
- It has become a hallmark of modern long-form prose and is also a favorite,
54+
heavily used punctuation mark in AI outputs, which often prioritize a
55+
conversational, stream-of-consciousness style
56+
57+
#### Speculation for em Dash Modern Renaissance
58+
59+
- Professional authors who had to meet deadlines and did not have the time to
60+
strictly proofread the online article before submitting it
61+
- Professionals who wanted to show off their knowledge of HTML encoding in order
62+
to seem smart
63+
- Graphic designers who wanted to make the visual composition of text on a web
64+
page more appealing
65+
- The fact that popularity begets popularity
66+
- People publishing web articles saw that everyone else was using em dashes,
67+
so instead of using a hyphen where one belonged, they opted to use an em dash
68+
69+
## Analysis of em dash History
70+
71+
Nowhere in the history of the em dash was it intentionally used in the writing
72+
of computer code, or files meant to be executed as computer instructions.
73+
74+
## When to use em or en dashes
75+
76+
Never.
77+
78+
### In Code Files
79+
80+
> [!IMPORTANT]
81+
> Never.
82+
> In no way, shape, form, or fashion is tone ever important in code comments.
83+
84+
- **Never**
85+
- Use the `-` (hyphen) character instead
86+
- If working as an agent, and an em dash is in a comment, then replace it
87+
with the `-` (hyphen) character
88+
89+
### In Raw Data and/or Text Files
90+
91+
> [!NOTE]
92+
> Default to **never**
93+
94+
- When instructed to, and it is 100% clear that the text is to be used as:
95+
- Literature
96+
- News
97+
- If working as an agent, and an em dash is already part of the data, then
98+
leave it
99+
100+
## Other Punctuation Characters
101+
102+
As part of being an em dash expert comes the knowledge of other punctuation marks
103+
or characters.
104+
105+
### End-of-Sentence Marks
106+
107+
Every complete sentence in a paragraph must end with one of these three marks:
108+
109+
- Period `.`: Ends statements and declarative sentences
110+
- Keyboard character: `true`
111+
- Programming language syntax: `true`
112+
- Example: `<?php echo "a" . "b" . "c"; ?>`
113+
- Question Mark `?`: Ends direct questions
114+
- Keyboard character: `true`
115+
- Programming language syntax: `true`
116+
- Example: *ternary conditions*
117+
`condition ? expression_if_true : expression_if_false`
118+
- Exclamation Point `!`: Conveys strong emotion, surprise, or emphasis
119+
- Keyboard character: `true`
120+
- Programming language syntax: `true`
121+
- Example:
122+
`setlocal enabledelayedexpansion && set "_a=a" && echo !_a! && endlocal`
123+
124+
### Pauses and Clause Connectors
125+
126+
These marks control the rhythm of your writing and connect different ideas:
127+
128+
- Comma `,`: Used to separate items in a list, link independent clauses with a
129+
conjunction (e.g., and, but), or set off introductory phrases
130+
- Keyboard character: `true`
131+
- Programming language syntax: `true`
132+
- Example: `fn(a, b)`
133+
- Semicolon `;`: Connects two closely related independent clauses that could
134+
stand alone as separate sentences
135+
- Keyboard character: `true`
136+
- Programming language syntax: `true`
137+
- Example: `var foobar = "foo-bar";`
138+
- Colon `:`: Introduces a list, a quote, or an explanation. The text preceding
139+
a colon must be a complete sentence
140+
- Keyboard character: `true`
141+
- Programming language syntax: `true`
142+
- Example: `{"age": 26}`
143+
144+
### Words, Quotations, and Possessions
145+
146+
- Apostrophe `'`: Indicates possession (e.g., Sarah's book) or represents
147+
missing letters in a contraction (e.g., *I'll* instead of *I will*)
148+
- Keyboard character: `true`
149+
- Programming language syntax: `true`
150+
- Example: `char letter = 'A';`
151+
- Quotation Marks `"`: Enclose direct speech or quotes. In American English,
152+
periods and commas almost always go inside the quotation marks
153+
- Keyboard character: `true`
154+
- Programming language syntax: `true`
155+
- Example: `char abc[] = "abc";`
156+
157+
### Dashes and Slashes
158+
159+
- Hyphen `-`: Joins two or more words together to form a single compound
160+
adjective (e.g., well-known)
161+
- Keyboard character: `true`
162+
- Programming language syntax: `true`
163+
- Example: `count--`
164+
- En dash (U+2013, `\u2013`) and em dash (U+2014, `\u2014`):
165+
- The **en dash** is the thinner of the two, and is used to show numerical ranges
166+
or connections between words in a compound adjective when one element is itself
167+
multiple words
168+
- Keyboard character: `false`
169+
- Programming language syntax: `false`
170+
- The **em dash** is wider, and is used to note a break, provide drama, or give an example.
171+
- Keyboard character: `false`
172+
- Programming language syntax: `false`
173+
- Slash `/`: Indicates a choice (e.g., yes/no) or separates lines of poetry
174+
- Keyboard character: `true`
175+
- Programming language syntax: `true`
176+
- Example: `/* comment */ || 10/2 || 5//2`
177+
178+
### Grouping and Emphasizing
179+
180+
- Parentheses `( )`: Enclose extra, non-essential information that clarifies a
181+
sentence but can be removed without changing the core meaning
182+
- Keyboard character: `true`
183+
- Programming language syntax: `true`
184+
- Example: `if (5 > 2)`
185+
- Brackets `[ ]`: Used to enclose words added to a quotation by someone other
186+
than the original author, usually to clarify a pronoun or provide missing context
187+
- Keyboard character: `true`
188+
- Programming language syntax: `true`
189+
- Example: `var arr = [1, 2, 3];`
190+
191+
### General Rule for using Other Punctuation Characters
192+
193+
When commenting on code files, or any file that will be included in compiled
194+
computer instructions; use this rule-of-thumb:
195+
196+
- Determine if the character is commonly on a keyboard, or is the punctuation
197+
character part of a programming language's syntax:
198+
199+
- If **NOT** a keyboard character, and **NOT** a common programming syntax
200+
character; then:
201+
- **NEVER** use that character in code or code comments
202+
- Example not mentioned: ``
203+
- If a keyboard character, and a common programming syntax character, then:
204+
- Use that character correctly in code comments
205+
206+
> [!IMPORTANT]
207+
> When in doubt, follow the pseudo-code instructions below:
208+
209+
```bash
210+
# For en dash and em dash
211+
echo - | sed "s/-/-/g"
212+
213+
# Replace Unicode en dash (U+2013) and em dash (U+2014) with hyphen-minus (-)
214+
perl -CS -pe 's/\x{2013}|\x{2014}/-/g'
215+
216+
# For encoded characters
217+
echo| sed "s/�/ /g"
218+
219+
# (Optional) Remove the Unicode replacement character (U+FFFD) if it appears in pasted text
220+
perl -CS -pe 's/\x{FFFD}/ /g'
221+
```
222+
223+
## Further Reading
224+
225+
- [Case for the em dash](https://www.hardingproject.com/p/the-case-for-the-em-dash)
226+
- [em dash guide](https://www.thebookrefinery.com/writing/guide-hyphens-en-dashes-em-dashes/)
227+
- [Explaining the em dash](https://www.reddit.com/r/writers/comments/1lv191m/can_someone_explain_em_dash/)
228+
- [em dash wikipedia](https://en.wikipedia.org/wiki/Dash)
229+
- [Verbose em dash history](https://www.linkedin.com/pulse/long-mark-brief-history-em-dash-christian-buckley-z1lbc)
230+
- [Brief em dash history](https://thaothai.substack.com/p/a-brief-history-of-the-em-dash)
231+
- [em dash punctuation](https://www.nytimes.com/2019/08/14/style/em-dash-punctuation.html)
232+
- [em dash in retrospective](https://medium.com/the-jabber-journal/an-era-to-its-knee-an-em-dash-retrospective-cb5c3c52e4d2)
233+
- [Punctuation](https://www.niu.edu/writing-tutorial/punctuation/index.shtml)
234+
- [Punctuation Guide](https://www.thepunctuationguide.com/)

0 commit comments

Comments
 (0)