explain-report

Name: explain-report
Author: minghinmatthewlam

34stars4forks

How to install explain-report?

minghinmatthewlam/agent-guards/explain-report

$npx -y skills add minghinmatthewlam/agent-guards --skill explain-report

Installs into the current project.

Summary

Create a focused, self-contained HTML report that helps the user understand, retain, and act on important information. Use when the user requests an HTML report or visual explanation; when substantial research, architecture, project knowledge, audits, incidents, comparisons, or a

Files · 1

View on GitHub

SKILL.md

1	# Explain Report
2
3	Create one readable HTML artifact that presents important, accepted information with a concise entry point and progressively available depth.
4
5	This skill owns presentation and understanding, not investigation quality or verification. Build the report from source-backed or orchestrator-accepted material. Link tests, screenshots, recordings, traces, logs, citations, and source files; never treat the report as proof by itself.
6
7	## Decide When To Use It
8
9	Use the report when at least one of these is true:
10
11	- the user explicitly asks for an HTML report, visual explanation, learning guide, or durable handoff;
12	- the information is important to understanding the project, its architecture, a major decision, or a significant body of work;
13	- several sources, components, findings, states, or trade-offs are easier to understand together than as linear chat;
14	- keeping chat concise would otherwise hide supporting context the user is likely to revisit;
15	- a visual relationship, comparison, hierarchy, flow, or timeline materially improves understanding.
16
17	Skip it for routine progress, transient heartbeat updates, small factual answers, minor changes, or material that has not been verified enough to present as accepted. Importance, not raw task size, is the deciding factor.
18
19	## Choose A Mode
20
21	Choose the mode without requiring the user to name it:
22
23	- Learning: concepts, mental model, examples, misconceptions, and how the pieces fit.
24	- Research: synthesized findings, source agreement or conflict, evidence quality, and implications.
25	- Decision: options, trade-offs, recommendation, assumptions, and decision criteria.
26	- Audit or incident: findings, impact, timeline when relevant, evidence, remediation, and residual risk.
27	- System or architecture: components, boundaries, ownership, data or control flow, and operational behavior.
28	- Change: when this skill was invoked directly for a code change, switch to `/explain-diff`. When already following this skill from `/explain-diff`, continue with these shared rules and add its code-change requirements.
29
30	Combine modes only when it improves the user's understanding. Do not create separate reports when one coherent report can cover the accepted material.
31
32	## Build The Report
33
34	Write one self-contained `.html` file with embedded CSS and only small optional JavaScript for navigation or lightweight interaction. The page must remain readable without JavaScript.
35
36	Use a durable global path when the user requested the artifact, the orchestrator designated it as the integrated report, or the report is intended as retained project knowledge:
37
38	```text
39	~/.codex/artifacts/reports/YYYY-MM-DD-<slug>.html
40	```
41
42	Use `/tmp/YYYY-MM-DD-<slug>.html` for forward tests, exploratory or worker-local reports, and other disposable artifacts. Create the parent directory when needed. Return the absolute path.
43
44	Adapt depth to the subject. Do not force a long report when a compact page is clearer.
45
46	## Information Architecture
47
48	Start with a concise layer that lets the user understand the outcome without reading the entire page:
49
50	1. At A Glance: purpose, result, and every item that materially affects what the user should do or believe.
51	2. Mental Model Or Key Findings: the central explanation, organized by concept rather than source order.
52	3. Evidence And Confidence: citations, source or proof links, verified facts, inference, conflicts, and unknowns.
53	4. Implications Or Decisions: actions, trade-offs, or how this changes the user's understanding.
54	5. Risks And Open Questions: residual uncertainty and follow-up work.
55	6. Supporting Detail: useful depth placed later or in semantic `<details>` blocks.
56
57	Rename or omit sections when the selected mode makes another structure clearer, but preserve the functions above. Use P0/P1/P2 as priority classes when ranking matters; repeat them as needed and never impose a fixed findings count.
58
59	## Visual And Writing Style
60
61	Choose the smallest useful visual:
62
63	- a flow or sequence for processes and interactions;
64	- a comparison table for options or repeated fields;
65	- a timeline for incidents or evolution;
66	- a hierarchy for ownership or nesting;
67	- a before/after representation for changed state;
68	- a simplified system or UI representation when spatial relationships matter.
69
70	Use normal semantic HTML and CSS. Avoid ASCII diagrams, decorative dashboards, quizzes

People who liked this also viewed

6 picks

Type

explain-report

34stars4forks

View on GitHub

How to install explain-report?

minghinmatthewlam/agent-guards/explain-report

$npx -y skills add minghinmatthewlam/agent-guards --skill explain-report

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Explain Report
2
3	Create one readable HTML artifact that presents important, accepted information with a concise entry point and progressively available depth.
4
5	This skill owns presentation and understanding, not investigation quality or verification. Build the report from source-backed or orchestrator-accepted material. Link tests, screenshots, recordings, traces, logs, citations, and source files; never treat the report as proof by itself.
6
7	## Decide When To Use It
8
9	Use the report when at least one of these is true:
10
11	- the user explicitly asks for an HTML report, visual explanation, learning guide, or durable handoff;
12	- the information is important to understanding the project, its architecture, a major decision, or a significant body of work;
13	- several sources, components, findings, states, or trade-offs are easier to understand together than as linear chat;
14	- keeping chat concise would otherwise hide supporting context the user is likely to revisit;
15	- a visual relationship, comparison, hierarchy, flow, or timeline materially improves understanding.
16
17	Skip it for routine progress, transient heartbeat updates, small factual answers, minor changes, or material that has not been verified enough to present as accepted. Importance, not raw task size, is the deciding factor.
18
19	## Choose A Mode
20
21	Choose the mode without requiring the user to name it:
22
23	- Learning: concepts, mental model, examples, misconceptions, and how the pieces fit.
24	- Research: synthesized findings, source agreement or conflict, evidence quality, and implications.
25	- Decision: options, trade-offs, recommendation, assumptions, and decision criteria.
26	- Audit or incident: findings, impact, timeline when relevant, evidence, remediation, and residual risk.
27	- System or architecture: components, boundaries, ownership, data or control flow, and operational behavior.
28	- Change: when this skill was invoked directly for a code change, switch to `/explain-diff`. When already following this skill from `/explain-diff`, continue with these shared rules and add its code-change requirements.
29
30	Combine modes only when it improves the user's understanding. Do not create separate reports when one coherent report can cover the accepted material.
31
32	## Build The Report
33
34	Write one self-contained `.html` file with embedded CSS and only small optional JavaScript for navigation or lightweight interaction. The page must remain readable without JavaScript.
35
36	Use a durable global path when the user requested the artifact, the orchestrator designated it as the integrated report, or the report is intended as retained project knowledge:
37
38	```text
39	~/.codex/artifacts/reports/YYYY-MM-DD-<slug>.html
40	```
41
42	Use `/tmp/YYYY-MM-DD-<slug>.html` for forward tests, exploratory or worker-local reports, and other disposable artifacts. Create the parent directory when needed. Return the absolute path.
43
44	Adapt depth to the subject. Do not force a long report when a compact page is clearer.
45
46	## Information Architecture
47
48	Start with a concise layer that lets the user understand the outcome without reading the entire page:
49
50	1. At A Glance: purpose, result, and every item that materially affects what the user should do or believe.
51	2. Mental Model Or Key Findings: the central explanation, organized by concept rather than source order.
52	3. Evidence And Confidence: citations, source or proof links, verified facts, inference, conflicts, and unknowns.
53	4. Implications Or Decisions: actions, trade-offs, or how this changes the user's understanding.
54	5. Risks And Open Questions: residual uncertainty and follow-up work.
55	6. Supporting Detail: useful depth placed later or in semantic `<details>` blocks.
56
57	Rename or omit sections when the selected mode makes another structure clearer, but preserve the functions above. Use P0/P1/P2 as priority classes when ranking matters; repeat them as needed and never impose a fixed findings count.
58
59	## Visual And Writing Style
60
61	Choose the smallest useful visual:
62
63	- a flow or sequence for processes and interactions;
64	- a comparison table for options or repeated fields;
65	- a timeline for incidents or evolution;
66	- a hierarchy for ownership or nesting;
67	- a before/after representation for changed state;
68	- a simplified system or UI representation when spatial relationships matter.
69
70	Use normal semantic HTML and CSS. Avoid ASCII diagrams, decorative dashboards, quizzes

People who liked this also viewed

6 picks

Type