Add AI Agent Skills support using the skills.sh convention

[benjaminloerincz]

Summary

This PR introduces AI Agent Skills for Nebula Logger using the skills.sh convention and a structure similar to the approach used by forcedotcom/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:

npx skills add jongpie/NebulaLogger

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:

• How do I install Nebula Logger?
• How should I implement logging in Apex?
• How do I log from LWC, Flow, Aura, or OmniStudio?
• What logging levels should I use in production?
• How should I structure scenarios, tags, and retention policies?

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.sh ecosystem.

What This PR Adds

New skills/ Directory

skills/
├── nebula-logger-install/
│   └── SKILL.md
├── nebula-logger-apex-logging/
│   └── SKILL.md
└── nebula-logger-best-practices/
    └── SKILL.md

Skill: Installation & Configuration

nebula-logger-install

Covers:

• Unlocked vs Managed package selection
• Installation methods
• Permission set assignments
• LoggerSettings configuration
• Common post-install troubleshooting

Skill: Apex, LWC, Aura, Flow & OmniStudio Usage

nebula-logger-apex-logging

Covers:

• Apex logging patterns
• Exception handling
• Record association
• Tags and scenarios
• Parent-child transaction correlation
• LWC logging
• Aura logging
• Flow logging
• OmniStudio integration
• Save method selection

Skill: Governance & Best Practices

nebula-logger-best-practices

Covers:

• Team-wide logging standards
• Environment-specific logging levels
• Retention and purging strategies
• Governor limit awareness
• Review guidance and operational best practices

skills.sh Configuration

Adds a skills.sh.json configuration file to organize skills into:

• Setup
• Usage
• Governance

README Enhancement

Adds a small "AI Agent Skills" section documenting how developers can install Nebula Logger skills using:

npx skills add jongpie/NebulaLogger

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:

• documentation-only
• additive
• low maintenance
• non-invasive
• backward compatible
• easy to extend in the future

It does not alter:

• Apex code
• LWC code
• metadata
• package configuration
• CI/CD workflows
• release processes

Impact

Runtime Impact

None.

Package Impact

None.

Metadata Impact

None.

Breaking Changes

None.

Future Opportunities

Potential future skills could include:

• Flow-focused implementation guidance
• OmniStudio-focused guidance
• Plugin Framework patterns
• Reporting and observability dashboards
• Advanced troubleshooting workflows
• Enterprise logging governance

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!

[jamessimone]

this is functionally out of date: Logger.exception(msg, ex); is the one-liner equivalent

[benjaminloerincz]

Thanks James! I removed this in my last commit.

[jamessimone]

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.

[benjaminloerincz]

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.

[jamessimone]

Thanks. @jongpie and I will take a look and see whether any further changes are necessary

[jamessimone]

this sentence is contradictory

[benjaminloerincz]

Thanks. Removing this sentence in the next commit.