@snoozer10/synthesize-skills

v1.3.0

Published

9 days ago

Use when authoring or installing reusable AI-agent skills — validated SKILL.md + blast-radius parity gate + live dashboard

0High
0Medium
0Low

snoozer10

ai agents skills opencode claude gemini blast-radius dashboard

synthesize-skills

Workspace for authoring, validating, and installing reusable AI-agent skills. Skills are SKILL.md files with YAML frontmatter, validated by scripts/validate.py, installed across 8 host directories (.agents/skills, .claude/skills, .opencode/skills, .gemini/skills, .codex/skills, .cursor/skills, .windsurf/skills, .copilot/skills). RED-GREEN-REFACTOR workflow enforces one skill at a time with pressure-scenario testing before acceptance.

📦 Skills Catalog (5 Canonical Skills)

| Skill | Description | Trigger | |---|---|---| | gemini-context-engineer | Creating, updating, auditing, or federating GEMINI.md workspace context files, detecting architectural reality drift, compiling task slices, or verifying workstream proof commands | Architectural drift, GEMINI.md sync, context compilation | | release-sync | Detecting release semver version drift across VERSION, GEMINI.md, and package.json, maintaining CHANGELOG and README hygiene, or atomically bumping release versions | Semver version drift, release prep, atomic bumping | | repo-blast-radius-sync | Checking code changes for orphaned callers, outdated tests, or stale documentation, discovering change blast radius, or verifying git staged parity against dependency registry | Refactoring, code modifications, staged parity | | repo-standards-engineer | Extracting codebase standards, response envelopes, and error codes via AST, injecting token-bounded invariants, shaping feature specs, or verifying deterministic executable contracts | Standards discovery, feature spec shaping, contract verification | | skill-creator | Authoring, scaffolding, validating, or packaging new reusable AI-agent skills across multiple agent ecosystems | New skill creation, skill scaffolding, validation |

Skill Details

`skill-creator`

Capabilities: Standardized scaffolding CLI utility (scripts/init_skill.py) generating spec-compliant skills, strict kebab-case naming validation, frontmatter generation with "Use when" triggers, zero-warning out-of-the-box baseline.
Structure: 1 script (init_skill.py), test suite (test_skill_creator_pressure.py), template compatibility.
Use when: Authoring, scaffolding, or packaging new AI-agent skills for distribution across agent ecosystems.

`repo-standards-engineer`

Capabilities: AST Standards Scanner (extracts envelopes, enums, DB patterns with SHA-256 caching), JIT Token Bounding (MIP ≤600 tokens), Spec Shaper (specs/<slug>/SPEC.md), Executable Assertion Contracts (verify_spec.py).
Structure: 5 scripts (discover_standards.py, inject_standards.py, index_standards.py, shape_spec.py, verify_spec.py), 3 templates, AST pattern reference.
Use when: Unfamiliar codebase onboarding, shaping feature specs, enforcing deterministic verification before completion.

`gemini-context-engineer`

Capabilities: JIT Context Compiler (MIP token bounding ≤600 tokens), VCS AST Delta Daemon (sub-100ms pre-commit sync), Executable Workstream Proofs (anti-premature completion harness).
Structure: 8 scripts, 9 reference guides, 5 test files, evals, benchmarks, assets.
Use when: Creating/maintaining GEMINI.md, mapping repo architecture, compiling task context, detecting architectural reality drift, verifying execution contracts.

`repo-blast-radius-sync`

Capabilities: Blast radius detection (callers, tests, docs), registry verification, live dashboard (port 8765), orphaned commit blocking.
Structure: 5 scripts (blast_radius.py, build_registry.py, dashboard.py, draft_doc_updates.py, verify_parity.py), 3 references.
Use when: Refactoring, adding features, fixing bugs where dependent artifacts must stay in sync.

`release-sync`

Capabilities: Version parity gate (80/20: FAIL on drift, WARN on hygiene), atomic semver bump across 5 files with rollback, portable (copy-paste to any project).
Structure: 2 scripts (check.py, bump.py), 2 references (API, examples).
Use when: VERSION/GEMINI.md/package.json drift, CHANGELOG/README hygiene, before semver bump.

🚀 Install

From Source (Always Works — Recommended)

git clone https://github.com/Snoozer10/synthesize-skills
cd synthesize-skills
python scripts/validate.py && python scripts/manifest.py
install.ps1 -Force    # Windows
bash install.sh --force  # POSIX

What happens:

Validates all 5 skills (CI gate)
Generates manifest.json mapping skills → host paths across 8 ecosystems
Copies skills to target host directories:
- .agents/skills/ (canonical)
- .claude/skills/
- .opencode/skills/
- .gemini/skills/
- .codex/skills/, .cursor/skills/, .windsurf/skills/, .copilot/skills/
SHA256 comparison skips identical files; creates .bak backups with rollback support

From npm (Published Package)

# Dual registry: npmjs.org (primary) + GitHub Packages (mirror)
npx --package @snoozer10/synthesize-skills repo-sync add <skill>

# Or install globally
npm i -g @snoozer10/synthesize-skills
repo-sync add <skill>

# Explicitly from GitHub Packages
npm i -g @snoozer10/synthesize-skills --registry=https://npm.pkg.github.com
repo-sync add <skill>

Provenance: All publishes include SLSA Level 1 provenance attestations via OIDC trusted publishers.

🖥️ Universal Platform Support (8 Host Ecosystems)

| Platform | Project Target | User-Global Target | Native Adapter | |---|---|---|---| | Open Agents Standard | .agents/skills/ | ~/.agents/skills/ | Canonical SSOT | | Antigravity / Gemini | .gemini/skills/ | ~/.gemini/skills/ | .gemini/rules/*.md | | Claude Code / CLI | .claude/skills/ | ~/.claude/skills/ | .claude/commands/*.md | | OpenAI Codex | .codex/skills/ | ~/.codex/skills/ | .codex/instructions/*.md | | OpenCode | .opencode/skills/ | ~/.config/opencode/skills/ | .opencode/commands/*.md | | Cursor | .cursor/skills/ | ~/.cursor/skills/ | .cursor/rules/*.mdc | | Codeium Windsurf | .windsurf/skills/ | ~/.codeium/windsurf/skills/ | .windsurf/rules/*.md | | GitHub Copilot | .copilot/skills/ | ~/.copilot/skills/ | Instructions block |

Installer CLI Switches

# PowerShell (Windows)
.\install.ps1 -Force                                      # Apply auto-detected install across active hosts
.\install.ps1 -Skill skill-creator -Force                 # Install single skill standalone
.\install.ps1 -Skill "release-sync,repo-blast-radius-sync" -Force # Install specific subset of skills
.\install.ps1 -Scope Global -Force                        # Install globally into user profiles (~/.gemini, ~/.claude, etc.)
.\install.ps1 -Target "claude,antigravity" -Force         # Selective multi-host targeting
.\install.ps1 -Rollback                                   # Safely rollback via transaction receipt

# POSIX Shell (Linux / macOS / WSL)
./install.sh --force                                      # Apply auto-detected install
./install.sh --skill skill-creator --force                # Install single skill standalone
./install.sh --skill "release-sync,repo-blast-radius-sync" --force # Install specific subset of skills
./install.sh --scope global --force                       # Install globally
./install.sh --target "claude,antigravity" --force        # Selective multi-host targeting
./install.sh --rollback                                   # Safely rollback via transaction receipt

🔄 Workflow: RED → GREEN → REFACTOR

Per docs/WORKFLOW.md:

RED: Write 1-3 pressure scenarios in tests/, run without skill, record exact failure verbatim
GREEN: Write smallest SKILL.md that fixes baseline failure. Re-run scenarios. Pass = agent complies.
REFACTOR: Add explicit counters and red-flags for new rationalizations. Re-verify. Keep token cost flat (move heavy refs to references/).

Stop-gate rules:

One skill at a time — untested edit = revert
Never batch-create skills
Pressure test must exist before skill implementation
Run python scripts/validate.py before every commit

🛠️ Development Commands

# Validation (CI gate — REQUIRED before commit)
python scripts/validate.py                    # All skills
python scripts/validate.py .agents/skills/<name>  # Single skill

# Manifest (run after adding/removing skill)
python scripts/manifest.py                    # Generates manifest.json

# Drift gate (dogfooding this repo)
python scripts/release_sync.py --check        # Exit 0 = no drift

# Atomic semver bump (updates 5 files with rollback)
python scripts/release_sync.py --bump patch --apply  # patch|minor|major

# Install
install.ps1                       # Windows dry-run
install.ps1 -Force                # Windows apply
bash install.sh                   # POSIX dry-run
bash install.sh --force           # POSIX apply

# Pre-commit hook (optional)
python scripts/release_sync.py --install-hooks

# Pressure tests
python tests/test_release_sync_pressure.py -v   # Drift detection + atomic bump scenarios

📦 Release Automation

Standard Release Flow (Triggers OIDC Dual-Registry Publish)

# 1. Ensure clean working tree and all tests pass
python scripts/validate.py && python scripts/release_sync.py --check

# 2. Bump version (updates VERSION, GEMINI.md, package.json, README region, CHANGELOG)
python scripts/release_sync.py --bump patch --apply  # or minor/major

# 3. Commit version bump
git add VERSION GEMINI.md package.json README.md CHANGELOG.md
git commit -m "chore: release v1.0.2"

# 4. Tag and push (triggers GitHub Actions release.yml)
git tag v1.0.2
git push origin main --tags

What happens on tag push:

validate job runs python scripts/validate.py
publish-npm job publishes to npmjs.org with provenance (uses NPM_TOKEN secret)
publish-github job publishes to GitHub Packages with provenance (uses GITHUB_TOKEN with packages: write)

Secrets Required

| Secret | Type | How to Create | |--------|------|---------------| | NPM_TOKEN | npm automation token (NOT personal token — 2FA causes EOTP) | npm token create --type=automation --read-only=false --cidr=0.0.0.0/0 | | GITHUB_TOKEN | Auto-provided by GitHub Actions | Requires packages: write permission (set in workflow) |

🏗️ Architecture

synthesize-skills/
├── .agents/skills/           # canonical skills (SSOT)
│   ├── gemini-context-engineer/
│   ├── release-sync/
│   ├── repo-blast-radius-sync/
│   ├── repo-standards-engineer/
│   └── skill-creator/
├── templates/
│   └── skill-template/       # SKILL.md starter (not installed)
├── scripts/
│   ├── validate.py           # Skill validator (CI gate)
│   ├── manifest.py           # Generates manifest.json (8 hosts)
│   ├── compile_adapters.py   # Compiles native adapters (6 host formats)
│   ├── detect_hosts.py       # Detects installed host platforms
│   ├── discover_standards.py # AST & regex standards discovery
│   ├── inject_standards.py   # JIT MIP token-bounded injector (≤600 tokens)
│   ├── index_standards.py    # Symbol & standards indexer
│   ├── shape_spec.py         # Spec Shaper & verification generator
│   ├── verify_spec.py        # Executable contract verification engine
│   ├── init_skill.py         # Standardized skill scaffolding utility
│   └── release_sync.py       # Version parity gate + atomic bump
├── tests/
│   ├── test_standards_engine.py
│   ├── test_installer_concurrency_rollback.py
│   ├── test_compile_adapters.py
│   ├── test_edge_cases_and_fault_injection.py
│   ├── test_blast_radius_parity.py
│   ├── test_release_sync_pressure.py
│   ├── test_release_sync_smoke.py
│   ├── test_skill_creator_pressure.py
│   └── test_skill_isolation_and_portability.py
├── exercises/                # RED-GREEN-REFACTOR learning modules
│   ├── 01-skill-authoring/       # 3 scenarios
│   ├── 02-pressure-testing/      # 2 scenarios
│   ├── 03-validation/            # 2 scenarios
│   └── 04-release-sync/          # 2 scenarios (drift, atomic bump)
├── docs/
│   ├── WORKFLOW.md           # RED-GREEN-REFACTOR stop-gate
│   ├── CONTRIBUTING.md       # Naming, description, validation rules
│   ├── error-solving/
│   │   └── understood-errors.md  # 17+ known error patterns
│   ├── handoff.md            # Session handoff template
│   └── plan/                 # Implementation plans
├── .github/workflows/
│   ├── validate.yml          # CI: validate on push/PR (Windows + Ubuntu)
│   └── release.yml           # CD: OIDC dual-registry publish on v* tags
├── Research and docs/        # upstream research (READ-ONLY)
├── The Created Skills/       # staging area (READ-ONLY)
├── install.ps1               # Windows installer (PowerShell native, locking, rollback)
├── install.sh                # POSIX installer (pure shell, locking, rollback)
├── manifest.json             # skill → host path mapping (8 hosts)
├── VERSION                   # Semver (synced by release_sync.py)
├── GEMINI.md                 # Project context for Gemini CLI
├── CONTINUITY.md             # Project state ledger
├── CHANGELOG.md              # Keep a Changelog format
├── README.md                 # This file
├── package.json              # npm package config
└── LICENSE                   # MIT

Component Reference

⚙️ Validation Rules (Exit Codes Matter)

| Check | Severity | Exit Code | |-------|----------|-----------| | name regex ^[a-z0-9]+(-[a-z0-9]+)*$ | ERROR | 1 | | dir == frontmatter name (allowlist: skill-template/skill-name) | ERROR | 1 | | description 1-500 chars | ERROR | 1 | | Frontmatter raw ≤1024 chars | ERROR | 1 | | Body <500 lines | ERROR | 1 | | Runnable code fence required (```python|bash|sh|ps1|js|ts) | ERROR | 1 | | description starts with "Use when" | WARN | 0 | | No first-person in description | WARN | 0 | | No workflow/step-by-step in body | WARN | 0 | | Keywords: required in body | WARN | 0 | | No @skills/@name/ links | WARN | 0 |

Run python scripts/validate.py before EVERY commit. CI runs this on Windows + Ubuntu (Python 3.11).

🔄 Version Sync (Atomic, 5 Files)

release_sync.py --bump patch --apply updates atomically with rollback:

VERSION
GEMINI.md (version: + last_indexed:)
package.json (version)
README.md (` Version: 1.3.0

CHANGELOG.md (ensures ## [Unreleased] exists)

Never manually edit these version fields. Use the script.

🛑 Hard Constraints (Violations = Revert)

Stdlib-only scripts — scripts/ uses Python stdlib only. No pip/npm deps.
One skill at a time — RED-GREEN-REFACTOR stop-gate (docs/WORKFLOW.md). Untested edit = revert.
No batch-create — Pressure test first (RED), minimal skill second (GREEN), close loopholes third (REFACTOR).
Read-only zones — Never touch Research and docs/ or The Created Skills/ without explicit ask.
Dir name = frontmatter name — Only skill-template/skill-name allowlisted mismatch.
Validate before commit — python scripts/validate.py must exit 0.

🧪 Testing Quirks

No pytest/Jest — Validation IS the test suite. scripts/validate.py is the gate.
Pressure tests live in tests/ (e.g., test_release_sync_pressure.py for drift/bump scenarios).
Exercises in exercises/ are learning modules, not CI tests.
Pre-commit hook available: python scripts/release_sync.py --install-hooks

🔧 OpenCode Config (`.opencode.json`)

{
  "default_agent": "orchestrator",
  "subagent_depth": 3,
  "agent": {
    "orchestrator": {
      "model": "opencode/nemotron-3-ultra-free",
      "permission": { "read": "allow", "glob": "allow", "grep": "allow", "list": "allow", "edit": "deny", "write": "deny", "bash": "deny" }
    }
  },
  "provider": { "opencode": { "options": { "blacklist": ["opencode/big-pickle", "opencode/muse-spark-1.2-free"] } } }
}

Orchestrator is read-only conductor. Subagents: @plan, @explorer, @private-builder, @sandboxed-builder, @architect, @auditor.

📁 Key Files to Know

| File | Purpose | |------|---------| | scripts/validate.py | Skill validator (CI gate) | | scripts/release_sync.py | Version parity gate + atomic bump | | scripts/manifest.py | Generates manifest.json | | .github/workflows/validate.yml | CI: validate on push/PR (Windows + Ubuntu) | | .github/workflows/release.yml | CD: OIDC dual-registry publish on v* tags | | docs/WORKFLOW.md | RED-GREEN-REFACTOR stop-gate rules | | docs/CONTRIBUTING.md | Naming, description, validation rules | | docs/error-solving/understood-errors.md | Known error patterns & resolutions | | docs/handoff.md | Session handoff template | | CONTINUITY.md | Project state ledger (updated per task) | | GEMINI.md | Project context for Gemini CLI | | CHANGELOG.md | Keep a Changelog format |

⚠️ Common Pitfalls (Agents Miss These)

| Pitfall | Fix | |---------|-----| | Editing Research and docs/ or The Created Skills/ | Don't. Read-only unless explicitly asked. | | Forgetting python scripts/manifest.py after adding skill | Run it. manifest.json must be committed. | | Using personal npm token (2FA) in CI | Use automation token: npm token create --type=automation | | Missing packages: write for GitHub Packages | Workflow has permissions: packages: write at job level. | | Manually editing VERSION/package.json/GEMINI.md | Use release_sync.py --bump patch --apply | | Batch-creating skills | One at a time. RED → GREEN → REFACTOR. | | Assuming validate.py catches everything | Run it against the specific skill: python scripts/validate.py .agents/skills/<name> |

🔗 References

Workflow: docs/WORKFLOW.md
Contributing: docs/CONTRIBUTING.md
Error Solving: docs/error-solving/understood-errors.md
Handoff Template: docs/handoff.md
Changelog: CHANGELOG.md
Continuity Ledger: CONTINUITY.md
License: LICENSE

Version: 1.3.0