agents-introspection

Name: agents-introspection
Author: PaulRBerg

66installs3forks

How to install agents-introspection?

paulrberg/agent-skills/agents-introspection

$npx -y skills add PaulRBerg/agent-skills --skill agents-introspection

Installs into the current project.

Summary

Retrospect on a task against local Codex/Claude Code transcripts; propose durable fixes (AGENTS.md, skills).

Files · 1

View on GitHub

SKILL.md

1	# Agents Introspection
2
3	Determine whether prior Codex and Claude Code work in the current project establishes a recurrence risk for the user's
4	task, then recommend the smallest durable intervention justified by the evidence.
5
6	Success means the report identifies transcript coverage, separates observed behavior from inference, applies a
7	consistent evidence bar, and either proposes a concrete prevention step or explains why no durable change is justified.
8
9	## Input
10
11	- `<task>` (required): the task, decision, incident, or workflow to evaluate. If omitted but the current conversation
12	states it clearly, use that task; otherwise ask for the missing task.
13
14	## Scope and Authority
15
16	- Inspect only Codex and Claude Code transcripts whose metadata or cwd resolves to the current project. Include another
17	project only when the user explicitly names its path.
18	- Treat every transcript as sensitive plaintext. Summarize instead of quoting; redact secrets, private addresses,
19	tokens, emails, and personal or customer data.
20	- Inspect and report by default. Edit AGENTS.md or skills only when the user explicitly asks to apply or implement
21	fixes, then make the smallest in-scope local change and validate it.
22	- Never modify transcript stores, write transcript excerpts or derived private data into repository files, or perform
23	external writes.
24
25	## Bounded Retrieval
26
27	Read `references/transcript-sources.md`, resolve the current project with `pwd -P`, and choose 3–6 short, discriminative
28	keywords from relevant filenames, commands, tools, errors, package names, issue IDs, and skill names.
29
30	1. Run the bundled miner for the current project, active sessions only, with the chosen keywords and `--max-sessions 8`.
31	2. Treat miner scores, themes, and correction, failure, verification, tool, or privacy counts only as candidate-ranking
32	signals. They are heuristic and are never evidence by themselves.
33	3. Validate project metadata or cwd before opening a candidate. Inspect up to five highest-relevance transcript bodies,
34	stopping earlier when the evidence bar is met. Include a comparable successful session when available.
35	4. If evidence is insufficient, retry once with broader keywords. If active history still lacks signal, retry once with
36	`--include-archived`.
37	5. Exceed these bounds only to resolve contradictory evidence or satisfy an explicitly exhaustive request. If the helper
38	fails, use one project-scoped manual fallback from the reference.
39
40	Stop and report the coverage gap when the bounded fallbacks still lack useful evidence. Absence of evidence is not
41	evidence that a failure never occurred.
42
43	For unusually long searches, send sparse progress updates only when a retrieval fallback begins, a finding changes the
44	likely intervention, or the search reaches its explicit bound. Use an outcome-first line such as
45	`🔎 Broadening transcript search — <verified reason and bound>` or
46	`⏳ Checking archived sessions — <verified active/archived coverage>`. Ground counts and coverage claims in miner/tool
47	output; do not narrate routine transcript reads.
48
49	## Evidence Contract
50
51	For each relevant session, record only concise, auditable observations about:
52
53	- ignored or misread AGENTS.md or skill instructions;
54	- wrong cwd, project root, source path, or path encoding;
55	- over-broad edits, unrelated churn, overwritten user work, or destructive commands;
56	- tooling, shell, parsing, retry, or verification mistakes;
57	- invented claims, vague reports, or missing tests and checks;
58	- successful patterns that prevented mistakes.
59
60	Connect each observation to the current task and label any causal or recurrence claim as inference. State conflicts and
61	weak coverage rather than averaging them away.
62
63	Use these confidence levels:
64
65	- High: at least two independent relevant sessions directly support the same pattern and its relevance to the
66	current task.
67	- Medium: one unambiguous relevant session supports the finding, or multiple sessions provide mixed support.
68	- Low: only indirect, ambiguous, or heuristic signals exist. Do not recommend a durable repository change from
69	low-confidence evidence.
70
71	A durable change requires either the same failure in at least two independent sessions or one unambiguous high-impact
72	failure that exposes a missing stable invariant. Treat lower-impact one-offs as manual guardrails.
73
74	## Choose the Smallest Intervention
75
76	- Update AGENTS.md when the lesson is stable, project-wide, and useful to agents working in that scope.
77	- Update an existing skill when the failure belongs clearly inside its current workflow.
78	- Propose a new skill only for a repeated, reusable procedure that spans projects or repositories.
79	- Add a script only when deterministic discovery, parsing, or validation would otherwise be rei

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

agents-introspection

66installs3forks

View on GitHub

How to install agents-introspection?

paulrberg/agent-skills/agents-introspection

$npx -y skills add PaulRBerg/agent-skills --skill agents-introspection

Installs into the current project.

Summary

Retrospect on a task against local Codex/Claude Code transcripts; propose durable fixes (AGENTS.md, skills).

Files · 1

View on GitHub

SKILL.md

1	# Agents Introspection
2
3	Determine whether prior Codex and Claude Code work in the current project establishes a recurrence risk for the user's
4	task, then recommend the smallest durable intervention justified by the evidence.
5
6	Success means the report identifies transcript coverage, separates observed behavior from inference, applies a
7	consistent evidence bar, and either proposes a concrete prevention step or explains why no durable change is justified.
8
9	## Input
10
11	- `<task>` (required): the task, decision, incident, or workflow to evaluate. If omitted but the current conversation
12	states it clearly, use that task; otherwise ask for the missing task.
13
14	## Scope and Authority
15
16	- Inspect only Codex and Claude Code transcripts whose metadata or cwd resolves to the current project. Include another
17	project only when the user explicitly names its path.
18	- Treat every transcript as sensitive plaintext. Summarize instead of quoting; redact secrets, private addresses,
19	tokens, emails, and personal or customer data.
20	- Inspect and report by default. Edit AGENTS.md or skills only when the user explicitly asks to apply or implement
21	fixes, then make the smallest in-scope local change and validate it.
22	- Never modify transcript stores, write transcript excerpts or derived private data into repository files, or perform
23	external writes.
24
25	## Bounded Retrieval
26
27	Read `references/transcript-sources.md`, resolve the current project with `pwd -P`, and choose 3–6 short, discriminative
28	keywords from relevant filenames, commands, tools, errors, package names, issue IDs, and skill names.
29
30	1. Run the bundled miner for the current project, active sessions only, with the chosen keywords and `--max-sessions 8`.
31	2. Treat miner scores, themes, and correction, failure, verification, tool, or privacy counts only as candidate-ranking
32	signals. They are heuristic and are never evidence by themselves.
33	3. Validate project metadata or cwd before opening a candidate. Inspect up to five highest-relevance transcript bodies,
34	stopping earlier when the evidence bar is met. Include a comparable successful session when available.
35	4. If evidence is insufficient, retry once with broader keywords. If active history still lacks signal, retry once with
36	`--include-archived`.
37	5. Exceed these bounds only to resolve contradictory evidence or satisfy an explicitly exhaustive request. If the helper
38	fails, use one project-scoped manual fallback from the reference.
39
40	Stop and report the coverage gap when the bounded fallbacks still lack useful evidence. Absence of evidence is not
41	evidence that a failure never occurred.
42
43	For unusually long searches, send sparse progress updates only when a retrieval fallback begins, a finding changes the
44	likely intervention, or the search reaches its explicit bound. Use an outcome-first line such as
45	`🔎 Broadening transcript search — <verified reason and bound>` or
46	`⏳ Checking archived sessions — <verified active/archived coverage>`. Ground counts and coverage claims in miner/tool
47	output; do not narrate routine transcript reads.
48
49	## Evidence Contract
50
51	For each relevant session, record only concise, auditable observations about:
52
53	- ignored or misread AGENTS.md or skill instructions;
54	- wrong cwd, project root, source path, or path encoding;
55	- over-broad edits, unrelated churn, overwritten user work, or destructive commands;
56	- tooling, shell, parsing, retry, or verification mistakes;
57	- invented claims, vague reports, or missing tests and checks;
58	- successful patterns that prevented mistakes.
59
60	Connect each observation to the current task and label any causal or recurrence claim as inference. State conflicts and
61	weak coverage rather than averaging them away.
62
63	Use these confidence levels:
64
65	- High: at least two independent relevant sessions directly support the same pattern and its relevance to the
66	current task.
67	- Medium: one unambiguous relevant session supports the finding, or multiple sessions provide mixed support.
68	- Low: only indirect, ambiguous, or heuristic signals exist. Do not recommend a durable repository change from
69	low-confidence evidence.
70
71	A durable change requires either the same failure in at least two independent sessions or one unambiguous high-impact
72	failure that exposes a missing stable invariant. Treat lower-impact one-offs as manual guardrails.
73
74	## Choose the Smallest Intervention
75
76	- Update AGENTS.md when the lesson is stable, project-wide, and useful to agents working in that scope.
77	- Update an existing skill when the failure belongs clearly inside its current workflow.
78	- Propose a new skill only for a repeated, reusable procedure that spans projects or repositories.
79	- Add a script only when deterministic discovery, parsing, or validation would otherwise be rei

People who liked this also viewed

6 picks

Type