diff --git a/README.md b/README.md index 6169d60..9256585 100644 --- a/README.md +++ b/README.md @@ -10,17 +10,19 @@ Each top-level folder is a self-contained, directly installable skill. | Skill | Purpose | | --- | --- | -| [`sysadmin-windows-startup-performance`](sysadmin-windows-startup-performance/) | Diagnose Windows startup performance with read-only baselines and data-driven analysis. | +| [`sysadmin-windows-startup-performance`](https://github.com/KarmCraft/skills-library/tree/main/sysadmin-windows-startup-performance) | Diagnose Windows startup performance with read-only baselines and data-driven analysis. | +| [`sysadmin-windows-startup-remediation`](https://github.com/KarmCraft/skills-library/tree/main/sysadmin-windows-startup-remediation) | Plan approved, reversible Windows startup changes from analysis findings. | ## Install Copy the skill folder you want into the skill directory used by your agent runtime. -For Codex on Windows: +Generic Windows example from the repository root: ```powershell $SkillName = "" -Copy-Item -Recurse ".\$SkillName" "$env:USERPROFILE\.codex\skills\$SkillName" +$SkillRoot = "" +Copy-Item -Recurse ".\$SkillName" (Join-Path $SkillRoot $SkillName) ``` For other `SKILL.md` compatible tools, use their documented skill location. diff --git a/sysadmin-windows-startup-performance/SKILL.md b/sysadmin-windows-startup-performance/SKILL.md index a52546e..430a74d 100644 --- a/sysadmin-windows-startup-performance/SKILL.md +++ b/sysadmin-windows-startup-performance/SKILL.md @@ -1,6 +1,6 @@ --- name: sysadmin-windows-startup-performance -description: Collect and analyze read-only Windows startup performance baselines. Use when Codex is asked to diagnose slow Windows boot or login, collect Diagnostics-Performance event log data, inspect startup apps, services, scheduled tasks, resource pressure, recent boot warnings, or prepare conservative data-driven recommendations without changing system configuration. +description: Collect and analyze read-only Windows startup performance baselines. Use when an agent or automation harness is asked to investigate slow Windows boot, sign-in, login delay, startup apps, registry Run keys, Startup folder items, scheduled tasks, services, Diagnostics-Performance event IDs 100-110, boot warnings, resource pressure, or produce evidence-based recommendations without changing system configuration. --- # Sysadmin Windows Startup Performance diff --git a/sysadmin-windows-startup-performance/agents/openai.yaml b/sysadmin-windows-startup-performance/agents/openai.yaml index fdef6a7..8d76c14 100644 --- a/sysadmin-windows-startup-performance/agents/openai.yaml +++ b/sysadmin-windows-startup-performance/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Sysadmin Windows Startup Performance" - short_description: "Diagnose Windows startup performance." - default_prompt: "For a first-time assessment, guide the user through five reboot cycles. After each boot, wait 3 to 5 minutes, then run $sysadmin-windows-startup-performance to collect one read-only startup baseline. After the fifth collection, run the single-baseline analyzer on the latest collection; when comparison is needed, analyze earlier baseline files one at a time and summarize repeated patterns." + short_description: "Measure slow Windows boot and login." + default_prompt: "Use $sysadmin-windows-startup-performance to collect elevated read-only Windows boot/login baselines and analyze slow startup evidence." diff --git a/sysadmin-windows-startup-performance/references/safety.md b/sysadmin-windows-startup-performance/references/safety.md index ee4752a..e1f4a27 100644 --- a/sysadmin-windows-startup-performance/references/safety.md +++ b/sysadmin-windows-startup-performance/references/safety.md @@ -40,6 +40,8 @@ If the user asks for changes, first provide a dry-run plan with: Require explicit approval before applying changes. +If uninstall guidance is requested and normal Windows uninstall entries are missing or broken, prefer first-party vendor cleanup tools from official sources. Recommend third-party removal tools only when no first-party option exists and the tool has a strong, long-standing community or professional-use history. Avoid unproven cleanup tools, repackaged installers, SEO download portals, and mirror-only sources. + ## Recommendation Threshold Prefer three or more comparable post-reboot baselines before recommending persistent startup changes. A single baseline is enough to identify what to measure next, not enough to aggressively optimize. diff --git a/sysadmin-windows-startup-performance/templates/local-performance/README.md b/sysadmin-windows-startup-performance/templates/local-performance/README.md index 41b4dbb..ece7744 100644 --- a/sysadmin-windows-startup-performance/templates/local-performance/README.md +++ b/sysadmin-windows-startup-performance/templates/local-performance/README.md @@ -11,8 +11,9 @@ Copy the skill scripts into `scripts/`, then run from an elevated PowerShell ses Generated baselines go in `state/`; Markdown reports go in `reports/`; logs are reserved for future scheduled runs. -To install this skill into Codex from the repository root: +To install this skill from the repository root into a compatible agent runtime: ```powershell -Copy-Item -Recurse .\sysadmin-windows-startup-performance "$env:USERPROFILE\.codex\skills\sysadmin-windows-startup-performance" +$SkillRoot = "" +Copy-Item -Recurse .\sysadmin-windows-startup-performance (Join-Path $SkillRoot "sysadmin-windows-startup-performance") ``` diff --git a/sysadmin-windows-startup-remediation/SKILL.md b/sysadmin-windows-startup-remediation/SKILL.md new file mode 100644 index 0000000..8421694 --- /dev/null +++ b/sysadmin-windows-startup-remediation/SKILL.md @@ -0,0 +1,44 @@ +--- +name: sysadmin-windows-startup-remediation +description: Plan and apply approved, reversible Windows startup remediation from prior analysis. Use when an agent or automation harness is asked to act on startup findings, disable or reconfigure autostart entries, registry Run keys, Startup folder items, Task Scheduler logon or startup tasks, auto-start services, vendor launchers or updaters, prepare rollback, vet uninstall tools, write change records, or verify post-change startup behavior with explicit approval. +--- + +# Sysadmin Windows Startup Remediation + +## Overview + +Use this skill after Windows startup performance analysis identifies candidates for action. It turns evidence into a dry-run remediation plan, requires explicit approval per target, applies only reversible changes, and records verification and rollback details. + +## Files + +- `references/safety.md`: approval, rollback, and stop rules. +- `references/target-types.md`: supported Windows startup target types and preferred actions. +- `templates/remediation-plan.md`: dry-run plan template to prepare before changes. +- `templates/change-record.md`: execution and verification record template. +- `reports/`: generated remediation plans and human-readable records. +- `state/`: local machine-specific execution state, snapshots, and rollback notes. +- `tools/`: reserved for future small helper utilities; no mutation tool is bundled yet. + +## Workflow + +1. Start from evidence: use a startup analysis JSON or report, preferably from the [`sysadmin-windows-startup-performance`](https://github.com/KarmCraft/skills-library/tree/main/sysadmin-windows-startup-performance) skill. If no analysis exists, ask to collect/read one first. +2. Read `references/safety.md` before proposing or applying changes. +3. Read `references/target-types.md` for target-specific action and rollback patterns. +4. Produce a dry-run plan using `templates/remediation-plan.md`; include exact target identity, evidence, proposed action, risk, expected effect, elevation needs, and rollback. +5. Ask for explicit approval for each target or clearly named group of identical low-risk targets. Do not treat general optimization intent as approval. +6. Before applying a change, capture current state needed for rollback and write/update a local record under `state/` or `reports/`. +7. Apply the least invasive reversible action. Prefer supported product settings or Windows-supported enable/disable operations over deleting registry values or files. +8. Verify immediately where possible, then recommend a reboot and a fresh performance baseline to measure effect. +9. Write a change record using `templates/change-record.md` with what changed, commands or manual steps used, verification result, and rollback path. + +## Operating Rules + +- Do not change startup entries, scheduled tasks, services, drivers, security tools, update tools, backup tools, sync-critical tools, or vendor utilities without explicit approval. +- Do not uninstall software by default. Prefer disabling startup behavior first unless the user explicitly requests uninstall guidance. +- Do not remove registry values or startup shortcuts when a reversible disable, rename, move-to-quarantine, or app setting is available. +- Do not batch many unrelated changes into one approval. Keep changes small enough to attribute startup impact. +- After each material change set, recommend rebooting, waiting 3 to 5 minutes after login, and collecting another read-only baseline. + +## Output + +Use `reports/` for human-readable plans and records, and `state/` for local snapshots or rollback state. These folders are ignored except for `.gitkeep` placeholders. diff --git a/sysadmin-windows-startup-remediation/agents/openai.yaml b/sysadmin-windows-startup-remediation/agents/openai.yaml new file mode 100644 index 0000000..13ae148 --- /dev/null +++ b/sysadmin-windows-startup-remediation/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Sysadmin Windows Startup Remediation" + short_description: "Plan reversible startup fixes." + default_prompt: "Use $sysadmin-windows-startup-remediation to plan approved, reversible startup changes from Windows startup analysis findings." diff --git a/sysadmin-windows-startup-remediation/references/safety.md b/sysadmin-windows-startup-remediation/references/safety.md new file mode 100644 index 0000000..3009bec --- /dev/null +++ b/sysadmin-windows-startup-remediation/references/safety.md @@ -0,0 +1,55 @@ +# Safety + +This skill is change-capable, so default to conservative behavior. + +## Approval Rules + +- Require explicit approval before every system change. +- Approval must name the target or plan item. If approval is broad or ambiguous, ask for clarification. +- Explain whether elevation is required before running elevated commands. +- Prefer one small change set at a time so boot impact can be attributed. + +## Required Before Change + +Every remediation item needs: + +- target identity +- evidence from analysis or local inspection +- proposed action +- expected effect +- risk and side effects +- exact rollback path +- verification step + +If any of these are missing, prepare the plan but do not apply the change. + +## Stop Rules + +Stop and ask before touching: + +- Microsoft, Windows, driver, firmware, antivirus, EDR, firewall, backup, disk, update, or identity components +- services with unclear dependencies +- startup entries owned by active development tools, sync clients, device utilities, or hardware control software when the user's workflow may depend on them +- entries whose publisher, executable, or purpose cannot be identified +- anything that requires deletion instead of a reversible disable or move + +## Download And Uninstall Tool Rules + +Treat downloading or running any removal, cleanup, or uninstall helper as a separate approved system change. Prefer first-party vendor tools from official support or download pages. Use third-party tools only when there is no first-party option and the tool has a strong, long-standing community or professional-use history. + +Do not use unproven cleanup tools, repackaged installers, SEO download portals, or mirror-only sources. Before proposing a tool, document its source URL, publisher, trust rationale, signature or hash when available, required elevation, expected scope, and rollback limitations. + +## Rollback Rules + +Capture current state before changing anything. Rollback must be feasible without guessing. + +Examples: + +- registry startup entry: record key path, value name, and original command +- Windows Task Scheduler task: record task path, task name, enabled state, triggers, actions, conditions, settings, and an exported XML copy before disabling; rollback by re-enabling the task or restoring the XML export +- service: record service name, startup type, delayed-auto setting if known, and current state +- startup-folder item: move to a clearly named quarantine folder and record original path + +## Verification + +After changes, verify the target state directly, then measure actual startup impact with a fresh reboot baseline. Do not claim startup improved from a configuration change alone. diff --git a/sysadmin-windows-startup-remediation/references/target-types.md b/sysadmin-windows-startup-remediation/references/target-types.md new file mode 100644 index 0000000..a5795ad --- /dev/null +++ b/sysadmin-windows-startup-remediation/references/target-types.md @@ -0,0 +1,63 @@ +# Target Types + +Use this reference to choose conservative actions for common startup targets. + +## Registry Run Entries + +Typical fields: `scope`, `kind`, `key_path`, `name`, `command`. + +Preferred actions: + +- use the application's own setting if available +- disable through Windows Startup Apps UI or Task Manager when possible +- as a fallback, export or record the value and move it to a rollback-safe holding key instead of deleting it + +Rollback: restore the original value name and command to the original key. + +## Startup Folder Items + +Typical fields: `scope`, `name`, `extension`, `path`, `command`. + +Preferred action: move the shortcut or file to a timestamped quarantine folder outside the Startup folder. + +Rollback: move the exact file back to the original path. + +## Scheduled Startup Or Logon Tasks + +Typical fields: `task_path`, `task_name`, `state`, `author`, `trigger_types`, `actions`. + +Preferred action: `Disable-ScheduledTask` for clearly nonessential third-party tasks. + +Rollback: `Enable-ScheduledTask` for the same task path and name. + +Do not modify tasks from Microsoft, security software, backup tools, device drivers, or update systems without a stronger reason and explicit user approval. + +## Auto-Start Services + +Typical fields: `name`, `display_name`, `state`, `status`, `delayed_auto_start`, `service_account`, `path`. + +Preferred actions: + +- leave services unchanged unless evidence is strong +- prefer vendor app settings first +- prefer delayed automatic or manual over disabled when appropriate + +Rollback: restore original startup type and delayed-auto setting, then start the service if it was running before. + +## Vendor Launchers And Updaters + +Prefer application settings or vendor-supported startup toggles. If the component only checks updates or opens a tray UI, disabling startup may be reasonable. If it controls hardware, licensing, backup, sync, or security, stop and ask. + +## Uninstall Guidance + +Uninstall is not the default remediation path. Provide uninstall guidance only when the user explicitly asks or when the analysis shows an unwanted application and disabling startup does not address the problem. + +Prefer standard Windows Apps and Features entries, the application's own uninstaller, or the vendor's documented installer maintenance mode first. When a program has no Add/Remove Programs entry, has a broken uninstall entry, or uses an extended installer that requires a cleanup utility, guidance may include a dedicated remover only after source vetting. + +Prefer tools in this order: + +- first-party vendor removal or cleanup tools from official support/download pages +- operating-system or package-manager supported uninstall mechanisms +- trusted third-party tools with a long community and professional-use history, only when no first-party option exists + +Avoid unproven cleanup tools, SEO download portals, repackaged installers, mirror sites without provenance, and utilities that bundle unrelated software. For any downloaded tool, record the source URL, publisher, reason it is trusted, signature or hash when available, required elevation, expected scope, and rollback limitations. Ask for explicit approval before downloading and again before running any removal tool. diff --git a/sysadmin-windows-startup-remediation/reports/.gitkeep b/sysadmin-windows-startup-remediation/reports/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/sysadmin-windows-startup-remediation/state/.gitkeep b/sysadmin-windows-startup-remediation/state/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/sysadmin-windows-startup-remediation/templates/change-record.md b/sysadmin-windows-startup-remediation/templates/change-record.md new file mode 100644 index 0000000..f10071c --- /dev/null +++ b/sysadmin-windows-startup-remediation/templates/change-record.md @@ -0,0 +1,28 @@ +# Windows Startup Remediation Record + +Plan: +Executed at: +Executed by: +Approved by: + +## Changes Applied + +| ID | Target | Action | Command or manual step | Result | +| --- | --- | --- | --- | --- | +| R1 | | | | | + +## Rollback State + +| ID | Rollback command or manual path | State captured | +| --- | --- | --- | +| R1 | | | + +## Verification + +- Immediate verification: +- Reboot baseline: +- Observed effect: + +## Notes + +- TBD diff --git a/sysadmin-windows-startup-remediation/templates/remediation-plan.md b/sysadmin-windows-startup-remediation/templates/remediation-plan.md new file mode 100644 index 0000000..8859b0b --- /dev/null +++ b/sysadmin-windows-startup-remediation/templates/remediation-plan.md @@ -0,0 +1,39 @@ +# Windows Startup Remediation Plan + +Source analysis: +Baseline or report: +Prepared at: +Prepared by: + +## Summary + +- Goal: +- Scope: +- Non-goals: +- Required approval: + +## Candidate Changes + +| ID | Target | Type | Evidence | Proposed action | Expected effect | Risk | Elevation | Rollback | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| R1 | | | | | | | | | + +## Execution Order + +1. TBD + +## Pre-Change Snapshot + +- TBD + +## Verification Plan + +- Immediate verification: +- Reboot verification: +- Follow-up baseline path: + +## Approval + +Approved items: +Approver: +Approval timestamp: diff --git a/sysadmin-windows-startup-remediation/tools/.gitkeep b/sysadmin-windows-startup-remediation/tools/.gitkeep new file mode 100644 index 0000000..e69de29