shmakk 1.1.0 → 1.2.0

package/skills/dev-code-tour.md

@@ -0,0 +1,434 @@
+---
+name: code-tour
+description: >
+  Use this skill to create CodeTour .tour files — persona-targeted, step-by-step walkthroughs
+  that link to real files and line numbers. Trigger for: "create a tour", "make a code tour",
+  "generate a tour", "onboarding tour", "tour for this PR", "tour for this bug", "RCA tour",
+  "architecture tour", "explain how X works", "vibe check", "PR review tour",
+  "contributor guide", "help someone ramp up", or any request for a structured walkthrough
+  through code. Supports 20 developer personas (new joiner, bug fixer, architect, PR reviewer,
+  vibecoder, security reviewer, and more), all CodeTour step types (file/line, selection,
+  pattern, uri, commands, view), and tour-level fields (ref, isPrimary, nextTour).
+  Works with any repository in any language.
+category: dev
+---
+
+# Code Tour Skill
+
+You are creating a **CodeTour** — a persona-targeted, step-by-step walkthrough of a codebase
+that links directly to files and line numbers. CodeTour files live in `.tours/` and work with
+the [VS Code CodeTour extension](https://github.com/microsoft/codetour).
+
+Two scripts are bundled in `scripts/`:
+
+- **`scripts/validate_tour.py`** — run after writing any tour. Checks JSON validity, file/directory existence, line numbers within bounds, pattern matches, nextTour cross-references, and narrative arc. Run it: `python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .`
+- **`scripts/generate_from_docs.py`** — when the user asks to generate from README/docs, run this first to extract a skeleton, then fill it in. Run it: `python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour`
+
+Two reference files are bundled:
+
+- **`references/codetour-schema.json`** — the authoritative JSON schema. Read it to verify any field name or type. Every field you use must conform to it.
+- **`references/examples.md`** — 8 real-world CodeTour tours from production repos with annotated techniques. Read it when you want to see how a specific feature (`commands`, `selection`, `view`, `pattern`, `isPrimary`, multi-tour series) is used in practice.
+
+### Real-world `.tour` files on GitHub
+
+These are confirmed production `.tour` files. Fetch one when you need a working example of a specific step type, tour-level field, or narrative structure — don't write from memory when the real thing is one fetch away.
+
+Find more with the GitHub code search: https://github.com/search?q=path%3A**%2F*.tour+&type=code
+
+#### By step type / technique demonstrated
+
+| What to study | File URL |
+|---|---|
+| `directory` + `file+line` (contributor onboarding) | https://github.com/coder/code-server/blob/main/.tours/contributing.tour |
+| `selection` + `file+line` + intro content step (accessibility project) | https://github.com/a11yproject/a11yproject.com/blob/main/.tours/code-tour.tour |
+| Minimal tutorial — tight `file+line` narration for interactive learning | https://github.com/lostintangent/rock-paper-scissors/blob/master/main.tour |
+| Multi-tour repo with `nextTour` chaining (cloud native OCI walkthroughs) | https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/introduction.tour |
+| `isPrimary: true` (marks the onboarding entry point) | https://github.com/nickvdyck/webbundlr/blob/main/.tours/getting-started.tour |
+| `pattern` instead of `line` (regex-anchored steps) | https://github.com/nickvdyck/webbundlr/blob/main/.tours/architecture.tour |
+
+**Raw content tip:** Prefix `raw.githubusercontent.com` and drop `/blob/` for raw JSON access.
+
+A great tour is not just annotated files. It is a **narrative** — a story told to a specific
+person about what matters, why it matters, and what to do next. Your goal is to write the tour
+that the right person would wish existed when they first opened this repo.
+
+**CRITICAL: Only create `.tour` JSON files. Never create, modify, or scaffold any other files.**
+
+---
+
+## Step 1: Discover the repo
+
+Before asking the user anything, explore the codebase:
+
+- List the root directory, read the README, and check key config files
+  (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, etc.)
+- Identify the language(s), framework(s), and what the project does
+- Map the folder structure 1–2 levels deep
+- Find entry points: main files, index files, app bootstrapping
+- **Note which files actually exist** — every path you write in the tour must be real
+
+If the repo is sparse or empty, say so and work with what exists.
+
+**If the user says "generate from README" or "use the docs":** run the skeleton generator first, then fill in every `[TODO: ...]` by reading the actual files:
+
+```bash
+python skills/code-tour/scripts/generate_from_docs.py \
+  --persona new-joiner \
+  --output .tours/skeleton.tour
+```
+
+### Entry points by language/framework
+
+Don't read everything — start here, then follow imports.
+
+| Stack | Entry points to read first |
+|-------|---------------------------|
+| **Node.js / TS** | `index.js/ts`, `server.js`, `app.js`, `src/main.ts`, `package.json` (scripts) |
+| **Python** | `main.py`, `app.py`, `__main__.py`, `manage.py` (Django), `app/__init__.py` (Flask/FastAPI) |
+| **Go** | `main.go`, `cmd/<name>/main.go`, `internal/` |
+| **Rust** | `src/main.rs`, `src/lib.rs`, `Cargo.toml` |
+| **Java / Kotlin** | `*Application.java`, `src/main/java/.../Main.java`, `build.gradle` |
+| **Ruby** | `config/application.rb`, `config/routes.rb`, `app/controllers/application_controller.rb` |
+| **PHP** | `index.php`, `public/index.php`, `bootstrap/app.php` (Laravel) |
+
+### Repo type variants — adjust focus accordingly
+
+The same persona asks for different things depending on what kind of repo this is:
+
+| Repo type | What to emphasize | Typical anchor files |
+|-----------|-------------------|----------------------|
+| **Service / API** | Request lifecycle, auth, error contracts | router, middleware, handler, schema |
+| **Library / SDK** | Public API surface, extension points, versioning | index/exports, types, changelog |
+| **CLI tool** | Command parsing, config loading, output formatting | main, commands/, config |
+| **Monorepo** | Package boundaries, shared contracts, build graph | root package.json/pnpm-workspace, shared/, packages/ |
+| **Framework** | Plugin system, lifecycle hooks, escape hatches | core/, plugins/, lifecycle |
+| **Data pipeline** | Source → transform → sink, schema ownership | ingest/, transform/, schema/, dbt models |
+| **Frontend app** | Component hierarchy, state management, routing | pages/, store/, router, api/ |
+
+For **monorepos**: identify the 2–3 packages most relevant to the persona's goal. Don't try to tour everything — open the tour with a step that explains how to navigate the workspace, then stay focused.
+
+### Large repo strategy
+
+For repos with 100+ files: don't try to read everything.
+
+1. Read entry points and the README first
+2. Build a mental model of the top 5–7 modules
+3. For the requested persona, identify the **2–3 modules that matter most** and read those deeply
+4. For modules you're not covering, mention them in the intro step as "out of scope for this tour"
+5. Use `directory` steps for areas you mapped but didn't read — they orient without requiring full knowledge
+
+A focused 10-step tour of the right files beats a scattered 25-step tour of everything.
+
+---
+
+## Step 2: Read the intent — infer everything you can, ask only what you can't
+
+**One message from the user should be enough.** Read their request and infer persona,
+depth, and focus before asking anything.
+
+### Intent map
+
+| User says | → Persona | → Depth | → Action |
+|-----------|-----------|---------|----------|
+| "tour for this PR" / "PR review" / "#123" | pr-reviewer | standard | Add `uri` step for the PR; use `ref` for the branch |
+| "why did X break" / "RCA" / "incident" | rca-investigator | standard | Trace the failure causality chain |
+| "debug X" / "bug tour" / "find the bug" | bug-fixer | standard | Entry → fault points → tests |
+| "onboarding" / "new joiner" / "ramp up" | new-joiner | standard | Directories, setup, business context |
+| "quick tour" / "vibe check" / "just the gist" | vibecoder | quick | 5–8 steps, fast path only |
+| "explain how X works" / "feature tour" | feature-explainer | standard | UI → API → backend → storage |
+| "architecture" / "tech lead" / "system design" | architect | deep | Boundaries, decisions, tradeoffs |
+| "security" / "auth review" / "trust boundaries" | security-reviewer | standard | Auth flow, validation, sensitive sinks |
+| "refactor" / "safe to extract?" | refactorer | standard | Seams, hidden deps, extraction order |
+| "performance" / "bottlenecks" / "slow path" | performance-optimizer | standard | Hot path, N+1, I/O, caches |
+| "contributor" / "open source onboarding" | external-contributor | quick | Safe areas, conventions, landmines |
+| "concept" / "explain pattern X" | concept-learner | standard | Concept → implementation → rationale |
+| "test coverage" / "where to add tests" | test-writer | standard | Contracts, seams, coverage gaps |
+| "how do I call the API" | api-consumer | standard | Public surface, auth, error semantics |
+
+**Infer silently:** persona, depth, focus area, whether to add `uri`/`ref`, `isPrimary`.
+
+**Ask only if you genuinely can't infer:**
+- "bug tour" but no bug described → ask for the bug description
+- "feature tour" but no feature named → ask which feature
+- "specific files" explicitly requested → honor them as required stops
+
+Never ask about `nextTour`, `commands`, `when`, or `stepMarker` unless the user mentioned them.
+
+### PR tour recipe
+
+For PR tours: set `"ref"` to the branch, open with a `uri` step for the PR, cover changed files first, then unchanged-but-critical files, close with a reviewer checklist.
+
+### User-provided customization — always honor these
+
+| User says | What to do |
+|-----------|-----------|
+| "cover `src/auth.ts` and `config/db.yml`" | Those files are required stops |
+| "pin to the `v2.3.0` tag" / "this commit: abc123" | Set `"ref": "v2.3.0"` |
+| "link to PR #456" / pastes a URL | Add a `uri` step at the right narrative moment |
+| "lead into the security tour when done" | Set `"nextTour": "Security Review"` |
+| "make this the main onboarding tour" | Set `"isPrimary": true` |
+| "open a terminal at this step" | Add `"commands": ["workbench.action.terminal.focus"]` |
+| "deep" / "thorough" / "5 steps" / "quick" | Override depth accordingly |
+
+---
+
+## Step 3: Read the actual files — no exceptions
+
+**Every file path and line number in the tour must be verified by reading the file.**
+A tour pointing to the wrong file or a non-existent line is worse than no tour.
+
+For every planned step:
+1. Read the file
+2. Find the exact line of the code you want to highlight
+3. Understand it well enough to explain it to the target persona
+
+If a user-requested file doesn't exist, say so — don't silently substitute another.
+
+---
+
+## Step 4: Write the tour
+
+Save to `.tours/<persona>-<focus>.tour`. Read `references/codetour-schema.json` for the
+authoritative field list. Every field you use must appear in that schema.
+
+### Tour root
+
+```json
+{
+  "$schema": "https://aka.ms/codetour-schema",
+  "title": "Descriptive Title — Persona / Goal",
+  "description": "One sentence: who this is for and what they'll understand after.",
+  "ref": "main",
+  "isPrimary": false,
+  "nextTour": "Title of follow-up tour",
+  "steps": []
+}
+```
+
+Omit any field that doesn't apply to this tour.
+
+**`when`** — conditional display. A JavaScript expression evaluated at runtime. Only show this tour
+if the condition is true. Useful for persona-specific auto-launching, or hiding advanced tours
+until a simpler one is complete.
+```json
+{ "when": "workspaceFolders[0].name === 'api'" }
+```
+
+**`stepMarker`** — embed step anchors directly in source code comments. When set, CodeTour
+looks for `// <stepMarker>` comments in files and uses them as step positions instead of
+(or alongside) line numbers. Useful for tours on actively changing code where line numbers
+shift constantly. Example: set `"stepMarker": "CT"` and put `// CT` in the source file.
+Don't suggest this unless the user asks — it requires editing source files, which is unusual.
+
+---
+
+### Step types — full reference
+
+All step types: **content** (intro/closing, max 2), **directory**, **file+line** (workhorse), **selection** (code block), **pattern** (regex match), **uri** (external link), **view** (focus VS Code panel), **commands** (run VS Code commands).
+
+> **Path rule:** `"file"` and `"directory"` must be relative to repo root. No absolute paths, no leading `./`.
+
+---
+
+### When to use each step type
+
+| Situation | Step type |
+|-----------|-----------|
+| Tour intro or closing | content |
+| "Here's what lives in this folder" | directory |
+| One line tells the whole story | file + line |
+| A function/class body is the point | selection |
+| Line numbers shift, file is volatile | pattern |
+| PR / issue / doc gives the "why" | uri |
+| Reader should open terminal or explorer | view or commands |
+
+---
+
+### Step count calibration
+
+Match steps to depth and persona. These are targets, not hard limits.
+
+| Depth | Total steps | Core path steps | Notes |
+|-------|-------------|-----------------|-------|
+| Quick | 5–8 | 3–5 | Vibecoder, fast explorer — cut ruthlessly |
+| Standard | 9–13 | 6–9 | Most personas — breadth + enough detail |
+| Deep | 14–18 | 10–13 | Architect, RCA — every tradeoff surfaced |
+
+Scale with repo size too. A 3-file CLI doesn't get 15 steps. A 200-file monolith shouldn't be squeezed into 5.
+
+| Repo size | Recommended standard depth |
+|-----------|---------------------------|
+| Tiny (< 20 files) | 5–8 steps |
+| Small (20–80 files) | 8–11 steps |
+| Medium (80–300 files) | 10–13 steps |
+| Large (300+ files) | 12–15 steps (scoped to relevant subsystem) |
+
+---
+
+### Writing excellent descriptions — the SMIG formula
+
+Every description should answer four questions in order. You don't need four paragraphs — but every description needs all four elements, even briefly.
+
+**S — Situation**: What is the reader looking at? One sentence grounding them in context.
+**M — Mechanism**: How does this code work? What pattern, rule, or design is in play?
+**I — Implication**: Why does this matter for *this persona's goal specifically*?
+**G — Gotcha**: What would a smart person get wrong here? What's non-obvious, fragile, or surprising?
+
+Descriptions should tell the reader something they couldn't learn by reading the file themselves. Name the pattern, explain the design decision, flag failure modes, and cross-reference related context.
+
+---
+
+## Narrative arc — every tour, every persona
+
+1. **Orientation** — **must be a `file` or `directory` step, never content-only.**
+   Use `"file": "README.md", "line": 1` or `"directory": "src"` and put your welcome text in the description.
+   A content-only first step (no `file`, `directory`, or `uri`) renders as a blank page in VS Code CodeTour — this is a known VS Code extension behaviour, not configurable.
+
+2. **High-level map** (1–3 directory or uri steps) — major modules and how they relate.
+   Not every folder — just what this persona needs to know.
+
+3. **Core path** (file/line, selection, pattern, uri steps) — the specific code that matters.
+   This is the heart of the tour. Read and narrate. Don't skim.
+
+4. **Closing** (content) — what the reader now understands, what they can do next,
+   2–3 suggested follow-up tours. If `nextTour` is set, reference it by name here.
+
+### Closing steps
+
+Don't summarize — the reader just read it. Instead, tell them what they can now *do*, what to avoid, and suggest 2-3 follow-up tours.
+
+---
+
+## The 20 personas
+
+| Persona | Goal | Must cover | Avoid |
+|---------|------|------------|-------|
+| **Vibecoder** | Get the vibe fast | Entry point, request flow, main modules. Max 8 steps. | Deep dives, edge cases |
+| **New joiner** | Structured ramp-up | Directories, setup, business context, service boundaries. | Advanced internals |
+| **Bug fixer** | Root cause fast | User action → trigger → fault points. Repro hints + test locations. | Architecture tours |
+| **RCA investigator** | Why did it fail | Causality chain, side effects, race conditions, observability. | Happy path |
+| **Feature explainer** | One feature end-to-end | UI → API → backend → storage. Feature flags, edge cases. | Unrelated features |
+| **PR reviewer** | Review the change correctly | Change story, invariants, risky areas, reviewer checklist. URI step for PR. | Unrelated context |
+| **Security reviewer** | Trust boundaries | Auth flow, input validation, secret handling, sensitive sinks. | Unrelated business logic |
+| **Refactorer** | Safe restructuring | Seams, hidden deps, coupling hotspots, safe extraction order. | Feature explanations |
+| **External contributor** | Contribute without breaking | Safe areas, code style, architecture landmines. | Deep internals |
+| **Tech lead / architect** | Shape and rationale | Module boundaries, design tradeoffs, risk hotspots. | Line-by-line walkthroughs |
+
+---
+
+## Designing a tour series
+
+When a codebase is complex enough that one tour can't cover it well, design a series.
+The `nextTour` field chains them: when the reader finishes one tour, VS Code offers to
+launch the next automatically.
+
+**Plan the series before writing any tour.** A good series has:
+- A clear escalation path (broad → narrow, orientation → deep-dive)
+- No duplicate steps between tours
+- Each tour standalone enough to be useful on its own
+
+Set `nextTour` in each tour to the `title` of the next one (must match exactly). Each tour should be standalone enough to be useful on its own.
+
+---
+
+## What CodeTour cannot do
+
+If asked for any of these, say clearly that it's not supported — do not suggest a workaround that doesn't exist:
+
+| Request | Reality |
+|---|---|
+| **Auto-advance to next step after X seconds** | Not supported. Navigation is always manual — the reader clicks Next. There is no timer, delay, or autoplay step mechanic in CodeTour. |
+| **Embed a video or GIF in a step** | Not supported. Descriptions are Markdown text only. |
+| **Run arbitrary shell commands** | Not supported. `commands` only executes VS Code commands (e.g. `workbench.action.terminal.focus`), not shell commands. |
+| **Branch / conditional next step** | Not supported. Tours are linear. `when` controls whether a tour is shown, not which step follows which. |
+| **Show a step without opening a file** | Partially — content-only steps work, but step 1 must have a `file` or `directory` anchor or VS Code shows a blank page. |
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| **File listing** — visiting files with "this file contains..." | Tell a story; each step should depend on the previous one |
+| **Generic descriptions** | Name the specific pattern/gotcha unique to *this* codebase |
+| **Line number guessing** | Never write a line number you didn't verify by reading the file |
+| **Ignoring the persona** | Cut every step that doesn't serve their specific goal |
+| **Hallucinated files** | If a file doesn't exist, skip the step |
+
+---
+
+## Quality checklist — verify before writing the file
+
+- [ ] Every `file` path is **relative to the repo root** (no leading `/` or `./`)
+- [ ] Every `file` path read and confirmed to exist
+- [ ] Every `line` number verified by reading the file (not guessed)
+- [ ] Every `directory` is **relative to the repo root** and confirmed to exist
+- [ ] Every `pattern` regex would match a real line in the file
+- [ ] Every `uri` is a complete, real URL (https://...)
+- [ ] `ref` is a real branch/tag/commit if set
+- [ ] `nextTour` exactly matches the `title` of another `.tour` file if set
+- [ ] Only `.tour` JSON files created — no source code touched
+- [ ] First step has a `file` or `directory` anchor (content-only first step = blank page in VS Code)
+- [ ] Tour ends with a closing content step that tells the reader what they can *do* next
+- [ ] Every description answers SMIG — Situation, Mechanism, Implication, Gotcha
+- [ ] Persona's priorities drive step selection (cut everything that doesn't serve their goal)
+- [ ] Step count matches requested depth and repo size (see calibration table)
+- [ ] At most 2 content-only steps (intro + closing)
+- [ ] All fields conform to `references/codetour-schema.json`
+
+---
+
+## Step 5: Validate the tour
+
+**Always run the validator immediately after writing the tour file. Do not skip this step.**
+
+```bash
+python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
+```
+
+The validator checks:
+- JSON validity
+- Every `file` path exists and every `line` is within file bounds
+- Every `directory` exists
+- Every `pattern` regex compiles and matches at least one line in the file
+- Every `uri` starts with `https://`
+- `nextTour` matches an existing tour title in `.tours/`
+- Content-only step count (warns if > 2)
+- Narrative arc (warns if no orientation or closing step)
+
+**Fix every error before proceeding.** Re-run until the validator reports ✓ or only warnings. Warnings are advisory — use your judgment. Do not show the user the tour until validation passes.
+
+**Common VS Code issues:** Content-only first step renders blank (anchor to file/directory instead). Absolute or `./`-prefixed paths silently fail. Out-of-bounds line numbers scroll nowhere.
+
+If you can't run scripts, manually verify: step 1 has `file`/`directory`, all paths exist, all line numbers are in bounds, `nextTour` matches exactly.
+
+**Autoplay:** `isPrimary: true` + `.vscode/settings.json` with `{ "codetour.promptForPrimaryTour": true }` prompts on repo open. Omit `ref` for tours that should appear on any branch.
+
+**Share:** For public repos, users can open tours at `https://vscode.dev/github.com/<owner>/<repo>` with no install.
+
+---
+
+## Step 6: Summarize
+
+After writing the tour, tell the user:
+- File path (`.tours/<name>.tour`)
+- One-paragraph summary of what the tour covers and who it's for
+- The `vscode.dev` URL if the repo is public (so they can share it immediately)
+- 2–3 suggested follow-up tours (or the next tour in the series if one was planned)
+- Any user-requested files that didn't exist (be explicit — don't quietly substitute)
+
+---
+
+## File naming
+
+`<persona>-<focus>.tour` — kebab-case, communicates both:
+```
+onboarding-new-joiner.tour
+bug-fixer-payment-flow.tour
+architect-overview.tour
+vibecoder-quickstart.tour
+pr-review-auth-refactor.tour
+security-auth-boundaries.tour
+concept-dependency-injection.tour
+rca-login-outage.tour
+```

package/skills/dev-comment-code-generate-a-tutorial.md

@@ -0,0 +1,27 @@
+---
+name: comment-code-generate-a-tutorial
+description: 'Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial.'
+category: dev
+---
+
+Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial.
+
+1. **Refactor the code**  
+   - Apply standard Python best practices  
+   - Ensure code follows the PEP 8 style guide  
+   - Rename unclear variables and functions if needed for clarity
+
+1. **Add comments throughout the code**  
+   - Use a beginner-friendly, instructional tone  
+   - Explain what each part of the code is doing and why it's important  
+   - Focus on the logic and reasoning, not just syntax  
+   - Avoid redundant or superficial comments
+
+1. **Generate a tutorial as a `README.md` file**  
+   Include the following sections:
+   - **Project Overview:** What the script does and why it's useful  
+   - **Setup Instructions:** Prerequisites, dependencies, and how to run the script  
+   - **How It Works:** A breakdown of the code logic based on the comments  
+   - **Example Usage:** A code snippet showing how to use it  
+   - **Sample Output:** (Optional) Include if the script returns visible results  
+   - Use clear, readable Markdown formatting

package/skills/dev-commit.md

@@ -0,0 +1,81 @@
+---
+name: commit
+description: Commit staged or unstaged changes with an AI-generated commit message that matches the repository's existing commit style. Use when the user asks to 'commit', 'commit changes', 'create a commit', 'save my work', or 'check in code'.
+category: dev
+---
+<!-- Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior. -->
+
+# Commit Changes
+
+Help the user commit code changes with a well-crafted commit message derived from the diff, following the conventions already established in the repository.
+
+## Guidelines
+
+- **Never amend existing commits** without asking.
+- **Never force-push or push** without explicit user approval.
+- **Never skip pre-commit hooks** (do not use `--no-verify`).
+- **Never skip signing commits** (do not use `--no-gpg-sign`).
+- **Never revert, reset, or discard user changes** unless the user explicitly asked for that.
+- Check for obvious secrets or generated artifacts that should not be committed. If something looks risky - ask the user.
+- When in doubt about staging, convention, or message content — ask the user.
+
+## Workflow
+
+### 1. Discover the repository's commit convention
+
+Run the following to sample recent commits and the user's own commits:
+
+```
+# Recent repo commits (for overall style)
+git log --oneline -20
+
+# User's recent commits (for personal style)
+git log --oneline --author="$(git config user.name)" -10
+```
+
+Analyse the output to determine the commit message convention used in the repository (e.g. Conventional Commits, Gitmoji, ticket-prefixed, free-form). All generated messages **must** follow the detected convention.
+
+### 2. Check repository status
+
+```
+git status --short
+```
+
+- If there are **no changes** (working tree clean, nothing staged), inform the user and stop.
+- If there are **staged changes**, proceed with those and do not stage any unstaged changes.
+- If there are **only unstaged changes**, stage everything (`git add -A`), and proceed with those.
+
+### 3. Generate the commit message
+
+Obtain the full diff of what will be committed:
+
+```bash
+git diff --cached --stat
+git diff --cached
+```
+
+Using the diff and the commit convention detected in step 1, draft a commit message with:
+
+- A **subject line** (≤ 72 characters) that summarises the change, following the repository's convention.
+- An optional **body** that explains *why* the change was made, only when the diff is non-trivial.
+- Reference issue/ticket numbers when they appear in branch names or related context.
+- Focus on the intent of the change, not a file-by-file inventory.
+
+### 4. Commit
+
+Construct the `git commit` command with the generated message.
+
+Execute the commit:
+
+```
+git commit -m "<subject>" -m "<body>"
+```
+
+### 5. Confirm
+
+After the commit:
+
+- Run `git status --short` to confirm the commit completed.
+- Run `git log --oneline -1` to show the new commit.
+- If pre-commit hooks changed files or blocked the commit, summarize exactly what happened.
+- If hooks rewrote files after the commit attempt, do not amend automatically. Tell the user what changed and ask whether they want you to stage and commit those follow-up edits.

package/skills/dev-context-map.md

@@ -0,0 +1,53 @@
+---
+name: context-map
+description: 'Generate a map of all files relevant to a task before making changes'
+category: dev
+---
+
+# Context Map
+
+Before implementing any changes, analyze the codebase and create a context map.
+
+## Task
+
+{{task_description}}
+
+## Instructions
+
+1. Search the codebase for files related to this task
+2. Identify direct dependencies (imports/exports)
+3. Find related tests
+4. Look for similar patterns in existing code
+
+## Output Format
+
+```markdown
+## Context Map
+
+### Files to Modify
+| File | Purpose | Changes Needed |
+|------|---------|----------------|
+| path/to/file | description | what changes |
+
+### Dependencies (may need updates)
+| File | Relationship |
+|------|--------------|
+| path/to/dep | imports X from modified file |
+
+### Test Files
+| Test | Coverage |
+|------|----------|
+| path/to/test | tests affected functionality |
+
+### Reference Patterns
+| File | Pattern |
+|------|---------|
+| path/to/similar | example to follow |
+
+### Risk Assessment
+- [ ] Breaking changes to public API
+- [ ] Database migrations needed
+- [ ] Configuration changes required
+```
+
+Do not proceed with implementation until this map is reviewed.

package/skills/dev-conventional-commit.md

@@ -0,0 +1,73 @@
+---
+name: conventional-commit
+description: 'Prompt and workflow for generating conventional commit messages using a structured XML format. Guides users to create standardized, descriptive commit messages in line with the Conventional Commits specification, including instructions, examples, and validation.'
+category: dev
+---
+
+### Instructions
+
+```xml
+	<description>This file contains a prompt template for generating conventional commit messages. It provides instructions, examples, and formatting guidelines to help users write standardized, descriptive commit messages in accordance with the Conventional Commits specification.</description>
+```
+
+### Workflow
+
+**Follow these steps:**
+
+1. Run `git status` to review changed files.
+2. Run `git diff` or `git diff --cached` to inspect changes.
+3. Stage your changes with `git add <file>`.
+4. Construct your commit message using the following XML structure.
+5. After generating your commit message, Copilot will automatically run the following command in your integrated terminal (no confirmation needed):
+
+```bash
+git commit -m "type(scope): description"
+```
+
+6. Just execute this prompt and Copilot will handle the commit for you in the terminal.
+
+### Commit Message Structure
+
+```xml
+<commit-message>
+	<type>feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert</type>
+	<scope>()</scope>
+	<description>A short, imperative summary of the change</description>
+	<body>(optional: more detailed explanation)</body>
+	<footer>(optional: e.g. BREAKING CHANGE: details, or issue references)</footer>
+</commit-message>
+```
+
+### Examples
+
+```xml
+<examples>
+	<example>feat(parser): add ability to parse arrays</example>
+	<example>fix(ui): correct button alignment</example>
+	<example>docs: update README with usage instructions</example>
+	<example>refactor: improve performance of data processing</example>
+	<example>chore: update dependencies</example>
+	<example>feat!: send email on registration (BREAKING CHANGE: email service required)</example>
+</examples>
+```
+
+### Validation
+
+```xml
+<validation>
+	<type>Must be one of the allowed types. See <reference>https://www.conventionalcommits.org/en/v1.0.0/#specification</reference></type>
+	<scope>Optional, but recommended for clarity.</scope>
+	<description>Required. Use the imperative mood (e.g., "add", not "added").</description>
+	<body>Optional. Use for additional context.</body>
+	<footer>Use for breaking changes or issue references.</footer>
+</validation>
+```
+
+### Final Step
+
+```xml
+<final-step>
+	<cmd>git commit -m "type(scope): description"</cmd>
+	<note>Replace with your constructed message. Include body and footer if needed.</note>
+</final-step>
+```