skill-automation-package 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,22 @@
 
 Portable repo-local skill automation for Codex and Claude Code.
 
-This repository ships a Python-installed automation bundle. It is not an npm runtime package; `package.json` is used here as a package manifest for managed assets, versioning, and install metadata.
+## Quick Start
+
+Install into the repository you are already in, then use the installed runtime immediately. The package is `npx`-first, but the installed runtime still uses Python 3.10+.
+
+```bash
+cd your-repo
+npx skill-automation-package install --target .
+python3 .claude/tools/skill_agent.py auto "add tests" --json
+```
+
+- no setup required beyond `npx` and Python 3.10+
+- works on existing repositories
+- safe: uses bounded managed blocks for generated guidance and ignore rules
+
+The published npm package is `skill-automation-package`. It is a thin installer frontend over the same Python-based automation bundle; the runtime and install core still live in Python.
+This remains a Python-installed automation bundle, not an npm runtime package.
 
 ## Why This Exists
 
@@ -17,39 +32,26 @@ After installation, an agent can:
 - archive low-value skills that stay unused long enough to become cleanup candidates
 - route future Codex and Claude Code sessions through the same workflow
 
-## What It Installs
-
-- `.claude/tools/skill_agent.py`
-- `.claude/skills/project-skill-router/`
-- optional `.claude/tests/test_skill_agent.py`
-- managed automation blocks for `AGENTS.md` and `CLAUDE.md`
-
-## Quick Start
+## Basic Flow
 
-Install into another repository:
-
-```bash
-python3 scripts/install.py --target /path/to/target-repo
-```
-
-Or use the npm wrapper entrypoint:
+Use the published package to install into another repository:
 
 ```bash
 npx skill-automation-package install --target /path/to/target-repo
 ```
 
-To update an existing target without forcing an unnecessary reinstall when it is already current:
+Update an existing target with version-aware reinstall behavior:
 
 ```bash
 npx skill-automation-package update --target /path/to/target-repo
 ```
 
-The npm entrypoint is a thin wrapper around the Python installer. It does not replace the Python core, and Python 3.10 or newer is still required.
-If you already have this repository checked out locally, the direct `python3 scripts/install.py ...` path remains fully supported.
+Python 3.10 or newer is still required. The npm entrypoint is a thin wrapper around the Python installer and does not replace the Python core.
+
 `install` always allows reinstall. `update` is version-aware and only reinstalls when the target reports an older installed version.
 Before reinstalling, the wrapper checks `.claude/skill-automation-package.json` in the target repo and reports whether the target is not installed, already at the current version, or behind the current package version.
 
-The installer copies the packaged assets, updates managed blocks in `AGENTS.md` and `CLAUDE.md` unless skipped, writes `.claude/skill-automation-package.json`, and refreshes `.claude/skills/registry.json`.
+The installer copies the packaged assets, updates managed blocks in `AGENTS.md` and `CLAUDE.md` unless skipped, updates a generated-state `.gitignore` block unless disabled, writes `.claude/skill-automation-package.json`, and refreshes `.claude/skills/registry.json`.
 
 Then, inside the target repository, start non-trivial work with:
 
@@ -63,6 +65,13 @@ If you want a preview before writing files:
 python3 .claude/tools/skill_agent.py auto "<task>" --dry-run --json
 ```
 
+## What It Installs
+
+- `.claude/tools/skill_agent.py`
+- five packaged core default skills under `.claude/skills/`: `project-skill-router/` plus read-only helpers for project summary, repo structure analysis, docs entrypoint guidance, and change summary
+- optional `.claude/tests/test_skill_agent.py`
+- managed automation blocks for `AGENTS.md` and `CLAUDE.md`
+
 ## Example Outcomes
 
 Representative `auto` outcomes look like this.
@@ -96,35 +105,59 @@ Create a new skill when no strong match exists:
 
 The exact skill name is inferred from the task, but the flow is stable: reuse when there is a strong match, otherwise scaffold a new reusable local skill and refresh the registry immediately.
 
-## Installation Guide
+## Advanced Installation
 
-Use this package when you have the package repository checked out locally and want to install the automation bundle into another repository.
+Use this package when you want to install the automation bundle into another repository. The published npm package is the default entrypoint, and the direct Python path remains available when you are working from a local checkout of this repository.
 
 ### Prerequisites
 
 - Python 3.10 or newer
-- for the npm entrypoint, Node.js 18 or newer
+- Node.js 18 or newer
+- npm or `npx` for the published package entrypoint
 - a target repository where you want repo-local skill automation under `.claude/`
 - write access to the target repository
 
 ### Standard Install
 
 1. Choose the target repository.
-2. Run the installer from this package repository:
+2. Use the published package:
+
+```bash
+npx skill-automation-package install --target /path/to/target-repo
+```
+
+### Manual Installation
+
+If you already have this repository checked out locally, the direct Python install path remains fully supported:
 
 ```bash
 python3 scripts/install.py --target /path/to/target-repo
 ```
 
-3. The installer will:
+### What The Installer Writes
 
 - copy `.claude/tools/skill_agent.py`
-- copy `.claude/skills/project-skill-router/`
+- copy the packaged core default skills under `.claude/skills/`
 - optionally copy `.claude/tests/test_skill_agent.py`
 - insert managed automation blocks into `AGENTS.md` and `CLAUDE.md`
+- insert a managed generated-state block into `.gitignore` unless disabled
 - write `.claude/skill-automation-package.json`
 - refresh `.claude/skills/registry.json`
 
+### Install Vs Update
+
+Install always runs and allows a deliberate reinstall:
+
+```bash
+npx skill-automation-package install --target /path/to/target-repo
+```
+
+Update is version-aware and skips work when the target is already current:
+
+```bash
+npx skill-automation-package update --target /path/to/target-repo
+```
+
 ### Why `AGENTS.md` And `CLAUDE.md` Are Updated
 
 The installer adds a bounded managed block so future Codex and Claude Code sessions start from the same routing command instead of bypassing the local skill system.
@@ -145,7 +178,7 @@ python3 .claude/tools/skill_agent.py list
 python3 .claude/tools/skill_agent.py auto "find or create the right reusable workflow" --json
 ```
 
-You should see the packaged router skill in the list, and `auto` should return either a reusable local skill match or a generated preview/result.
+You should see the packaged core skills in the list, including the router, and `auto` should return either a reusable local skill match or a generated preview/result.
 
 ### Common Install Variants
 
@@ -153,17 +186,24 @@ You should see the packaged router skill in the list, and `auto` should return e
 - Skip the packaged test file: `python3 scripts/install.py --target /path/to/target-repo --no-tests`
 - Skip managed `AGENTS.md`: `python3 scripts/install.py --target /path/to/target-repo --skip-agents`
 - Skip managed `CLAUDE.md`: `python3 scripts/install.py --target /path/to/target-repo --skip-claude`
+- Disable `.gitignore` updates: `python3 scripts/install.py --target /path/to/target-repo --gitignore-mode none`
+- Ignore the whole local-only install: `python3 scripts/install.py --target /path/to/target-repo --gitignore-mode local-only`
 
 ## Managed File Behavior
 
 - If `AGENTS.md` or `CLAUDE.md` does not exist, install creates the file and inserts the managed block.
 - If both package markers already exist, install replaces only the content inside that managed block.
 - If the markers are missing, install appends the managed block to the end of the existing file.
+- By default, install also creates or updates a managed `.gitignore` block for generated state only.
+- Use `--gitignore-mode none` to leave `.gitignore` untouched, or `--gitignore-mode local-only` when the whole install should stay local to one checkout.
 - `--dry-run` previews the install result without creating the target directory or writing package files, and its status lines use `Would ...` wording for changes that are only being previewed.
+- Dry-run output includes package file groups for files that would be created, updated, left unchanged, or reported as previously installed but no longer shipped.
+- Dry-run output also reports whether each managed guidance file would be created, replaced, appended, left unchanged, or skipped.
 
 ## Target Repo Git Hygiene
 
 Decide up front whether the installed automation should be shared through version control or kept local to one checkout.
+The default installer policy is shared-friendly: it adds only generated-state patterns to `.gitignore`.
 
 ### Shared Automation In Version Control
 
@@ -172,11 +212,11 @@ Use this when the repository wants shared repo-local skills and shared entrypoin
 Usually commit:
 
 - `.claude/tools/skill_agent.py`
-- `.claude/skills/project-skill-router/`
+- the packaged core default skills under `.claude/skills/`
 - `.claude/tests/test_skill_agent.py` when installed
 - `AGENTS.md` and `CLAUDE.md` when you want the managed guidance blocks shared with the team
 
-Usually ignore:
+The installer adds this generated-state block by default:
 
 ```gitignore
 .claude/skills/registry.json
@@ -197,10 +237,11 @@ Use this when the install is only for one developer checkout and should not affe
 
 Typical approach:
 
-- install with `--skip-agents --skip-claude` if you do not want top-level guidance files touched
+- install with `--gitignore-mode local-only`
+- add `--skip-agents --skip-claude` if you do not want top-level guidance files touched
 - ignore the installed automation tree and any optional managed docs
 
-Example:
+The local-only mode manages this block:
 
 ```gitignore
 .claude/
@@ -235,7 +276,17 @@ npx skill-automation-package update --target /path/to/target-repo
 
 - `update` is a version-aware reinstall, not a partial update.
 - `update` blocks implicit downgrade attempts; use `install` only when you intentionally want to replace the target with the current package version.
-- If install metadata is malformed, `update` stops and asks you to use `install` for a deliberate reinstall.
+- If install metadata is malformed, incomplete, for a different package, or missing a usable asset list, `update` stops and asks you to use `install` for a deliberate reinstall.
+
+Metadata recovery behavior:
+
+| State | `install` behavior | `update` behavior |
+| --- | --- | --- |
+| Missing metadata | Proceeds as a new install | Stops and asks for `install` |
+| Same version | Reinstalls deliberately | No-ops |
+| Older version | Reinstalls deliberately | Runs reinstall |
+| Newer version | Warns and reinstalls deliberately | Blocks downgrade |
+| Malformed or incomplete metadata | Warns and reinstalls deliberately | Stops and asks for `install` |
 
 What gets updated in place:
 
@@ -342,10 +393,22 @@ Do not update `CLAUDE.md`:
 python3 scripts/install.py --target /path/to/target-repo --skip-claude
 ```
 
+Do not update `.gitignore`:
+
+```bash
+python3 scripts/install.py --target /path/to/target-repo --gitignore-mode none
+```
+
+Use a local-only `.gitignore` policy:
+
+```bash
+python3 scripts/install.py --target /path/to/target-repo --gitignore-mode local-only
+```
+
 ## Package Layout
 
 - `assets/.claude/tools/skill_agent.py`: resolver, search, scaffold, usage tracking, refresh review/update, and prune CLI
-- `assets/.claude/skills/project-skill-router/`: default reusable routing skill
+- `assets/.claude/skills/`: packaged core default skills, including the router and four read-only helper skills
 - `scripts/package_layout.py`: shared package manifest loader and asset copy helpers
 - `templates/agents_block.md`: managed block for `AGENTS.md`
 - `templates/claude_block.md`: managed block for `CLAUDE.md`

package/assets/.claude/skills/core-change-summary/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: core-change-summary
+description: Summarize the current working tree or recent changes in a read-only way. Use when an agent needs fast change context without editing the repo.
+---
+
+# Core Change Summary
+
+## Goal
+
+Build a concise summary of what changed, where it changed, and what still looks important before deeper review or follow-up work.
+
+## Workflow
+
+1. Inspect the current working tree, changed files, and the smallest relevant diff or file set.
+2. Group changes by area, intent, or likely effect instead of listing raw filenames only.
+3. Call out obvious risks, open questions, or verification gaps that follow from the observed changes.
+4. Keep the output read-only and limited to summary, not repo modification.
+
+## Guardrails
+
+- Do not create, edit, or delete repository files.
+- Do not infer intent that is not supported by the observed changes.
+- Prefer a compact status summary over a file-by-file changelog.

package/assets/.claude/skills/core-change-summary/skill.json

@@ -0,0 +1,31 @@
+{
+  "category": "workflow",
+  "summary": "Summarize the current working tree or recent changes without editing the repository.",
+  "management_mode": "locked",
+  "tags": [
+    "changes",
+    "summary",
+    "read-only",
+    "review"
+  ],
+  "triggers": [
+    "summarize the current changes",
+    "what changed in this repo",
+    "give me a change summary",
+    "show me the current working tree status"
+  ],
+  "steps": [
+    "Inspect the current working tree, changed files, and the smallest relevant diff or file set.",
+    "Group changes by area, intent, or likely effect.",
+    "Call out obvious risks, open questions, or verification gaps from the observed changes.",
+    "Keep the result read-only and focused on summary."
+  ],
+  "validation": [
+    "Reference the files or diffs used to build the summary.",
+    "Avoid modifying repository files while summarizing changes."
+  ],
+  "examples": [
+    "Summarize the current working tree before I continue.",
+    "Explain the recent changes and any obvious follow-up risks."
+  ]
+}

package/assets/.claude/skills/core-docs-entrypoint-guidance/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: core-docs-entrypoint-guidance
+description: Identify the best documentation entrypoints and reading order in a read-only way. Use when an agent needs to find canonical docs without changing the repo.
+---
+
+# Core Docs Entrypoint Guidance
+
+## Goal
+
+Point an agent to the smallest set of documents worth reading first and distinguish active references from lower-priority material.
+
+## Workflow
+
+1. Inspect the root `README.md`, `docs/` tree, and any obvious operations or reference directories.
+2. Separate canonical docs from working notes, archives, examples, or historical records.
+3. Recommend a practical reading order for the current task.
+4. Keep the output read-only and focused on navigation, not documentation edits.
+
+## Guardrails
+
+- Do not create, edit, or delete repository files.
+- Do not treat archived or draft material as current truth unless the repo says so.
+- Prefer a short ordered list of entrypoints over a broad document dump.

package/assets/.claude/skills/core-docs-entrypoint-guidance/skill.json

@@ -0,0 +1,31 @@
+{
+  "category": "docs",
+  "summary": "Identify the best documentation entrypoints and reading order from the existing repo.",
+  "management_mode": "locked",
+  "tags": [
+    "docs",
+    "navigation",
+    "read-only",
+    "onboarding"
+  ],
+  "triggers": [
+    "where should I start reading docs",
+    "find the canonical documentation",
+    "guide me through this repo's docs",
+    "what docs matter first"
+  ],
+  "steps": [
+    "Inspect the root README and the main docs directories.",
+    "Separate canonical references from working notes or archives.",
+    "Recommend the smallest useful reading order for the current task.",
+    "Keep the result read-only and grounded in the existing doc structure."
+  ],
+  "validation": [
+    "Call out which docs are active references and which are background material.",
+    "Avoid changing documentation files while guiding entrypoints."
+  ],
+  "examples": [
+    "Show me which docs to read first in this repository.",
+    "Point me to the canonical docs before I start implementation."
+  ]
+}

package/assets/.claude/skills/core-project-summary/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: core-project-summary
+description: Produce a read-only summary of the repository's purpose, main components, and current constraints. Use when an agent needs fast onboarding context without changing the repo.
+---
+
+# Core Project Summary
+
+## Goal
+
+Build a short, source-grounded summary of what the repository does and what matters before deeper work.
+
+## Workflow
+
+1. Read the root `README.md`, top-level manifests, and the most relevant entry directories before summarizing.
+2. Identify the repository purpose, main subsystems, runtime or build stack, and current constraints from existing files only.
+3. Keep the output read-only: summarize what exists, cite the files you used, and do not create or modify repository files.
+4. End with the smallest set of next files or directories worth reading for the current task.
+
+## Guardrails
+
+- Do not create, edit, or delete repository files.
+- Do not invent architecture, roadmap, or ownership details that are not supported by source material.
+- Prefer a short orientation summary over a long document.

package/assets/.claude/skills/core-project-summary/skill.json

@@ -0,0 +1,31 @@
+{
+  "category": "docs",
+  "summary": "Summarize the repository purpose, main components, and current constraints from existing files.",
+  "management_mode": "locked",
+  "tags": [
+    "summary",
+    "onboarding",
+    "read-only",
+    "context"
+  ],
+  "triggers": [
+    "summarize this project",
+    "give me a project overview",
+    "what does this repo do",
+    "onboard me to this repository"
+  ],
+  "steps": [
+    "Read the root README, top-level manifests, and the most relevant entry directories.",
+    "Extract the repository purpose, main components, and current constraints from existing files only.",
+    "Keep the result read-only and grounded in the files you inspected.",
+    "Point to the next files or directories worth reading."
+  ],
+  "validation": [
+    "Name the files or directories used to build the summary.",
+    "Avoid unsupported claims or repo changes."
+  ],
+  "examples": [
+    "Summarize this repository before we start coding.",
+    "Give me a quick project overview and the most important files to read next."
+  ]
+}

package/assets/.claude/skills/core-repo-structure-analysis/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: core-repo-structure-analysis
+description: Map the repository layout, key entrypoints, and likely edit locations in a read-only way. Use when an agent needs to understand where code, docs, tests, or config live without changing the repo.
+---
+
+# Core Repo Structure Analysis
+
+## Goal
+
+Create a compact map of the repository layout so an agent can find the right area before making changes.
+
+## Workflow
+
+1. Inspect the top-level directories, manifests, and obvious entrypoint files before drawing conclusions.
+2. Group the repository into major areas such as application code, tests, docs, scripts, tooling, or generated assets.
+3. Explain which directories are likely to matter for the current task and why.
+4. Keep the analysis read-only and limit the output to navigation guidance rather than implementation advice.
+
+## Guardrails
+
+- Do not create, edit, or delete repository files.
+- Do not claim a directory is authoritative unless the repository structure supports that conclusion.
+- Prefer a practical map of likely edit locations over a full file inventory.

package/assets/.claude/skills/core-repo-structure-analysis/skill.json

@@ -0,0 +1,31 @@
+{
+  "category": "workflow",
+  "summary": "Map the repository layout, entrypoints, and likely edit locations without changing files.",
+  "management_mode": "locked",
+  "tags": [
+    "structure",
+    "navigation",
+    "read-only",
+    "codebase"
+  ],
+  "triggers": [
+    "analyze this repo structure",
+    "map this codebase",
+    "where is everything in this repo",
+    "find the right directory for this task"
+  ],
+  "steps": [
+    "Inspect the top-level directories, manifests, and obvious entrypoints.",
+    "Group the repository into major areas such as app code, tests, docs, and tooling.",
+    "Call out the directories or files most relevant to the current task.",
+    "Keep the result read-only and focused on navigation."
+  ],
+  "validation": [
+    "Reference the directories or files that support the structure map.",
+    "Avoid changing the repository while analyzing it."
+  ],
+  "examples": [
+    "Map this repository before I start editing files.",
+    "Show me where the main code, tests, docs, and tooling live."
+  ]
+}

package/assets/.claude/tests/test_skill_agent.py

@@ -452,6 +452,40 @@ class SkillAgentTests(unittest.TestCase):
         self.assertEqual(payload[0]["name"], "dusty-skill")
         self.assertEqual(payload[0]["status"], "candidate")
 
+    def test_usage_keeps_packaged_core_helper_protected(self) -> None:
+        old_timestamp = (datetime.now(UTC) - timedelta(days=60)).replace(microsecond=0).isoformat()
+        self.write_skill(
+            "core-project-summary",
+            description="Summarize the repository in a read-only way.",
+            metadata={
+                "category": "docs",
+                "summary": "Summarize the repository in a read-only way.",
+                "created_at": old_timestamp,
+                "updated_at": old_timestamp,
+                "management_mode": "locked",
+            },
+        )
+
+        result = subprocess.run(
+            [
+                sys.executable,
+                str(SCRIPT_PATH),
+                "usage",
+                "--repo-root",
+                str(self.repo_root),
+                "--status",
+                "protected",
+                "--json",
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload[0]["name"], "core-project-summary")
+        self.assertEqual(payload[0]["status"], "protected")
+
     def test_prune_apply_archives_candidate_skill(self) -> None:
         old_timestamp = (datetime.now(UTC) - timedelta(days=60)).replace(microsecond=0).isoformat()
         self.write_skill(

package/assets/.claude/tools/skill_agent.py

@@ -335,7 +335,14 @@ TITLE_CASE_OVERRIDES = {
     "xcode": "Xcode",
 }
 
-PROTECTED_SKILLS = {"project-skill-router", "omc-reference"}
+PROTECTED_SKILLS = {
+    "project-skill-router",
+    "core-project-summary",
+    "core-repo-structure-analysis",
+    "core-docs-entrypoint-guidance",
+    "core-change-summary",
+    "omc-reference",
+}
 ARCHIVE_DIRNAME = "_archived"
 USAGE_FILENAME = "usage.json"
 USAGE_HISTORY_LIMIT = 12

package/bin/skill-automation-package.js

@@ -7,6 +7,7 @@ const fs = require("fs");
 const path = require("path");
 
 const MIN_PYTHON = { major: 3, minor: 10 };
+const PACKAGE_NAME = "skill-automation-package";
 const INSTALL_METADATA_PATH = path.join(".claude", "skill-automation-package.json");
 
 function main() {
@@ -145,10 +146,35 @@ function detectInstallState(targetRoot, currentVersion) {
   try {
     const raw = fs.readFileSync(metadataPath, "utf8");
     const metadata = JSON.parse(raw);
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+      return { status: "unknown", targetRoot, metadataPath, reason: "invalid-shape" };
+    }
+
+    if (typeof metadata.name !== "string" || metadata.name.trim() === "") {
+      return { status: "unknown", targetRoot, metadataPath, reason: "missing-name" };
+    }
+    const installedName = metadata.name.trim();
+    if (installedName !== PACKAGE_NAME) {
+      return {
+        status: "unknown",
+        targetRoot,
+        metadataPath,
+        reason: "wrong-package",
+        installedName,
+      };
+    }
+
     if (typeof metadata.version !== "string" || metadata.version.trim() === "") {
       return { status: "unknown", targetRoot, metadataPath, reason: "missing-version" };
     }
 
+    if (!Array.isArray(metadata.assets)) {
+      return { status: "unknown", targetRoot, metadataPath, reason: "invalid-assets" };
+    }
+    if (!metadata.assets.every((asset) => typeof asset === "string" && asset.trim() !== "")) {
+      return { status: "unknown", targetRoot, metadataPath, reason: "invalid-assets" };
+    }
+
     const installedVersion = metadata.version.trim();
     const installedParsed = parseVersion(installedVersion);
     const currentParsed = parseVersion(currentVersion);
@@ -252,12 +278,7 @@ function printLifecycleSafety() {
 
 function describeUnknownMetadata(state, mode, currentVersion) {
   const metadataPath = state?.metadataPath || INSTALL_METADATA_PATH;
-  const reasonLabel = {
-    "invalid-json": "could not be parsed as JSON",
-    "missing-version": "does not contain a usable version",
-    "invalid-version": "contains a version that could not be compared",
-  };
-  const detail = reasonLabel[state?.reason] || "could not be compared";
+  const detail = describeMetadataProblem(state);
 
   if (mode === "install") {
     return `skill-automation-package: existing install metadata at ${metadataPath} ${detail}; reinstalling with version ${currentVersion}.`;
@@ -266,6 +287,19 @@ function describeUnknownMetadata(state, mode, currentVersion) {
   return `skill-automation-package: existing install metadata at ${metadataPath} ${detail}; use install to force a reinstall.`;
 }
 
+function describeMetadataProblem(state) {
+  const reasonLabel = {
+    "invalid-json": "could not be parsed as JSON",
+    "invalid-shape": "is not a JSON object",
+    "missing-name": "does not contain a usable package name",
+    "wrong-package": `belongs to package "${state?.installedName || "(unknown)"}" instead of ${PACKAGE_NAME}`,
+    "missing-version": "does not contain a usable version",
+    "invalid-version": "contains a version that could not be compared",
+    "invalid-assets": "does not contain a usable assets list",
+  };
+  return reasonLabel[state?.reason] || "could not be compared";
+}
+
 function printUsage(subcommand) {
   if (subcommand) {
     console.error(`skill-automation-package: unsupported subcommand "${subcommand}".`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-automation-package",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Portable repo-local skill automation bundle for Codex and Claude Code.",
   "bin": {
     "skill-automation-package": "bin/skill-automation-package.js"
@@ -11,6 +11,10 @@
     "scripts/package_layout.py",
     "assets/.claude/tools/skill_agent.py",
     "assets/.claude/skills/project-skill-router/",
+    "assets/.claude/skills/core-project-summary/",
+    "assets/.claude/skills/core-repo-structure-analysis/",
+    "assets/.claude/skills/core-docs-entrypoint-guidance/",
+    "assets/.claude/skills/core-change-summary/",
     "assets/.claude/tests/test_skill_agent.py",
     "templates/agents_block.md",
     "templates/claude_block.md",
@@ -25,12 +29,17 @@
     "test:wrapper": "node --test tests/node/wrapper.test.js",
     "test:assets": "PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s assets/.claude/tests -p 'test_*.py'",
     "install:dry-run": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/install.py --target /tmp/skill-automation-package-dry-run --dry-run",
+    "release:integrity": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/check_release_integrity.py",
     "sync-assets": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_assets.py",
-    "release:check": "npm run test && npm run test:assets && npm run test:wrapper && npm run install:dry-run && npm pack --dry-run --cache /tmp/skill-automation-package-npm-cache"
+    "release:check": "npm run test && npm run test:assets && npm run test:wrapper && npm run release:integrity && npm run install:dry-run && npm pack --dry-run --cache /tmp/skill-automation-package-npm-cache"
   },
   "managed_assets": [
     ".claude/tools/skill_agent.py",
-    ".claude/skills/project-skill-router"
+    ".claude/skills/project-skill-router",
+    ".claude/skills/core-project-summary",
+    ".claude/skills/core-repo-structure-analysis",
+    ".claude/skills/core-docs-entrypoint-guidance",
+    ".claude/skills/core-change-summary"
   ],
   "optional_assets": [
     ".claude/tests/test_skill_agent.py"

package/scripts/install.py

@@ -5,6 +5,7 @@ import argparse
 import json
 import subprocess
 import sys
+from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 
@@ -21,6 +22,7 @@ from package_layout import (
     PackageLayout,
     TEMPLATES_ROOT,
     copy_assets,
+    iter_asset_files,
     load_package_layout,
 )
 
@@ -34,6 +36,44 @@ CLAUDE_MARKERS = (
     "<!-- SKILL-AUTOMATION:CLAUDE:END -->",
 )
 
+GITIGNORE_MARKERS = (
+    "# SKILL-AUTOMATION:GITIGNORE:START",
+    "# SKILL-AUTOMATION:GITIGNORE:END",
+)
+
+GITIGNORE_PATTERNS = {
+    "generated": (
+        "# Generated skill automation state",
+        ".claude/skills/registry.json",
+        ".claude/skills/usage.json",
+        ".claude/skills/_archived/",
+        ".claude/skill-automation-package.json",
+        ".claude/**/__pycache__/",
+        ".claude/**/*.pyc",
+    ),
+    "local-only": (
+        "# Local-only skill automation install",
+        ".claude/",
+        "AGENTS.md",
+        "CLAUDE.md",
+    ),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ManagedBlockPlan:
+    changed: bool
+    state: str
+    updated: str
+
+
+@dataclass(frozen=True, slots=True)
+class PackageFilePreview:
+    would_create: tuple[Path, ...]
+    would_update: tuple[Path, ...]
+    unchanged: tuple[Path, ...]
+    stale: tuple[Path, ...]
+
 
 def main() -> int:
     parser = build_parser()
@@ -52,11 +92,11 @@ def main() -> int:
         executable_assets=layout.executable_assets,
         dry_run=args.dry_run,
     )
-    wrote_agents = False
-    wrote_claude = False
+    agents_plan = ManagedBlockPlan(changed=False, state="skipped", updated="")
+    claude_plan = ManagedBlockPlan(changed=False, state="skipped", updated="")
 
     if not args.skip_agents:
-        wrote_agents = install_managed_block(
+        agents_plan = install_managed_block(
             target_file=target / "AGENTS.md",
             template_path=TEMPLATES_ROOT / "agents_block.md",
             markers=AGENTS_MARKERS,
@@ -65,7 +105,7 @@ def main() -> int:
         )
 
     if not args.skip_claude:
-        wrote_claude = install_managed_block(
+        claude_plan = install_managed_block(
             target_file=target / "CLAUDE.md",
             template_path=TEMPLATES_ROOT / "claude_block.md",
             markers=CLAUDE_MARKERS,
@@ -73,6 +113,12 @@ def main() -> int:
             dry_run=args.dry_run,
         )
 
+    gitignore_plan = install_gitignore_block(
+        target_file=target / ".gitignore",
+        mode=args.gitignore_mode,
+        dry_run=args.dry_run,
+    )
+
     manifest_path = target / ".claude" / "skill-automation-package.json"
     wrote_manifest = write_install_manifest(
         manifest_path=manifest_path,
@@ -90,12 +136,26 @@ def main() -> int:
     agents_label = "Would update AGENTS.md" if args.dry_run else "Updated AGENTS.md"
     claude_label = "Would update CLAUDE.md" if args.dry_run else "Updated CLAUDE.md"
     manifest_label = "Would write install manifest" if args.dry_run else "Wrote install manifest"
+    copied_label = "Would copy files" if args.dry_run else "Copied files"
+    gitignore_label = "Would update .gitignore" if args.dry_run else "Updated .gitignore"
     print(f"Installed skill automation package {layout.version} into {target}")
-    print(f"Copied files: {len(copied_files)}")
-    print(f"{agents_label}: {'yes' if wrote_agents else 'no'}")
-    print(f"{claude_label}: {'yes' if wrote_claude else 'no'}")
+    print(f"{copied_label}: {len(copied_files)}")
+    print(f"{agents_label}: {'yes' if agents_plan.changed else 'no'}")
+    print(f"{claude_label}: {'yes' if claude_plan.changed else 'no'}")
+    print(f"{gitignore_label}: {'yes' if gitignore_plan.changed else 'no'}")
     print(f"{manifest_label}: {'yes' if wrote_manifest else 'no'}")
     print(f"Refreshed registry: {'yes' if refreshed else 'no'}")
+    if args.dry_run:
+        print_dry_run_preview(
+            build_package_file_preview(
+                layout=layout,
+                target_root=target,
+                asset_paths=selected_assets,
+            ),
+            agents_state=agents_plan.state,
+            claude_state=claude_plan.state,
+            gitignore_state=gitignore_plan.state,
+        )
     return 0
 
 
@@ -129,6 +189,16 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Preview the installation without writing files.",
     )
+    parser.add_argument(
+        "--gitignore-mode",
+        choices=("generated", "local-only", "none"),
+        default="generated",
+        help=(
+            "Manage a package-owned .gitignore block. `generated` ignores only "
+            "generated state, `local-only` ignores the whole local install, and "
+            "`none` leaves .gitignore untouched."
+        ),
+    )
     return parser
 
 
@@ -139,16 +209,85 @@ def install_managed_block(
     markers: tuple[str, str],
     title: str,
     dry_run: bool,
-) -> bool:
+) -> ManagedBlockPlan:
+    plan = build_managed_block_plan(
+        target_file=target_file,
+        template_path=template_path,
+        markers=markers,
+        title=title,
+    )
+    if not dry_run:
+        target_file.parent.mkdir(parents=True, exist_ok=True)
+        target_file.write_text(plan.updated, encoding="utf-8")
+    return plan
+
+
+def build_managed_block_plan(
+    *,
+    target_file: Path,
+    template_path: Path,
+    markers: tuple[str, str],
+    title: str,
+) -> ManagedBlockPlan:
     block = template_path.read_text(encoding="utf-8").strip() + "\n"
     start_marker, end_marker = markers
     existing = target_file.read_text(encoding="utf-8") if target_file.exists() else ""
     updated = upsert_block(existing, block, start_marker, end_marker, title)
+    state = classify_managed_block_state(existing, updated, start_marker, end_marker)
+    return ManagedBlockPlan(changed=updated != existing, state=state, updated=updated)
+
+
+def install_gitignore_block(
+    *,
+    target_file: Path,
+    mode: str,
+    dry_run: bool,
+) -> ManagedBlockPlan:
+    if mode == "none":
+        return ManagedBlockPlan(changed=False, state="skipped", updated="")
+
+    block = build_gitignore_block(mode)
+    existing = target_file.read_text(encoding="utf-8") if target_file.exists() else ""
+    updated = upsert_block(
+        existing,
+        block,
+        GITIGNORE_MARKERS[0],
+        GITIGNORE_MARKERS[1],
+        "",
+    )
+    state = classify_managed_block_state(
+        existing,
+        updated,
+        GITIGNORE_MARKERS[0],
+        GITIGNORE_MARKERS[1],
+    )
 
     if not dry_run:
         target_file.parent.mkdir(parents=True, exist_ok=True)
         target_file.write_text(updated, encoding="utf-8")
-    return updated != existing
+    return ManagedBlockPlan(changed=updated != existing, state=state, updated=updated)
+
+
+def build_gitignore_block(mode: str) -> str:
+    patterns = GITIGNORE_PATTERNS[mode]
+    return "\n".join([GITIGNORE_MARKERS[0], *patterns, GITIGNORE_MARKERS[1]]) + "\n"
+
+
+def classify_managed_block_state(
+    existing: str,
+    updated: str,
+    start_marker: str,
+    end_marker: str,
+) -> str:
+    if updated == existing:
+        return "unchanged"
+    if not existing.strip():
+        return "create"
+    start_index = existing.find(start_marker)
+    end_index = existing.find(end_marker)
+    if start_index != -1 and end_index != -1 and end_index >= start_index:
+        return "replace"
+    return "append"
 
 
 def upsert_block(
@@ -204,5 +343,94 @@ def refresh_registry(target: Path) -> None:
     )
 
 
+def build_package_file_preview(
+    *,
+    layout: PackageLayout,
+    target_root: Path,
+    asset_paths: list[Path],
+) -> PackageFilePreview:
+    current_assets: set[Path] = set()
+    would_create: list[Path] = []
+    would_update: list[Path] = []
+    unchanged: list[Path] = []
+
+    for source_path, relative_path in iter_asset_files(ASSETS_ROOT, asset_paths):
+        current_assets.add(relative_path)
+        target_path = target_root / relative_path
+        if not target_path.exists():
+            would_create.append(relative_path)
+            continue
+        if files_match(source_path, target_path):
+            unchanged.append(relative_path)
+            continue
+        would_update.append(relative_path)
+
+    stale = [
+        path
+        for path in read_previous_install_assets(target_root)
+        if path not in current_assets and (target_root / path).exists()
+    ]
+
+    return PackageFilePreview(
+        would_create=tuple(sorted(would_create)),
+        would_update=tuple(sorted(would_update)),
+        unchanged=tuple(sorted(unchanged)),
+        stale=tuple(sorted(stale)),
+    )
+
+
+def files_match(source_path: Path, target_path: Path) -> bool:
+    if not target_path.is_file():
+        return False
+    return source_path.read_bytes() == target_path.read_bytes()
+
+
+def read_previous_install_assets(target_root: Path) -> list[Path]:
+    manifest_path = target_root / ".claude" / "skill-automation-package.json"
+    if not manifest_path.exists():
+        return []
+    try:
+        payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return []
+    assets = payload.get("assets")
+    if not isinstance(assets, list):
+        return []
+
+    previous: list[Path] = []
+    for value in assets:
+        if not isinstance(value, str):
+            continue
+        path = Path(value)
+        if path.is_absolute():
+            continue
+        previous.append(path)
+    return previous
+
+
+def print_dry_run_preview(
+    preview: PackageFilePreview,
+    *,
+    agents_state: str,
+    claude_state: str,
+    gitignore_state: str,
+) -> None:
+    print("Package file preview:")
+    print_preview_paths("would create", preview.would_create)
+    print_preview_paths("would update", preview.would_update)
+    print_preview_paths("unchanged", preview.unchanged)
+    print_preview_paths("previously installed but no longer shipped", preview.stale)
+    print("Managed file preview:")
+    print(f"  AGENTS.md: {agents_state}")
+    print(f"  CLAUDE.md: {claude_state}")
+    print(f"  .gitignore: {gitignore_state}")
+
+
+def print_preview_paths(label: str, paths: tuple[Path, ...]) -> None:
+    print(f"  {label}: {len(paths)}")
+    for path in paths:
+        print(f"    - {path}")
+
+
 if __name__ == "__main__":
     raise SystemExit(main())