docs(readme): rename repo and add detailed Claude-style skill authoring guide
This commit is contained in:
247
README.md
247
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 `<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/`
|
||||
- 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 <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-name>.skill`
|
||||
- `package/per-skill/<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/`.
|
||||
- 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
|
||||
|
||||
Reference in New Issue
Block a user