Add AI Agent Skills support using the skills.sh convention - #1004
Add AI Agent Skills support using the skills.sh convention#1004benjaminloerincz wants to merge 9 commits into
Conversation
|
|
||
| 1. Always call `Logger.saveLog()`. | ||
| 2. Place `Logger.saveLog()` in `finally` blocks for transactional code paths. | ||
| 3. Use the lowest effective logging level (`ERROR` for failures, `INFO` for business milestones, fine-grained levels for diagnostics). |
There was a problem hiding this comment.
The parenthetical addendum is at odds with the spirit of this point (also, "business milestones" ? How perfectly vague!).
Perhaps a better way to put point 3:
Logging affects performance, but fine-grained log levels like FINEST and FINER can be used (in conjunction with Logger Settings) to skip logging statements in code-intensive path except when debugging.
Prefer higher-level logging (ERROR, WARN, and INFO) for only the most salient info.
There was a problem hiding this comment.
Thanks for the input. I like this direction and will update the text accordingly:
Use logging levels strategically. Fine-grained levels such as FINE, FINER, and FINEST can be combined with Logger Settings to avoid unnecessary logging overhead in performance-sensitive code paths and enable deeper diagnostics only when needed. Reserve higher-level logging (ERROR, WARN, and INFO) for information that is operationally significant.
There was a problem hiding this comment.
Thanks. @jongpie and I will take a look and see whether any further changes are necessary
…age, and best practices
- Renamed the existing nebula-logger-apex-logging skill to nebula-logger-instrumentation and restructured it to cover Apex, LWC, Aura, Flow, and OmniStudio as peer runtime contexts (rather than Apex-first with the other runtimes appended)
- Added a new 'Optional Dependency via CallableLogger' subsection describing how ISVs can integrate with Nebula Logger dynamically without requiring their customers to install it
- Added a Supported API Surface section in nebula-logger-instrumentation as the canonical policy statement and cross-referenced it from the testing and plugin skills
- Added four new skills:
1. nebula-logger-console: browsing logging data in the UI
2. nebula-logger-purging-and-retention: LogRetentionDate__c, LogBatchPurger scheduling, per-scenario retention overrides
3. nebula-logger-testing-your-code: writing subscriber-owned tests using only the global surface
4. nebula-logger-plugin-development: extending Nebula Logger unlocked package via LoggerPlugin.Triggerable and LoggerPlugin.Batchable
- Updated skills.sh.json to group the seven skills under Setup, Usage, Operations, Governance, and Extending headings
- Updated all of the skills to only reference Nebula Logger's global Apex classes/methods and the exported c/logger LWC module. The plugin-development skill is a deliberate exception since the LoggerPlugin interfaces are public-by-design inside the unlocked package
- Added a top-level skills/README.md as the landing page for all of the skills, with a skill index and a note on the skills.sh publishing model
… ID and version number in skills/nebula-logger-install any time a new package version is created (just like how README.md is auto-updated). Managed package IDs will be updated manually for now (most of the managed package changes are done manually) Also fixed the managed package version ID for v4.19.0 in nebula-logger/managed-package/sfdx-project.json, it had the wrong ID
|
@benjaminloerincz thanks so much for submitting this PR, I think this is good idea to include in the repo (and thanks to @jamessimone for all of the feedback!). I've just pushed some commits with a mix of changes:
My hope is to try to merge this in the next few days, but if either of y'all have time to review the changes, I'd love to hear your thoughts. |
|
I'll review tomorrow morning! |
…of other changes to content
|
@benjaminloerincz and @jamessimone I've just pushed up some more changes (some to address @benjaminloerincz 's comments, and some other changes for issues/gaps I noticed). If either of you have time to take a look, let me know if you have any other suggestions. |
| System.Assert.areEqual(1, entries.size()); | ||
| System.Assert.areEqual('ERROR', entries[0].LoggingLevel__c); | ||
| System.Assert.areEqual(account.Id, entries[0].RecordId__c); | ||
| System.Assert.areEqual(thrownException.getMessage, entries[0].ExceptionMessage__c); |
There was a problem hiding this comment.
Parentheses are missing: It should be thrownException.getMessage() instead of thrownException.getMessage.
| - Multiple `saveLog()` calls in a transaction are fine, and often the right choice. Reasonable places to save intermediate state include after each chunk in a batch, at the end of each iteration of a long-running loop's outer scope (never the inner scope - see below), before an async handoff (Queueable / Future / Batchable), and inside a `finally` block that catches an exception you're about to rethrow. Each save publishes only what's in the buffer at that moment, so the entries persist even if the rest of the transaction later blows up. | ||
| - What's wrong is calling `saveLog()` after every single log entry. That turns N log calls into N platform-event publishes, burns through `getLimitPublishImmediateDML()` (100 per transaction) fast, and eats into the org's daily platform event allocation for no operational benefit. If you find yourself typing `Logger.info(...); Logger.saveLog();` repeatedly, buffer the entries and save once after the group. | ||
| - Never call `saveLog()` inside the innermost body of a loop over records. Buffer entries in the loop and call `saveLog()` after the loop (or at safe checkpoints - after N iterations, after a chunk of work, etc.), not after each record. | ||
| - Place a `Logger.saveLog()` call in a `finally` block for transactional code paths so it still runs when an exception escapes the try. Pair it with `Logger.setSaveMethod(...)` at the top of the method if the default `EVENT_BUS` isn't right for that path (see the save-method notes in item 1). |
There was a problem hiding this comment.
"item 1" has changed due to this commit. Thus, this should be adjusted.
3 participants
Summary
This PR introduces AI Agent Skills for Nebula Logger using the
skills.shconvention and a structure similar to the approach used byforcedotcom/sf-skills.The goal is to help AI coding assistants such as GitHub Copilot, Claude Code, Cursor, Windsurf, Gemini CLI, Cline, and other compatible agents understand how to correctly install, configure, and use Nebula Logger.
With this change, developers can install Nebula Logger-specific guidance directly into their AI-assisted development workflow via:
The implementation is intentionally documentation-only and does not introduce any runtime, packaging, metadata, or API changes.
Motivation
Nebula Logger has become one of the most widely used logging and observability frameworks in the Salesforce ecosystem.
As AI-assisted development becomes increasingly common, developers frequently ask coding agents questions such as:
Without project-specific guidance, AI assistants often generate generic Salesforce logging approaches rather than Nebula Logger best practices.
This PR aims to provide Nebula Logger-specific knowledge directly to AI agents using the emerging
skills.shecosystem.What This PR Adds
New
skills/DirectorySkill: Installation & Configuration
nebula-logger-installCovers:
Skill: Apex, LWC, Aura, Flow & OmniStudio Usage
nebula-logger-apex-loggingCovers:
Skill: Governance & Best Practices
nebula-logger-best-practicesCovers:
skills.sh Configuration
Adds a
skills.sh.jsonconfiguration file to organize skills into:README Enhancement
Adds a small "AI Agent Skills" section documenting how developers can install Nebula Logger skills using:
Inspiration
The initial idea for this contribution was inspired by the excellent community content around Nebula Logger.
In particular, Amit Chaudhary's (@amit-salesforce) Apex Hours article "Nebula Logger Salesforce: The Complete Setup, Usage & Best Practices Guide" did a fantastic job of bringing installation guidance, architecture concepts, practical implementation patterns, and operational best practices together in a single resource.
That article inspired the idea of making Nebula Logger knowledge available directly within AI-assisted development workflows.
The skill contents included in this PR were written specifically for this repository and are intended to complement the existing project documentation, README, and Wiki.
Many thanks to Amit for helping promote Nebula Logger across the Salesforce community.
Design Principles
This contribution was intentionally designed to be:
It does not alter:
Impact
Runtime Impact
None.
Package Impact
None.
Metadata Impact
None.
Breaking Changes
None.
Future Opportunities
Potential future skills could include:
These ideas were intentionally left out of the initial contribution to keep the PR small, focused, and easy to review.
Feedback Welcome
I'd love to get feedback on whether maintaining AI Agent Skills within the Nebula Logger repository is something that would be valuable to the project long term.
The implementation is intentionally lightweight and can be adjusted to match the preferred documentation strategy of the project.
Thank you for taking the time to review this contribution!