feat: add agent-ready skill (RHDH-aware, consolidated)

README.md

@@ -71,6 +71,13 @@ Track work across the four RHDH Jira projects.
 
 - **[rhdh](./skills/rhdh/SKILL.md)** — Entry point and router. Detects your environment, runs `doctor` checks, maintains a cross-session worklog, and routes to the right skill. Start here if you're not sure what you need.
 
+### Repository Readiness
+
+Prepare any git repository for effective AI agent use.
+
+- **[agent-ready](./skills/agent-ready/SKILL.md)** — Assess a repository against agentready criteria, then walk through and address each gap interactively. Runs the [agentready](https://github.com/ambient-code/agentready) CLI, presents failing findings by tier, and delegates AGENTS.md creation to `init-agents-md`.
+- **[init-agents-md](./skills/init-agents-md/SKILL.md)** — Bootstrap `AGENTS.md` and `CLAUDE.md` for any repository. Detects build/test commands from config files and CI, asks 3 targeted questions, and writes a minimal draft for human review.
+
 ### Meta
 
 - **[skill-maker](./skills/skill-maker/SKILL.md)** — Create new skills or consolidate existing ones following the [Agent Skills open standard](https://agentskills.io/specification). Interviews you about scope and edge cases before drafting.

skills/agent-ready/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: agent-ready
+description: |
+  Assesses a git repository's readiness for use by AI coding agents using the agentready CLI, then walks through and addresses each gap. Use when asked to "assess agent readiness", "run agentready", "check how agent-ready this repo is", "make this repo agent-ready", "improve our agent readiness score", "run the agent ready CLI", "assess this repo for AI agents", or "what's our agentready score".
+---
+
+## Prerequisites
+
+`uvx` is a hard dependency. Verify it is available before any other step:
+
+```bash
+uvx --version
+```
+
+If missing, stop: "`uvx` is required. Install via `pip install uv` or see [uv installation](https://docs.astral.sh/uv/getting-started/installation/)."
+
+## Step 1: Setup
+
+**Path:** Default to the current working directory. If the user provided a path, use that instead. Validate it is a git repository:
+
+```bash
+git -C . rev-parse --is-inside-work-tree  # replace . with the user-provided path if one was given
+```
+
+If not a git repository, stop and tell the user.
+
+**Config file:** Only use a config file if the user explicitly provided one. Do not ask. If a path was given, verify it exists before proceeding.
+
+## Step 2: Run the assessment
+
+Create a temp directory and run the assessment:
+
+```bash
+REPORT_DIR=$(mktemp -d)  # on Windows: use %TEMP% or Python tempfile
+uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \
+  -o "$REPORT_DIR" \
+  .  # replace . with the user-provided path if one was given
+```
+
+Append `-c <config-path>` to the command if the user provided a config file.
+
+Note the value of `$REPORT_DIR` — shell variables do not persist across tool calls and Step 5 will need it.
+
+Parse `$REPORT_DIR/assessment-latest.json`. Extract:
+- `overall_score`, `certification_level`
+- `findings` — each with `attribute.id`, `attribute.tier`, `attribute.default_weight`, `attribute.name`, `status`, `score`, `evidence`, `remediation`
+
+## Step 3: Present summary
+
+Show a brief summary before diving into findings:
+
+```
+Score: <overall_score>/100 — <certification_level>
+Failing: <N> findings (<N1> Tier 1, <N2> Tier 2, ...)
+```
+
+If there are no failing findings, congratulate the user and stop — do not ask to work through anything.
+
+Otherwise ask:
+
+> "Fix applicable findings automatically, or review each one individually?
+> **auto** (default) — apply self-contained fixes immediately; prompt only when input is needed
+> **review** — prompt yes/skip/defer/quit for every finding"
+
+Default to **auto** if the user just says yes, presses Enter, or says "fix everything".
+
+## Step 4: Work through findings
+
+Work only through findings where `status == "fail"`. Skip `not_applicable` and `pass` findings silently.
+
+**Sort order:** ascending tier (Tier 1 first), then descending `attribute.default_weight` within each tier.
+
+### Auto mode
+
+Apply each fix without prompting **unless** any of the following are true — in which case, pause and prompt:
+
+- The fix requires project-specific input (CI platform, package ecosystem, project name, language)
+- The finding might not apply to this repo type (e.g., `src/` layout for a GitOps YAML repo, lock files for a repo with no package dependencies) — present it and ask whether to apply or skip
+- It is the `agent_instructions` finding — always delegate to `init-agents-md` interactively
+
+**Skip without prompting** findings that require human rationale to be meaningful — ADRs, design intent, and architecture decisions. These cannot be generated without fabricating context the agent doesn't have.
+
+After processing all findings, list what was applied, what was prompted, and what was skipped, then proceed to Step 5.
+
+### Review mode
+
+For each finding, present:
+
+```
+[Tier <N>] <attribute.name> — <score>/100
+Evidence: <evidence items, one per line>
+
+Remediation: <remediation.summary>
+
+Apply this fix? [yes / skip / defer / quit]
+```
+
+**yes** — apply the fix (see special cases below), then move to the next finding.  
+**skip** — move on; do not revisit. Use this if the finding doesn't apply to this repo.  
+**defer** — note it; present again after the re-run.  
+**quit** — stop immediately.
+
+**ADR and design intent findings in review mode:** Do not present the JSON remediation. Instead ask:
+
+> "Do you have any architectural decisions worth capturing here? If so, describe the decision and why it was made — I'll write the ADR. Skip if you'd prefer to add these manually later."
+
+If the user provides input, write the ADR or design doc using their rationale. If they skip, move on.
+
+### Special case: `agent_instructions` finding (both modes)
+
+Do not apply the JSON remediation. Instead, invoke the `init-agents-md` skill:
+
+> "Invoking the `init-agents-md` skill to create AGENTS.md for this repository."
+
+Use the Skill tool: `init-agents-md`. After it completes, return to this skill and continue with the next finding.
+
+### Applying fixes (auto and review modes)
+
+Use the `remediation.steps`, `remediation.commands`, and `remediation.examples` from the JSON as the implementation guide. Do not invent steps beyond what the JSON provides.
+
+## Step 5: Re-run and present results
+
+Re-run the assessment (shell variables from Step 2 do not persist — create a new temp dir):
+
+```bash
+REPORT_DIR=$(mktemp -d)  # on Windows: use %TEMP% or Python tempfile
+uvx --from git+https://github.com/ambient-code/agentready agentready -- assess \
+  -o "$REPORT_DIR" \
+  .  # or user-provided path
+```
+
+Include `-c <config-path>` if the user provided a config file.
+
+Show before/after:
+
+```
+Before: <old_score>/100 (<old_certification_level>)
+After:  <new_score>/100 (<new_certification_level>)
+
+Remaining failures: <N> findings
+```
+
+If there are remaining failures (including deferred ones), ask:
+
+> "Would you like to continue addressing the remaining findings?"
+
+If yes, repeat Step 4 with the remaining failures. If no, stop.
+
+## Gotchas
+
+- The first `uvx` run fetches and builds agentready from GitHub — this can take 30–60 seconds. Subsequent runs use the cache and are much faster. If the fetch fails (network error, build error), tell the user and stop — do not attempt to proceed without a valid report.
+- Do not output the report to the repository directory — use the temp dir to avoid polluting the working tree.
+- `not_applicable` findings reflect the detected language stack; do not mention them unless the user asks.
+- Deferred findings are not lost — they surface again after the re-run.
+- Never invent rationale for ADRs, design docs, or architecture decisions — these require human context the agent doesn't have. In auto mode, skip them. In review mode, ask the user for the rationale before writing anything.

skills/init-agents-md/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: init-agents-md
+description: >-
+  Use when asked to bootstrap, create, initialize, or generate an AGENTS.md or
+  context file for a repository. Also use when asked to "set up AI agent
+  context", "create repo context file", "add AGENTS.md", "scaffold context
+  file", "init agents md", "create CLAUDE.md for a repo", "make my repo
+  AI-friendly", or "help agents understand this codebase".
+---
+
+## Goal
+
+Write a minimal `AGENTS.md` and `CLAUDE.md` in the current working directory.
+The output is a starting point — the human must review and edit before committing.
+
+**Research finding (ETH Zurich, Feb 2026):** Auto-generated context files shipped
+as-is reduce agent success rates by ~3% and increase costs by 20-23%. This skill
+generates a draft. The human edits it aggressively before committing.
+
+## Step 1: Check for existing files
+
+If `AGENTS.md` already exists in the CWD, ask:
+
+> "AGENTS.md already exists. Overwrite it? (yes/no)"
+
+If no: stop. Tell the user to delete it first and re-run the skill.  
+If yes: proceed.
+
+## Step 2: Detect commands
+
+Scan these files in the CWD:
+
+| File | What to extract |
+|------|-----------------|
+| `package.json` | `scripts` entries matching build, test, lint, typecheck, dev/start |
+| `Makefile` / `GNUmakefile` | Targets: build, test, lint, check, run |
+| `pyproject.toml` | `[tool.pytest]`, `[tool.ruff]`, `[tool.mypy]`, `[project.scripts]` |
+| `setup.cfg`, `tox.ini` | test commands |
+| `Taskfile.yml` | task definitions |
+| `go.mod` | signals Go project — look for `go test`, `go build`, `go vet` in Makefile or CI |
+| `Cargo.toml` | signals Rust — look for `cargo test`, `cargo build`, `cargo clippy` |
+| `.github/workflows/*.yml` | `run:` steps containing test/lint/build/typecheck keywords |
+| `.gitlab-ci.yml` | `script:` entries |
+| `Jenkinsfile` | `sh` steps |
+
+**Cross-reference rule:** If a `package.json` script and a CI `run:` step agree, use
+that form. If they differ, prefer the CI form — it's what actually runs in the
+pipeline. If a command cannot be found or confidently inferred, omit it. Do not guess.
+
+Look for these command categories:
+
+- **Build** — compiles, bundles, or packages the project
+- **Test all** — runs the full test suite without external dependencies
+- **Test single file/package** — runs tests for one module
+- **Lint** — runs the linter across the project
+- **Lint single file** — lints one file in isolation
+- **Type check** — static type checking
+- **Run/dev** — starts the dev server or app locally
+
+## Step 3: Interactive prompting
+
+Ask these questions **one at a time**. Wait for each answer before asking the
+next. Accept "skip" or a blank answer to omit that section entirely.
+
+**Question 1 — Key Conventions:**
+> "What are 2-3 project conventions an AI agent couldn't discover by reading the
+> code? For example: a required wrapper type for API responses, a naming rule for
+> files, a directory that must never be imported directly, or where generated
+> files live. Skip if none come to mind."
+
+**Question 2 — Architecture:**
+> "Are there any non-obvious places where things live — for example, a feature
+> configured in one place but evaluated elsewhere, or a shared internal API that
+> shouldn't be called directly? Skip if the directory names make it obvious."
+
+**Question 3 — PR Conventions:**
+> "Any commit message format, required CI checks, or PR conventions agents should
+> know? For example: Conventional Commits format, a required sign-off, or a label
+> that blocks merge. Skip if standard."
+
+## Step 4: Write the files
+
+Infer the project name from `package.json` (`name` field), `go.mod` (module path,
+last segment), `pyproject.toml` (`[project] name`), `Cargo.toml` (`[package] name`),
+or the CWD directory name as a fallback.
+
+Write `AGENTS.md` using only the content that was found or provided. Omit any
+section — including its header — where you have nothing to say:
+
+```markdown
+# [Project name]
+
+## Build & Test Commands
+- Build: `[command]`
+- Test all: `[command]`
+- Test single file: `[command]`
+- Lint: `[command]`
+- Lint single file: `[command]`
+- Type check: `[command]`
+- Run: `[command]`
+
+## Key Conventions
+- [convention from Q1 answer]
+
+## Architecture
+- [note from Q2 answer]
+
+## PR Conventions
+- Agent-assisted commits should include an `Assisted-by: <model>` footer
+- [convention from Q3 answer]
+```
+
+Write `CLAUDE.md` with exactly this content:
+
+```markdown
+@AGENTS.md
+```
+
+## Step 5: Review gate
+
+After writing the files, say this exactly:
+
+> **Review before committing.**
+>
+> `AGENTS.md` and `CLAUDE.md` have been written to this directory. Before committing:
+>
+> 1. Open `AGENTS.md` in your editor
+> 2. Run each listed command to confirm it actually works
+> 3. Delete anything an agent could figure out by reading the code
+> 4. Apply this test to every line: *"Would removing this cause an agent to make a
+>    mistake it wouldn't otherwise make?"* If not, delete it.
+>
+> Target: under 150 lines. Every unnecessary line makes agents slightly worse at
+> following the lines that matter.
+
+Do not offer to commit the files. Do not suggest the files are ready to use.
+
+## Gotchas
+
+- If no commands are found at all, still write the file and tell the user which
+  files you looked in and found nothing useful
+- Do not invent commands not present in config or CI — a hallucinated command is
+  worse than an omitted one
+- If a script name is ambiguous (e.g., `npm run check` could be lint or typecheck),
+  add a brief inline note: `- Lint: \`npm run check\` (appears to run ESLint)`
+- Omit the `## Architecture` and `## Key Conventions` sections entirely when the
+  user skips those questions — don't leave placeholder comment lines
+- Always include the `Assisted-by` footer line in `## PR Conventions` even if the
+  user skips Q3 — it applies to any repo where agents contribute
+- If `CLAUDE.md` already exists and contains more than `@AGENTS.md`, ask before
+  overwriting it