{
  "markdown": "# pskoett-ai-skills\n\nA collection of skills for AI agents. Follows the [Agent Skills specification](https://agentskills.io/specification).\nThis repository is my personal skill testing ground.\n\n## Philosophy\n\nEvery skill in this collection is built around a philosophy — a principle that addresses a specific failure mode in how agents work today. `plan-interview` is about collaborative planning: before codebase exploration starts, user and agent run a structured interview to align on constraints, scope, risk, and success criteria — and to surface whether a preparatory refactor should come before the main change. `intent-framed-agent` makes execution intent explicit so scope drift becomes visible. `context-surfing` monitors context quality and exits cleanly before degradation corrupts output. `verify-gate` runs compile, test, and lint checks so the agent doesn't need you to tell it the output was wrong if a test can. `self-healing` turns mid-task failures into verified, reusable artifacts instead of swept-under-the-rug retries. `simplify-and-harden` uses the peak context at end-of-task for a focused quality and security review. `self-improvement` turns repeated mistakes into durable rules that persist across sessions.\n\nThe common thread: agents have peak context at specific moments — after planning, mid-execution, at completion, after learning — and these skills are designed to exploit those peaks. Each skill encodes a philosophy that agents struggle to internalize on their own, turning it into a structured workflow they can follow reliably.\n\nIf you want to improve agent output over time, you need two loops, not one. The inner loop catches failures during a running session: the agent detects a problem, verifies its work against machine signals, and — with `self-healing` — recovers, files the verified fix as a reusable artifact, and continues, without you touching anything. The outer loop closes gaps across sessions: you capture where the agent failed, figure out what knowledge was missing, and encode it somewhere the agent can reach next time. `learning-aggregator` reads accumulated learnings across sessions and surfaces patterns. `harness-updater` encodes those patterns as permanent rules in project instruction files. `eval-creator` turns promoted rules into regression tests. `pre-flight-check` surfaces all of this at the start of the next session — closing the loop. The knowledge gaps get smaller with every cycle as it compounds.\n\n`skill-pipeline` ties these pieces together by classifying the task and routing it through the right combination at the right depth.\n\nOne skill sits outside the two loops by design: `control-session-orchestrator` is an orchestration-layer skill, not an inner/outer-loop step. It runs *above* the pipeline — coordinating multi-agent, multi-session work from a Codex, Copilot, or agent-app control session — and is invoked directly rather than routed by `skill-pipeline`.\n\n## Install\n\nInstall as a Claude Code plugin from this repo's marketplace. Run each command from inside Claude Code:\n\n1. Register this repo as a plugin marketplace:\n   ```\n   /plugin marketplace add pskoett/pskoett-skills\n   ```\n2. Install the plugin from that marketplace:\n   ```\n   /plugin install pskoett-ai-skills@pskoett-skills\n   ```\n3. Reload so skills, agents, and hooks register:\n   ```\n   /reload-plugins\n   ```\n\nThis installs the full bundle: skills, audit agents, and hooks.\n\n### Codex\n\nThe same bundle now ships as a repo-local Codex plugin from `plugin/`.\n\n1. Open this repository in Codex.\n2. Restart Codex after pulling the latest repo state so it reloads repo marketplaces.\n3. Open the plugin directory, choose the `pskoett skills` marketplace, and install `pskoett-ai-skills`.\n\nCodex reads the marketplace from `.agents/plugins/marketplace.json` and the plugin manifest from `plugin/.codex-plugin/plugin.json`.\n\n### GitHub Copilot CLI\n\nThe same bundle ships as a Copilot CLI plugin nested under `plugin/.copilot-plugin/`, reusing the shared `plugin/skills/`, `plugin/agents/`, and `plugin/hooks/` content:\n\n```\ncopilot plugin marketplace add pskoett/pskoett-skills\ncopilot plugin install pskoett-ai-skills\n```\n\nCopilot reads the marketplace from `.github/plugin/marketplace.json` and the plugin manifest from `plugin/.copilot-plugin/plugin.json`.\n\n### Individual skills via GitHub CLI (`gh skill`)\n\nGitHub CLI now supports Agent Skills via [`gh skill`](https://cli.github.com/manual/gh_skill_install). Requires GitHub CLI `v2.90.0` or later.\n\n```bash\n# Browse this repo's skills interactively\ngh skill install pskoett/pskoett-skills\n\n# Install specific skills directly\ngh skill install pskoett/pskoett-skills verify-gate\ngh skill install pskoett/pskoett-skills self-healing\ngh skill install pskoett/pskoett-skills simplify-and-harden\ngh skill install pskoett/pskoett-skills self-improvement\n\n# Target a specific host and scope when needed\ngh skill install pskoett/pskoett-skills verify-gate --agent codex --scope user\n```\n\n`gh skill` installs to the correct skill directory for the selected host, including GitHub Copilot, Claude Code, Codex, Cursor, and Gemini CLI.\n\n### Individual skills via the Agent Skills CLI\n\nIf you only want specific skills and not the full plugin bundle:\n\n```bash\nnpx skills add pskoett/pskoett-skills/skills/verify-gate\nnpx skills add pskoett/pskoett-skills/skills/self-healing\nnpx skills add pskoett/pskoett-skills/skills/simplify-and-harden\nnpx skills add pskoett/pskoett-skills/skills/self-improvement\n```\n\nWorks with any agent following the [Agent Skills specification](https://agentskills.io/specification).\n\n### Manual install\n\nClone and copy (or symlink) the skill directories you want:\n\n```bash\ngit clone https://github.com/pskoett/pskoett-skills.git\ncp -r pskoett-skills/skills/verify-gate ~/.claude/skills/\n```\n\n\n## Structure\n\n```\nskills/\n  skill-name/\n    SKILL.md         # Required - skill definition with YAML frontmatter\n    scripts/         # Optional - executable code\n    references/      # Optional - documentation loaded on demand\n    assets/          # Optional - templates, images, data files\n```\n\n## Skills\n\n| Skill | Description |\n|-------|-------------|\n| [agent-teams-simplify-and-harden](skills/agent-teams-simplify-and-harden/) | Implementation + audit loop using parallel agent teams with structured simplify, harden, and document passes |\n| [context-surfing](skills/context-surfing/) | Monitors context window health and rides peak context quality for maximum output fidelity during multi-step execution |\n| [control-session-orchestrator](skills/control-session-orchestrator/) | Control-plane workflow for coordinating multi-agent, multi-session project work from Codex, GitHub Copilot, or agent-app sessions |\n| [intent-framed-agent](skills/intent-framed-agent/) | Captures a lightweight intent contract at execution start and monitors coding-task drift until resolution |\n| [plan-interview](skills/plan-interview/) | Runs a structured interview before planning non-trivial implementations |\n| [self-healing](skills/self-healing/) | Active runtime recovery — diagnose, patch, verify, file the verified fix when a command, test, helper, env, or external service fails mid-task |\n| [self-improvement](skills/self-improvement/) | Captures learnings and errors with hook-based activation and automatic skill extraction |\n| [skill-pipeline](skills/skill-pipeline/) | Pipeline orchestrator that classifies tasks and routes them through the right skill combination at the right depth |\n| [simplify-and-harden](skills/simplify-and-harden/) | Post-completion self-review that runs simplify, harden, and micro-documentation passes before signaling done |\n| [verify-gate](skills/verify-gate/) | Machine verification gate (compile, test, lint) between implementation and quality review with fix loop |\n| [learning-aggregator](skills/learning-aggregator/) | Cross-session analysis of .learnings/ files — finds patterns, ranks promotion candidates |\n| [pre-flight-check](skills/pre-flight-check/) | Session-start scan that surfaces relevant learnings, errors, and eval status before work begins |\n| [eval-creator](skills/eval-creator/) | Creates permanent eval cases from promoted learnings and runs regression checks |\n\n## CI Skills (gh-aw) (beta)\n\nHeadless CI variants for GitHub Agentic Workflows. Each mirrors an interactive skill but runs without human interaction — scanning, reporting, and optionally gating PRs.\n\n| Skill | Description |\n|-------|-------------|\n| [self-healing-ci](skills/self-healing-ci/) | CI-only self-healing workflow — diagnoses failed PR checks, proposes verified patches as PR comments or label-gated commits, files HEAL entries to `.learnings/HEALS.md` |\n| [self-improvement-ci](skills/self-improvement-ci/) | CI-only self-improvement workflow for recurring failure-pattern capture using gh-aw |\n| [simplify-and-harden-ci](skills/simplify-and-harden-ci/) | CI-only simplify/harden workflow for pull requests using gh-aw with headless scan/report gates |\n| [learning-aggregator-ci](skills/learning-aggregator-ci/) | CI-only cross-session learning aggregation — scheduled pattern detection and gap reporting using gh-aw |\n| [eval-creator-ci](skills/eval-creator-ci/) | CI-only eval regression runner — per-PR eval checks and scheduled eval creation from promoted patterns using gh-aw |\n\n## Two Loops\n\nThe skills implement two feedback loops that improve agent output over time.\n\n**Inner loop** (within a session): detect → verify → recover\n**Outer loop** (across sessions): inspect → encode → regress-test\n\nEach skill prevents a distinct failure mode:\n\n| Skill | Loop | Failure it prevents |\n|-------|------|-------------------|\n| `plan-interview` | — | Building the wrong thing |\n| `intent-framed-agent` | Inner (detect) | Scope creep during execution |\n| `context-surfing` | Inner (detect + recover) | Degraded-context corruption |\n| `verify-gate` | Inner (verify + recover) | Shipping code that doesn't compile or pass tests |\n| `self-healing` | Inner (recover) | Mid-task failures becoming silent recurrences instead of verified, reusable fixes |\n| `simplify-and-harden` | Inner (detect) | Shipping rough/insecure code |\n| `self-improvement` | Bridge (capture) | Repeating the same mistakes |\n| `pre-flight-check` | Bridge (surface) | Starting work blind to known patterns |\n| `learning-aggregator` | Outer (inspect) | Accumulated learnings nobody reads |\n| `harness-updater` | Outer (encode) | Patterns that never become rules |\n| `eval-creator` | Outer (regress-test) | Fixed issues that silently regress |\n\n### Inner Loop Lifecycle\n\n```\n[plan-interview] → [intent-framed-agent] ⟂ [context-surfing] → [verify-gate] → [simplify-and-harden] → [self-improvement]\n                                          ↑   concurrent    ↑    ↳ [self-healing] (on failure: diagnose → patch → verify → file HEAL)\n                                                                  ↻ fix loop\n```\n\n**Stage 1 — Planning** (manual gate): `plan-interview` runs a structured interview and produces a plan file in `docs/plans/`. This is the only skill that requires explicit invocation (`/plan-interview`). Downstream skills activate automatically when present, but each works independently if earlier stages are skipped.\n\n**Stage 2 — Execution** (concurrent monitoring): `intent-framed-agent` captures the intent frame and monitors *scope* drift. `context-surfing` monitors *context quality* drift. Both run simultaneously. If both fire at once, context-surfing's exit takes precedence — degraded context makes scope checks unreliable.\n\n**Stage 3 — Verification** (machine gate): `verify-gate` runs the project's compile, test, and lint commands. If any fail, `self-healing` takes the diagnosis loop: identify root cause, write the fix (script, env tweak, alt command), verify by re-running, and file a `HEAL-` entry to `.learnings/HEALS.md`. Verify-gate then re-checks. Up to 3 attempts per phase before abandoning. Only when all checks pass does work proceed to the quality review.\n\n**Stage 4 — Review** (post-completion): `simplify-and-harden` runs three passes (simplify, harden, document) on the completed work.\n\n**Stage 5 — Learning** (automatic): `self-improvement` captures recurring patterns from the session to `.learnings/`.\n\n### Outer Loop Lifecycle\n\n```\n.learnings/ → [learning-aggregator] → [harness-updater] → [eval-creator]\n                                                              ↓\n                                              [pre-flight-check] → next session\n```\n\n**Inspect**: `learning-aggregator` reads all `.learnings/` files, groups by pattern, and ranks promotion candidates.\n\n**Encode**: `harness-updater` agent takes promotion candidates and applies them as rules in CLAUDE.md, AGENTS.md, and copilot-instructions.md.\n\n**Regress-test**: `eval-creator` turns promoted patterns into permanent test cases in `.evals/` and runs regression checks.\n\n**Bridge**: `pre-flight-check` surfaces accumulated learnings and eval status at session start, feeding outer loop improvements back into the inner loop.\n\n### Artifacts at each stage\n\n| Stage | Artifact | Location |\n|-------|----------|----------|\n| Planning | Plan file | `docs/plans/plan-NNN-<slug>.md` |\n| Execution | Intent frame | Emitted in session output |\n| Execution | Handoff file (on drift exit) | `.context-surfing/handoff-<slug>-<timestamp>.md` |\n| Verification | Pass/fail signal | Emitted in session output |\n| Recovery | Verified heal entry + (lazy) artifacts | `.learnings/HEALS.md`, `.learnings/heals/<HEAL-ID>/` |\n| Review | Structured YAML summary | Appended to task output |\n| Learning | Learning entries | `.learnings/LEARNINGS.md`, `ERRORS.md`, `FEATURE_REQUESTS.md` |\n| Aggregation | Gap report | Emitted by learning-aggregator |\n| Encoding | Updated rules | CLAUDE.md, AGENTS.md |\n| Regression | Eval cases + results | `.evals/EVAL_INDEX.md`, `.evals/cases/` |\n\n### Pipeline depth\n\nEvery skill works standalone. The pipeline is the recommended combination, not a hard dependency — each skill silently adapts when upstream artifacts are absent.\n\nMatch depth to complexity:\n\n| Task | Skills |\n|------|--------|\n| Trivial (typo fix, rename) | None |\n| Small (isolated bug fix) | `verify-gate` + `self-healing` (on failure) + `simplify-and-harden` |\n| Medium (feature, multi-file) | `intent-framed-agent` + `verify-gate` + `self-healing` + `simplify-and-harden` |\n| Large (refactor, new architecture) | Full inner loop pipeline |\n| Long-running (multi-session) | Full inner loop — `context-surfing` is critical |\n| Periodic (weekly, sprint boundary) | Outer loop: `learning-aggregator` → `harness-updater` → `eval-creator` |\n\n## Usage\n\nTo use a skill, add it to your agent's configuration or reference it directly.\n\n### Hook Setup\n\nSkills with hooks register them via SKILL.md frontmatter when installed as a plugin. For standalone use, add to `.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [{\n      \"matcher\": \"\",\n      \"hooks\": [\n        {\n          \"type\": \"command\",\n          \"command\": \"./skills/self-improvement/scripts/activator.sh\"\n        }\n      ]\n    }],\n    \"SessionStart\": [{\n      \"matcher\": \"\",\n      \"hooks\": [\n        {\n          \"type\": \"command\",\n          \"command\": \"./skills/context-surfing/scripts/handoff-checker.sh\"\n        },\n        {\n          \"type\": \"command\",\n          \"command\": \"./skills/pre-flight-check/scripts/pre-flight.sh\"\n        }\n      ]\n    }],\n    \"PostToolUse\": [{\n      \"matcher\": \"Bash\",\n      \"hooks\": [\n        {\n          \"type\": \"command\",\n          \"command\": \"./skills/self-improvement/scripts/error-detector.sh\"\n        }\n      ]\n    }]\n  }\n}\n```\n\n| Hook | Script | Skill | Purpose |\n|------|--------|-------|---------|\n| UserPromptSubmit | `activator.sh` | self-improvement | Reminds to evaluate learnings after tasks |\n| SessionStart | `handoff-checker.sh` | context-surfing | Detects unread handoff files from previous context exits |\n| SessionStart | `pre-flight.sh` | pre-flight-check | Surfaces accumulated learnings, errors, and eval status |\n| PostToolUse (Bash) | `error-detector.sh` | self-improvement | Detects command failures for automatic error logging |\n\nAll hooks are lightweight (~50-200 tokens) and output nothing when no signals exist.\n\n## Contributing\n\nFeel free to submit PRs with new skills or improvements to existing ones.\n",
  "bytes": 16341,
  "sha": "41c35e17fdb15204f91b5ee39d482a39648abc490be5f6402b685cc80bbb384f",
  "repo_slug": "pskoett/pskoett-ai-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_pskoett_pskoett_ai_skills_self_improving_168d9c9b/readme"
}