From 797fa9f117fc1b9003940a2316c1df17ade8b485 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Thu, 19 Mar 2026 15:05:58 +0100 Subject: [PATCH] docs(readme): rename repo and add detailed Claude-style skill authoring guide --- README.md | 247 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 246 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2db4a5a..53f93e5 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# CEV Skills for Claude Code +# 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. @@ -25,6 +25,247 @@ Main outputs: - `package/bundles/mechanical-skills-collection.zip` - `package/PACKAGES_INDEX.md` +### Package folder definitions +- `package/per-skill/` + - Contains one package per skill in both formats (`.skill` and `.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 `.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.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/` + - Validation report in `package/PACKAGES_INDEX.md` +6. Import into Claude: + - Upload `package/per-skill/my-new-skill.skill` (or `.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: +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 .” + +### 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` +- `package/per-skill/.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/`. - Internal distribution: use the `mechanical-skills-collection.zip` bundle. @@ -35,3 +276,7 @@ Main outputs: ## 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