Skip to content

Port engagement skills into HoEN

ContributorsMyles Henaghan

When to use: A maintainer wants reusable skill IP from another checkout (engagement repo, portfolio library, or .agents/skills/ on an app) merged into library/skills/ with customer-safe redaction and validation.

This skill is the Authoring path for compounding engagement work back into the library. It complements create-hoen-skill (which defines shape) and redact-with-personas (which scrubs identifiers).

Preconditions

  • git-hygiene — feature branch off clean, up-to-date main; never commit directly to main.
  • Local clones of HoEN and the source repo (paths the driver provides).
  • Write access to HoEN only; source repo is read-only unless fixing typos.

Where skills live in source repos

Source layout Typical path Notes
HoEN-style library library/skills/<name>/SKILL.md May include references/, scripts/, prompts folded into skill
Engagement-local .agents/skills/<name>/SKILL.md Often single-file; scripts may live elsewhere in the app repo
Diagnosis prompts library/prompts/diagnosis/<topic>/ Fold into an existing HoEN skill folder (validator allows only skill-local dirs)

Scan both trees if the engagement mirrors HoEN partially.

End-to-end flow

flowchart TB
  A[git-hygiene on HoEN] --> B[Inventory source vs HoEN]
  B --> C[Classify each skill]
  C --> D[Driver selects scope]
  D --> E[Redact and genericize]
  E --> F[Copy merge validate]
  F --> G[Radar blips if new]
  G --> H[Commit on feature branch]

Step 1 — Inventory (skills trawl)

For each repo root, list skill folders that contain SKILL.md:

HOEN=/path/to/hoen-library
SRC=/path/to/engagement-or-child-library

find "$HOEN/library/skills" -maxdepth 2 -name SKILL.md 2>/dev/null | sed 's|/SKILL.md||' | xargs -n1 basename | sort -u
find "$SRC/library/skills" -maxdepth 2 -name SKILL.md 2>/dev/null | sed 's|/SKILL.md||' | xargs -n1 basename | sort -u
find "$SRC/.agents/skills" -maxdepth 2 -name SKILL.md 2>/dev/null | sed 's|/SKILL.md||' | xargs -n1 basename | sort -u

For every name in the union, record:

Field How
In HoEN? / In source? Set membership
Last updated git log -1 --format=%ci -- <skill-path> in each repo
Same content? Tree hash of all files under the skill folder, or diff -ru
Description First lines of frontmatter description:

Present a short table to the driver. Do not port until they confirm scope (which skills, which renames, what to skip).

Common name mappings

Some engagements rename skills HoEN already has. Compare by intent, not only folder name:

Source name (examples) HoEN target
*-diagnostic prompt + skill Existing diagnose skill (e.g. fold prompt into change-throughput/)
unit-test-authoring unit-test (keep HoEN canonical name)
lakebase-branching database-branching (merge Lakebase ops into existing skill)
Customer design-system skill Skip — HoEN uses neutral messaging (wue-messaging)

Document any new mapping in the port PR body.

Step 2 — Classify each candidate

Class Action
Identical No port needed; note for driver
HoEN stale Update HoEN from source; redact while merging
Source-only, generic Add new folder under library/skills/<name>/
Source-only, platform-locked Skip unless driver wants a redacted generic variant
Merge into existing Patch HoEN skill; do not duplicate folder names
Prompts / templates Move under skill references/ or assets/; fix links

Default skip list unless driver opts in: customer branding, single-tenant infra IDs, engagement-only registry paths, skills with no reusable pattern.

Step 3 — Redact and genericize

Before writing into HoEN:

  1. Use redact-with-personas and local library/personas/.assigned-personas.yaml (gitignored) for entity swaps.
  2. Replace customer product names, ticket prefixes, subscription IDs, emails, and internal repo URLs with persona labels or placeholders.
  3. Replace engagement-specific paths with neutral patterns (tests/, app/api/, “repo release script”) while keeping command shapes that transfer.
  4. Set HoEN provenance (origin_project, adapted_from, source_commit when known).
  5. Align phase, hoen, and maturity with CONVENTIONS.md.

Keep branch names and commit subjects customer-neutral when the driver asks.

Step 4 — Port mechanics

New or updated skill folder

mkdir -p library/skills/<name>
# SKILL.md + optional references/, assets/, scripts/, evals/

Rules from create-hoen-skill:

  • Folder name equals frontmatter name:.
  • No top-level templates/ in skill folders — use assets/.
  • Under 500 lines in SKILL.md; spill to references/.

Validation

Ignore transient folders under library/skills/ (.trash/, local synced/) when validate fails on them — move aside, run validate, restore:

node library-maintenance/scripts/validate.mjs

Fix radar alignment errors by editing website/overrides/assets/data/data-library.js:

  • New skill → add a RADAR_BLIPS entry (name matches folder; omit ring so maturity comes from frontmatter).
  • Material update → set movement: 'moved' and refresh blurb.

Commit strategy

Prefer reviewable commits on one feature branch:

  1. Shared skill updates (drift fixes from a library-style source).
  2. New skills (net additions).
  3. Engagement-local promotions (.agents/skills → HoEN), if split helps review.

Use commit-message-conventions. Lead with 👓 in the body when the port is large.

Do not commit gitignored persona assignment files or engagement secrets.

Step 5 — Handoff

  • Summarize what was ported, skipped, and merged.
  • Note validator and any tests run on ported scripts.
  • Remind driver to push the feature branch and open a PR; do not push without ask.

Checklist (copy for PR test plan)

  • [ ] git-hygiene branch from main
  • [ ] Inventory table shared with driver; scope confirmed
  • [ ] Redaction applied; no customer identifiers in diff
  • [ ] validate.mjs passes
  • [ ] Radar blips updated for new/changed skills
  • [ ] hoen-intro routing still accurate if catalog changed materially

References

Troubleshooting

Symptom Likely cause Fix
validate fails on .trash or synced Extra skill-like folders Temporarily move aside; exclude from port
Radar check fails New skill without blip Add entry in data-library.js
Prompt port has nowhere to go Top-level prompts disallowed Fold into skill references/
Duplicate skill intent Source renamed Merge into existing HoEN name
Huge single-file skill Engagement .agents/skills Split to references/; keep SKILL.md scannable