Gyschuaner/from-idea-to-personal-site

Edit Site Part

Goal

Make a targeted improvement to one part of an existing static site while preserving the rest of the site.

This skill is for iterative polish after a site already exists. It should feel like careful local editing, not a new generation pass.

Contract

Inputs:

• Existing static site folder, target page, screenshot/local URL, or natural-language description of the target region.
• EDITING.md and relevant HTML/CSS/JS files.
• Desired before/after text, style, responsive behavior, or small interaction change.

Outputs:

• A focused edit to the affected page section, component, copy block, style rule, or lightweight interaction.
• Updated EDITING.md only when future editing instructions need to change.
• Brief report of where the change was made, files changed, and validation performed.

Boundaries:

• Do not rebuild the whole site, change theme direction, import posts, personalize many fields, or publish.
• Do not touch unrelated pages/assets.
• Do not introduce dependencies, build steps, or root-absolute site-local paths.

Success gate:

• The requested local change is visible in the same browser region that was confirmed before editing.
• Desktop/mobile or interaction checks pass for the affected surface.
• No unrelated layout or navigation changes were introduced.

If gate fails:

• Re-map the browser region to source and make the smallest corrective edit.
• Run or suggest review-static-site when the issue affects shared navigation, many pages, assets, encoding, or publishing readiness.

Use When

Use this skill when the user asks to:

• Change one section, card, block, component, or page region.
• Make a visual detail smaller, calmer, denser, cleaner, more playful, more technical, or less distracting.
• Fix a mobile layout problem, text overflow, spacing issue, or awkward alignment.
• Adjust a small interaction such as hover, theme toggle, menu behavior, copy button, filter, tab, or animation.
• Rewrite or shorten a specific piece of visible text.
• Match a screenshot or user comment for a localized area.

Do not use this skill for full-site generation, theme search, close recreation of a new reference site, large personal-content replacement, article migration, deployment, or framework conversion.

Inputs

Use whatever the user provides:

• Site root folder and target page.
• A screenshot, browser view, local URL, or natural-language description of the problem.
• The exact text, section name, class name, or visual area to change.
• EDITING.md, if present.
• Existing HTML/CSS/JS files.
• Any desired before/after wording or style direction.

If the target area is ambiguous, inspect the site and make the smallest reasonable interpretation. Ask a short clarification only when multiple plausible edits would produce very different results.

Workflow

1. Before editing, use the browser to confirm the target page and target region.
2. Read EDITING.md when present, then inspect the relevant HTML/CSS/JS.
3. Use search to find matching visible text, IDs, classes, data blocks, or component-like markup.
4. Map the confirmed browser region to the relevant source files, selectors, data blocks, or event handlers.
5. Make the smallest coherent edit that satisfies the request.
6. Keep the existing design language unless the user explicitly asks to change it.
7. After editing, return to the same page and region in the browser and verify the change there.
8. Report what changed and mention any follow-up validation needed.

Scope Control

Keep the edit local.

• Prefer editing the existing section, class, or data object instead of creating a parallel duplicate.
• Avoid rewriting the whole page when a section-level change is enough.
• Avoid changing shared CSS variables unless the user wants a site-wide style change.
• Avoid touching unrelated pages, assets, or content.
• Preserve navigation, page map, placeholder strategy, and EDITING.md conventions.
• Preserve the site's path strategy; do not introduce root-absolute site-local paths such as /assets/..., /posts/..., /images/..., or /data/... during a local edit.
• If a small request exposes a larger structural issue, explain the tradeoff before making broad changes.

When the user asks for a broad visual shift across multiple pages, suggest using a larger-generation or redesign skill instead of stretching this one.

Locate The Right Place

Use a layered lookup:

1. Search for the visible text or nearby labels.
2. Search EDITING.md for the section/page map.
3. Inspect navigation links and page filenames.
4. Inspect semantic tags such as header, main, section, article, aside, and footer.
5. Inspect CSS selectors and JavaScript event hooks.
6. Use browser devtools or screenshots when the source location is not obvious.

If repeated content is rendered from data, edit the source data rather than only the generated-looking markup.

Design Preservation

Fit the edit into the current site.

• Reuse existing spacing, typography, colors, borders, shadows, icons, and motion patterns.
• Keep text within its container on desktop and mobile.
• Avoid making decorative effects interfere with reading.
• Respect prefers-reduced-motion when changing animation.
• Keep article/detail pages calmer than heavily styled home pages unless the user asks otherwise.
• Do not add a marketing-style hero or unrelated decorative section to a personal website or blog.

When changing copy, match the existing voice and the user's language.

Interaction Edits

For JavaScript or interaction changes:

• Find existing event listeners and state conventions before adding new ones.
• Keep vanilla JavaScript if the site is plain static.
• Avoid introducing dependencies or build steps.
• When generating links, search results, image URLs, or navigation items in JavaScript, use page-relative paths that work from the affected page depth.
• Test click, keyboard, mobile, and repeated-use states when relevant.
• Preserve accessibility basics such as focus, labels, and reduced-motion behavior.

Responsive Fixes

For layout or mobile issues:

• Check both desktop and mobile widths.
• Prefer CSS changes that preserve the desktop layout while fixing narrow screens.
• Use stable dimensions, wrapping, min/max widths, grid/flex adjustments, and overflow control.
• Do not hide important content on mobile just to make the layout fit.

Editing Guide

If the change affects how future edits should be made, update EDITING.md.

Update it when:

• A new section, class, data field, or interaction pattern is introduced.
• Content storage moves to a new file or data object.
• The user requested a change that future agents may need to preserve.

Do not update EDITING.md for tiny copy or spacing changes unless the guide would otherwise become misleading.

Validation

Validate the affected surface, not necessarily the whole site.

Use an actually available interactive browser tool before editing to confirm the target page and region. "Available" means it is exposed in the current turn's callable tool list. In Codex this may be the Browser/in-app browser plugin when routed into the turn; in other agents it may be an equivalent visible browser, browser-use tool, or devtools-backed browser. After editing, return to that same page and region in the interactive browser to verify the result.

If no interactive browser tool is callable, do not pretend the before/after browser confirmation happened. Ask the user to enable or invoke the browser tool if the edit depends on visual region mapping; for Codex, that may mean sending a request that explicitly mentions @browser. If the user does not re-route or the client has no such tool, fall back to Playwright, screenshots, or source inspection and state the limitation.

Do not default to Playwright, screenshots-only validation, or source inspection alone when an interactive browser tool is actually callable. Use Playwright only as a fallback when no interactive browser tool is callable, when the user explicitly asks for it, or when repeatable scripted regression is specifically needed.

For visual, responsive, or interactive edits, check the changed region in the relevant desktop/mobile viewports and exercise the changed interaction.

Run or suggest review-static-site only when the edit affects shared navigation, global layout, many pages, asset paths, source encoding, or publishing readiness.

If the edit touches href, src, CSS url(...), images, fonts, favicons, data files, or JavaScript-generated URLs, verify that the affected page still works with page-relative paths and that direct-opening the static file will not lose CSS, JS, or images.

Output

For local edits, only report:

• Where the change was made.
• Which files changed.
• What validation was done.

Mention broader review-static-site validation only when it is actually recommended. Do not repeat the report or over-explain the whole codebase.