skills-hub/README.md

# Mechanical Engineering Skills Hub

Support repository for office use of Claude Code, with ready-to-import skills to solve mechanical design and materials engineering questions.

## Goal
- Provide modular skills (`SKILL.md`) for real engineering workflows.
- Make Claude import easy through `.skill` and `.zip` packages.
- Keep a single, versioned source of truth for skills, test prompts, and exports.

## Repository Structure
- `skill/`: skill sources (one folder per skill, each with `SKILL.md`).
- `script/`: automation tools (packaging and utilities).
- `package/`: generated outputs (`per-skill/`, `bundles/`, package index).

## Packaging
Generate import-ready packages for all skills:

```bash
python3 script/package_skills.py
```

Main outputs:
- `package/per-skill/skill/<skill-name>.skill`
- `package/per-skill/zip/<skill-name>.zip`
- `package/bundles/mechanical-skills-collection.zip`
- [`package/PACKAGES_INDEX.md`](package/PACKAGES_INDEX.md)

### Package folder definitions
- `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
1. Create a new folder under `skill/`:
   - Example: `skill/my-new-skill/`
2. Add `SKILL.md` inside that folder.
3. Ensure `SKILL.md` has YAML frontmatter with at least:
   - `name: my-new-skill`
   - `description: ...`
4. Run packaging:

```bash
python3 script/package_skills.py
```

5. Check results:
   - Per-skill package files in `package/per-skill/skill/` and `package/per-skill/zip/`
   - Validation report in [`package/PACKAGES_INDEX.md`](package/PACKAGES_INDEX.md)
6. 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`](package/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:
1. Define intent and boundaries.
2. Draft the skill.
3. Create realistic test prompts.
4. Run tests (with-skill and baseline where possible).
5. Evaluate outputs qualitatively and quantitatively.
6. Improve the skill based on evidence.
7. Repeat until stable.
8. 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:
```text
skill/my-skill/
└── SKILL.md
```

Recommended for medium/complex skills:
```text
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:

```md
---
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 <keyword>.”

### 5) Progressive disclosure (context efficiency)
Use a 3-layer design:
1. Metadata (`name`, `description`) always available.
2. `SKILL.md` body loaded when triggered.
3. 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
```md
---
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:
```json
{
  "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:
1. Identify failure patterns.
2. Revise skill instructions/support files.
3. Re-run evals in a new iteration.

### 10) Description optimization loop
For better trigger accuracy:
1. Build mixed trigger evals (should-trigger and should-not-trigger).
2. Test current description repeatedly.
3. Refine description based on misses and false positives.
4. 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:
```bash
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`](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