Support annotate command and add SKILL.md

cli/skills/get-mslearn-docs/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: get-mslearn-docs
+description: >
+  Use this skill when you need documentation from Microsoft Learn before writing
+  code — for example, "use Azure Functions", "configure Cosmos DB", "set up App
+  Service", or any time the user asks you to work with a Microsoft technology
+  and you need current reference material. Fetch the docs with mslearn before
+  answering, rather than relying on training knowledge.
+---
+
+# Get Microsoft Learn Docs via mslearn
+
+When you need documentation for a Microsoft technology, fetch it with the
+
+`mslearn` CLI rather than guessing from training data. This gives you the
+
+current, correct content straight from Microsoft Learn.
+
+## Step 1 — Search for the right doc
+
+```bash
+
+mslearn search "<microsoft product or topic>"
+
+```
+
+Review the search results to find the most relevant document `contentUrl`. If nothing matches, try a broader term.
+
+Pick the best-matching `id` from the results (e.g. `openai/chat`, `anthropic/sdk`,
+`stripe/api`). If nothing matches, try a broader term.
+
+## Step 2 — Fetch the doc
+
+```bash
+
+mslearn fetch <contentUrl>
+
+```
+
+To fetch only a specific section (saves tokens):
+
+
+```bash
+
+mslearn fetch "<contentUrl>" --section "<section name>"
+
+```
+
+
+
+To limit output length:
+
+
+
+```bash
+
+mslearn fetch "<contentUrl>" --max-chars 3000
+
+```
+
+## Step 3 — Use the docs
+
+Read the fetched content and use it to write accurate code or answer the question.
+
+Do not rely on memorized API shapes — use what the docs say.
+
+## Step 4 — Search for code samples
+
+If you need working code examples, search the official Microsoft code samples:
+
+
+
+```bash
+
+mslearn code-search "<microsoft product or topic>"
+
+```
+
+
+
+To filter by programming language:
+
+
+
+```bash
+
+mslearn code-search "<microsoft product or topic>" --language <programming language>
+
+```
+
+## Step 5 — Annotate what you learned
+
+**ALWAYS perform this step before finishing.** Review what you learned and ask yourself:
+
+1. Did the docs contain any surprising behavior, version-specific caveats, or
+   non-obvious prerequisites?
+2. Did you find that the docs were misleading, incomplete, or required combining
+   multiple pages to get a working answer?
+3. Is there project-specific context (e.g., "we use .NET 8, not 6") that would
+   help future sessions?
+
+If ANY of the above apply, save an annotation:
+
+```bash
+mslearn annotate "<contentUrl>" "<note text>"
+```
+
+Annotations are local, persist across sessions, and are keyed by URL. Keep notes
+concise and actionable. Don't repeat what's already in the doc.
+
+If none apply, explicitly state: "No annotation needed — docs were
+straightforward."
+
+To view an existing annotation:
+
+```bash
+mslearn annotate "<contentUrl>"
+```
+
+## Step 6 — Review and manage annotations
+
+List all saved annotations:
+
+
+
+```bash
+
+mslearn annotate --list
+
+```
+
+
+
+Remove an annotation that is no longer relevant:
+
+
+
+```bash
+
+mslearn annotate "<contentUrl>" --clear
+
+```
+
+## Quick reference
+
+| Goal | Command |
+
+|------|---------|
+
+| Search docs | `mslearn search "<microsoft product or topic>"` |
+
+| Fetch a doc | `mslearn fetch "<contentUrl>"` |
+
+| Fetch one section | `mslearn fetch "<contentUrl>" --section "<section name>"` |
+
+| Limit output size | `mslearn fetch "<contentUrl>" --max-chars 3000` |
+
+| Search code samples | `mslearn code-search "<microsoft product or topic>"` |
+
+| Filter by language | `mslearn code-search "<microsoft product or topic>" --language <programming language>` |
+
+| Save a note | `mslearn annotate "<contentUrl>" "<note text>"` |
+
+| View a note | `mslearn annotate "<contentUrl>"` |
+
+| List all notes | `mslearn annotate --list` |
+
+| Remove a note | `mslearn annotate "<contentUrl>" --clear` |
+
+| Check connectivity | `mslearn doctor` |
+
+| Check (JSON output) | `mslearn doctor --format json` |
+
+
+
+## Notes
+
+- All docs are fetched from the Microsoft Learn MCP server at `https://learn.microsoft.com/api/mcp`
+- The `<contentUrl>` argument must be a valid Microsoft Learn URL
+- Use `--section` with `fetch` to reduce token usage when you only need part of a page
+- Use `mslearn doctor` to verify that your environment and connectivity are working
+- Override the endpoint with `MSLEARN_ENDPOINT` env var or `--endpoint <url>` flag
+
+
+

cli/src/commands/annotate.ts

@@ -0,0 +1,71 @@
+import { Command } from 'commander';
+
+import type { CliContext } from '../context.js';
+import { normalizeUrl } from '../utils/options.js';
+import { ensureTrailingNewline } from '../utils/text.js';
+import { UsageError } from '../utils/errors.js';
+
+interface AnnotateCommandOptions {
+  clear?: boolean;
+  list?: boolean;
+}
+
+export function registerAnnotateCommand(program: Command, context: CliContext): void {
+  program
+    .command('annotate')
+    .description('Attach a local note to a Microsoft Learn URL. Notes persist across sessions.')
+    .argument('[url]', 'Microsoft Learn document URL.')
+    .argument('[note]', 'Note text to attach to the URL.')
+    .option('--clear', 'Remove the annotation for this URL.')
+    .option('--list', 'List all saved annotations.')
+    .action((url: string | undefined, note: string | undefined, options: AnnotateCommandOptions) => {
+      const store = context.createAnnotationStore();
+
+      if (options.list) {
+        const annotations = store.list();
+        if (annotations.length === 0) {
+          context.writeOut(ensureTrailingNewline('No annotations.'));
+          return;
+        }
+        const lines: string[] = [];
+        for (const a of annotations) {
+          lines.push(`${a.url} (${a.updatedAt})`);
+          lines.push(`  ${a.note}`);
+          lines.push('');
+        }
+        context.writeOut(ensureTrailingNewline(lines.join('\n')));
+        return;
+      }
+
+      if (!url) {
+        throw new UsageError(
+          'Missing required argument: <url>. Usage: mslearn annotate <url> <note> | mslearn annotate <url> --clear | mslearn annotate --list',
+        );
+      }
+
+      const normalizedUrl = normalizeUrl(url);
+
+      if (options.clear) {
+        const removed = store.clear(normalizedUrl);
+        if (removed) {
+          context.writeOut(ensureTrailingNewline(`Annotation cleared for ${normalizedUrl}.`));
+        } else {
+          context.writeOut(ensureTrailingNewline(`No annotation found for ${normalizedUrl}.`));
+        }
+        return;
+      }
+
+      if (!note) {
+        const existing = store.read(normalizedUrl);
+        if (existing) {
+          context.writeOut(ensureTrailingNewline(`${existing.url} (${existing.updatedAt})\n${existing.note}`));
+        } else {
+          context.writeOut(ensureTrailingNewline(`No annotation for ${normalizedUrl}.`));
+        }
+        return;
+      }
+
+      const annotation = store.write(normalizedUrl, note);
+      context.writeOut(ensureTrailingNewline(`Annotation saved for ${annotation.url}.`));
+    });
+}

cli/src/context.ts

@@ -1,4 +1,5 @@
 import { createLearnCliClient, type LearnCliClientLike, type LearnClientOptions } from './mcp/client.js';
+import { createFileAnnotationStore, type AnnotationStore } from './utils/annotations.js';
 
 export interface CliContext {
   env: NodeJS.ProcessEnv;
@@ -7,6 +8,7 @@ export interface CliContext {
   writeErr: (value: string) => void;
   fetchImpl: typeof fetch;
   createClient: (options: LearnClientOptions) => LearnCliClientLike;
+  createAnnotationStore: () => AnnotationStore;
 }
 
 export function createDefaultContext(version: string): CliContext {
@@ -21,5 +23,6 @@ export function createDefaultContext(version: string): CliContext {
     },
     fetchImpl: globalThis.fetch.bind(globalThis) as typeof fetch,
     createClient: (options) => createLearnCliClient(options),
+    createAnnotationStore: () => createFileAnnotationStore(),
   };
 }

cli/src/index.ts

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module';
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 
+import { registerAnnotateCommand } from './commands/annotate.js';
 import { registerCodeSearchCommand } from './commands/code-search.js';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerFetchCommand } from './commands/fetch.js';
@@ -40,6 +41,7 @@ export function createProgram(context: CliContext): Command {
   registerFetchCommand(program, context);
   registerCodeSearchCommand(program, context);
   registerDoctorCommand(program, context);
+  registerAnnotateCommand(program, context);
 
   return program;
 }

cli/src/utils/annotations.ts

@@ -0,0 +1,95 @@
+import { mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import envPaths from 'env-paths';
+
+export interface Annotation {
+  url: string;
+  note: string;
+  updatedAt: string;
+}
+
+export interface AnnotationStore {
+  read(url: string): Annotation | undefined;
+  write(url: string, note: string): Annotation;
+  clear(url: string): boolean;
+  list(): Annotation[];
+}
+
+interface FileAnnotationStoreOptions {
+  annotationsDir?: string;
+  now?: () => number;
+}
+
+export function getDefaultAnnotationsDir(): string {
+  const paths = envPaths('mslearn', { suffix: '' });
+  return join(paths.data, 'annotations');
+}
+
+export function createFileAnnotationStore(options: FileAnnotationStoreOptions = {}): AnnotationStore {
+  return new FileAnnotationStore(options);
+}
+
+function urlToFilename(url: string): string {
+  return url.replace(/[^a-zA-Z0-9.-]/g, '_') + '.json';
+}
+
+class FileAnnotationStore implements AnnotationStore {
+  private readonly annotationsDir: string;
+  private readonly now: () => number;
+
+  constructor(options: FileAnnotationStoreOptions) {
+    this.annotationsDir = options.annotationsDir ?? getDefaultAnnotationsDir();
+    this.now = options.now ?? Date.now;
+  }
+
+  read(url: string): Annotation | undefined {
+    try {
+      const filePath = join(this.annotationsDir, urlToFilename(url));
+      const raw = readFileSync(filePath, 'utf8');
+      return JSON.parse(raw) as Annotation;
+    } catch {
+      return undefined;
+    }
+  }
+
+  write(url: string, note: string): Annotation {
+    mkdirSync(this.annotationsDir, { recursive: true });
+    const annotation: Annotation = {
+      url,
+      note,
+      updatedAt: new Date(this.now()).toISOString(),
+    };
+    const filePath = join(this.annotationsDir, urlToFilename(url));
+    writeFileSync(filePath, JSON.stringify(annotation, null, 2), 'utf8');
+    return annotation;
+  }
+
+  clear(url: string): boolean {
+    try {
+      const filePath = join(this.annotationsDir, urlToFilename(url));
+      unlinkSync(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  list(): Annotation[] {
+    try {
+      const files = readdirSync(this.annotationsDir).filter((f) => f.endsWith('.json'));
+      const results: Annotation[] = [];
+      for (const file of files) {
+        try {
+          const raw = readFileSync(join(this.annotationsDir, file), 'utf8');
+          results.push(JSON.parse(raw) as Annotation);
+        } catch {
+          // skip malformed files
+        }
+      }
+      return results;
+    } catch {
+      return [];
+    }
+  }
+}