Agent Skills › Ephemeral-AI-Lab/layerfs › layerfs-sdk-observe

layerfs-sdk-observe

GitHub

用于观察、测量和排查 LayerFS 运行时状态，通过调用链追踪、存储指标和守护进程日志进行诊断，不涉及实际工作执行。

.agents/skills/layerfs-sdk-observe/SKILL.md Ephemeral-AI-Lab/layerfs

Trigger Scenarios

需要分析 SDK 调用耗时和阶段性能检查存储去重压缩历史或异常膨胀排查 Daemon 内部操作如 Store、SQLite 行为查看 Workspace 未提交内容或文件历史

Install

npx skills add Ephemeral-AI-Lab/layerfs --skill layerfs-sdk-observe -g -y

More Options

Non-standard path

npx skills add https://github.com/Ephemeral-AI-Lab/layerfs/tree/main/.agents/skills/layerfs-sdk-observe -g -y

Use without installing

npx skills use Ephemeral-AI-Lab/layerfs@layerfs-sdk-observe

指定 Agent (Claude Code)

npx skills add Ephemeral-AI-Lab/layerfs --skill layerfs-sdk-observe -a claude-code -g -y

安装 repo 全部 skill

npx skills add Ephemeral-AI-Lab/layerfs --all -g -y

预览 repo 内 skill

npx skills add Ephemeral-AI-Lab/layerfs --list

SKILL.md

Frontmatter

{
    "name": "layerfs-sdk-observe",
    "description": "Use when observing, measuring or troubleshooting a LayerFS run rather than doing the work itself. Activates on the LayerFS call trace (`LAYERFS_TRACE`, `LAYERFS_TRACE_STEP`), SDK operation timing and phase breakdowns, LayerFS storage deduplication and compression over history, `@layerfs\/sdk\/operator` (`store.stats`, `store.commits`, `files.history`, `workspace.overlay`, `process.*`), or LayerFS daemon logs and observation records."
}

Observing a LayerFS run

Status: Current general guide. For whoever watches or troubleshoots a LayerFS run (an orchestrator, a maintainer), not for an agent doing the work. Using the SDK is the separate layerfs-js-sdk skill.

This skill uses internal surfaces: the @layerfs/sdk/operator entry point, the opt-in call trace and the daemon's diagnostic records. None of them changes the project. Don't hand them to an agent doing production work.

Question	Source	Page
How long did each SDK call take, and which phase was slow?	Call trace (`LAYERFS_TRACE`) with phase timing	tracing
Is storage deduplicating and compressing over a long history, or blowing up?	`operator.store.stats`, `operator.store.commits`, trace `sizes`	storage metrics
What did the Store, SQLite, locks and FUSE do during a call?	Daemon records in `docker logs`, decoded and joined to the trace	daemon logs
What does a Workspace hold uncommitted, what is a file's history, which background processes run?	Operator methods	operator

Collecting a run

For an agent run you want to analyse afterwards:

Before the run, set LAYERFS_TRACE=<run>/trace.jsonl for every process. Ask the agent to set LAYERFS_TRACE_STEP on each command it runs.
Record identities: LayerFS commit, daemon binary, runtime image digest, addon build.
Snapshot operator.store.stats() at the start, every N Commits if you can, and at the end.
After the run, before closing the Sandboxes: page operator.store.commits(branch) for every Branch, and save docker logs <container> for every Sandbox (the container identifier is in $LAYERFS_HOME/_sandboxes/<sandbox name>/container).
Decode and join: see daemon logs. Build the per-step table: see storage metrics.