{
  "markdown": "# pskoett-ai-skills\n\nA collection of skills for AI agents. Follows the [Agent Skills specification](https://agentskills.io/specification) and ships an [Agent Plugins 1.0](https://agent-plugins.org/specification) portable package.\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\n### Agent Plugins 1.0\n\nThe portable package entrypoint is [`agent-plugin/plugin.json`](agent-plugin/plugin.json). Point an Agent Plugins-compatible client or packager at the `agent-plugin/` directory.\n\nThe portable package contains the curated Agent Skills bundle only. Agent Plugins 1.0 does not standardize hooks, agents, commands, or installation UX, so the native Claude Code, Codex, and GitHub Copilot adapters below remain the supported way to load those client-specific capabilities. A `hooks/` directory inside an individual portable skill is a skill resource, not an automatically registered plugin hook. This repository does not publish a portable `mcp.json` because it provides no MCP server.\n\n### Claude Code\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| [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 four phases (simplify, harden, document, re-verify) 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\n`skills/` is canonical. Regenerate both native and portable bundles after changing a bundled skill:\n\n```bash\n./scripts/sync-plugin.sh\npython3 scripts/test-sync-plugin.py\n```\n\nValidate the native package and the Agent Plugins 1.0 package:\n\n```bash\npython3 scripts/validate-plugin.py\nuv run --with jsonschema==4.25.1 --with PyYAML==6.0.3 \\\n  python3 scripts/validate-agent-plugin.py\n```\n\nThe portable validator uses vendored copies of the published 1.0.0 schemas under `schemas/agent-plugins/1.0.0/`. Validate individual generated skills with the Agent Skills reference CLI when changing skill metadata:\n\n```bash\nuvx --from 'git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref' \\\n  skills-ref validate agent-plugin/skills/verify-gate\n```\n",
  "bytes": 17734,
  "sha": "65179c9216bd8bf659d6d9982c3d5ba31a8aa5d9467c77ea0b57e6079a4d467a",
  "repo_slug": "pskoett/pskoett-ai-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_pskoett_pskoett_ai_skills_pskoett_ai_ski_159a774e/readme"
}