diff --git a/docs/README.skills.md b/docs/README.skills.md index 1f24d0b37..2cf0733ae 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -219,6 +219,8 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [napkin](../skills/napkin/SKILL.md) | Visual whiteboard collaboration for Copilot CLI. Creates an interactive whiteboard that opens in your browser — draw, sketch, add sticky notes, then share everything back with Copilot. Copilot sees your drawings and text, and responds with analysis, suggestions, and ideas. | `assets/napkin.html`
`assets/step1-activate.svg`
`assets/step2-whiteboard.svg`
`assets/step3-draw.svg`
`assets/step4-share.svg`
`assets/step5-response.svg` | | [next-intl-add-language](../skills/next-intl-add-language/SKILL.md) | Add new language to a Next.js + next-intl application | None | | [noob-mode](../skills/noob-mode/SKILL.md) | Plain-English translation layer for non-technical Copilot CLI users. Translates every approval prompt, error message, and technical output into clear, jargon-free English with color-coded risk indicators. | `references/examples.md`
`references/glossary.md` | +| [now-sdk-explain](../skills/now-sdk-explain/SKILL.md) | Use whenever the user mentions fluent, ServiceNow, or the now-sdk, OR when the user prompts for edits within a fluent application (identified by a now.config.json at the project root). Fetches SDK documentation via now-sdk explain — covers API types, metadata conventions, skills, and project structure. Pass a topic to read it directly, or omit to browse available topics. | None | +| [now-sdk-setup](../skills/now-sdk-setup/SKILL.md) | Configure the environment so now-sdk explain is usable. Run before now-sdk-explain if the command is not found or returns errors. | None | | [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None | | [onboard-context-matic](../skills/onboard-context-matic/SKILL.md) | Interactive onboarding tour for the context-matic MCP server. Walks the user through what the server does, shows all available APIs, lets them pick one to explore, explains it in their project language, demonstrates model_search and endpoint_search live, and ends with a menu of things the user can ask the agent to do. USE FOR: first-time setup; "what can this MCP do?"; "show me the available APIs"; "onboard me"; "how do I use the context-matic server"; "give me a tour". DO NOT USE FOR: actually integrating an API end-to-end (use integrate-context-matic instead). | None | | [oo-component-documentation](../skills/oo-component-documentation/SKILL.md) | Create or update standardized object-oriented component documentation using a shared template plus mode-specific guidance for new and existing docs. | `assets/documentation-template.md`
`references/create-mode.md`
`references/update-mode.md` | diff --git a/skills/now-sdk-explain/SKILL.md b/skills/now-sdk-explain/SKILL.md new file mode 100644 index 000000000..887602ce8 --- /dev/null +++ b/skills/now-sdk-explain/SKILL.md @@ -0,0 +1,60 @@ +--- +name: now-sdk-explain +description: Use whenever the user mentions fluent, ServiceNow, or the now-sdk, OR when the user prompts for edits within a fluent application (identified by a now.config.json at the project root). Fetches SDK documentation via now-sdk explain — covers API types, metadata conventions, skills, and project structure. Pass a topic to read it directly, or omit to browse available topics. +argument-hint: "[topic]" +--- + + +## Usage + +IMPORTANT: _Never_ open a full topic without first viewing the summary via the `--peek` option! This will prevent you from accidentally opening the wrong topic and wasting context space. + +To show all available topics with their related tags: +```bash +npx @servicenow/sdk explain --list --format=raw +``` + +To search for topics, showing the descriptions of all matches: +```bash +npx @servicenow/sdk explain --list --peek --format=raw +``` + +To preview topics using the `--peek` option: +```bash +npx @servicenow/sdk explain --peek --format=raw +``` + +Once you are certain you want to read the full topic, open it like this: +```bash +npx @servicenow/sdk explain --format=raw +``` + +## What to Search for + +- **Metadata types** — `BusinessRule`, `Table`, `Acl`, `Flow`, `ScriptInclude`, `ClientScript` +- **Skills** — workflows like `build`, `transform`, `deploy`, `auth` +- **Conventions** — `naming`, `structure`, `scoping`, `file-layout` + +## Prerequisite knowledge and guidelines + +- The first time this skill is invoked in a session, please familiarize yourself with general fluent development by reading everything under `npx @servicenow/sdk explain quickstart --list --format=raw`. +- Always use the `npx @servicenow/sdk` cli commands whenever possible to create, build, and deploy fluent projects. + +## For any task — always start here + +- Start by searching for topics using `npx @servicenow/sdk explain --list --format=raw`. +- Continue by reading the relevant topics, always using `npx @servicenow/sdk explain --peek --format=raw`, to preview the description before committing to read the full topic. +- Provided the description is relevant, continue to read the full topic using `npx @servicenow/sdk explain --format=raw`. +- Many items are spread out across multiple topics. As such, it is very important to read all relevant topics before making any changes. + +## If a now-sdk command fails + +Invoke `/now-sdk-setup` if the error indicates an environment configuration problem: + +- `@servicenow/sdk is not in this registry` — `@servicenow/sdk` is not installed +- Node.js version errors (e.g. `The engine "node" is incompatible`) + +Do **not** invoke `/now-sdk-setup` for other errors — these are not environment problems and that skill will not help: + +- `No documentation found for ""` — wrong topic name, try `--list` +- `No match for ""` — use a different search term diff --git a/skills/now-sdk-setup/SKILL.md b/skills/now-sdk-setup/SKILL.md new file mode 100644 index 000000000..8c0eb1bb2 --- /dev/null +++ b/skills/now-sdk-setup/SKILL.md @@ -0,0 +1,27 @@ +--- +name: now-sdk-setup +description: Configure the environment so now-sdk explain is usable. Run before now-sdk-explain if the command is not found or returns errors. +--- + +## Step 1: Check Node version + +Run `node --version`. + +Node 20 or higher is required. If the version is below 20, run: + +```bash +nvm install 20 +nvm use 20 +``` + +Then re-check `node --version` to confirm before continuing. If there is no node version found, or they don't have nvm, ask them to install node and nvm and then run the command again. + +## Step 2: Check @servicenow/sdk installation and version + +Run `npx @servicenow/sdk --version` to check the installed version. + +- If `@servicenow/sdk` is not found, install it using `npm install -g @servicenow/sdk@latest`. +- If the version is below **4.6.0**, update it using `npm install -g @servicenow/sdk@latest`. Version 4.6.0 is the minimum that supports the `explain` command via `npx`. +- If the version is 4.6.0 or higher, the SDK is ready. Proceed to the next step. + +Verify by running `npx @servicenow/sdk explain quickstart --list --format=raw`. If it succeeds, setup is complete.