agentleFS
SolaceProductsSolaceProducts/solace-broker-mcp/.claude/skills/add-logs/SKILL.md

add-logs

Skill18 starsChanged 4 months agoApache-2.0View on GitHub

Add secure, compliant slog logging to Go code following the project's secure logging rules

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. About 0 are common, 9 are distinctive, and 11 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add structured log/slog logging to Go code that follows the project's secure logging rules.

    line 9
  2. Distinctive:

    After implementing a new feature or function that needs logging

    line 13
  3. Very specific:

    When migrating log.Printf calls to slog

    line 14
  4. Distinctive:

    When adding logging to an existing file that lacks it

    line 15
  5. Distinctive:

    If invoked without arguments, ask the user which file or function to target.

    line 22
  6. Very specific:

    Read the secure logging rules at docs/_internal/secure-logging-rules.md in the project root.

    line 28
  7. Distinctive:

    Read the file or function the user specified.

    line 32
  8. Very specific:

    Use slog.Info(), slog.Warn(), or slog.Error() — not log.Printf

    line 50
  9. Very specific:

    Use structured fields: slog.String("key", value), slog.Int("key", value), slog.Duration("key", value)

    line 51
  10. Distinctive:

    Keep the message string static and descriptive (no variable data in the message)

    line 52
  11. Distinctive:

    Never log anything on the Never-Log list (passwords, usernames, tokens, auth headers, raw config maps, URLs with embedded credentials)

    line 56
  12. Very specific:

    Never use fmt.Sprintf in the message string with external data

    line 57
  13. Very specific:

    Never log raw structs with slog.Any("key", someStruct) — log explicit fields

    line 58
  14. Very specific:

    Never log raw err.Error() from external systems (SEMP, HTTP) without reviewing what it could contain

    line 59
  15. Distinctive:

    Never log to stdout — always stderr

    line 60
  16. Very specific:

    Ensure the file imports log/slog.

    line 64
  17. Very specific:

    Every log line must pass the Never-Log list check from docs/_internal/secure-logging-rules.md

    line 114
  18. Distinctive:

    Every significant event must include the fields from the Always-Log table

    line 115
  19. Distinctive:

    If unsure whether something is safe to log, don't log it — flag it for the user

    line 116
  20. Very specific:

    When migrating from log.Printf, don't just swap the call — redesign it with structured fields

    line 117

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add Logs

Add structured log/slog logging to Go code that follows the project's secure logging rules. Invoked with /add-logs.

When to use

  • After implementing a new feature or function that needs logging
  • When migrating log.Printf calls to slog
  • When adding logging to an existing file that lacks it

Usage

  • /add-logs <file_path> — add logging to a specific file
  • /add-logs <file_path> <function_name> — add logging to a specific function

If invoked without arguments, ask the user which file or function to target.

Steps

Step 1: Read the rules

Read the secure logging rules at docs/_internal/secure-logging-rules.md in the project root. These rules are non-negotiable — every log line you write must comply.

Step 2: Read the target code

Read the file or function the user specified. Understand what it does, what events are significant, and what data flows through it.

Step 3: Identify loggable events

For each function, identify events that belong in the Always-Log list from the rules:

  • Server startup/shutdown
  • Tool invocations (tool name, broker alias, outcome, duration)
  • Tool errors (tool name, broker alias, error_type, http_status)
  • Broker connections created (broker alias, URL)
  • Config loaded (broker_count, port)
  • Any error or failure path

Step 4: Write the log calls

For each event, write a slog call following these constraints:

Always:

  • Use slog.Info(), slog.Warn(), or slog.Error() — not log.Printf
  • Use structured fields: slog.String("key", value), slog.Int("key", value), slog.Duration("key", value)
  • Keep the message string static and descriptive (no variable data in the message)
  • Include all required fields from the Always-Log table

Never:

  • Never log anything on the Never-Log list (passwords, usernames, tokens, auth headers, raw config maps, URLs with embedded credentials)
  • Never use fmt.Sprintf in the message string with external data
  • Never log raw structs with slog.Any("key", someStruct) — log explicit fields
  • Never log raw err.Error() from external systems (SEMP, HTTP) without reviewing what it could contain
  • Never log to stdout — always stderr

Step 5: Check for imports

Ensure the file imports log/slog. If it still imports log, check if any log.Printf calls remain. If not, remove the log import.

Step 6: Present the changes

Show the user the changes with clear explanation of what each log line captures and why.

Examples

Good log calls

// Tool invocation — all required fields present
slog.Info("tool invoked",
    slog.String("tool", toolName),
    slog.String("broker", brokerAlias),
    slog.String("outcome", "success"),
    slog.Duration("duration", elapsed))

// Error with structured context — no raw err.Error() from external source
slog.Error("SEMP call failed",
    slog.String("tool", toolName),
    slog.String("broker", brokerAlias),
    slog.String("operation", opID),
    slog.Int("http_status", statusCode))

// Startup — alias list, not config map
slog.Info("server starting",
    slog.String("port", cfg.Port),
    slog.Int("broker_count", len(cfg.Brokers)),
    slog.Any("broker_aliases", pool.Aliases()))

Bad log calls (never write these)

// BAD: raw struct may contain credentials
slog.Info("config loaded", slog.Any("config", cfg))

// BAD: fmt.Sprintf with external data in message
slog.Info(fmt.Sprintf("tool %s called", userInput))

// BAD: logging password
slog.Info("broker connected", slog.String("password", config.Auth.Password))

// BAD: raw error from SEMP may contain credentials
slog.Error("failed", slog.String("error", err.Error()))

Rules

  • Every log line must pass the Never-Log list check from docs/_internal/secure-logging-rules.md
  • Every significant event must include the fields from the Always-Log table
  • If unsure whether something is safe to log, don't log it — flag it for the user
  • When migrating from log.Printf, don't just swap the call — redesign it with structured fields

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.