package/per-skill/
- Root folder for per-skill artifacts.
- Split by format for cleaner browsing:
  - package/per-skill/skill/ for .skill
  - package/per-skill/zip/ for .zip
- Use this folder when you want to import a single skill into Claude.
- File naming is based on the name field in each SKILL.md frontmatter.
package/bundles/
- Contains collection-level archives (for example mechanical-skills-collection.zip).
- This is mainly for distribution, backup, or sharing the full skill set at once.
- It is not intended as a single-skill import artifact.
package/upload-md/
- Contains flattened .md copies named <skill-name>.md (for example gear-design.md).
- Useful for manual upload workflows where unique filenames are easier than many SKILL.md files with identical names.
- These are convenience exports; the source of truth remains skill/<skill-name>/SKILL.md.

Add a New Skill and Package It

Create a new folder under skill/:
- Example: skill/my-new-skill/
Add SKILL.md inside that folder.
Ensure SKILL.md has YAML frontmatter with at least:
- name: my-new-skill
- description: ...
Run packaging:

python3 script/package_skills.py

Check results:
- Per-skill package files in package/per-skill/skill/ and package/per-skill/zip/
- Validation report in package/PACKAGES_INDEX.md
Import into Claude:
- Upload package/per-skill/skill/my-new-skill.skill (or .zip from package/per-skill/zip/).

Notes:

If a skill is missing SKILL.md, it is skipped.
If name or description is missing in frontmatter, it is skipped.
If two skills use the same name, the script auto-adds a suffix and logs a warning in PACKAGES_INDEX.md.

Detailed Skill Authoring Guide (Claude-Style)

This section mirrors the depth of the official Claude Skills guidance and adapts it to this repository.

1) Skill lifecycle (end-to-end)

The recommended loop is:

Define intent and boundaries.
Draft the skill.
Create realistic test prompts.
Run tests (with-skill and baseline where possible).
Evaluate outputs qualitatively and quantitatively.
Improve the skill based on evidence.
Repeat until stable.
Package and distribute.

Use this as an iterative engineering process, not a one-shot prompt-writing exercise.

2) Anatomy of a skill

Each skill is one directory under skill/ with SKILL.md as required entrypoint.

Minimal:

skill/my-skill/
└── SKILL.md

Recommended for medium/complex skills:

skill/my-skill/
├── SKILL.md
├── scripts/       # deterministic helpers that can be executed
├── references/    # long docs loaded only when needed
└── assets/        # templates/static resources used in outputs

3) `SKILL.md` contract (mandatory parts)

At minimum, include YAML frontmatter and Markdown instructions:

---
name: my-skill
description: What it does and when to trigger it.
---

# My Skill
...

Required in this repo for packaging:

name
description

Optional Claude frontmatter fields:

disable-model-invocation
allowed-tools

4) Triggering strategy (`description` is critical)

The description field is the primary trigger mechanism. A weak description causes under-triggering.

Write descriptions that include:

What the skill does.
When to use it (explicit contexts and user phrasings).
Near-adjacent cases where this skill should still win.

Good pattern:

“Use this skill whenever the user asks X, Y, Z, even if they do not explicitly mention .”

5) Progressive disclosure (context efficiency)

Use a 3-layer design:

Metadata (name, description) always available.
SKILL.md body loaded when triggered.
Support files loaded/executed as needed.

Best practices:

Keep SKILL.md focused and ideally under ~500 lines.
Move large details to references/.
Link support files from SKILL.md with clear “when to read/use” guidance.

6) Writing style that scales

Prefer imperative and actionable instructions, but explain the “why” behind constraints.

Include:

Required inputs.
Assumptions policy when data is missing.
Step-by-step workflow.
Expected output structure/template.
Quality checks before final answer.

Avoid:

Overfitting to one example.
Excessive rigid rules without rationale.
Bloated SKILL.md with reference-heavy material inline.

7) Suggested `SKILL.md` skeleton

---
name: my-skill
description: What this skill does and when Claude should use it.
---

# My Skill

## Objective
Expected outcome and decision context.

## Required Inputs
What data is mandatory and how to handle missing data.

## Workflow
1. Frame the problem.
2. Run core analysis.
3. Apply checks/constraints.
4. Produce recommendation.

## Output Format
Exact structure to return.

## Quality Gates
Validation checklist before finalizing.

8) Test prompts and eval setup

After drafting, define realistic prompts in skill/evals/evals.json (or a skill-specific eval folder if you split later).

Template:

{
  "skill_name": "my-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "Realistic user request",
      "expected_output": "What good output should contain",
      "files": []
    }
  ]
}

Guidelines:

Use real user language (messy, informal, partial requirements).
Cover edge cases and near-miss cases.
Keep prompts substantive enough to require skill usage.

9) Evaluation loop (practical)

When possible, compare:

With skill.
Baseline (without skill or previous version).

Evaluate:

Qualitative quality (clarity, utility, correctness).
Quantitative checks (assertions that are objectively verifiable).
Efficiency signals (time/tokens when available).

Then:

Identify failure patterns.
Revise skill instructions/support files.
Re-run evals in a new iteration.

10) Description optimization loop

For better trigger accuracy:

Build mixed trigger evals (should-trigger and should-not-trigger).
Test current description repeatedly.
Refine description based on misses and false positives.
Re-test on held-out cases.

Use tricky near-misses, not obviously unrelated negatives.

11) Safety and “lack of surprise”

Skill behavior must match user intent and must be safe.

Never include:

Malware/exploit behavior.
Misleading instructions for unauthorized access or data exfiltration.

Skill content should be predictable from the skill’s description and purpose.

12) Packaging and distribution in this repo

Once a skill is ready:

python3 script/package_skills.py

Generated artifacts:

package/per-skill/skill/<skill-name>.skill
package/per-skill/zip/<skill-name>.zip
package/bundles/mechanical-skills-collection.zip
package/PACKAGES_INDEX.md (validation summary, warnings, skipped items)

A skill is skipped by the packager if:

SKILL.md is missing.
YAML frontmatter is invalid.
name or description is missing.

13) Quick quality checklist before publish

Frontmatter has name and description.
Description clearly states trigger contexts.
SKILL.md has objective, workflow, output format, quality gates.
Support files are referenced and purposeful.
Evals include realistic and edge-case prompts.
Packaging passes and index shows no unexpected skips/warnings.

Import in Claude

Single import: upload a file from package/per-skill/skill/ (or package/per-skill/zip/).
Internal distribution: use the mechanical-skills-collection.zip bundle.

Operational Notes

Source skills live in skill/.
Files in package/ are generated artifacts.

License

This project is released under the MIT License. See LICENSE.

References

Claude Skills page: https://claude.ai/customize/skills
Claude Code Skills docs: https://docs.anthropic.com/en/docs/claude-code/skills

README.md Unescape Escape

Mechanical Engineering Skills Hub

Goal

Repository Structure

Packaging

Package folder definitions