Skip to content

Commit 972736b

Browse files
committed
docs: add inline code formatting guidance to docs skill
Adds a new subsection covering backtick conventions: concept names in plain text ("message ID"), variable names backticked (`msgId`), headers backticked (`x-ably-msg-id`), and functions with parentheses (`send()`).
1 parent 823582f commit 972736b

File tree

1 file changed

+22
-0
lines changed

1 file changed

+22
-0
lines changed

.claude/skills/docs/SKILL.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,28 @@ This page covers the cancellation feature of the AI Transport SDK.
113113
parenthetical asides, not ``. This applies to prose, code comments,
114114
and table cells.
115115

116+
### Inline code formatting
117+
118+
Use backticks for anything that references code - variable names, function
119+
names, header names, enum values, type names, file paths. Do not use backticks
120+
for plain-English concept names.
121+
122+
- **Concept names** are plain text: "message ID", "turn", "cancel signal"
123+
- **Variable/field names** are backticked: `msgId`, `turnId`, `serial`
124+
- **Header names** are backticked: `x-ably-msg-id`, `x-ably-turn-id`
125+
- **Functions** always include parentheses: `send()`, `cancel()`, not `send` or `cancel`
126+
- **Types and interfaces** are backticked: `ClientTransport`, `Codec<TEvent, TMessage>`
127+
- **Enum values** are backticked: `streaming`, `finished`, `aborted`
128+
129+
```markdown
130+
<!-- Good -->
131+
The message ID is available as `msg.id`. Call `transport.send()` to publish,
132+
which sets the `x-ably-msg-id` header.
133+
134+
<!-- Bad: concept name backticked, function missing parens -->
135+
The `message ID` is available as `msg.id`. Call `transport.send` to publish.
136+
```
137+
116138
### Define jargon on first use
117139

118140
Every technical term that a reader might not know needs either an inline

0 commit comments

Comments
 (0)