--- name: packaging-to-github description: Promote a proven skill from a live Hermes agent into a reusable GitHub package. Use when an agent or operator asks to share, publish, export, genericize, sanitize, or synchronize a Hermes-created skill into the AI-colleague package repository for reuse by other agents, environments, or teams. --- # Package a Hermes Skill to GitHub Turn a skill that works in one Hermes environment into a safe, portable skill for other teams. Preserve reusable task expertise while removing organization-specific context and runtime residue. ## Core distinction Generalize the environment, not the useful expertise. - Keep task-domain knowledge that makes the skill valuable, such as financial-model review logic, incident-triage steps, or content-quality checks. - Remove facts and assumptions that bind the skill to one organization, customer, person, project, schema, deployment, or private operating history. - Replace required environment bindings with explicit placeholders or documented inputs. - Remove narrow details instead of inventing fake generic equivalents when those details are not necessary to perform the task. A skill is ready to share only when a new team can understand when to use it, supply its own bindings, and execute it without access to the source environment. ## Workflow ### 1. Establish the source and scope Identify: - the live skill directory that Hermes actually used - the agent and capability that own the behavior - one or more successful usage examples or other evidence that the skill is worth promoting - the requested destination repository and publication boundary Treat the live skill as source material, not as a directory to mirror blindly. Do not modify the live runtime while preparing the package unless the user explicitly asks for both changes. Stop and ask for direction when the source, target repository, ownership, or publication authorization cannot be determined safely. ### 2. Decide whether it should be shared or agent-owned Place the skill according to who should own the behavior: - `agents/shared-skills///` for behavior useful across roles and not owned by one agent capability - `agents////` for role-specific or capability-specific behavior Specialized does not mean unshareable. Keep an agent-owned skill specialized when its domain judgment is the reusable value. Move it to shared skills only when multiple roles should use the same behavior and authority model. Use the exact lowercase hyphen-case skill name for both the folder and the `name` field. Keep names short, action-oriented, and under 64 characters. ### 3. Copy only the functional skill Copy the skill into the selected package boundary without following symlinks. Include only resources needed to perform the skill: ```text / SKILL.md scripts/ # optional deterministic helpers references/ # optional knowledge loaded only when needed assets/ # optional files used in generated output agents/ # optional interface metadata ``` Exclude runtime and authoring residue: - caches, logs, transcripts, scratch files, backups, usage telemetry, and generated output - `.env`, credentials, tokens, cookies, SSH material, and local configuration - unrelated documentation such as README, changelog, quick-start, or installation files - symlinks and copied dependency trees - examples whose only value is recording one company's work See [references/hermes-skill-export.md](references/hermes-skill-export.md) for safe traversal and repository placement. ### 4. Extract the reusable contract Before rewriting, state the skill's contract in plain language: - Trigger: What user requests or situations should activate it? - Outcome: What reusable result does it produce? - Inputs: What must the target environment provide? - Workflow: Which decisions and steps are essential? - Outputs: What artifacts or changes should result? - Boundaries: What requires approval, escalation, or a different skill? - Validation: How can another agent know the work is correct? Remove material that does not support this contract. Do not preserve historical decisions, retired architectures, team rosters, client migrations, or unrelated operational notes inside the skill. ### 5. Generalize and sanitize Apply [references/generalization-checklist.md](references/generalization-checklist.md) to every text file, script, asset name, example, and metadata file. Use these transformations: - organization, product, customer, partner, project, and person names → neutral role language or `{{PLACEHOLDER}}` - emails, phone numbers, account IDs, chat IDs, database IDs, URLs, IPs, ports, webhook paths, and absolute paths → inputs, configuration, or placeholders - local table, field, channel, bank, repository, and workflow names → generic concepts unless the literal identifier is required by a supported tool - business-specific examples → small neutral examples that demonstrate the same decision pattern - hardcoded script values → arguments, environment variables, configuration, or explicit constants the installer must set - organization policy presented as universal truth → configurable policy or an explicit prerequisite Never copy a real secret and then rely on later redaction. If secret material is encountered, exclude it immediately and report the exposure without reproducing its value. ### 6. Rewrite the skill for progressive disclosure Follow the standard skill format: - Keep YAML frontmatter to `name` and `description` only. - Put what the skill does and when it should trigger in `description`. - Write the body as concise imperative instructions for another capable agent. - Keep `SKILL.md` under 500 lines; aim substantially shorter. - Keep the essential workflow in `SKILL.md` and move detailed, conditionally useful material to one-level-deep references. - Add scripts only for repeated deterministic operations, and test them directly. - Reference every bundled file from `SKILL.md` or remove it. - Avoid duplicating the same rule in the body and references. - Do not add a README inside the skill or capability folder. Preserve tool-specific instructions only when the tool is part of the skill's actual contract. Otherwise describe the capability generically and let the target environment choose its implementation. ### 7. Validate portability and safety Run the available skill validator, preferably the `skill-creator` `quick_validate.py`, against the packaged skill directory. Then verify manually: ```bash find -type l -print find -type d -name __pycache__ -o -type f -name '*.pyc' rg -n '' git diff --check ``` Also inspect for: - malformed or extra frontmatter fields - a folder name that differs from the skill name - unreferenced bundled files - absolute local paths and private hostnames - secret-shaped values and high-entropy tokens - hidden files and generated artifacts - instructions that assume unavailable memory, schemas, credentials, or tools - examples that reveal source-organization facts Validation must include judgment; a clean regex scan does not prove that prose is generalized. ### 8. Review the package as a new team Read only the packaged skill and ask: 1. Would a new agent know when this skill applies? 2. Can it execute the workflow without source-company knowledge? 3. Are required tools and inputs explicit? 4. Does it retain the expertise that made the source skill useful? 5. Are approval and external-action boundaries clear? 6. Can success be checked from observable output? If any answer is no, revise before publishing. ### 9. Publish with a narrow Git scope Before changing Git state: - inspect the branch, remote, and working tree - distinguish the packaged skill from unrelated user changes - review the complete diff for the skill and any necessary catalog/spec update - stage only the intended paths - if the working tree already has unrelated edits or untracked residue, or if `git push` is rejected because the remote moved ahead, switch to a fresh clone or clean worktree and re-apply only the intended skill paths there instead of reconciling unrelated local state in place - when the user specifies an agent-owned category path such as `agents/iris//...`, preserve that exact category layout and verify the destination contains the full skill directories, not just `SKILL.md` - do not invent an intermediate `skills/` folder under an agent path unless the user explicitly asked for it; if the requested shape is `/iris//...`, package to `agents/iris//...` - when the user gives a shorthand shared-skills destination like `/shared-skills/sh-system/`, interpret it relative to the repo's shared-skills root and package to `agents/shared-skills/sh-system/...` - after copying, verify the exact final tree with `git ls-tree` or `find` before committing so path-shape mistakes are caught before push Commit and push only when the user authorized publication. Use a message that describes the reusable capability, not the source company's incident or project. After pushing, verify the repository path or raw skill URL and confirm the working tree state. Do not bundle unrelated cleanup into the publication commit. ## Acceptance criteria The packaged skill is complete when: - it has a clear trigger and reusable outcome - its folder and frontmatter follow the standard skill format - it is placed under the correct shared or agent capability boundary - organization-specific facts, identifiers, secrets, and runtime residue are absent - required environment bindings are explicit - useful domain expertise remains intact - every bundled resource is necessary and discoverable - scripts and structural validation pass - the diff contains only the intended package scope - the published artifact is reachable when publication was requested ## Report back Lead with whether the skill was packaged and, if requested, published. Briefly name: - the destination and ownership choice - what was generalized or removed by category - validation performed - any target-environment inputs still required Do not expose redacted values or dump a file-by-file sanitization log.