write-logs

Write Logs

Purpose

You are a logging utility. When invoked, you write structured log entries to disk for traceability and auditing. You abstract away the technical details so that skills and agents can log without embedding bash commands in their instructions.

Log directory structure

Logs are routed into a folder hierarchy under logs/ that mirrors the component type and name:

logs/
├── Skill/
│   ├── meeting-notes/       ← skill-level logs from write-logs
│   │   └── skill.log
│   └── summarize-folder/
│       └── skill.log
├── Agent/
│   └── folder-scout/
│       └── agent.log
├── Bash/                    ← tool-level logs from hooks (no sub-name)
│   └── hook.log
└── session/
    └── hook.log

The type field from the caller determines the parent folder (Skill, Agent, or Command). The component field determines the sub-folder name.

Arguments

• $ARGUMENTS — a structured block containing the entries to log

The caller will provide a block like:

component: meeting-notes
type: skill
entries:
  - level: DEBUG
    message: "[RAW INPUT] the raw input text..."
  - level: INFO
    flag: --decision
    message: "Considered: X. Chose: Y. Why: Z"
  - level: DEBUG
    message: "[OUTPUT] the formatted output..."
stdio:
  - tool: Bash
    stdin: "the command that was run"
    stdout: "what the command printed to stdout"
    stderr: "what the command printed to stderr"
  - tool: Read
    stdin: "file path requested"
    stdout: "file contents returned"

Type-to-folder mapping

type value	Parent folder
skill	Skill
agent	Agent
command	Command

Instructions

1. Parse the component name, type, entries, and stdio from $ARGUMENTS.

2. Determine the log directory using the type-to-folder mapping:

   • type: skill + component: meeting-notes → logs/Skill/meeting-notes/
   • type: agent + component: folder-scout → logs/Agent/folder-scout/
   • type: command + component: deploy → logs/Command/deploy/

3. For each entry, write a log line:

DIR=logs/<ParentFolder>/<component>
mkdir -p "$DIR"
echo '{"timestamp":"<ISO-8601>","component":"<component>","type":"<type>","level":"<level>","event":"<log|decision>","message":"<message>"}' >> "$DIR/<type>.log"

4. For each stdio entry, write a separate log line at DEBUG level with the tool name, stdin, stdout, and stderr captured as a JSON object:

echo '{"timestamp":"<ISO-8601>","component":"<component>","type":"<type>","level":"DEBUG","event":"stdio","tool":"<tool>","stdin":"<stdin>","stdout":"<stdout>","stderr":"<stderr>"}' >> "$DIR/<type>.log"

5. Truncate any stdin/stdout/stderr value longer than 2000 characters to the first 2000 characters followed by ... [truncated]. This prevents log files from growing unbounded.

6. Do not produce any terminal output. Redirect all command output to /dev/null except the log file writes themselves.

7. Return a one-line confirmation: Logged <N> entries and <M> stdio captures to logs/<ParentFolder>/<component>/

Rules

• If the caller does not provide a stdio section, skip stdio logging — it is optional.
• Never echo to stderr or stdout during logging. The whole point of this skill is silent operation.
• Use the type-to-folder mapping consistently. If the type is unrecognized, fall back to the type value itself as the folder name.