engineering-skill-creator
Skill7 starsChanged 6 months agoApache-2.0View on GitHub
Author a new skill for this repository in the established format: YAML frontmatter with `Use when... Don't use for...` description, Pitfalls catalogue, Procedure checklist, fallback strategies, JSON output envelope, and (where third-party libraries or standards are referenced) a first-use `LICENSE_NOTIFICATION.txt` artifact. Use when you are adding a new skill or refactoring an existing one. Don't use to add features to an existing skill without rewriting its SKILL.md.
In this repository31 other files it gives its agents.
- absorption-stripping-designSkill
- bayesian-hierarchical-process-modelsSkill
- caustic-merox-extractionSkill
- censored-regressionSkill
- compositional-data-analysisSkill
- control-valve-sizing-isa75Skill
- convective-heat-transfer-correlationsSkill
- design-of-experimentsSkill
- dimensionless-numbersSkill
- distillation-shortcut-designSkill
- distributed-lag-modelsSkill
- engg-skills-commonSkill
- engineering-statisticsSkill
- equation-of-state-selectionSkill
- heat-exchanger-sizingSkill
- literature-search-engineeringSkill
- material-energy-balancesSkill
- pipe-flow-pressure-dropSkill
- process-causal-inference-dagsSkill
- process-units-conversionSkill
- reactor-sizing-and-kineticsSkill
- relief-valve-sizing-api520Skill
- separator-vessel-sizingSkill
- sour-gas-amine-treatingSkill
- statistical-process-controlSkill
- steam-tables-iapwsSkill
- thermo-process-propertiesSkill
- time-series-process-data-analysisSkill
- two-phase-flowSkill
- uvSkill
- vle-flash-calculationsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 3 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Use this skill as the reference whenever you create a new skill or rewrite an existing one.
- Very specific: line 55
Every script writes JSON via result_envelope() (or DOT/text for the rare diagrammatic case) and requires --output as the only output …
- Very specific: line 59
If the script references any third-party library, standard, or external API, it MUST call write_license_notification() on first invocation.
- Very specific: line 74
Create skills/<name>/SKILL.md from references/skill_template.md.
- Very specific: line 75
Create skills/<name>/scripts/<short_name>.py using the PEP-723 header pattern and the result_envelope + write_license_notification helpers.
- Very specific: line 78
Create skills/<name>/references/<topic>.md documents for any methodology or background the user (or a code reviewer) will need.
- Very specific: line 80
If the script needs a new pure-Python or thin-wrapper helper, add it to skills/engg-skills-common/engg_skills_common/<module>.py and import …
- Very specific: line 83
Add tests in tests/test_<module>.py covering at least one happy path, one edge case, and one error case for any new shared-library function.
- Distinctive: line 87
Add a row to the README skill table.
- Very specific: line 88
Run uv run pytest -q and at least one end-to-end script invocation before committing.
- Distinctive: line 116
If the skill borders on a regulated calculation (relief, pressure vessel, electrical area classification), make the "Safety and Scope" …
- Distinctive: line 119
If a third-party library is not installable in some environments, the script should give a clear error message naming the missing library …
- Very specific: line 125
Run python3 tools/validate_hermes_skills.py skills --strict-directory-match after adding or rewriting a skill.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Engineering Skill Creator
Overview
This meta-skill is the canonical template for any new engineering skill in
this repository. The convention mirrors Google DeepMind's science-skills
format (YAML frontmatter, scripts that always write to --output, JSON
envelope, first-use license notification) and adds engineering-specific
elements: explicit safety scope where relevant, sources listed in
SKILL_LICENSES.md, fallback strategies for missing optional dependencies,
and an anti-patterns section.
Use this skill as the reference whenever you create a new skill or rewrite
an existing one. The template files in references/ are the source of
truth for the format.
When to Use
- You are adding a brand-new skill folder.
- You are refactoring an existing skill to the current format.
- You are documenting an internal review of the format itself.
Don't use for
- Adding a new script to an existing skill without rewriting the SKILL.md.
- Editing the shared
engg-skills-commonlibrary (that is developer code, not a user-facing skill). - Authoring the
uvinfrastructure skill (it has its own minimal shape).
Core Rules
- The YAML
descriptionMUST follow the pattern:<one-sentence what the skill does>. Use when <scenarios>. Don't use for <complementary scope>. - Every script writes JSON via
result_envelope()(or DOT/text for the rare diagrammatic case) and requires--outputas the only output channel. - Stdout is reserved for a single success message; warnings/diagnostics go inside the JSON envelope.
- If the script references any third-party library, standard, or external
API, it MUST call
write_license_notification()on first invocation. - The skill MUST list at least 8 specific common mistakes for the domain.
- Procedure sections MUST be numbered checklists, not prose paragraphs.
- Fallback strategies MUST cover at least one realistic failure mode (missing dep, edge case input, etc.).
Utility Scripts
This meta-skill does not have scripts; the templates in references/ are
copy-paste starting points.
Procedure
- Pick a lowercase hyphenated folder name (e.g.
vle-flash-calculations) and use the same value in frontmattername. - Create
skills/<name>/SKILL.mdfromreferences/skill_template.md. - Create
skills/<name>/scripts/<short_name>.pyusing the PEP-723 header pattern and theresult_envelope+write_license_notificationhelpers. - Create
skills/<name>/references/<topic>.mddocuments for any methodology or background the user (or a code reviewer) will need. - If the script needs a new pure-Python or thin-wrapper helper, add it to
skills/engg-skills-common/engg_skills_common/<module>.pyand import from the script via the establishedsys.path.insertpattern. - Add tests in
tests/test_<module>.pycovering at least one happy path, one edge case, and one error case for any new shared-library function. - Append a row to
SKILL_LICENSES.mdsummarising the upstream sources and the engineering standards referenced (numbers only, not text). - Add a row to the README skill table.
- Run
uv run pytest -qand at least one end-to-end script invocation before committing.
Pitfalls
- Writing a generic description like "Use when a user asks for engineering work matching this scope" — that defeats skill routing.
- Reproducing standard text (API, ASME, ISA, GPSA, TEMA): cite the number only and require the user to procure the standard.
- Embedding kij values, NIST table data, or vendor correlations without attribution; cite the source for every number.
- Forgetting the
LICENSE_NOTIFICATION.txtfirst-use call when the script imports a third-party library. - Putting heavy dependencies (
pymc,arviz) in the project-levelpyproject.toml; declare them in the script's PEP-723 header instead so users pay the cost only for the skills that need them. - Returning Python objects from
result_enveloperesultsfield that cannot be JSON-serialised (numpy types, pandas Index). Convert to native Python first. - Forgetting to round / sanity-check final numbers in the script before emitting them. The JSON should look correct without further processing.
- Skipping the "fallback strategies" section because the happy path works.
- Writing scripts that print results to stdout; the contract is JSON-only.
- Putting safety-critical wording in a single paragraph without a dedicated "Safety and Scope" section.
Fallback Strategies
- If the skill borders on a regulated calculation (relief, pressure vessel, electrical area classification), make the "Safety and Scope" section explicit and decline to produce final-design numbers.
- If a third-party library is not installable in some environments, the script should give a clear error message naming the missing library and the install command.
Verification
- Run
python3 tools/validate_hermes_skills.py skills --strict-directory-matchafter adding or rewriting a skill. - Confirm the skill folder name matches
name, the description includes routing guidance, and referenced scripts or files exist.
References
references/skill_template.md— copy-paste SKILL.md template.references/calculation_result_schema.md— JSON envelope schema.references/script_template.md— copy-paste Python CLI template.
Anti-Patterns
- Authoring a skill whose description is duplicated verbatim from another skill.
- Producing skill content that quotes standards extensively rather than citing them.
- Authoring a script that does work outside its declared scope.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

