skill-automation-package 0.2.0 → 0.2.2

package/README.md

@@ -2,7 +2,8 @@
 
 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.
+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
 
@@ -20,32 +21,32 @@ After installation, an agent can:
 ## What It Installs
 
 - `.claude/tools/skill_agent.py`
-- `.claude/skills/project-skill-router/`
+- 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`
 
 ## Quick Start
 
-Install into another repository:
+Use the published package to install into another repository:
 
 ```bash
-python3 scripts/install.py --target /path/to/target-repo
+npx skill-automation-package install --target /path/to/target-repo
 ```
 
-Or use the npm wrapper entrypoint:
+Update an existing target with version-aware reinstall behavior:
 
 ```bash
-npx skill-automation-package install --target /path/to/target-repo
+npx skill-automation-package update --target /path/to/target-repo
 ```
 
-To update an existing target without forcing an unnecessary reinstall when it is already current:
+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.
+
+If you already have this repository checked out locally, the direct Python install path remains fully supported:
 
 ```bash
-npx skill-automation-package update --target /path/to/target-repo
+python3 scripts/install.py --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.
 `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.
 
@@ -98,33 +99,54 @@ The exact skill name is inferred from the task, but the flow is stable: reuse wh
 
 ## Installation Guide
 
-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
+```
+
+3. Or, if you already have this repository checked out locally, run the Python installer directly:
 
 ```bash
 python3 scripts/install.py --target /path/to/target-repo
 ```
 
-3. The installer will:
+4. The installer will:
 
 - 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`
 - 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 +167,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
 
@@ -172,7 +194,7 @@ 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
 
@@ -345,7 +367,7 @@ python3 scripts/install.py --target /path/to/target-repo --skip-claude
 ## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-automation-package",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",
@@ -30,7 +34,11 @@
   },
   "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"