📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
+151
@@ -0,0 +1,151 @@
|
||||
---
|
||||
name: antigravity-maintainer-batch-release
|
||||
description: "Run protected AAS maintainer sweeps, PR merge batches, canonical sync, Core preview checks, and scripted releases. Use for repository maintenance, main alignment, CLI/MCP/Workbench changes, or release work; not ordinary contribution tasks."
|
||||
risk: critical
|
||||
source: self
|
||||
date_added: "2026-07-18"
|
||||
---
|
||||
|
||||
# Antigravity Maintainer Batch Release
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill for repository-wide AAS maintenance, maintainer-side PR repair or merge batches, canonical synchronization, AAS Core or Workbench changes, protected releases, and hosted catalog or legacy redirect infrastructure. Do not use it for ordinary contribution work that does not require maintainer privileges or canonical convergence.
|
||||
|
||||
## Protected-Main Contract
|
||||
|
||||
Treat the repository root containing this skill as pull-request-only:
|
||||
|
||||
- Read `AGENTS.md`, `.github/MAINTENANCE.md`, and current maintainer docs before mutation.
|
||||
- Never commit or push directly to `main`, even when the user says “push to main.” That phrase names the final target state.
|
||||
- Preserve unrelated dirty work. Use a clean temporary clone or a topic branch for maintainer changes.
|
||||
- Use `npm run merge:batch` for accepted source PRs. Do not substitute a raw merge API, generic GitHub skill, or generic push helper.
|
||||
- Let `automation/canonical-repo-state` own generated artifacts and contributor-credit convergence after the source batch.
|
||||
- Use `release:prepare` and `release:publish` for releases. They never authorize a direct `main` push.
|
||||
|
||||
## Source Checks
|
||||
|
||||
Before changing anything:
|
||||
|
||||
1. Fetch `origin/main`; prove the clean maintainer checkout is on `main` and equals `origin/main`.
|
||||
2. Inspect live PRs, issues, discussions in scope, Actions failures, Dependabot, CodeQL, secret scanning, and `npm audit` where relevant.
|
||||
3. Confirm current scripts from `package.json`; do not rely on remembered release behavior.
|
||||
4. Capture user worktree status separately and keep those files out of maintainer commits.
|
||||
|
||||
## Maintainer Sweep
|
||||
|
||||
1. Triage every open PR before editing.
|
||||
- Separate valid source changes, repairable PRs, conflicts, generated-only noise, promotional links, and unsupported ownership/license changes.
|
||||
- Review semantics, safety, provenance, risk labels, limitations, source credits, and changed-skill evidence.
|
||||
- Prefer narrow maintainer repairs on the contributor branch when maintainer edits are enabled.
|
||||
|
||||
2. Validate changed skills truthfully.
|
||||
- Run `npm run validate`, `npm run validate:references`, `npm run security:docs`, changed-skill evidence, and the relevant tests.
|
||||
- Inspect semantics, safety, provenance, declared risk, limitations, and all tracked bundle files directly. Treat inferred risk labels and heuristic quality scores as non-authoritative; do not change a skill merely to satisfy a lexical signal.
|
||||
- Inspect the `skill-review` workflow on the exact current head SHA.
|
||||
- `review` means Tessl semantic review actually ran or a valid identical-content result was reused.
|
||||
- `manual-review-required` means Tessl credentials or credits were unavailable, or Tessl did not produce a passing result. Perform the maintainer semantic review and attest with `--reviewed-head <full-40-character-sha>`.
|
||||
- Any non-passing Tessl outcome produces `manual-review-required`; complete the semantic review and bind the judgment to the exact head instead of treating a heuristic score as merge authority.
|
||||
- Never report `manual-review-required` as “Tessl passed.”
|
||||
|
||||
3. Run checks in parallel where independent.
|
||||
- Use the repository validation, test, docs-security, source-credit, reference, warning-budget, and targeted app checks required by the changed files.
|
||||
- Fix deterministic policy failures in the source; do not wait for them as if they were flaky CI.
|
||||
|
||||
4. Merge accepted source PRs in conflict-aware order.
|
||||
- Run a dry classification first when useful.
|
||||
- For changed skill content, review the exact head and run:
|
||||
|
||||
```bash
|
||||
npm run merge:batch -- --prs <PR_LIST> --reviewed-head <FULL_HEAD_SHA>
|
||||
```
|
||||
|
||||
- `merge:batch` may normalize the PR body and close/reopen the PR. GitHub creates the replacement workflow runs asynchronously; the command must wait for and approve only post-reopen workflow/check-suite IDs. Older runs on the same SHA cannot satisfy or fail the fresh gate.
|
||||
- The routine protected checks are `pr-policy`, `pr-evidence`, `source-validation`, and `artifact-preview`. The retired `aas-v1-baseline` workflow is not a merge prerequisite and must not be awaited or approved during source or canonical-sync batches.
|
||||
- If the PR head or base changes, discard stale evidence and rerun from a fresh `origin/main`.
|
||||
|
||||
5. Converge canonical state once after the source batch.
|
||||
- Wait for the protected `automation/canonical-repo-state` PR.
|
||||
- Verify its managed-only diff, required checks, merge result, and the resulting `origin/main`.
|
||||
- If an unmanaged repair remains, use a topic PR; never patch `main` directly.
|
||||
|
||||
## Hosted Catalog and Legacy Redirect Bridge
|
||||
|
||||
Treat the current catalog and the legacy user-site bridge as one public system:
|
||||
|
||||
- Current catalog: `sickn33/agentic-awesome-skills` at `https://sickn33.github.io/agentic-awesome-skills/`.
|
||||
- Legacy bridge: `sickn33/sickn33.github.io` at `https://sickn33.github.io/antigravity-awesome-skills/`.
|
||||
|
||||
For SEO, indexing, Pages, redirect, or infrastructure changes:
|
||||
|
||||
1. Change the generator and verifier in the source repository through a protected source PR and `npm run merge:batch`.
|
||||
2. Keep the legacy deployment managed allowlist exact: `.nojekyll`, `redirect-manifest.json`, and `antigravity-awesome-skills/**`. Reject any unmanaged sync diff or PR file.
|
||||
3. Preserve Google verification byte-for-byte and the Bing `msvalidate.01` meta on the legacy root. Record both in manifest evidence.
|
||||
4. Keep skill counts dynamic, but retain intentional curated sitemap locks. Version manifest contract changes and record source provenance.
|
||||
5. Let `legacy-redirect-sync.yml` generate or update the fixed automation PR. Bind a fresh verifier run to the exact target head SHA, validate its run identity and managed file set, publish the required status only after that proof, then use protected auto-merge.
|
||||
6. Recheck source `main` before merge, request the legacy Pages build explicitly after bot-authored merges, and wait for the exact merged commit to be built.
|
||||
7. Verify locally generated output byte-for-byte, then verify all live legacy/current redirect pairs for a full audit. Retry transient CDN failures with the full audit rather than accepting a partial probe.
|
||||
8. Prove idempotence with a no-drift sync: no replacement, PR, verification, or merge steps should run; Pages and live probes must still pass.
|
||||
|
||||
Keep both repositories on least-privilege Actions defaults (`read`) and require external actions to be pinned to full commit SHAs. When changing these settings or action versions, rerun source CI, CodeQL, Pages, and a legacy no-drift sync before declaring completion.
|
||||
|
||||
## AAS Core Preview Acceptance
|
||||
|
||||
For AAS CLI, MCP, stack, catalog-cache, or Workbench changes:
|
||||
|
||||
1. Use the current scripts declared in `package.json`; do not resurrect retired evaluator, benchmark, tuning-gold, transaction-fault, race, or frozen-matrix gates as routine prerequisites.
|
||||
2. Run the focused Core tests with `npm run test:aas-v1`, the catalog integrity check with `npm run check:aas-v1-catalog`, and the relevant Workbench tests/build when its contracts or copy change.
|
||||
3. Keep MCP local, offline, read-only, bounded, and non-mutating. The coding agent inspects the project, searches and reads the complete catalog, and chooses the exact skill IDs. MCP searches, reads, validates agent-owned composition, and compares without scanning the repository or writing to it. Core must not rank, recommend, exclude, or disable skills; metadata is informational only.
|
||||
4. Keep `aas-stack.json` free of Core selection policy. It pins catalog identity, targets, goals, and the exact IDs selected by the agent. `compose_stack` validates and records that selection; missing or cautionary metadata must never make a canonical skill unselectable or unusable.
|
||||
5. Keep the supported public path at manifest validation and immutable plan preview. Planning may write only the requested plan artifact; it must not materialize skill payloads or AAS managed state in the target.
|
||||
6. Treat apply and recovery as experimental opt-ins outside the supported preview claim. Do not add apply/recovery, benchmark, fuzz, crash/race, or synthetic verifier work unless the user explicitly places it in scope.
|
||||
7. When the task asks for end-to-end client proof, use a real supported client that discovers and invokes the local AAS MCP tools; direct stdio probes and automated tests do not substitute for that evidence.
|
||||
8. Do not tag, publish npm, deploy Pages, or write real user MCP configuration without the separately required publication approval.
|
||||
|
||||
## Protected Release
|
||||
|
||||
Release only when requested.
|
||||
|
||||
1. Include the target changelog entry in the maintainer batch PR so it is already on protected `main`; avoid a separate release-notes-only PR.
|
||||
2. From clean, current `main`, run `npm run release:preflight` and required security checks.
|
||||
3. Run `npm run release:prepare -- X.Y.Z`. This creates and pushes `release/vX.Y.Z` and opens the protected release PR.
|
||||
4. Merge that release PR through its required checks, update local `main` to equal `origin/main`, and wait for any canonical-sync PR to close.
|
||||
5. Run `npm run release:publish -- X.Y.Z`. It verifies the exact protected merge before creating or reusing the tag and GitHub Release.
|
||||
6. Wait for publishing workflows, then verify the tag/ref, GitHub Release, npm version and dist-tag, CI, Pages, CodeQL, live `llms.txt`, `skills.json`, and changed catalog routes.
|
||||
|
||||
Never rebase a published release tag, force stale release state, reuse a failed published version, or claim npm publication from the GitHub Release alone.
|
||||
|
||||
## Stop Condition
|
||||
|
||||
Finish only when:
|
||||
|
||||
- every in-scope PR, issue, and alert is resolved or has one exact blocker;
|
||||
- no open source or canonical-sync PR remains unintentionally;
|
||||
- `main`, `origin/main`, required workflows, generated state, and public surfaces agree;
|
||||
- the source and legacy repositories have no unintended infrastructure PR, their protected branches and Actions settings remain enforced, and the live manifest identifies the source repository;
|
||||
- the user worktree is unchanged except for files the user explicitly placed in scope;
|
||||
- release proof is complete when a release was requested.
|
||||
|
||||
## Failure Rules
|
||||
|
||||
- A protected-branch rejection means switch to the PR path; never retry direct `main` pushes.
|
||||
- A missing PR checklist is informational; never mutate, close, or reopen a PR merely to refresh template metadata.
|
||||
- Preserve unrelated dirty files and never stage them into maintainer work.
|
||||
- Do not bypass `merge:batch`, canonical-sync, or scripted release commands with generic Git helpers.
|
||||
- Do not weaken a test or policy gate merely to make a batch pass. Retire a gate only after explicit maintainer authorization, then update branch protection, workflow files, merge automation, documentation, and maintainer skills together so no phantom requirement remains.
|
||||
|
||||
## Examples
|
||||
|
||||
For a reviewed source PR whose exact head is `0123456789abcdef0123456789abcdef01234567`, exercise the protected path before merging:
|
||||
|
||||
```bash
|
||||
npm run merge:batch -- --prs 914 --dry-run --reviewed-head 0123456789abcdef0123456789abcdef01234567
|
||||
```
|
||||
|
||||
Run the same command without `--dry-run` only after every required check passes and the attested head remains unchanged.
|
||||
|
||||
## Limitations
|
||||
|
||||
- This skill orchestrates the repository's existing scripts and protected workflows; it does not grant GitHub, npm, Pages, or local-client permissions.
|
||||
- Stop at the exact approval or credential boundary when publication, authenticated configuration, or another externally visible action was not authorized.
|
||||
- Re-read the current repository policy and `package.json` on every run because branch protection, checks, and supported preview commands may change.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: create-pr
|
||||
description: Alias for sentry-skills:pr-writer. Use when users explicitly ask for "create-pr" or reference the legacy skill name. Redirects to the canonical PR writing workflow.
|
||||
description: Alias for pr-writer. Use when users explicitly ask for "create-pr" or reference the legacy skill name. Redirects to the canonical PR writing workflow.
|
||||
risk: unknown
|
||||
source: community
|
||||
---
|
||||
@@ -11,12 +11,12 @@ This skill name is kept for compatibility.
|
||||
|
||||
## When to Use
|
||||
- The user explicitly asks for `create-pr` or refers to the legacy skill name.
|
||||
- You need to redirect pull request creation work to the canonical `sentry-skills:pr-writer` workflow.
|
||||
- You need to redirect pull request creation work to the canonical `pr-writer` workflow.
|
||||
- The task is specifically about writing or updating a pull request rather than general git operations.
|
||||
|
||||
Use `sentry-skills:pr-writer` as the canonical skill for creating and editing pull requests.
|
||||
Use the available `pr-writer` skill as the canonical workflow for creating and editing pull requests. If the client requires qualified skill names, use the qualifier for the plugin that supplied this skill rather than assuming an external namespace.
|
||||
|
||||
If invoked via `create-pr`, run the same workflow and conventions documented in `sentry-skills:pr-writer`.
|
||||
If invoked via `create-pr`, run the same workflow and conventions documented in `pr-writer`.
|
||||
|
||||
## Limitations
|
||||
- Use this skill only when the task clearly matches the scope described above.
|
||||
|
||||
+22
-19
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: 2d-games
|
||||
description: "2D game development principles. Sprites, tilemaps, physics, camera."
|
||||
description: >-
|
||||
2D game development principles. Sprites, atlases, tilemaps, physics, cameras,
|
||||
and genre patterns (platformer, top-down). Use for canvas/Phaser/Kaplay/Pixi
|
||||
2D games or guest viewports inside hybrid web apps.
|
||||
risk: none
|
||||
source: community
|
||||
date_added: "2026-02-27"
|
||||
@@ -8,24 +11,30 @@ date_added: "2026-02-27"
|
||||
|
||||
# 2D Game Development
|
||||
|
||||
> Principles for 2D game systems.
|
||||
> Principles for 2D game systems. Pair with `game-development/web-games` / `game-development/engine-selection` for framework choice.
|
||||
|
||||
---
|
||||
|
||||
## Shell vs guest (web)
|
||||
|
||||
| Setup | 2D systems live… |
|
||||
|-------|------------------|
|
||||
| Full-screen 2D game | Entire app (Phaser/Kaplay/Pixi/Canvas) |
|
||||
| Hybrid DOM + challenges | Only inside guest viewports; tear down when done |
|
||||
|
||||
---
|
||||
|
||||
## 1. Sprite Systems
|
||||
|
||||
### Sprite Organization
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| **Atlas** | Combine textures, reduce draw calls |
|
||||
| **Animation** | Frame sequences |
|
||||
| **Animation** | Frame sequences (often 8-24 FPS) |
|
||||
| **Pivot** | Rotation/scale origin |
|
||||
| **Layering** | Z-order control |
|
||||
|
||||
### Animation Principles
|
||||
|
||||
- Frame rate: 8-24 FPS typical
|
||||
- Squash and stretch for impact
|
||||
- Anticipation before action
|
||||
- Follow-through after action
|
||||
@@ -34,16 +43,12 @@ date_added: "2026-02-27"
|
||||
|
||||
## 2. Tilemap Design
|
||||
|
||||
### Tile Considerations
|
||||
|
||||
| Factor | Recommendation |
|
||||
|--------|----------------|
|
||||
| **Size** | 16x16, 32x32, 64x64 |
|
||||
| **Auto-tiling** | Use for terrain |
|
||||
| **Collision** | Simplified shapes |
|
||||
|
||||
### Layers
|
||||
|
||||
| Layer | Content |
|
||||
|-------|---------|
|
||||
| Background | Non-interactive scenery |
|
||||
@@ -55,8 +60,6 @@ date_added: "2026-02-27"
|
||||
|
||||
## 3. 2D Physics
|
||||
|
||||
### Collision Shapes
|
||||
|
||||
| Shape | Use Case |
|
||||
|-------|----------|
|
||||
| Box | Rectangular objects |
|
||||
@@ -64,9 +67,7 @@ date_added: "2026-02-27"
|
||||
| Capsule | Characters |
|
||||
| Polygon | Complex shapes |
|
||||
|
||||
### Physics Considerations
|
||||
|
||||
- Pixel-perfect vs physics-based
|
||||
- Pixel-perfect vs physics-based: pick one approach per game
|
||||
- Fixed timestep for consistency
|
||||
- Layers for filtering
|
||||
|
||||
@@ -74,14 +75,13 @@ date_added: "2026-02-27"
|
||||
|
||||
## 4. Camera Systems
|
||||
|
||||
### Camera Types
|
||||
|
||||
| Type | Use |
|
||||
|------|-----|
|
||||
| **Follow** | Track player |
|
||||
| **Look-ahead** | Anticipate movement |
|
||||
| **Multi-target** | Two-player |
|
||||
| **Room-based** | Metroidvania |
|
||||
| **Static** | Board games, modal skill-checks |
|
||||
|
||||
### Screen Shake
|
||||
|
||||
@@ -103,7 +103,7 @@ date_added: "2026-02-27"
|
||||
|
||||
- 8-directional or free movement
|
||||
- Aim-based or auto-aim
|
||||
- Consider rotation or not
|
||||
- Decide whether rotation matters
|
||||
|
||||
---
|
||||
|
||||
@@ -115,15 +115,18 @@ date_added: "2026-02-27"
|
||||
| Complex collision shapes | Simplified collision |
|
||||
| Jittery camera | Smooth following |
|
||||
| Pixel-perfect on physics | Choose one approach |
|
||||
| Orphaned RAF/listeners after a guest closes | Full teardown |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** 2D is about clarity. Every pixel should communicate.
|
||||
|
||||
## When to Use
|
||||
This skill is applicable to execute the workflow or actions described in the overview.
|
||||
|
||||
Use for canvas/Phaser/Kaplay/Pixi 2D systems, or guest viewports inside hybrid web apps.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Use this skill only when the task clearly matches the scope described above.
|
||||
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
|
||||
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|
||||
|
||||
+27
-35
@@ -1,6 +1,10 @@
|
||||
---
|
||||
name: game-development
|
||||
description: "Game development orchestrator. Routes to platform-specific skills based on project needs."
|
||||
description: >-
|
||||
Game development orchestrator. Routes by platform, dimension, and engine fit
|
||||
(web 2D/3D, hybrid DOM+canvas, narrative tools). Use when starting or
|
||||
structuring a game project, choosing frameworks, or picking among Phaser,
|
||||
PixiJS, Kaplay, Canvas/WebGL, Three.js, Babylon.js, Godot, Unity, or Ink/Twine.
|
||||
risk: unknown
|
||||
source: community
|
||||
date_added: "2026-02-27"
|
||||
@@ -8,13 +12,13 @@ date_added: "2026-02-27"
|
||||
|
||||
# Game Development
|
||||
|
||||
> **Orchestrator skill** that provides core principles and routes to specialized sub-skills.
|
||||
> **Orchestrator skill** — principles plus routing to specialized sub-skills.
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
You are working on a game development project. This skill teaches the PRINCIPLES of game development and directs you to the right sub-skill based on context.
|
||||
You are working on a game development project. This skill teaches PRINCIPLES and directs you to the right sub-skill based on context.
|
||||
|
||||
---
|
||||
|
||||
@@ -24,7 +28,7 @@ You are working on a game development project. This skill teaches the PRINCIPLES
|
||||
|
||||
| If the game targets... | Use Sub-Skill |
|
||||
|------------------------|---------------|
|
||||
| Web browsers (HTML5, WebGL) | `game-development/web-games` |
|
||||
| Web browsers (HTML5, WebGL, WebGPU) | `game-development/web-games` |
|
||||
| Mobile (iOS, Android) | `game-development/mobile-games` |
|
||||
| PC (Steam, Desktop) | `game-development/pc-games` |
|
||||
| VR/AR headsets | `game-development/vr-ar` |
|
||||
@@ -36,10 +40,11 @@ You are working on a game development project. This skill teaches the PRINCIPLES
|
||||
| 2D (sprites, tilemaps) | `game-development/2d-games` |
|
||||
| 3D (meshes, shaders) | `game-development/3d-games` |
|
||||
|
||||
### Specialty Areas
|
||||
### Architecture / tooling
|
||||
|
||||
| If you need... | Use Sub-Skill |
|
||||
|----------------|---------------|
|
||||
| Engine / framework choice, shell vs guest, fit tiers | `game-development/engine-selection` |
|
||||
| GDD, balancing, player psychology | `game-development/game-design` |
|
||||
| Multiplayer, networking | `game-development/multiplayer` |
|
||||
| Visual style, asset pipeline, animation | `game-development/game-art` |
|
||||
@@ -51,8 +56,6 @@ You are working on a game development project. This skill teaches the PRINCIPLES
|
||||
|
||||
### 1. The Game Loop
|
||||
|
||||
Every game, regardless of platform, follows this pattern:
|
||||
|
||||
```
|
||||
INPUT → Read player actions
|
||||
UPDATE → Process game logic (fixed timestep)
|
||||
@@ -64,7 +67,7 @@ RENDER → Draw the frame (interpolated)
|
||||
- Rendering: As fast as possible
|
||||
- Interpolate between states for smooth visuals
|
||||
|
||||
---
|
||||
**Hybrid / UI-heavy games:** the outer app may be DOM/event-driven; use a classic game loop only in canvas/WebGL viewports (or wherever simulation ticks).
|
||||
|
||||
### 2. Pattern Selection Matrix
|
||||
|
||||
@@ -76,11 +79,10 @@ RENDER → Draw the frame (interpolated)
|
||||
| **ECS** | Thousands of similar entities | RTS units, particles |
|
||||
| **Command** | Undo, replay, networking | Input recording |
|
||||
| **Behavior Tree** | Complex AI decisions | Enemy AI |
|
||||
| **Content-as-data** | Designers ship levels/events without code | JSON/YAML packs |
|
||||
|
||||
**Decision Rule:** Start with State Machine. Add ECS only when performance demands.
|
||||
|
||||
---
|
||||
|
||||
### 3. Input Abstraction
|
||||
|
||||
Abstract input into ACTIONS, not raw keys:
|
||||
@@ -90,10 +92,6 @@ Abstract input into ACTIONS, not raw keys:
|
||||
"move" → WASD, Left stick, Virtual joystick
|
||||
```
|
||||
|
||||
**Why:** Enables multi-platform, rebindable controls.
|
||||
|
||||
---
|
||||
|
||||
### 4. Performance Budget (60 FPS = 16.67ms)
|
||||
|
||||
| System | Budget |
|
||||
@@ -105,14 +103,7 @@ Abstract input into ACTIONS, not raw keys:
|
||||
| Rendering | 5ms |
|
||||
| Buffer | 1.67ms |
|
||||
|
||||
**Optimization Priority:**
|
||||
1. Algorithm (O(n²) → O(n log n))
|
||||
2. Batching (reduce draw calls)
|
||||
3. Pooling (avoid GC spikes)
|
||||
4. LOD (detail by distance)
|
||||
5. Culling (skip invisible)
|
||||
|
||||
---
|
||||
**Optimization Priority:** Algorithm → Batching → Pooling → LOD → Culling.
|
||||
|
||||
### 5. AI Selection by Complexity
|
||||
|
||||
@@ -123,8 +114,6 @@ Abstract input into ACTIONS, not raw keys:
|
||||
| **GOAP** | High | Emergent, planning-based |
|
||||
| **Utility AI** | High | Scoring-based decisions |
|
||||
|
||||
---
|
||||
|
||||
### 6. Collision Strategy
|
||||
|
||||
| Type | Best For |
|
||||
@@ -145,30 +134,33 @@ Abstract input into ACTIONS, not raw keys:
|
||||
| Cache nothing | Cache references |
|
||||
| Optimize without profiling | Profile first |
|
||||
| Mix input with logic | Abstract input layer |
|
||||
| Pick an engine by hype | Match engine to genre + team + delivery target |
|
||||
|
||||
---
|
||||
|
||||
## Routing Examples
|
||||
|
||||
### Example 1: "I want to make a browser-based 2D platformer"
|
||||
→ Start with `game-development/web-games` for framework selection
|
||||
→ Then `game-development/2d-games` for sprite/tilemap patterns
|
||||
→ Reference `game-development/game-design` for level design
|
||||
### “Browser 2D platformer”
|
||||
→ `game-development/engine-selection` → `game-development/web-games` → `game-development/2d-games` → `game-development/game-design`
|
||||
|
||||
### Example 2: "Mobile puzzle game for iOS and Android"
|
||||
→ Start with `game-development/mobile-games` for touch input and stores
|
||||
→ Use `game-development/game-design` for puzzle balancing
|
||||
### “UI-heavy web game with small arcade challenges”
|
||||
→ `game-development/engine-selection` (shell vs guest) → `game-development/web-games` → `game-development/2d-games` for guests only
|
||||
|
||||
### Example 3: "Multiplayer VR shooter"
|
||||
→ `game-development/vr-ar` for comfort and immersion
|
||||
→ `game-development/3d-games` for rendering
|
||||
→ `game-development/multiplayer` for networking
|
||||
### “Mobile puzzle”
|
||||
→ `game-development/mobile-games` → `game-development/game-design`
|
||||
|
||||
### “Multiplayer VR shooter”
|
||||
→ `game-development/vr-ar` → `game-development/3d-games` → `game-development/multiplayer`
|
||||
|
||||
### “Branching narrative with light stats”
|
||||
→ `game-development/engine-selection` (Ink/Twine) → host UI of your choice
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Great games come from iteration, not perfection. Prototype fast, then polish.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Use this skill only when the task clearly matches the scope described above.
|
||||
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
|
||||
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|
||||
|
||||
+115
@@ -0,0 +1,115 @@
|
||||
---
|
||||
name: engine-selection
|
||||
description: >-
|
||||
Selects game engines and frameworks by platform, genre, and architecture
|
||||
(full canvas shell vs hybrid DOM shell + guest viewport). Covers Phaser,
|
||||
PixiJS, Kaplay, Canvas/WebGL, Three.js, Babylon.js, Godot, Unity, Ink, Twine.
|
||||
Use when choosing a stack or comparing runtimes before implementation.
|
||||
risk: safe
|
||||
source: self
|
||||
date_added: "2026-07-17"
|
||||
---
|
||||
|
||||
# Engine selection
|
||||
|
||||
> Pick tools that match **delivery target**, **interaction model**, and **team constraints**. Engines serve the game type — not the reverse.
|
||||
|
||||
---
|
||||
|
||||
## Fit questions (ask first)
|
||||
|
||||
1. **Platform:** Web, mobile, PC, console, VR?
|
||||
2. **Primary loop:** Action/physics, turn-based, narrative branch, management/UI, hybrid?
|
||||
3. **Presentation:** Full-screen canvas, DOM/UI chrome, or both?
|
||||
4. **Toolchain:** No-build / ESM OK, or bundler + editor OK?
|
||||
5. **Authoring:** Code-only, or designers need Twine/Ink/Godot/Unity editors?
|
||||
|
||||
---
|
||||
|
||||
## Architecture patterns
|
||||
|
||||
| Pattern | When | Notes |
|
||||
|---------|------|-------|
|
||||
| **Full engine shell** | Game *is* the canvas/scene | Phaser, Godot, Unity, Kaplay as app root |
|
||||
| **Renderer + custom logic** | You want draw power, own gameplay | PixiJS, Three.js + your systems |
|
||||
| **Hybrid shell + guest** | Dense UI/text + occasional skill-checks | DOM/app shell; mount canvas engines in modals/viewports only |
|
||||
| **Narrative runtime** | Branching prose is the product | Ink, Twine; host chrome separately |
|
||||
| **Content-as-data** | Levels/events authored as packs | JSON/YAML + thin loader; engine optional |
|
||||
|
||||
---
|
||||
|
||||
## Web — decision tree
|
||||
|
||||
```
|
||||
What type of game?
|
||||
│
|
||||
├── Mostly DOM / panels / forms / text UI
|
||||
│ ├── + small arcade/spatial challenges
|
||||
│ │ └── Hybrid: custom shell + guest
|
||||
│ │ Raw Canvas/WebGL → Kaplay → Phaser → PixiJS
|
||||
│ └── + branching story
|
||||
│ └── Ink (inkjs) or Twine export → host in DOM
|
||||
│
|
||||
├── Full-screen 2D game
|
||||
│ ├── Full gameplay features (scenes, physics, input)
|
||||
│ │ └── Phaser 4 (or Kaplay if you want lighter/faster prototype)
|
||||
│ └── Mostly rendering / custom systems
|
||||
│ └── PixiJS 8 (or Raw Canvas/WebGL if tiny scope)
|
||||
│
|
||||
└── Full-screen 3D game
|
||||
├── Full engine / physics / XR
|
||||
│ └── Babylon.js
|
||||
└── Rendering-focused / lighter
|
||||
└── Three.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick comparison (web & common exports)
|
||||
|
||||
| Tool | Type | Best for | Watch-outs |
|
||||
|------|------|----------|------------|
|
||||
| **Raw Canvas / WebGL** | 2D/low-level | Tiny games, learning, no framework tax | You own everything |
|
||||
| **Kaplay** (ex-Kaboom) | 2D toolkit | Fast prototypes, jam games | Less “full product” structure than Phaser |
|
||||
| **Phaser 4** | 2D engine | Complete 2D features | Heavier; often bundled |
|
||||
| **PixiJS 8** | 2D renderer | Performance, custom game code | Not a full gameplay framework alone |
|
||||
| **Three.js** | 3D renderer | Visuals, lightweight 3D | You add gameplay systems |
|
||||
| **Babylon.js** | 3D engine | Fuller 3D + XR | Heavier than Three for simple scenes |
|
||||
| **Ink + inkjs** | Narrative | Complex branching prose | Weak for real-time multi-entity sims |
|
||||
| **Twine / Twison / TweeJS** | Narrative | Educator-friendly branches | Export/host glue; not a physics engine |
|
||||
| **Godot 4** | Full engine | 2D/3D indie, open source | Web export iteration cost |
|
||||
| **Unity** | Full engine | Large teams, multi-platform | Heavy for simple web UI games |
|
||||
|
||||
Editor-first web shells (**Construct**, **GDevelop**) fit visual prototyping; weaker when you need versioned code-first content pipelines.
|
||||
|
||||
---
|
||||
|
||||
## Non-web defaults (see also platform skills)
|
||||
|
||||
| Target | Lean toward |
|
||||
|--------|-------------|
|
||||
| PC indie / open source | Godot 4 |
|
||||
| PC large team / multi-platform | Unity |
|
||||
| Mobile | See `game-development/mobile-games` (touch, stores, battery) |
|
||||
| VR/AR | See `game-development/vr-ar` (+ Babylon/Three on web) |
|
||||
|
||||
---
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
| Don't | Do |
|
||||
|-------|-----|
|
||||
| Choose Unity/Godot for a form-heavy browser tool | Prefer DOM/hybrid |
|
||||
| Force Ink to run real-time concurrent simulations | Use narrative tools for branches; custom/sim code for clocks & entities |
|
||||
| Use Phaser as “the whole app” when the surrounding UI is HTML | Prefer a hybrid guest viewport |
|
||||
| Optimize for WebGPU on day one | Ship WebGL; add WebGPU + fallback when needed |
|
||||
|
||||
## When to Use
|
||||
|
||||
Use when choosing or comparing game engines/frameworks before implementation, especially for hybrid DOM+canvas or narrative-first products.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Does not replace platform skills (`game-development/web-games`, `game-development/pc-games`, …).
|
||||
- Final choice still depends on team skill and shipping constraints.
|
||||
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|
||||
+47
-45
@@ -1,6 +1,10 @@
|
||||
---
|
||||
name: web-games
|
||||
description: "Web browser game development principles. Framework selection, WebGPU, optimization, PWA."
|
||||
description: >-
|
||||
Web browser game development. Framework selection (Phaser, PixiJS, Kaplay,
|
||||
Canvas/WebGL, Three.js, Babylon.js), hybrid DOM+canvas, WebGPU, optimization,
|
||||
PWA, audio unlock. Use when building HTML5/WebGL/WebGPU games or choosing a
|
||||
browser runtime.
|
||||
risk: unknown
|
||||
source: community
|
||||
date_added: "2026-02-27"
|
||||
@@ -8,7 +12,7 @@ date_added: "2026-02-27"
|
||||
|
||||
# Web Browser Game Development
|
||||
|
||||
> Framework selection and browser-specific principles.
|
||||
> Framework selection and browser-specific principles. For stack choice details see `game-development/engine-selection`.
|
||||
|
||||
---
|
||||
|
||||
@@ -20,25 +24,43 @@ date_added: "2026-02-27"
|
||||
What type of game?
|
||||
│
|
||||
├── 2D Game
|
||||
│ ├── Full game engine features? → Phaser
|
||||
│ └── Raw rendering power? → PixiJS
|
||||
│ ├── Full game engine features? → Phaser 4
|
||||
│ ├── Fast prototype / jam? → Kaplay
|
||||
│ ├── Raw rendering power? → PixiJS 8
|
||||
│ └── Tiny / no dependency? → Raw Canvas / WebGL
|
||||
│
|
||||
├── 3D Game
|
||||
│ ├── Full engine (physics, XR)? → Babylon.js
|
||||
│ └── Rendering focused? → Three.js
|
||||
│ └── Rendering focused? → Three.js
|
||||
│
|
||||
└── Hybrid / Canvas
|
||||
└── Custom → Raw Canvas/WebGL
|
||||
├── Hybrid (DOM UI + canvas moments)
|
||||
│ └── Custom shell + guest viewport
|
||||
│ (Canvas/Kaplay/Phaser/Pixi inside a region/modal)
|
||||
│
|
||||
└── Narrative-first
|
||||
└── Ink (inkjs) or Twine export + DOM host
|
||||
```
|
||||
|
||||
### Comparison (2025)
|
||||
### Comparison
|
||||
|
||||
| Framework | Type | Best For |
|
||||
|-----------|------|----------|
|
||||
| **Phaser 4** | 2D | Full game features |
|
||||
| **PixiJS 8** | 2D | Rendering, UI |
|
||||
| **Three.js** | 3D | Visualizations, lightweight |
|
||||
| **Babylon.js 7** | 3D | Full engine, XR |
|
||||
| **Raw Canvas / WebGL** | 2D / low-level | Small scope, full control |
|
||||
| **Kaplay** | 2D toolkit | Rapid prototypes |
|
||||
| **Phaser 4** | 2D engine | Full game features |
|
||||
| **PixiJS 8** | 2D renderer | Rendering, custom systems |
|
||||
| **Three.js** | 3D renderer | Visualizations, lightweight 3D |
|
||||
| **Babylon.js** | 3D engine | Full engine, XR |
|
||||
|
||||
### Hybrid shell + guest
|
||||
|
||||
Use when chrome is HTML (menus, inventories, text, dashboards) but bursts of play need a canvas:
|
||||
|
||||
1. Mount guest in a container; pass context in.
|
||||
2. Run a **local** game loop in the guest.
|
||||
3. Return results (score, pass/fail); **destroy** guest (RAF, listeners, GL context as needed).
|
||||
|
||||
Do not let the guest own global app routing unless the product *is* a full-screen game.
|
||||
|
||||
---
|
||||
|
||||
@@ -56,8 +78,8 @@ What type of game?
|
||||
|
||||
### Decision
|
||||
|
||||
- **New projects**: Use WebGPU with WebGL fallback
|
||||
- **Legacy support**: Start with WebGL
|
||||
- **New GPU-heavy projects**: Use WebGPU with WebGL fallback
|
||||
- **Broad legacy / simple 2D**: Start with WebGL or Canvas 2D
|
||||
- **Feature detection**: Check `navigator.gpu`
|
||||
|
||||
---
|
||||
@@ -69,7 +91,7 @@ What type of game?
|
||||
| Constraint | Strategy |
|
||||
|------------|----------|
|
||||
| No local file access | Asset bundling, CDN |
|
||||
| Tab throttling | Pause when hidden |
|
||||
| Tab throttling | Pause when hidden (`visibilitychange`) |
|
||||
| Mobile data limits | Compress assets |
|
||||
| Audio autoplay | Require user interaction |
|
||||
|
||||
@@ -85,16 +107,12 @@ What type of game?
|
||||
|
||||
## 4. Asset Strategy
|
||||
|
||||
### Compression Formats
|
||||
|
||||
| Type | Format |
|
||||
|------|--------|
|
||||
| Textures | KTX2 + Basis Universal |
|
||||
| Textures | KTX2 + Basis Universal (or WebP/PNG for simple 2D) |
|
||||
| Audio | WebM/Opus (fallback: MP3) |
|
||||
| 3D Models | glTF + Draco/Meshopt |
|
||||
|
||||
### Loading Strategy
|
||||
|
||||
| Phase | Load |
|
||||
|-------|------|
|
||||
| Startup | Core assets, <2MB |
|
||||
@@ -105,35 +123,16 @@ What type of game?
|
||||
|
||||
## 5. PWA for Games
|
||||
|
||||
### Benefits
|
||||
|
||||
- Offline play
|
||||
- Install to home screen
|
||||
- Full screen mode
|
||||
- Push notifications
|
||||
|
||||
### Requirements
|
||||
|
||||
- Service worker for caching
|
||||
- Web app manifest
|
||||
- HTTPS
|
||||
**Benefits:** offline play, install, fullscreen, optional push.
|
||||
**Requirements:** service worker, web app manifest, HTTPS.
|
||||
|
||||
---
|
||||
|
||||
## 6. Audio Handling
|
||||
|
||||
### Browser Requirements
|
||||
|
||||
- Audio context requires user interaction
|
||||
- Create AudioContext on first click/tap
|
||||
- Resume context if suspended
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Use Web Audio API
|
||||
- Pool audio sources
|
||||
- Preload common sounds
|
||||
- Compress with WebM/Opus
|
||||
- Create/resume `AudioContext` on first click/tap
|
||||
- Prefer Web Audio API; pool sources; preload common SFX
|
||||
- Compress with WebM/Opus when possible
|
||||
|
||||
---
|
||||
|
||||
@@ -146,15 +145,18 @@ What type of game?
|
||||
| Block on audio load | Lazy load audio |
|
||||
| Skip compression | Compress everything |
|
||||
| Assume fast connection | Handle slow networks |
|
||||
| Leave canvas engines running off-screen | Tear down guests |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Browser is the most accessible platform. Respect its constraints.
|
||||
|
||||
## When to Use
|
||||
This skill is applicable to execute the workflow or actions described in the overview.
|
||||
|
||||
Use when building HTML5/WebGL/WebGPU games, choosing a browser runtime, or wiring hybrid DOM+canvas guests.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Use this skill only when the task clearly matches the scope described above.
|
||||
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
|
||||
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|
||||
|
||||
+1
-11
@@ -20,9 +20,8 @@ Master advanced Git techniques to maintain clean history, collaborate effectivel
|
||||
- Clarify goals, constraints, and required inputs.
|
||||
- Apply relevant best practices and validate outcomes.
|
||||
- Provide actionable steps and verification.
|
||||
- If detailed examples are required, open `resources/implementation-playbook.md`.
|
||||
|
||||
## Use this skill when
|
||||
## When to Use
|
||||
|
||||
- Cleaning up commit history before merging
|
||||
- Applying specific commits across branches
|
||||
@@ -405,15 +404,6 @@ git reflog
|
||||
git branch recovered-branch abc123
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- **references/git-rebase-guide.md**: Deep dive into interactive rebase
|
||||
- **references/git-conflict-resolution.md**: Advanced conflict resolution strategies
|
||||
- **references/git-history-rewriting.md**: Safely rewriting Git history
|
||||
- **assets/git-workflow-checklist.md**: Pre-PR cleanup checklist
|
||||
- **assets/git-aliases.md**: Useful Git aliases for advanced workflows
|
||||
- **scripts/git-clean-branches.sh**: Clean up merged and stale branches
|
||||
|
||||
## Limitations
|
||||
- Use this skill only when the task clearly matches the scope described above.
|
||||
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
|
||||
|
||||
+4
-4
@@ -32,22 +32,22 @@ Do not use this skill for a maintainer merge batch, canonical synchronization, v
|
||||
|
||||
## Workflow
|
||||
|
||||
Use the helper only after the safety gates pass. With no paths it stages all current changes, so use that form only when every dirty file belongs to the requested commit:
|
||||
Use the helper only after the safety gates pass. Resolve the installed directory that contains this `SKILL.md` and substitute its absolute path for `<skill-directory>` below; do not assume the current working directory is the catalog repository. With no paths the helper stages all current changes, so use that form only when every dirty file belongs to the requested commit:
|
||||
|
||||
```bash
|
||||
bash skills/git-pushing/scripts/smart_commit.sh
|
||||
bash "<skill-directory>/scripts/smart_commit.sh"
|
||||
```
|
||||
|
||||
With custom message:
|
||||
|
||||
```bash
|
||||
bash skills/git-pushing/scripts/smart_commit.sh "feat: add feature"
|
||||
bash "<skill-directory>/scripts/smart_commit.sh" "feat: add feature"
|
||||
```
|
||||
|
||||
To stage only named files, pass them after `--`:
|
||||
|
||||
```bash
|
||||
bash skills/git-pushing/scripts/smart_commit.sh "fix: scope change" -- path/to/file
|
||||
bash "<skill-directory>/scripts/smart_commit.sh" "fix: scope change" -- path/to/file
|
||||
```
|
||||
|
||||
The helper handles isolated staging, commit creation, and push; it does not replace validation, release tooling, or a rebase required by an advanced upstream branch.
|
||||
|
||||
+187
@@ -0,0 +1,187 @@
|
||||
---
|
||||
name: markstream-install
|
||||
description: "Install and configure Markstream streaming Markdown renderers for Vue, React, Svelte, Angular, Nuxt, Next.js, and Vue 2 applications."
|
||||
category: frontend
|
||||
risk: safe
|
||||
source: https://github.com/Simon-He95/markstream-vue/tree/main/.agents/skills/markstream-install
|
||||
source_repo: Simon-He95/markstream-vue
|
||||
source_type: official
|
||||
date_added: "2026-07-19"
|
||||
author: Simon-He95
|
||||
tags: [markdown, streaming, vue, react, svelte, angular, ai-chat]
|
||||
tools: [claude, cursor, gemini, codex]
|
||||
license: MIT
|
||||
license_source: https://github.com/Simon-He95/markstream-vue/blob/main/license
|
||||
---
|
||||
|
||||
# Markstream Install
|
||||
|
||||
## Overview
|
||||
|
||||
Integrate the correct [Markstream](https://github.com/Simon-He95/markstream-vue) streaming Markdown renderer into an existing frontend application. This skill selects the framework package, installs only requested optional peers, preserves safe HTML and Mermaid defaults, and handles CSS, streaming state, and SSR boundaries.
|
||||
|
||||
Read [references/scenarios.md](references/scenarios.md) before selecting packages or optional peers.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when the user asks to:
|
||||
|
||||
- add streaming Markdown rendering to an AI chat or document interface;
|
||||
- install Markstream in Vue, Nuxt, React, Next.js, Svelte, Angular, or Vue 2;
|
||||
- repair missing Markstream styles, an incorrect framework package, or an SSR failure;
|
||||
- replace another Markdown renderer with Markstream;
|
||||
- choose between static content, built-in smooth streaming, or externally parsed AST input.
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Inspect the host application
|
||||
|
||||
Before changing dependencies, inspect:
|
||||
|
||||
- the framework and version in `package.json`;
|
||||
- the existing package-manager lockfile;
|
||||
- whether the application uses SSR;
|
||||
- reset, Tailwind, UnoCSS, or design-system styles;
|
||||
- required optional features such as highlighted code, Monaco, Mermaid, D2, or KaTeX.
|
||||
|
||||
Do not select `markstream-vue` merely because the source repository has Vue in its name. Choose the framework-specific package from the scenario table.
|
||||
|
||||
### 2. Install the smallest dependency set
|
||||
|
||||
Install exactly one framework package and preserve the repository's package manager. Add optional peers only when the requested UI uses their feature.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
npm install markstream-vue
|
||||
npm install markstream-react
|
||||
npm install markstream-svelte
|
||||
npm install markstream-angular
|
||||
npm install markstream-vue2
|
||||
```
|
||||
|
||||
For Vue 2.6, also install and register `@vue/composition-api`. Vue 2.7 has a built-in Composition API and must not install that plugin.
|
||||
|
||||
### 3. Wire styles in the correct order
|
||||
|
||||
Import application resets before Markstream styles. Import package CSS explicitly instead of relying on component imports to inject it.
|
||||
|
||||
For Tailwind or UnoCSS, put the matching package stylesheet in a component layer:
|
||||
|
||||
```css
|
||||
@import 'markstream-vue/index.css' layer(components);
|
||||
```
|
||||
|
||||
When math rendering is enabled, also import:
|
||||
|
||||
```css
|
||||
@import 'katex/dist/katex.min.css';
|
||||
```
|
||||
|
||||
Vue CLI 4 and other Webpack 4-based Vue 2 projects do not understand package export maps. Use the published file path in those projects:
|
||||
|
||||
```ts
|
||||
import 'markstream-vue2/dist/index.css'
|
||||
```
|
||||
|
||||
### 4. Add the smallest working renderer
|
||||
|
||||
Prefer `content` for static documents and most streaming chat interfaces. Markstream's built-in smooth streaming can pace irregular token delivery without requiring the host application to maintain an AST.
|
||||
|
||||
Use `nodes` plus `final` only when a worker, shared AST store, custom transform, or another application layer already owns parsing.
|
||||
|
||||
### 5. Handle framework boundaries
|
||||
|
||||
- In Nuxt, keep browser-only optional peers behind client boundaries.
|
||||
- In Next.js, use root `markstream-react` inside a `'use client'` component for live SSE or WebSocket streams.
|
||||
- Use `markstream-react/next` for SSR-first HTML with hydration and `markstream-react/server` for server-only rendering.
|
||||
- Use `markstream-svelte` only with Svelte 5.
|
||||
- Confirm the host meets the current `markstream-angular` version requirement.
|
||||
- In Vue 3, use `mode="chat"` for AI chat, `mode="docs"` for rich documents, and `mode="minimal"` for lightweight non-chat surfaces.
|
||||
|
||||
### 6. Preserve safe defaults
|
||||
|
||||
HTML policy defaults to `safe`, and Mermaid uses strict mode. Do not broaden either setting unless the user explicitly identifies a trusted legacy surface that requires it. Scope any exception to that surface.
|
||||
|
||||
### 7. Validate
|
||||
|
||||
Run the smallest relevant build, typecheck, or test command. Confirm:
|
||||
|
||||
1. the selected package matches the framework;
|
||||
2. only requested optional peers were added;
|
||||
3. styles load after resets;
|
||||
4. SSR pages do not evaluate browser-only peers on the server;
|
||||
5. static content and at least one incremental update render correctly.
|
||||
|
||||
Report the selected package, added peers, CSS location, streaming input choice, and validation command.
|
||||
|
||||
## Examples
|
||||
|
||||
### Vue 3 streaming chat
|
||||
|
||||
```vue
|
||||
<MarkdownRender
|
||||
mode="chat"
|
||||
:content="markdown"
|
||||
:final="false"
|
||||
smooth-streaming="auto"
|
||||
:fade="false"
|
||||
typewriter
|
||||
/>
|
||||
```
|
||||
|
||||
### Vue 3 completed chat history
|
||||
|
||||
```vue
|
||||
<MarkdownRender
|
||||
mode="chat"
|
||||
:content="markdown"
|
||||
:final="true"
|
||||
:smooth-streaming="false"
|
||||
:fade="true"
|
||||
:typewriter="false"
|
||||
/>
|
||||
```
|
||||
|
||||
Setting `final=true` tells the parser that the document is complete; disabling pacing alone does not finalize trailing constructs.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Install the minimal peer set instead of every optional integration.
|
||||
- Keep the renderer mode stable when a chat message transitions from streaming to history.
|
||||
- Let an existing outer message virtualizer own mounted rows; coordinate Markstream height metrics instead of adding a competing virtualizer.
|
||||
- Scope component overrides with `customId` or `custom-id` when multiple render surfaces coexist.
|
||||
- Test SSR and incremental client updates separately.
|
||||
|
||||
## Limitations
|
||||
|
||||
- This skill does not choose application-specific visual styling or chat architecture.
|
||||
- Optional browser-heavy peers can require framework-specific client boundaries and bundler configuration.
|
||||
- Vue 2.6 and legacy Webpack projects require the compatibility steps documented above.
|
||||
- Current package and framework requirements must be checked against the host lockfile and Markstream documentation before installation.
|
||||
|
||||
## Security & Safety Notes
|
||||
|
||||
- Package installation changes the dependency manifest and lockfile. Review the proposed package set before running the install command.
|
||||
- Do not enable trusted HTML or non-strict Mermaid rendering for untrusted model output.
|
||||
- Keep optional browser runtimes out of server-only execution paths.
|
||||
- Run installs only inside the intended project directory and use its existing package manager.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** Styles appear missing or are overwritten.
|
||||
**Solution:** Load resets first, then the matching Markstream stylesheet explicitly.
|
||||
- **Problem:** A completed response still looks incomplete.
|
||||
**Solution:** Set `final=true` when the stream finishes, not only `smoothStreaming=false`.
|
||||
- **Problem:** Next.js evaluates browser-only code on the server.
|
||||
**Solution:** Select the root, `/next`, or `/server` entry according to the render boundary.
|
||||
- **Problem:** Lightweight highlighting does not activate after installing `stream-markdown`.
|
||||
**Solution:** On Vue, Vue 2, or React, configure `MarkdownCodeBlockNode` as the `code_block` override.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Installation](https://markstream.simonhe.me/guide/installation)
|
||||
- [AI chat and streaming](https://markstream.simonhe.me/guide/ai-chat-streaming)
|
||||
- [Performance](https://markstream.simonhe.me/guide/performance)
|
||||
- [Troubleshooting](https://markstream.simonhe.me/guide/troubleshooting)
|
||||
- [Component overrides](https://markstream.simonhe.me/guide/component-overrides)
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
# Install Scenarios
|
||||
|
||||
## Package selection
|
||||
|
||||
| Host app | Package and setup |
|
||||
|----------|-------------------|
|
||||
| Vue 3 / Nuxt 3 or 4 | `markstream-vue` |
|
||||
| Vue 2.6 | `markstream-vue2` plus `@vue/composition-api`; register the plugin before mounting the app |
|
||||
| Vue 2.7 | `markstream-vue2`; use Vue's built-in Composition API and do not install `@vue/composition-api` |
|
||||
| React 18+ / Next.js | `markstream-react` |
|
||||
| Angular 20+ | `markstream-angular` |
|
||||
| Svelte 5 | `markstream-svelte` |
|
||||
|
||||
## Peer selection
|
||||
|
||||
| Feature | Peer | Supported packages | Activation |
|
||||
|---------|------|--------------------|------------|
|
||||
| Lightweight highlighted code blocks | `stream-markdown` | `markstream-vue`, `markstream-vue2`, `markstream-react` | Configure the package's `MarkdownCodeBlockNode` as the `code_block` override |
|
||||
| Monaco-powered code blocks | `stream-monaco` | All framework packages | Install only when Monaco interactions are required |
|
||||
| Mermaid diagrams | `mermaid` | All framework packages | Install when Mermaid fences are rendered |
|
||||
| D2 diagrams | `@terrastruct/d2` | All framework packages | Install when D2 fences are rendered |
|
||||
| KaTeX math | `katex` | All framework packages | Install and load KaTeX CSS when math is rendered |
|
||||
|
||||
## CSS checklist
|
||||
|
||||
- Load reset styles first.
|
||||
- Load the framework-specific Markstream CSS after the reset.
|
||||
- In Tailwind or UnoCSS projects, use `@import '...' layer(components)`.
|
||||
- Import KaTeX CSS when math is enabled.
|
||||
- When rendering standalone node components directly, wrap them with the relevant package root class such as `.markstream-vue`, `.markstream-react`, or `.markstream-svelte`.
|
||||
|
||||
## Input choice
|
||||
|
||||
- `content`: static documents, low-frequency updates, and most SSE or token-streaming chat surfaces.
|
||||
- `content` with built-in smooth streaming: irregular AI streams whose visible output should be paced independently from raw chunk cadence.
|
||||
- `smoothStreaming="auto"` or `smooth-streaming="auto"` is the default.
|
||||
- Auto pacing activates when `typewriter=true` or `maxLiveNodes <= 0` / `max-live-nodes <= 0`.
|
||||
- `typewriter` controls the cursor and defaults to `false`.
|
||||
- `fade` controls node-entry and streamed-text fade effects.
|
||||
- `nodes` plus `final`: worker-preparsed content, shared AST stores, custom AST transforms, or cases where another layer already owns parsing.
|
||||
|
||||
## Next.js entry selection
|
||||
|
||||
| Surface | Entry |
|
||||
|---------|-------|
|
||||
| Live SSE or WebSocket output in a Client Component | `markstream-react` |
|
||||
| SSR-first HTML with client hydration | `markstream-react/next` |
|
||||
| Server-only Markdown rendering | `markstream-react/server` |
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
name: modellix
|
||||
description: "Integrate Modellix unified API/CLI for async AI image and video generation (model run --wait, task download)."
|
||||
category: creative
|
||||
risk: critical
|
||||
source: community
|
||||
source_repo: Modellix/modellix-skill
|
||||
source_type: official
|
||||
date_added: "2026-07-16"
|
||||
author: Modellix
|
||||
tags: [image-generation, video-generation, modellix, cli, api]
|
||||
tools: [claude, cursor, gemini]
|
||||
license: "MIT"
|
||||
license_source: "https://github.com/Modellix/modellix-skill/blob/main/LICENSE"
|
||||
---
|
||||
|
||||
# Modellix
|
||||
|
||||
## Overview
|
||||
|
||||
Modellix is a Model-as-a-Service platform for AI image and video generation. This skill teaches agents to use the official `modellix-cli` workflow (doctor → model run --wait → task download).
|
||||
|
||||
Upstream package: https://github.com/Modellix/modellix-skill/tree/main/modellix-skill
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Generate images from text prompts
|
||||
- Generate or edit videos from text or images
|
||||
- Call Modellix models through a unified API/CLI
|
||||
- The user mentions Modellix, Seedream, Seedance, Nano Banana, or similar providers via Modellix
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Authenticate with `MODELLIX_API_KEY` or `modellix-cli auth login`
|
||||
2. Run `modellix-cli doctor --json`
|
||||
3. Use default models when unspecified (T2I: `google/nano-banana-2-lite`, T2V: `bytedance/seedance-2.0-mini-t2v`)
|
||||
4. Submit with `modellix-cli model run --wait --json`
|
||||
5. Persist outputs with `modellix-cli task download`
|
||||
|
||||
## Examples
|
||||
|
||||
### Text-to-image
|
||||
|
||||
```bash
|
||||
modellix-cli model run \
|
||||
--model-slug google/nano-banana-2-lite \
|
||||
--body '{"prompt":"A cinematic sunset over a futuristic city"}' \
|
||||
--wait --timeout 5m --json
|
||||
```
|
||||
|
||||
### Text-to-video
|
||||
|
||||
```bash
|
||||
modellix-cli model run \
|
||||
--model-slug bytedance/seedance-2.0-mini-t2v \
|
||||
--body '{"prompt":"Ocean waves under a cloudy sunset"}' \
|
||||
--wait --timeout 10m --json
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Prefer CLI `model run --wait` over hand-rolled polling
|
||||
- Before a paid submission, disclose the provider, model, prompt or source media that will leave the machine, expected cost, and output path; obtain explicit user approval
|
||||
- Prefer session-scoped API-key use; run `modellix-cli auth login` only when the user approves persistent local credential storage
|
||||
- Do not blindly retry paid submissions after unknown outcomes — check `task history`
|
||||
- Confirm the destination and overwrite policy before `task download`; never replace an existing file without explicit approval
|
||||
- Fetch request schemas from `model describe` `docs_url` or https://docs.modellix.ai/llms.txt
|
||||
|
||||
## Security & Safety Notes
|
||||
|
||||
- Requires a Modellix API key; never print secrets in logs
|
||||
- Prompts and uploaded source media leave the machine for `api.modellix.ai` and Modellix CDN processing
|
||||
- Paid generation consumes account balance and must not be submitted or retried without the approval described above
|
||||
|
||||
## Limitations
|
||||
|
||||
- Requires a Modellix account, network access, a valid API key, and sufficient account balance.
|
||||
- Model availability, request schemas, pricing, quotas, moderation, and generation time are controlled by Modellix and may change.
|
||||
- Generated outputs require human review for quality, rights, privacy, and policy compliance before publication.
|
||||
- This skill documents the CLI workflow only; it does not define a REST fallback or guarantee that a completed remote task downloads successfully.
|
||||
+15
-7
@@ -154,8 +154,10 @@ Own net-new PPTX creation in this workflow. When a PPTX file is required,
|
||||
create a small task-specific builder with the user's approved environment. Start
|
||||
slides from a blank layout and create native objects from the final bounding
|
||||
boxes. Enable word wrap, disable automatic text resizing, set text insets and
|
||||
alignment explicitly, and reject zero or negative bounding boxes before
|
||||
building.
|
||||
alignment explicitly, and reject zero or negative bounding boxes for non-line
|
||||
objects before building. Validate lines by requiring two distinct endpoints;
|
||||
horizontal and vertical lines may have a zero-height or zero-width bounding
|
||||
box.
|
||||
|
||||
Save the authored specification, PPTX, build manifest, audit records, and
|
||||
source manifest together. Do not add a large shared renderer or copy source
|
||||
@@ -181,7 +183,11 @@ with the slide ID, object ID, reason, owner, and review date.
|
||||
|
||||
The skill provides a read-only analysis contract, not packaged code. For a
|
||||
specific task, use `python-pptx` and the Office Open XML package to inspect a
|
||||
presentation. Produce only the context needed for the task:
|
||||
presentation. Use OOXML package inspection when `python-pptx` cannot expose
|
||||
theme, master, layout, relationship, notes, comments, animation, media, or
|
||||
non-modeled formatting evidence. Resolve the package relationship graph;
|
||||
never infer slide order from filenames or copy source package parts. Produce
|
||||
only the context needed for the task:
|
||||
|
||||
* Compact prompt context with slide count, styles, brands, template, and layout
|
||||
* Full extraction with `layout_tree`, summary metrics, and render-aware elements
|
||||
@@ -189,8 +195,10 @@ presentation. Produce only the context needed for the task:
|
||||
* Style-master analysis with colors, fonts, layout usage, and flow patterns
|
||||
|
||||
Use [reference-deck analysis recipes](references/reference-deck-analysis.md)
|
||||
and [Python guidance](references/python-snippets.md) as static implementation
|
||||
references. Keep all extraction read-only.
|
||||
and [reference-deck analysis patterns](references/reference-deck-analysis-patterns.md) as static implementation
|
||||
references. Use the bundled `references/ooxml-parsing.md` guidance for the
|
||||
package-part map, relationship resolution, namespace, and secure parsing
|
||||
requirements. Keep all extraction read-only.
|
||||
|
||||
## Visual Assets
|
||||
|
||||
@@ -208,8 +216,8 @@ objects.
|
||||
Before any external generation call, disclose the provider and model, what
|
||||
prompt or source material will leave the machine, the likely cost, and the
|
||||
output path. Obtain explicit confirmation unless the user already authorized
|
||||
that exact operation. Never overwrite an existing output without separate
|
||||
confirmation.
|
||||
that exact operation. Never overwrite an existing output or manifest without
|
||||
separate explicit confirmation.
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
+7
-3
@@ -20,16 +20,20 @@ A.y < B.y + B.h AND B.y < A.y + A.h
|
||||
For each text object estimate whether its text fits within its bbox.
|
||||
|
||||
Rough capacity (Latin):
|
||||
- Characters per line ≈ `(bbox.w × 72) / (font_size × 0.5)`, using `0.5 em` as an average Latin glyph-width factor
|
||||
- Characters per line ≈ `(bbox.w × 72) / (font_size × 0.5)`, using `0.5 em`
|
||||
as an average Latin glyph-width factor
|
||||
- Lines available ≈ `(bbox.h × 72) / (font_size × 1.2)`
|
||||
_(bbox in inches, font_size in pt)_
|
||||
|
||||
Adjustments:
|
||||
- **CJK / full-width text:** use a glyph-width factor near `1.0 em` instead of `0.5 em`. The extractor reports `non_ascii_text` — use it to flag CJK-heavy slides.
|
||||
- **CJK / full-width text:** halve the characters-per-line value (full-width glyphs ≈ 2× Latin advance). The extractor reports `non_ascii_text` — use it to flag CJK-heavy slides.
|
||||
- **Text on a shape/card:** subtract ≈0.1 in of inner padding from each side of the shape before computing capacity; the text occupies the inset inner area, not the full shape.
|
||||
|
||||
- **Pass:** estimated text volume ≤ available capacity.
|
||||
- **Warning:** likely overflow → inspect the generated PPTX or rendered preview, then shorten bullets, enlarge the bbox, or split the slide when clipping is confirmed. This estimate is a triage heuristic, not a deterministic failure by itself.
|
||||
- **Warning:** likely overflow → inspect the generated PPTX or rendered preview,
|
||||
then shorten bullets, enlarge the bbox, or split the slide when clipping is
|
||||
confirmed. This estimate is a triage heuristic, not a deterministic failure
|
||||
by itself.
|
||||
**Never set `font_size` below 9 pt for `classification: "content"` objects.**
|
||||
|
||||
## 3. Font Size Minimums
|
||||
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
# OOXML Parsing Reference
|
||||
|
||||
A `.pptx` is an Open Packaging Conventions ZIP archive. Inspect it read-only
|
||||
by resolving its relationship graph; do not assume sequential filenames or
|
||||
copy package parts into a generated deck.
|
||||
|
||||
## Package-Part Map
|
||||
|
||||
| Need | Parts |
|
||||
| --- | --- |
|
||||
| Slide order | `ppt/presentation.xml`, `ppt/_rels/presentation.xml.rels` |
|
||||
| Slide text and shapes | Slide parts resolved from presentation relationships (commonly `ppt/slides/slideN.xml`) |
|
||||
| Layout, notes, images, charts | The slide's relationship part (commonly `ppt/slides/_rels/slideN.xml.rels`) |
|
||||
| Template geometry | `ppt/slideLayouts/`, `ppt/slideMasters/` |
|
||||
| Colors and fonts | Theme parts resolved from presentation/master relationships (commonly under `ppt/theme/`) |
|
||||
| Notes and comments | `ppt/notesSlides/`, `ppt/comments/` |
|
||||
| Media and embeddings | `ppt/media/`, `ppt/embeddings/` |
|
||||
|
||||
## Relationship Resolution
|
||||
|
||||
1. Start with `ppt/presentation.xml`; use its slide ID list and
|
||||
`ppt/_rels/presentation.xml.rels` to resolve slides in presentation order.
|
||||
2. For every part that needs linked content, resolve targets from that part's
|
||||
`.rels` file relative to the owning part rather than from a hard-coded path.
|
||||
3. Retain the relationship ID, type, resolved target, and any unreadable or
|
||||
missing target in the analysis result.
|
||||
4. Treat raw element ordering as evidence for rendering, not as a reason to
|
||||
reproduce a source slide or its package XML.
|
||||
|
||||
## Namespaces
|
||||
|
||||
- PresentationML: `http://schemas.openxmlformats.org/presentationml/2006/main`
|
||||
- DrawingML: `http://schemas.openxmlformats.org/drawingml/2006/main`
|
||||
- Office relationships: `http://schemas.openxmlformats.org/officeDocument/2006/relationships`
|
||||
- Package relationships: `http://schemas.openxmlformats.org/package/2006/relationships`
|
||||
|
||||
## Analysis Output Guidance
|
||||
|
||||
For a read-only extraction, retain the slide number, resolved relationship
|
||||
target, concatenated text, shape counts, notes, relationship types, and
|
||||
OOXML-only markers such as animations, comments, transitions, unsupported
|
||||
shapes, and non-modeled formatting. For design context, retain theme
|
||||
color/font tokens without inventing an RGB value when a scheme or system color
|
||||
cannot be fully resolved.
|
||||
|
||||
Record the input deck path, inspected parts, relationship-resolution errors,
|
||||
and unreadable XML in the analysis manifest. Keep the result limited to the
|
||||
evidence needed for the requested analysis.
|
||||
|
||||
## Secure, Read-Only Handling
|
||||
|
||||
- Treat a source deck as untrusted input. Reject path traversal, symlinks,
|
||||
oversized members, and compressed archive bombs before reading ZIP members.
|
||||
- Parse XML with a secure parser. Disable DTD loading, entity expansion, and
|
||||
network access.
|
||||
- Preserve `xml:space="preserve"` semantics when collecting text.
|
||||
- Do not modify the source archive, overwrite it, or blindly copy XML, media,
|
||||
fonts, images, or embedded files into a new deck.
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# PPTX Python Snippets
|
||||
# Reference-Deck Analysis Patterns
|
||||
|
||||
It describes how to approach PPTX extraction and style analysis with `python-pptx`, using short illustrative
|
||||
snippets — not a packaged module to copy wholesale.
|
||||
+30
-8
@@ -6,8 +6,9 @@ This file is static guidance for inspecting existing `.pptx` files and defining
|
||||
|
||||
- Keep only static guidance for reference-deck prompt context, extraction, folder analysis, and style-master inspection.
|
||||
- Do not place runtime scripts, model assets, importable Python modules, or generated artifacts here.
|
||||
- This skill ships no importable code; implement the extraction/style-analysis contract on demand with `python-pptx`.
|
||||
- `python-snippets.md` holds documentation-only `python-pptx` guidance — approach notes plus short illustrative snippets. Do not import from it or recreate packaged `.py` resources from it.
|
||||
- This skill ships no importable code; implement the extraction/style-analysis and read-only OOXML inspection contracts on demand with `python-pptx`, `zipfile`, and a secure XML parser.
|
||||
- `reference-deck-analysis-patterns.md` holds documentation-only `python-pptx` guidance — approach notes plus short illustrative snippets. Do not import from it or recreate packaged `.py` resources from it.
|
||||
- `ooxml-parsing.md` holds documentation-only package-part, relationship, namespace, and security guidance. It is not a runtime dependency or script template.
|
||||
|
||||
## Analysis Recipes
|
||||
|
||||
@@ -28,15 +29,34 @@ Produce a full JSON extraction including:
|
||||
- `summary` complexity metrics
|
||||
- `slides[*].layout_tree` with groups/objects
|
||||
- `ooxml_elements` for render-aware inspection
|
||||
- resolved package relationships, OOXML-only markers, and parsing exceptions
|
||||
|
||||
### 3. Folder Batch Recipe
|
||||
### 3. OOXML Package Inspection Recipe
|
||||
|
||||
Use read-only package inspection when high-level APIs do not expose the needed
|
||||
evidence: slide order, theme tokens, masters/layouts, notes, comments,
|
||||
animations, media, charts, or non-modeled formatting.
|
||||
|
||||
- Resolve slide order from `ppt/presentation.xml` and its relationship part.
|
||||
Do not derive it from `slideN.xml` filenames.
|
||||
- Resolve every relationship target relative to its owning source part, not its
|
||||
`.rels` part. Retain the relationship type, target, and unreadable XML errors
|
||||
in the result.
|
||||
- Preserve theme colors and fonts as tokens when they cannot be reliably
|
||||
resolved to RGB values.
|
||||
- Parse untrusted XML with a secure parser; do not enable DTDs, entity
|
||||
expansion, or network access.
|
||||
- Keep the source package read-only and never copy its XML parts into a new
|
||||
deck.
|
||||
|
||||
### 4. Folder Batch Recipe
|
||||
|
||||
Process a folder of decks to produce:
|
||||
|
||||
- One `.pptx-spec.json` file per deck
|
||||
- A `manifest.json` to track outputs
|
||||
|
||||
### 4. Style Master Recipe
|
||||
### 5. Style Master Recipe
|
||||
|
||||
Run style-only analysis when you need design lock signals:
|
||||
|
||||
@@ -44,7 +64,7 @@ Run style-only analysis when you need design lock signals:
|
||||
- Typography and font-size distribution
|
||||
- Master/layout usage and flow patterns
|
||||
|
||||
### 5. Reference Template Catalog Recipe
|
||||
### 6. Reference Template Catalog Recipe
|
||||
|
||||
When a reference deck should inform a new deck's layout rhythm, produce a
|
||||
human-readable catalog from the existing prompt-context, extraction, and
|
||||
@@ -83,9 +103,11 @@ Suggested catalog shape:
|
||||
## Related Responsibilities
|
||||
|
||||
This reference covers PPTX prompt context, extraction, folder batch analysis,
|
||||
style-master inspection, and the derived reference-template catalog only.
|
||||
style-master inspection, read-only OOXML package inspection, and the derived
|
||||
reference-template catalog only. See [OOXML parsing guidance](ooxml-parsing.md)
|
||||
for the package-part map and parser safety rules.
|
||||
|
||||
- Use the parent `pptx-deck-creation` workflow for narrative/source preparation,
|
||||
together with [design profiles](design-profiles.md) for profile selection.
|
||||
together with [design profiles](design-profiles.md) for profile selection.
|
||||
- Use [visual asset guidelines](visual-asset-adapters.md) for acquiring and
|
||||
placing icons, images, SVGs, and infographics.
|
||||
placing icons, images, SVGs, and infographics.
|
||||
|
||||
+23
-13
@@ -19,9 +19,9 @@ Shared rules:
|
||||
- On failure, write a failure manifest; never substitute a placeholder and call it generated.
|
||||
- Never request secrets in chat or a prompt dialog. For cloud auth use `.env` or `az login`.
|
||||
- Before a billable generation call or any request that sends user-provided or
|
||||
source material to a third party, disclose the provider/model, the material
|
||||
that will leave the machine, likely cost, and output path. Obtain explicit
|
||||
confirmation unless the user already authorized that exact operation.
|
||||
source material to a third party, disclose the provider/model, the material
|
||||
that will leave the machine, likely cost, and output path. Obtain explicit
|
||||
confirmation unless the user already authorized that exact operation.
|
||||
|
||||
---
|
||||
|
||||
@@ -62,7 +62,7 @@ def icon_search(query, limit=8, prefix=None, color=None, out_dir="assets/icons")
|
||||
|
||||
## 2. Web Image Search
|
||||
|
||||
Prefer the browsing or image-search capability available in the current client.
|
||||
Prefer the VS Code fetch tools (`fetch_webpage`) or an MCP image-search tool you have available.
|
||||
When you already have a direct image URL (from search results or the user), download it locally:
|
||||
|
||||
```python
|
||||
@@ -102,8 +102,9 @@ Generate through a user-managed provider (OpenAI or Azure OpenAI). Read credenti
|
||||
never accept secrets via chat.
|
||||
|
||||
Before running the snippet, obtain the external-call confirmation described in
|
||||
the shared rules. If `output_path` already exists, choose a new path or obtain
|
||||
separate overwrite confirmation; do not silently replace it.
|
||||
the shared rules. If `output_path` or its manifest already exists, choose a new
|
||||
path or obtain separate explicit overwrite confirmation; do not silently
|
||||
replace either file.
|
||||
|
||||
```python
|
||||
import base64, json, os
|
||||
@@ -111,15 +112,20 @@ from pathlib import Path
|
||||
from openai import OpenAI, AzureOpenAI # provided by the user's environment
|
||||
|
||||
def text_to_infographic(prompt, output_path, provider="openai",
|
||||
model_or_deployment="gpt-image-1", size="1024x1024"):
|
||||
model_or_deployment="gpt-image-1", size="1024x1024",
|
||||
confirmed=False, allow_overwrite=False):
|
||||
output = Path(output_path)
|
||||
manifest_path = output.with_suffix(".manifest.json")
|
||||
existing = [path for path in (output, manifest_path) if path.exists()]
|
||||
if existing:
|
||||
if existing and not allow_overwrite:
|
||||
raise FileExistsError(f"Refusing to overwrite existing paths: {existing}")
|
||||
manifest_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
manifest = {"provider": provider, "model_or_deployment": model_or_deployment,
|
||||
"output_path": output_path}
|
||||
if not confirmed:
|
||||
manifest.update(status="cancelled", error="External generation was not confirmed")
|
||||
manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
|
||||
return manifest
|
||||
try:
|
||||
if provider == "azure-openai":
|
||||
client = AzureOpenAI(
|
||||
@@ -130,17 +136,20 @@ def text_to_infographic(prompt, output_path, provider="openai",
|
||||
else:
|
||||
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
|
||||
result = client.images.generate(model=model_or_deployment, prompt=prompt, size=size)
|
||||
output.parent.mkdir(parents=True, exist_ok=True)
|
||||
output.write_bytes(base64.b64decode(result.data[0].b64_json))
|
||||
manifest["status"] = "ok"
|
||||
except Exception as exc: # report, never fake-generate
|
||||
manifest.update(status="error", error=str(exc))
|
||||
manifest_path.write_text(json.dumps(manifest, indent=2))
|
||||
manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
|
||||
return manifest
|
||||
```
|
||||
|
||||
- Ask the user for any missing non-secret values: provider, prompt,
|
||||
model/deployment, size, and output path.
|
||||
- Collect missing values via `vscode_askQuestions`: provider, prompt, model/deployment, size, output path.
|
||||
- Before calling the function, disclose the provider/model, material leaving
|
||||
the machine, likely cost, and output path. Set `confirmed=True` only after
|
||||
the user explicitly authorizes that exact external request. Set
|
||||
`allow_overwrite=True` only after separate explicit approval to replace every
|
||||
existing output or manifest path.
|
||||
- Use `.env` or `az login` for auth; never ask for keys/tokens in chat or the dialog.
|
||||
- Use generated art as a supporting visual. Recreate essential text, labels,
|
||||
metrics, and steps with native PowerPoint objects. Add a vector asset only
|
||||
@@ -155,4 +164,5 @@ NotebookLM has no public generation API, so treat this as an optional, user-conf
|
||||
- If the user has a NotebookLM/MCP bridge tool configured, call it with `source_refs` + `prompt`,
|
||||
then save the returned image locally and record provenance.
|
||||
- If no bridge is configured, **fall back to Text → Infographic (section 4)** or omit the asset.
|
||||
- Apply the same provenance and failure-manifest rules as the other generation guidelines.
|
||||
- Apply the same confirmation, overwrite, provenance, and failure-manifest
|
||||
rules as the other generation guidelines.
|
||||
|
||||
@@ -18,14 +18,14 @@ Create pull requests following Sentry's engineering practices.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before creating a PR, ensure all changes are committed. If there are uncommitted changes, run the `sentry-skills:commit` skill first to commit them properly.
|
||||
Before creating a PR, ensure all changes are committed. If there are uncommitted changes, run the available `commit` skill first to commit them properly.
|
||||
|
||||
```bash
|
||||
# Check for uncommitted changes
|
||||
git status --porcelain
|
||||
```
|
||||
|
||||
If the output shows any uncommitted changes (modified, added, or untracked files that should be included), invoke the `sentry-skills:commit` skill before proceeding.
|
||||
If the output shows any uncommitted changes (modified, added, or untracked files that should be included), invoke the available `commit` skill before proceeding. If the client requires qualified skill names, use the qualifier for the plugin that supplied this skill.
|
||||
|
||||
## Process
|
||||
|
||||
|
||||
+3
-9
@@ -31,13 +31,7 @@ Before mutation:
|
||||
|
||||
If the repository names a mandatory maintainer skill or guarded command, delegate to it instead of inventing a parallel branch, merge, sync, or release path. In `agentic-awesome-skills`, use `antigravity-maintainer-batch-release` and `npm run merge:batch`; `main` is pull-request-only.
|
||||
|
||||
For the AAS agent-first control plane, also preserve the independent acceptance boundary:
|
||||
|
||||
- keep product, verifier, and benchmark-gold changes in separate protected pull requests;
|
||||
- never expose held-out or abstention labels to product code, tuning, or manual diagnosis;
|
||||
- run acceptance against the packed CLI/MCP artifact as a black box on every frozen operating-system and runtime leg;
|
||||
- re-freeze the verifier baseline after an independently reviewed verifier or tuning-gold correction, then rebase and retest the product;
|
||||
- treat any hard-policy violation, write/network attempt from MCP, nondeterministic canonical payload, or partial transactional state as a release blocker.
|
||||
The routine protected checks for `agentic-awesome-skills` are `pr-policy`, `pr-evidence`, `source-validation`, and `artifact-preview`. The supported AAS Core preview uses targeted unit tests plus one packed Linux/Node LTS smoke path and Workbench review. Do not resurrect the retired certified-v1 baseline, benchmark, tuning-gold, transaction-fault, race, or frozen OS/runtime matrix as routine merge gates.
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -78,7 +72,7 @@ Treat audit-tool output as evidence to verify, not automatic permission to upgra
|
||||
#### CI and release health
|
||||
|
||||
- failing, cancelled, skipped, or stale workflow runs;
|
||||
- inconsistent runtime matrices and unpinned or obsolete actions;
|
||||
- stale, redundant, or unjustifiably broad runtime matrices and unpinned or obsolete actions;
|
||||
- required checks, branch protection, release permissions, and secret boundaries;
|
||||
- mismatch between documented and implemented release commands.
|
||||
|
||||
@@ -90,7 +84,7 @@ Treat audit-tool output as evidence to verify, not automatic permission to upgra
|
||||
|
||||
#### Code-quality signals
|
||||
|
||||
- dead code, stale TODO/FIXME items, debug logging, commented-out code, and missing tests;
|
||||
- dead code, stale implementation markers, debug logging, commented-out code, and missing tests;
|
||||
- unsafe defaults, suppressed errors, credential exposure, and environment-specific paths.
|
||||
|
||||
For FAF projects only, also inspect declared `.faf`, `.faf-dna`, sync, score, and MCP contracts with the project's installed FAF commands.
|
||||
|
||||
-616
@@ -1,616 +0,0 @@
|
||||
---
|
||||
name: tools-page-seo-optimizer
|
||||
description: "Framework-agnostic SEO workflow for any site with multiple tool, product, or feature pages. Covers duplicate content, unique meta tags, heading hierarchy, internal linking, URL slugs, E-E-A-T, content registry pattern for scaling 50–500 pages, and blog content strategy for position 50–68 keywords."
|
||||
category: seo
|
||||
risk: safe
|
||||
source: community
|
||||
source_type: community
|
||||
author: whoisabhishekadhikari
|
||||
date_added: "2026-06-19"
|
||||
tags: [seo, tools-pages, product-pages, duplicate-content, content-registry, meta-tags, internal-linking, url-slugs, e-e-a-t, framework-agnostic]
|
||||
tools: [claude-code, cursor, codex-cli, gemini-cli, opencode]
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Tools Page SEO Optimizer
|
||||
|
||||
You are an expert in technical SEO and content strategy for sites with large collections of tool, product, or feature pages. Your workflow is framework-agnostic — applies to Django, Rails, Laravel, Express, Next.js, Nuxt, Astro, WordPress, and static HTML.
|
||||
|
||||
Derived from a real audit that found 93 of 105 tool pages sharing identical template prose and ranking at average position 68. This skill is the playbook that fixes it.
|
||||
|
||||
---
|
||||
|
||||
## Quick-Start Decision Tree
|
||||
|
||||
```
|
||||
Full audit from scratch? → Run all phases in order
|
||||
All tool pages rank the same? → Phase 2 (Content Registry) first
|
||||
Meta titles/descriptions all generic? → Phase 1 (Meta Tags)
|
||||
Tool pages buried / hard to navigate? → Phase 5 (Internal Linking)
|
||||
Bad URL slugs? → Phase 6 (URL Slug Hygiene)
|
||||
Site looks authorless to Google? → Phase 7 (E-E-A-T)
|
||||
Stuck at position 50–68 on keywords? → Phase 9 (Blog Content Strategy)
|
||||
Fixes deployed but unsure they're live? → Phase 10 (Live Verification)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Codebase Reconnaissance
|
||||
|
||||
**Before writing any code**, locate these in the codebase. Names vary by framework — adapt.
|
||||
|
||||
| What to find | Common locations |
|
||||
|---|---|
|
||||
| URL routing | `routes.rb`, `urls.py`, `routes/`, `pages/`, `app/` |
|
||||
| Head / meta template | `_head.html`, `layout.js`, `base.html`, `app.blade.php` |
|
||||
| Tool/page registry | config file, database seed, JSON, `lib/guides.js`, `data/tools.js` |
|
||||
|
||||
**Answer these before writing a single line:**
|
||||
|
||||
1. How are tool pages generated — static files, database loop, config registry, CMS?
|
||||
2. Where is the shared template that renders `<title>`, `<meta name="description">`, `<h1>`?
|
||||
3. Does each tool have its own content fields, or does every tool fall back to the same template prose?
|
||||
4. Is there a central list of all tool slugs you can iterate over programmatically?
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Meta Titles & Descriptions
|
||||
|
||||
### The core problem
|
||||
|
||||
Every tool page sharing the same `<title>` template with only the tool name swapped in
|
||||
is the single most common reason tool sites rank poorly. Google treats near-identical titles
|
||||
as duplicate pages and demotes all of them.
|
||||
|
||||
### Title tag formula
|
||||
|
||||
```
|
||||
{Tool Name} | {Specific Outcome} — {Brand}
|
||||
```
|
||||
|
||||
| ✅ Good | ❌ Bad |
|
||||
|---|---|
|
||||
| `Meta Tag Generator \| Create Perfect SEO Titles Free — MySite` | `Meta Tag Generator - MySite Tools` |
|
||||
| `Broken Link Finder \| Scan Any Page for Dead URLs — MySite` | `Broken Link Finder - Free Online Tool \| MySite` |
|
||||
|
||||
**Rules:**
|
||||
- ≤ 60 characters total
|
||||
- Primary keyword in the first 40 characters
|
||||
- Every tool has a **unique** title — no two tools share the same one
|
||||
- Include "Free" where accurate — measurably improves CTR
|
||||
|
||||
### Meta description formula
|
||||
|
||||
```
|
||||
{What it does — one action sentence}. {Key differentiator}. {CTA}.
|
||||
```
|
||||
|
||||
Example: `Scan any webpage for broken links in seconds. Checks internal and external URLs,
|
||||
exports results as CSV. Free, no account needed.`
|
||||
|
||||
**Rules:**
|
||||
- 120–160 characters
|
||||
- Action verbs: Generate, Scan, Check, Analyze, Convert, Build, Find
|
||||
- Every tool gets a **custom** description — zero template filler
|
||||
|
||||
### Implementation (any framework)
|
||||
|
||||
```html
|
||||
<!-- Generic template pattern -->
|
||||
<title>{{ tool.meta_title | default(tool.name + " | " + site_name) }}</title>
|
||||
<meta name="description" content="{{ tool.meta_description | default(tool.tagline) }}">
|
||||
```
|
||||
|
||||
### Validation script — run before every deploy
|
||||
|
||||
```python
|
||||
# validate_meta.py
|
||||
import json, sys
|
||||
|
||||
tools = json.load(open('data/tools.json'))
|
||||
errors = []
|
||||
|
||||
for t in tools:
|
||||
slug = t.get('slug', '?')
|
||||
title = t.get('meta_title', '')
|
||||
desc = t.get('meta_description', '')
|
||||
if not title: errors.append(f"MISSING TITLE: {slug}")
|
||||
elif len(title) > 60: errors.append(f"TITLE TOO LONG ({len(title)}): {slug}")
|
||||
if not desc: errors.append(f"MISSING DESC: {slug}")
|
||||
elif len(desc) < 120: errors.append(f"DESC TOO SHORT ({len(desc)}): {slug}")
|
||||
elif len(desc) > 160: errors.append(f"DESC TOO LONG ({len(desc)}): {slug}")
|
||||
|
||||
if errors:
|
||||
print('\n'.join(errors)); sys.exit(1)
|
||||
print(f"✅ All {len(tools)} tools passed meta validation")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Content Registry (The Highest-Leverage Fix)
|
||||
|
||||
**Root cause of poor rankings on tool sites:** 80–95% of tool pages share identical
|
||||
template prose. Google sees them as thin, near-duplicate pages and ranks none well.
|
||||
Fix this before anything else.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
```bash
|
||||
# Find shared prose in your templates — if these strings appear in a shared template
|
||||
# file, you have the problem
|
||||
D1=$(grep -rn "powerful tool that helps" templates/ src/ 2>/dev/null | head -5)
|
||||
[ -n "$D1" ] && echo " ✗ Shared template prose found" || echo " ✓ No shared prose"
|
||||
D2=$(grep -rn "easy to use" templates/ src/ 2>/dev/null | head -5)
|
||||
[ -n "$D2" ] && echo " ✗ Template filler found"
|
||||
```
|
||||
|
||||
### Registry entry structure (framework-agnostic)
|
||||
|
||||
```yaml
|
||||
# data/tools/meta-tag-generator.yaml (or JSON, DB columns, JS object — adapt to your stack)
|
||||
slug: meta-tag-generator
|
||||
name: Meta Tag Generator
|
||||
meta_title: "Meta Tag Generator | Create Perfect SEO Titles & Descriptions Free"
|
||||
meta_description: "Generate optimized title tags and meta descriptions with live character
|
||||
counters. Enforces Google's 60/160 char limits. Instant, free, no account needed."
|
||||
|
||||
introduction: >
|
||||
The meta tag generator creates the two most critical on-page SEO elements —
|
||||
your title tag and meta description — with live character counters that enforce
|
||||
Google's recommended limits before you publish. [80+ unique words minimum]
|
||||
|
||||
best_practices:
|
||||
- "Include your primary keyword within the first 40 characters of the title"
|
||||
- "Write a unique description per page — duplicate descriptions waste crawl budget"
|
||||
- "Use action verbs in descriptions: Generate, Find, Check, Analyze"
|
||||
|
||||
how_to_steps:
|
||||
- name: "Enter your page details"
|
||||
text: "Type your target keyword, page topic, and a brief summary of the content"
|
||||
- name: "Check the live character counters"
|
||||
text: "Keep title ≤60 chars and description ≤160 chars"
|
||||
- name: "Copy and paste the output"
|
||||
text: "Paste the generated tags into your HTML <head> section"
|
||||
|
||||
faqs:
|
||||
- q: "Does Google always use my meta description?"
|
||||
a: "No — Google rewrites descriptions ~63% of the time. Write them anyway for
|
||||
social shares and some SERPs."
|
||||
- q: "What happens if my title is over 60 characters?"
|
||||
a: "Google truncates it with an ellipsis, cutting off your message mid-sentence."
|
||||
|
||||
related_tools:
|
||||
- og-tag-generator
|
||||
- schema-markup-generator
|
||||
- heading-analyzer
|
||||
```
|
||||
|
||||
### Minimum viable unique content per tool
|
||||
|
||||
| Field | Minimum | Priority |
|
||||
|---|---|---|
|
||||
| `meta_title` | Unique, ≤60 chars | 🔴 Critical |
|
||||
| `meta_description` | Unique, 120–160 chars | 🔴 Critical |
|
||||
| `introduction` | 80+ unique words | 🔴 Critical |
|
||||
| `best_practices` | 3–5 tool-specific items | 🟡 High |
|
||||
| `how_to_steps` | 3 real steps for THIS tool | 🟡 High |
|
||||
| `faqs` | 2 tool-specific Q&As | 🟡 High |
|
||||
| `related_tools` | 2–4 slug references | 🟢 Medium |
|
||||
|
||||
**Rule: complete one tool fully before starting the next.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — H1 and Heading Hierarchy
|
||||
|
||||
### H1 formula
|
||||
|
||||
```
|
||||
{Tool Name} | {Outcome Phrase}
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- One `<h1>` per page — only the tool name/title
|
||||
- Must be unique per page
|
||||
|
||||
### Heading hierarchy
|
||||
|
||||
```
|
||||
h1 — Tool name (one per page)
|
||||
h2 — Major sections: "How It Works", "Best Practices", "FAQs", "Related Tools"
|
||||
h3 — Subsections: individual FAQ items, feature callouts, step headers
|
||||
```
|
||||
|
||||
Never skip levels. No h1 → h3 without an h2.
|
||||
|
||||
```bash
|
||||
# Audit heading hierarchy on a live page
|
||||
curl -s "https://yourdomain.com/tools/meta-tag-generator" \
|
||||
| grep -oE '<h[1-6][^>]*>.*?</h[1-6]>'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Accessibility
|
||||
|
||||
Accessibility failures lower Core Web Vitals scores — a direct ranking signal.
|
||||
|
||||
Every icon-only interactive element needs `aria-label`:
|
||||
|
||||
```html
|
||||
<button aria-label="Copy to clipboard"><svg>...</svg></button>
|
||||
<button aria-label="Go to next page">›</button>
|
||||
<input type="search" aria-label="Search tools" placeholder="Search...">
|
||||
```
|
||||
|
||||
```bash
|
||||
# Find icon-only buttons missing aria-label
|
||||
B=$(grep -rn "<button" templates/ 2>/dev/null | grep -v "aria-label" | grep -v ">[A-Za-z]" | head -5)
|
||||
[ -n "$B" ] && echo " ⚠ Icon buttons missing aria-label:" && echo "$B" || echo " ✓ Buttons have aria-labels"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Internal Linking
|
||||
|
||||
Internal links between tools are how PageRank flows through your site. A tool with no
|
||||
inbound internal links is effectively invisible to Google even with great content.
|
||||
|
||||
### Hub-and-Spoke model
|
||||
|
||||
```
|
||||
Homepage
|
||||
└── Category: Keyword Tools
|
||||
├── Keyword Density Checker ←→ Keyword Suggestion Tool
|
||||
└── SERP Preview Tool ←→ Meta Tag Generator
|
||||
└── Category: Technical SEO
|
||||
├── XML Sitemap Visualizer ←→ Robots.txt Creator
|
||||
└── Robots.txt Creator ←→ Redirect Generator
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
- Every tool links **to** at least 2 related tools (use `related_tools` from registry)
|
||||
- Every tool is linked **from** at least 2 other tools or category pages
|
||||
- No orphan tools — every tool reachable within 3 clicks from homepage
|
||||
|
||||
```bash
|
||||
# Orphan detection — tools with too few inbound references
|
||||
for slug in $(cat data/slugs.txt 2>/dev/null); do
|
||||
C=$(grep -rl "$slug" templates/ 2>/dev/null | wc -l | tr -d ' ')
|
||||
[ "$C" -lt 2 ] && echo " ORPHAN RISK: $slug ($C refs)"
|
||||
done
|
||||
```
|
||||
|
||||
### Template implementation
|
||||
|
||||
```html
|
||||
{% if tool.related_tools %}
|
||||
<section>
|
||||
<h2>Related Tools</h2>
|
||||
{% for slug in tool.related_tools %}
|
||||
{% set rel = get_tool(slug) %}
|
||||
<a href="/tools/{{ slug }}">{{ rel.name }} — {{ rel.tagline }}</a>
|
||||
{% endfor %}
|
||||
</section>
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — URL Slug Hygiene
|
||||
|
||||
| ✅ Good | ❌ Bad | Problem |
|
||||
|---|---|---|
|
||||
| `/tools/meta-tag-generator` | `/tools/tool-1` | No keywords |
|
||||
| `/tools/keyword-density-checker` | `/tools/free-online-keyword-density-checker-tool-free` | Keyword stuffed |
|
||||
| `/tools/broken-link-finder` | `/tools/brokenLinkFinder` | camelCase |
|
||||
|
||||
**Formula:** `{primary-keyword-phrase}` — lowercase, hyphens, no stop words, no "free" / "online" / "tool" padding.
|
||||
|
||||
```bash
|
||||
# Audit — list longest slugs (likely stuffed)
|
||||
curl -s "https://yourdomain.com/sitemap.xml" \
|
||||
| grep -oE '<loc>[^<]+' | sed 's/<loc>//' \
|
||||
| grep "/tools/" \
|
||||
| awk -F'/tools/' '{print length($2), $2}' | sort -n | tail -20
|
||||
```
|
||||
|
||||
If renaming a slug, always 301 redirect old → new and update all internal links.
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — E-E-A-T Signals
|
||||
|
||||
Tool sites rank poorly when they look authorless and dateless.
|
||||
|
||||
### Author byline + date (every tool page)
|
||||
|
||||
```html
|
||||
<p class="tool-byline">
|
||||
Built by <a href="/about">Your Name</a>
|
||||
<time datetime="{{ tool.updated_at }}"> · Updated {{ tool.updated_at | date }}</time>
|
||||
</p>
|
||||
```
|
||||
|
||||
### Trust pillars section
|
||||
|
||||
```html
|
||||
<section class="trust-pillars">
|
||||
<div>✅ <strong>100% Free</strong> — no account, no credit card</div>
|
||||
<div>🔒 <strong>Privacy First</strong> — your data never leaves your browser</div>
|
||||
<div>⚡ <strong>Instant Results</strong> — processed in under 1 second</div>
|
||||
</section>
|
||||
```
|
||||
|
||||
### About / author page
|
||||
|
||||
Create `/about` with: real name, credentials, why you built the tools, contact info.
|
||||
Link to it from every tool page byline. This is the single highest-impact E-E-A-T fix
|
||||
for solo-built tool sites.
|
||||
|
||||
---
|
||||
|
||||
## Phase 8 — Scaling to 100+ Tools
|
||||
|
||||
When the content registry pattern is working for 10–20 tools, the next challenge is
|
||||
scaling it to 100+ without losing quality or introducing duplicates.
|
||||
|
||||
### Batch completion gate
|
||||
|
||||
Never commit a partial batch. Before every commit touching tool content:
|
||||
|
||||
```bash
|
||||
# Count tools with introduction content vs total tools
|
||||
python3 -c "
|
||||
import json
|
||||
tools = json.load(open('data/tools.json'))
|
||||
total = len(tools)
|
||||
done = sum(1 for t in tools if t.get('introduction','').strip())
|
||||
print(f'{done}/{total} tools have introduction content')
|
||||
if done < total:
|
||||
missing = [t['slug'] for t in tools if not t.get('introduction','').strip()]
|
||||
print('Missing:', missing)
|
||||
"
|
||||
```
|
||||
|
||||
Only commit when the count is **100% complete**. A partial batch (e.g. 93/105) means
|
||||
12 tools still have thin template prose — enough for Google to flag the site as inconsistent.
|
||||
|
||||
### Batch writing order
|
||||
|
||||
Prioritise tools in this order:
|
||||
1. Tools already receiving impressions in Google Search Console (low-hanging fruit)
|
||||
2. Tools in your most-linked categories (PageRank concentration)
|
||||
3. Remaining tools alphabetically
|
||||
|
||||
### Build verification before commit
|
||||
|
||||
```bash
|
||||
# Confirm build compiles cleanly after batch content additions
|
||||
npm run build # Next.js / Nuxt
|
||||
python manage.py check # Django
|
||||
rails assets:precompile # Rails
|
||||
# Zero errors = safe to commit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 9 — Blog Content Strategy (Position 50–68 Keywords)
|
||||
|
||||
Tool pages rank well for transactional keywords ("meta tag generator", "check broken links").
|
||||
But informational keywords ("how to write meta descriptions", "what is keyword density") sit
|
||||
at position 50–68 — too deep to get clicks — because tool pages aren't the right content
|
||||
format for them. Blog posts are.
|
||||
|
||||
### Diagnosis: find your 50–68 keywords
|
||||
|
||||
In Google Search Console → Search Results → filter by Position > 49 AND Position < 69.
|
||||
These are queries where you have enough authority to rank but the wrong page type is ranking.
|
||||
|
||||
### Blog post targeting formula
|
||||
|
||||
```
|
||||
Post title: {Informational keyword} — {Year} Guide
|
||||
Target keyword: the exact query from GSC
|
||||
Content length: 1,000–1,500 words
|
||||
Internal links: link to 2–3 relevant tools from within the post body
|
||||
```
|
||||
|
||||
Example mapping:
|
||||
|
||||
| GSC keyword (pos 50–68) | Blog post title | Tool to link |
|
||||
|---|---|---|
|
||||
| "how to write meta descriptions" | "How to Write Meta Descriptions That Get Clicks (2025)" | meta-tag-generator |
|
||||
| "what is keyword density" | "Keyword Density: What It Is and How to Check It" | keyword-density-checker |
|
||||
| "how to find broken links" | "How to Find and Fix Broken Links on Any Website" | broken-link-finder |
|
||||
| "xml sitemap best practices" | "XML Sitemap Best Practices for 2025" | xml-sitemap-visualizer |
|
||||
|
||||
### Blog post structure (SEO-optimised)
|
||||
|
||||
```
|
||||
H1: {Target keyword} — the exact GSC query, naturally phrased
|
||||
Intro (100 words): answer the question directly in the first paragraph
|
||||
H2: What is {topic}?
|
||||
H2: Why it matters for SEO
|
||||
H2: How to {action} — step by step
|
||||
H3: Step 1
|
||||
H3: Step 2
|
||||
H3: Step 3
|
||||
H2: Common mistakes
|
||||
H2: {Tool name} — try it free ← internal link to your tool
|
||||
Conclusion: summarise + CTA to the tool
|
||||
```
|
||||
|
||||
### Blog post meta requirements
|
||||
|
||||
- `meta_title`: include year where relevant ("2025") — improves CTR on informational queries
|
||||
- `meta_description`: answer the question in one sentence + "Free tool included"
|
||||
- `canonical`: must point to the exact blog URL
|
||||
- `datePublished` + `dateModified` in schema — critical for freshness signals
|
||||
|
||||
### Internal link rule for blog posts
|
||||
|
||||
Every blog post must contain at least **2 contextual inline links** to relevant tools,
|
||||
not just a "Related Tools" sidebar. Inline links within body copy pass significantly
|
||||
more PageRank than sidebar links.
|
||||
|
||||
```html
|
||||
<!-- Good — inline contextual link -->
|
||||
<p>Use our <a href="/tools/meta-tag-generator">meta tag generator</a> to preview
|
||||
how your title and description appear in Google results before publishing.</p>
|
||||
|
||||
<!-- Weak — sidebar only, no body link -->
|
||||
<aside>Related: Meta Tag Generator</aside>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 10 — Live Deployment Verification
|
||||
|
||||
A fix that compiles cleanly can still fail in production. After every push, verify
|
||||
the live site — not just the build.
|
||||
|
||||
```bash
|
||||
seo:verify() {
|
||||
local D="$1"; local F=0
|
||||
for p in "/" "/tools/meta-tag-generator" "/blog" "/category" "/privacy" "/terms"; do
|
||||
local C=$(curl -so /dev/null -w "%{http_code}" "$D$p")
|
||||
echo "$C $p"; [ "$C" = "200" ] || ((F++))
|
||||
done
|
||||
local C=$(curl -so /dev/null -w "%{http_code}" "$D/tools/this-slug-does-not-exist-xyz")
|
||||
echo "Soft 404 check: $C (expect 404)"; [ "$C" = "404" ] || { echo " ✗ Soft 404"; ((F++)); }
|
||||
curl -s "$D/tools/meta-tag-generator" | grep -qi "canonical" && echo " ✓ Canonical present" || { echo " ✗ Canonical missing"; ((F++)); }
|
||||
local C2=$(curl -so /dev/null -w "%{http_code}" "$D/favicon.ico")
|
||||
echo "Favicon: $C2 (expect 200)"; [ "$C2" = "200" ] || { echo " ✗ Favicon missing"; ((F++)); }
|
||||
local J=$(curl -s "$D/tools/meta-tag-generator" | grep -c "application/ld+json" || true)
|
||||
[ "$J" -ge 1 ] && echo " ✓ Schema: $J blocks" || { echo " ✗ No schema found"; ((F++)); }
|
||||
return $F
|
||||
}
|
||||
```
|
||||
|
||||
### Expected results
|
||||
|
||||
| Check | Expected |
|
||||
|---|---|
|
||||
| All key pages | 200 |
|
||||
| Invalid tool slug | 404 |
|
||||
| `<link rel="canonical">` present | Yes |
|
||||
| `/favicon.ico` | 200 |
|
||||
| `application/ld+json` blocks | ≥ 1 per tool page |
|
||||
|
||||
If any check fails — **do not move on**. Diagnose and fix before the next phase.
|
||||
|
||||
---
|
||||
|
||||
## Phase 11 — Pre-Commit Validation
|
||||
|
||||
```bash
|
||||
seo:validate() {
|
||||
python3 validate_meta.py || return 1
|
||||
python3 -c "
|
||||
import json
|
||||
from collections import Counter
|
||||
tools = json.load(open('data/tools.json', 'r'))
|
||||
titles = [t.get('meta_title', '') for t in tools]
|
||||
dups = [t for t, c in Counter(titles).items() if c > 1 and t]
|
||||
print(dups) if dups else print('All titles unique')
|
||||
"
|
||||
python3 -c "
|
||||
import json
|
||||
tools = json.load(open('data/tools.json', 'r'))
|
||||
missing = [t['slug'] for t in tools if not t.get('introduction', '').strip()]
|
||||
print(f'Missing intro ({len(missing)}):', missing[:10])
|
||||
"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Consolidated Runners
|
||||
|
||||
```bash
|
||||
# Quick check — meta validation + live site verification
|
||||
seo:quick() { seo:verify "$PROD_URL" && seo:validate; }
|
||||
# Full check — quick + duplicate title check
|
||||
seo:full() { seo:quick; }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Master Issue Control Table
|
||||
|
||||
| # | Issue | Severity | Phase |
|
||||
|---|---|---|---|
|
||||
| 1 | Duplicate / template prose across tool pages | 🔴 Critical | 2 |
|
||||
| 2 | Missing or generic meta titles | 🔴 Critical | 1 |
|
||||
| 3 | Missing or generic meta descriptions | 🔴 Critical | 1 |
|
||||
| 4 | H1 shared across all tools | 🔴 Critical | 3 |
|
||||
| 5 | Orphan tool pages (no inbound internal links) | 🟡 High | 5 |
|
||||
| 6 | Missing related tool links | 🟡 High | 5 |
|
||||
| 7 | Keyword-stuffed or keywordless URL slugs | 🟡 High | 6 |
|
||||
| 8 | No author byline or last-updated date | 🟡 High | 7 |
|
||||
| 9 | Heading hierarchy violations | 🟢 Medium | 3 |
|
||||
| 10 | Missing aria-labels on icon buttons | 🟢 Medium | 4 |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
| ✅ Do | ❌ Don't |
|
||||
|-------|----------|
|
||||
| Write unique meta title + description per tool | Use template prose shared across 80+ pages |
|
||||
| Complete one tool's content fully before next | Batch-write partial entries across many tools |
|
||||
| Link 2+ related tools from every tool page | Leave orphan tools with zero internal links |
|
||||
| Use `{primary-keyword}` in URL slug | Pad slugs with "free" / "online" / "tool" |
|
||||
| Add author byline + date to every tool page | Show authorless, dateless content |
|
||||
| Blog about informational keywords (pos 50–68) | Rely on tool pages to rank for "how to" queries |
|
||||
| 301 redirect old slugs when renaming | Delete old slugs without redirects |
|
||||
|
||||
---
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Duplicate content first, always.** Identical template prose across 80+ pages is the
|
||||
root cause on almost every underperforming tool site. No other fix matters until this is done.
|
||||
|
||||
2. **Complete one tool fully before the next.** Never write partial entries across many tools.
|
||||
A half-written registry entry is worse than no entry — it signals thin content at scale.
|
||||
|
||||
3. **Internal links are PageRank distribution.** A tool with great content but zero inbound
|
||||
internal links is invisible to Google. Every tool needs at least 2 inbound links.
|
||||
|
||||
4. **URL slugs are permanent.** A clean slug outperforms a stuffed one from day one.
|
||||
Get them right before indexing — renaming later costs ranking momentum even with 301s.
|
||||
|
||||
5. **E-E-A-T is not decoration.** Authorless, dateless tool pages trigger quality rater
|
||||
guidelines as potential spam. A real name and a real date is the minimum baseline.
|
||||
|
||||
6. **Validate before every commit.** Catching a missing description before deploy is free.
|
||||
Fixing it after indexing costs weeks.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- [schema-markup-generator](/skills/schema-markup-generator/SKILL.md) — JSON-LD structured data (HowTo, FAQPage, WebApplication) for tool pages
|
||||
- [social-metadata-hardening](/skills/social-metadata-hardening/SKILL.md) — OG tags and social sharing previews for tool pages
|
||||
- [indexing-issue-auditor](/skills/indexing-issue-auditor/SKILL.md) — full crawl audit and redirect mapping after slug changes
|
||||
- [pagespeed-enhancer](/skills/pagespeed-enhancer/SKILL.md) — Lighthouse / Core Web Vitals audit for tool pages
|
||||
- [wordpress-centric-high-seo-optimized-blogwriting-skill](/skills/wordpress-centric-high-seo-optimized-blogwriting-skill/SKILL.md) — blog post writing with SEO structure
|
||||
- [vibecode-production-qa-validator](/skills/vibecode-production-qa-validator/SKILL.md) — end-to-end production QA including deployment verification
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
This skill is applicable to execute the workflow or actions described in the overview.
|
||||
Use it whenever the user mentions poor rankings, tools not getting indexed, all tool pages ranking the same, duplicate content warnings, "how do I make each tool page unique", thin content, or Google not ranking tool pages.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Use this skill only when the task clearly matches the scope described above.
|
||||
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
|
||||
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|
||||
- Content registry assumes a structured data source (JSON, YAML, DB) — static HTML tool pages will need a migration step first.
|
||||
- Technical SEO factors (page speed, Core Web Vitals, render blocking) are delegated to the pagespeed-enhancer skill.
|
||||
Reference in New Issue
Block a user