Skip to content

Commit e92df24

Browse files
matttmattt
authored
Add SKILL.md (#50)
* Add SKILL.md * Document AI Agent skill
1 parent 8986a15 commit e92df24

4 files changed

Lines changed: 254 additions & 71 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,12 @@ sosumi fetch https://developer.apple.com/documentation/swift/array --json
148148
sosumi search "SwiftData" --json
149149
```
150150

151+
### AI Agent Skill
152+
153+
Want your AI coding assistant to use Sosumi consistently?
154+
Use the hosted skill file:
155+
[`https://sosumi.ai/SKILL.md`](https://sosumi.ai/SKILL.md)
156+
151157
### Chrome Extension
152158

153159
You can also use Sosumi from a community-contributed

‎public/SKILL.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
name: sosumi
3+
description: Fetches Apple documentation as Markdown via Sosumi. Use for Apple API reference, Human Interface Guidelines, WWDC transcripts, and external Swift-DocC pages.
4+
---
5+
6+
# Sosumi Skill
7+
8+
Use this skill to reliably fetch Apple docs as Markdown when coding agents need precise API details.
9+
10+
## When to Use
11+
12+
Use Sosumi when the request involves any of the following:
13+
14+
- Apple platform APIs (`Swift`, `SwiftUI`, `UIKit`, `AppKit`, `Foundation`, etc.)
15+
- API signatures, availability, parameter behavior, or return semantics
16+
- Human Interface Guidelines questions
17+
- WWDC session transcript lookup
18+
- External Swift-DocC documentation (for example, GitHub Pages or Swift Package Index hosts)
19+
20+
## Core Workflow
21+
22+
1. If you already have a `developer.apple.com` URL, replace the host with `sosumi.ai` and keep the same path.
23+
2. If you do not know the exact page path, search first, then fetch the best match.
24+
3. Prefer specific symbol pages instead of broad top-level pages when answering implementation questions.
25+
26+
## HTTP Usage
27+
28+
Replace `developer.apple.com` with `sosumi.ai`:
29+
30+
- Original: `https://developer.apple.com/documentation/swift/array`
31+
- AI-readable: `https://sosumi.ai/documentation/swift/array`
32+
33+
## Content Types
34+
35+
### Apple API Reference
36+
37+
- Pattern: `https://sosumi.ai/documentation/{framework}/{symbol}`
38+
- Examples:
39+
- `https://sosumi.ai/documentation/swift/array`
40+
- `https://sosumi.ai/documentation/swiftui/view`
41+
42+
### Human Interface Guidelines
43+
44+
- Pattern: `https://sosumi.ai/design/human-interface-guidelines/{topic}`
45+
- Examples:
46+
- `https://sosumi.ai/design/human-interface-guidelines`
47+
- `https://sosumi.ai/design/human-interface-guidelines/foundations/color`
48+
49+
### Apple Video Transcripts
50+
51+
- Pattern: `https://sosumi.ai/videos/play/{collection}/{id}`
52+
- Examples:
53+
- `https://sosumi.ai/videos/play/wwdc2021/10133`
54+
- `https://sosumi.ai/videos/play/meet-with-apple/208`
55+
56+
### External Swift-DocC
57+
58+
- Pattern: `https://sosumi.ai/external/{full-https-url}`
59+
- Examples:
60+
- `https://sosumi.ai/external/https://apple.github.io/swift-argument-parser/documentation/argumentparser/`
61+
- `https://sosumi.ai/external/https://swiftpackageindex.com/pointfreeco/swift-composable-architecture/1.23.1/documentation/composablearchitecture`
62+
63+
## MCP Tools Quick Reference
64+
65+
Use these when Sosumi is configured as an MCP server (`https://sosumi.ai/mcp`):
66+
67+
| Tool | Parameters | Use |
68+
|---|---|---|
69+
| `searchAppleDocumentation` | `query: string` | Search Apple documentation and return structured results |
70+
| `fetchAppleDocumentation` | `path: string` | Fetch Apple docs or HIG content by path as Markdown |
71+
| `fetchAppleVideoTranscript` | `path: string` | Fetch Apple video transcript by `/videos/play/...` path |
72+
| `fetchExternalDocumentation` | `url: string` | Fetch external Swift-DocC page by absolute HTTPS URL |
73+
74+
## Best Practices
75+
76+
- Search first if the exact path is unknown.
77+
- Fetch targeted symbol pages for coding questions.
78+
- Keep source links in answers so users can verify details quickly.
79+
- Use Sosumi paths directly in responses whenever referencing Apple documentation pages.
80+
81+
## Troubleshooting
82+
83+
### 404 or sparse output
84+
85+
- The path may be incorrect or too broad.
86+
- Run a search query first, then fetch a specific result path.
87+
88+
### External page cannot be fetched
89+
90+
- The host may block access via `robots.txt` or `X-Robots-Tag` directives.
91+
- Try another canonical page URL for the same symbol.

‎public/index.html‎

Lines changed: 104 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -223,18 +223,24 @@
223223
}
224224

225225
#clients .interface-tabs,
226-
#clients .client-tabs {
226+
#clients .mcp-tabs,
227+
#cli .cli-tabs,
228+
#skill .skill-tabs {
227229
background: var(--surface-inset);
228230
border-radius: 0.5rem;
229231
overflow: hidden;
230232
}
231233

232-
#clients .tab-buttons {
234+
#clients .mcp-tabs .tab-buttons,
235+
#cli .cli-tabs .tab-buttons,
236+
#skill .skill-tabs .tab-buttons {
233237
display: flex;
234238
border-bottom: 1px solid var(--border);
235239
}
236240

237-
#clients .tab-button {
241+
#clients .mcp-tabs .tab-button,
242+
#cli .cli-tabs .tab-button,
243+
#skill .skill-tabs .tab-button {
238244
flex: 1;
239245
padding: 1rem 1.5rem;
240246
background: transparent;
@@ -247,124 +253,93 @@
247253
border-bottom: 2px solid transparent;
248254
}
249255

250-
#clients .tab-button:hover {
256+
#clients .mcp-tabs .tab-button:hover,
257+
#cli .cli-tabs .tab-button:hover,
258+
#skill .skill-tabs .tab-button:hover {
251259
color: var(--text);
252260
background: var(--surface-inset-deep);
253261
}
254262

255-
#clients .tab-button.active {
263+
#clients .mcp-tabs .tab-button.active,
264+
#cli .cli-tabs .tab-button.active,
265+
#skill .skill-tabs .tab-button.active {
256266
color: var(--text);
257267
border-bottom-color: var(--accent);
258268
background: var(--surface);
259269
}
260270

261-
#clients .tab-content {
271+
#clients .mcp-tabs .tab-content,
272+
#skill .skill-tabs .tab-content {
262273
position: relative;
263274
}
264275

265-
#clients .tab-pane {
276+
#clients .mcp-tabs .tab-pane,
277+
#cli .cli-tabs .tab-pane,
278+
#skill .skill-tabs .tab-pane {
266279
display: none;
267280
padding: 1.5rem;
268281
}
269282

270-
#clients .tab-pane.active {
283+
#clients .mcp-tabs .tab-pane.active,
284+
#cli .cli-tabs .tab-pane.active,
285+
#skill .skill-tabs .tab-pane.active {
271286
display: block;
272287
}
273288

274-
#clients .tab-pane h3 {
289+
#clients .mcp-tabs .tab-pane h3 {
275290
margin-top: 0;
276291
margin-bottom: 1rem;
277292
color: var(--text);
278293
}
279294

280-
#clients .tab-pane h4 {
295+
#clients .mcp-tabs .tab-pane h4 {
281296
margin-top: 1.5rem;
282297
margin-bottom: 0.75rem;
283298
color: var(--text-secondary);
284299
font-size: 1rem;
285300
}
286301

287-
#clients .tab-pane ol {
302+
#clients .mcp-tabs .tab-pane ol {
288303
margin: 0.75rem 0;
289304
padding-left: 1.5rem;
290305
}
291306

292-
#clients .tab-pane li {
307+
#clients .mcp-tabs .tab-pane li {
293308
margin-bottom: 0.5rem;
294309
}
295310

296-
#clients .tab-pane p {
311+
#clients .mcp-tabs .tab-pane p,
312+
#cli .cli-tabs .tab-pane p,
313+
#skill .skill-tabs .tab-pane p {
297314
margin: 0.75rem 0;
298315
}
299316

300-
#clients .tab-pane em {
317+
#clients .mcp-tabs .tab-pane em {
301318
color: var(--text-secondary);
302319
font-style: italic;
303320
}
304321

305-
#cli .runtime-tabs {
306-
background: var(--surface-inset);
307-
border-radius: 0.5rem;
308-
overflow: hidden;
322+
#cli .cli-tabs {
309323
margin-top: 1.5rem;
310324
}
311325

312-
#cli .runtime-tabs .tab-buttons {
313-
display: flex;
314-
border-bottom: 1px solid var(--border);
315-
}
316-
317-
#cli .runtime-tabs .tab-button {
318-
flex: 1;
319-
padding: 0.75rem 1.5rem;
320-
background: transparent;
321-
border: none;
322-
color: var(--text-secondary);
323-
font-family: var(--font-sans);
324-
font-size: 1rem;
325-
cursor: pointer;
326-
transition: all 0.2s ease;
327-
border-bottom: 2px solid transparent;
328-
}
329-
330-
#cli .runtime-tabs .tab-button:hover {
331-
color: var(--text);
332-
background: var(--surface-inset-deep);
333-
}
334-
335-
#cli .runtime-tabs .tab-button.active {
336-
color: var(--text);
337-
border-bottom-color: var(--accent);
338-
background: var(--surface);
339-
}
340-
341-
#cli .runtime-tabs .tab-pane {
342-
display: none;
343-
padding: 1.5rem;
344-
}
345-
346-
#cli .runtime-tabs .tab-pane.active {
347-
display: block;
348-
}
349-
350-
#cli .runtime-tabs .tab-pane p {
351-
margin: 0.75rem 0;
352-
}
353-
354326
@media (max-width: 768px) {
355-
#clients .tab-buttons,
356-
#cli .runtime-tabs .tab-buttons {
327+
#clients .mcp-tabs .tab-buttons,
328+
#cli .cli-tabs .tab-buttons,
329+
#skill .skill-tabs .tab-buttons {
357330
flex-direction: column;
358331
}
359332

360-
#clients .tab-button,
361-
#cli .runtime-tabs .tab-button {
333+
#clients .mcp-tabs .tab-button,
334+
#cli .cli-tabs .tab-button,
335+
#skill .skill-tabs .tab-button {
362336
border-bottom: 1px solid var(--border);
363337
border-right: none;
364338
}
365339

366-
#clients .tab-button.active,
367-
#cli .runtime-tabs .tab-button.active {
340+
#clients .mcp-tabs .tab-button.active,
341+
#cli .cli-tabs .tab-button.active,
342+
#skill .skill-tabs .tab-button.active {
368343
border-bottom-color: var(--border);
369344
border-right: 2px solid var(--accent);
370345
}
@@ -484,6 +459,11 @@
484459
color: var(--code-punctuation-color);
485460
}
486461

462+
pre code .comment {
463+
color: var(--text-tertiary);
464+
font-style: italic;
465+
}
466+
487467
pre code .sosumi-entry {
488468
background-color: var(--surface-inset-deep);
489469
display: block;
@@ -580,7 +560,7 @@
580560
});
581561
});
582562

583-
document.querySelectorAll('.client-tabs, .runtime-tabs').forEach(tabGroup => {
563+
document.querySelectorAll('.mcp-tabs, .cli-tabs, .skill-tabs').forEach(tabGroup => {
584564
const buttons = tabGroup.querySelectorAll('.tab-button');
585565
const panes = tabGroup.querySelectorAll('.tab-pane');
586566
buttons.forEach(button => {
@@ -635,7 +615,7 @@ <h1>
635615
This service translates Apple Developer documentation, Human Interface Guidelines, WWDC sessions, and external Swift-DocC sites into AI-friendly Markdown.
636616
</p>
637617
<p>
638-
Access it in your <a href="#http">browser</a>, over <a href="#mcp">MCP</a>, from the <a href="#cli">command line</a>, or with an unofficial <a href="https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj" rel="noopener noreferrer">Chrome extension</a>.
618+
Access it in your <a href="#http">browser</a>, over <a href="#mcp">MCP</a>, from the <a href="#cli">command line</a>, as an <a href="#skill">AI skill</a>, or with an unofficial <a href="https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj" rel="noopener noreferrer">Chrome extension</a>.
639619
</p>
640620
</header>
641621

@@ -685,7 +665,7 @@ <h2>MCP Usage</h2>
685665
</p>
686666

687667
<figure id="clients">
688-
<div class="client-tabs">
668+
<div class="mcp-tabs">
689669
<div class="tab-buttons">
690670
<button class="tab-button active" data-tab="copilot-xcode">GitHub Copilot for Xcode</button>
691671
<button class="tab-button" data-tab="cursor">Cursor</button>
@@ -898,7 +878,7 @@ <h2>CLI Usage</h2>
898878
</p>
899879
</header>
900880

901-
<div class="runtime-tabs">
881+
<div class="cli-tabs">
902882
<div class="tab-buttons">
903883
<button class="tab-button active" data-tab="rt-node">Node.js</button>
904884
<button class="tab-button" data-tab="rt-bun">Bun</button>
@@ -956,6 +936,60 @@ <h3>Local Server</h3>
956936
<pre><code>sosumi serve
957937
sosumi serve --port 8787</code></pre>
958938
</section>
939+
940+
<section id="skill">
941+
<header>
942+
<h2>AI Agent Skill</h2>
943+
<p>
944+
Teach your coding assistant to use Sosumi consistently with:
945+
<code class="no-wrap"><a href="https://sosumi.ai/SKILL.md">https://sosumi.ai/SKILL.md</a></code>
946+
</p>
947+
</header>
948+
949+
<div class="skill-tabs">
950+
<div class="tab-buttons">
951+
<button class="tab-button active" data-tab="skill-claude-code">Claude Code</button>
952+
<button class="tab-button" data-tab="skill-codex">Codex</button>
953+
<button class="tab-button" data-tab="skill-cursor">Cursor</button>
954+
<button class="tab-button" data-tab="skill-agents">Other</button>
955+
</div>
956+
957+
<div class="tab-content">
958+
<div class="tab-pane active" id="skill-claude-code-tab">
959+
<p>Install as a reusable skill (personal or project-level):</p>
960+
<pre><code><span class="comment"># Personal skill (all your projects)</span>
961+
mkdir -p ~/.claude/skills/sosumi
962+
curl -o ~/.claude/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
963+
964+
<span class="comment"># Project skill (just this project)</span>
965+
mkdir -p .claude/skills/sosumi
966+
curl -o .claude/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md</code></pre>
967+
</div>
968+
969+
<div class="tab-pane" id="skill-codex-tab">
970+
<p>Install globally:</p>
971+
<pre><code><span class="comment"># Global instructions (all your projects)</span>
972+
curl -o ~/.codex/AGENTS.md https://sosumi.ai/SKILL.md</code></pre>
973+
</div>
974+
975+
<div class="tab-pane" id="skill-cursor-tab">
976+
<p>Install as a Cursor skill (global or project-level):</p>
977+
<pre><code><span class="comment"># Personal skill (all your projects)</span>
978+
mkdir -p ~/.cursor/skills/sosumi
979+
curl -o ~/.cursor/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
980+
981+
<span class="comment"># Project skill (just this project)</span>
982+
mkdir -p .cursor/skills/sosumi
983+
curl -o .cursor/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md</code></pre>
984+
</div>
985+
986+
<div class="tab-pane" id="skill-agents-tab">
987+
<p>For AGENTS-compatible tools, you can add project instructions:</p>
988+
<pre><code>curl -o AGENTS.md https://sosumi.ai/SKILL.md</code></pre>
989+
</div>
990+
</div>
991+
</div>
992+
</section>
959993
</main>
960994

961995

0 commit comments

Comments
 (0)