davide/engineering-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
Davide Grilli
2026-03-23 09:50:41 +01:00
commit 1fd77b6457
4 changed files with 655 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+25
View File
@@ -0,0 +1,25 @@
# Generated zip packages
dist/
# Operating system
.DS_Store
Thumbs.db
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
*.egg-info/
.venv/
venv/
# Editors
.vscode/
.idea/
*.swp
*.swo
# Claude Code local settings (not versioned)
.claude/settings.local.json
ANTHROPIC-SKILLS-DOCS.md
+524
View File
@@ -0,0 +1,524 @@
# Anthropic Agent Skills — Reference Documentation
> Extracted from official Anthropic documentation — March 2026.
> **Primary target: [claude.ai](https://claude.ai)** (Pro, Max, Team, Enterprise plans with code execution enabled).
> Sources: [Agent Skills Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) · [Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) · [Help Center — Creating custom Skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
---
## Table of contents
1. [What are Skills?](#1-what-are-skills)
2. [How Skills work — Progressive disclosure](#2-how-skills-work--progressive-disclosure)
3. [Skill structure](#3-skill-structure)
4. [SKILL.md format and frontmatter](#4-skillmd-format-and-frontmatter)
5. [How to upload a Skill to claude.ai](#5-how-to-upload-a-skill-to-claudeai)
6. [Runtime environment on claude.ai](#6-runtime-environment-on-claudeai)
7. [Authoring best practices](#7-authoring-best-practices)
8. [Common patterns](#8-common-patterns)
9. [Workflows and feedback loops](#9-workflows-and-feedback-loops)
10. [Security considerations](#10-security-considerations)
11. [Limitations on claude.ai](#11-limitations-on-claudeai)
12. [Pre-built Agent Skills](#12-pre-built-agent-skills)
13. [Troubleshooting](#13-troubleshooting)
---
## 1. What are Skills?
Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates, reference files) that Claude uses automatically when relevant.
**Key benefits:**
- **Specialize Claude**: Tailor capabilities for domain-specific tasks
- **Reduce repetition**: Create once, use automatically across conversations
- **Compose capabilities**: Combine Skills to build complex workflows
Unlike prompts (one-off conversation instructions), Skills load on-demand and eliminate the need to repeatedly provide the same guidance.
**On claude.ai**, both pre-built and custom Skills are available. Pre-built Skills (PowerPoint, Excel, Word, PDF) work out of the box. Custom Skills are uploaded as `.zip` files and are available to the uploading user only.
---
## 2. How Skills work — Progressive disclosure
Skills load in three stages. Only relevant content occupies the context window at any time.
### Level 1 — Metadata (always loaded, ~100 tokens per Skill)
The YAML frontmatter (`name` + `description`) is pre-loaded at startup into the system prompt. Claude knows the Skill exists and when to use it — zero token cost until triggered.
### Level 2 — Instructions (loaded when triggered, < 5k tokens)
The body of `SKILL.md` is read from the filesystem when the Skill becomes relevant. This contains procedural knowledge: workflows, best practices, guidance.
### Level 3 — Resources (loaded as needed, no practical limit)
Supporting files live on the filesystem and are read only when Claude needs them. Scripts are **executed** via bash; only the output enters the context window — the script code itself never consumes tokens.
| Level | When loaded | Token cost | Content |
|-------|-------------|------------|---------|
| 1: Metadata | Always (startup) | ~100 tokens / Skill | `name` and `description` from YAML frontmatter |
| 2: Instructions | When Skill is triggered | < 5k tokens | `SKILL.md` body |
| 3: Resources | As needed | Effectively unlimited | Bundled files and scripts |
### Example: loading a Skill
1. **Startup** — system prompt includes: `PDF Processing — Extract text and tables from PDF files`
2. **User request** — "Extract the text from this PDF"
3. **Claude reads** `pdf-skill/SKILL.md` → instructions loaded into context
4. **Claude determines** form filling is not needed → `FORMS.md` is not read
5. **Claude executes** the task using `SKILL.md` instructions
---
## 3. Skill structure
Every Skill is a directory with `SKILL.md` as the required entrypoint.
```text
my-skill/
├── SKILL.md # Required — main instructions
├── reference.md # Optional — detailed reference docs
├── examples.md # Optional — usage examples
└── scripts/
├── analyze.py # Optional — utility scripts (executed, not loaded)
└── validate.py
```
**Pattern: domain-specific organization** (for complex Skills)
```text
my-skill/
├── SKILL.md # Overview and navigation
└── reference/
├── topic-a.md
├── topic-b.md
└── topic-c.md
```
When uploaded to claude.ai, the entire directory is zipped and uploaded as a single `.zip` file.
---
## 4. SKILL.md format and frontmatter
Every `SKILL.md` starts with YAML frontmatter between `---` markers.
### Minimal working example
```yaml
---
name: mechanical-calculations
description: Performs structural calculations, stress analysis, fatigue checks, and beam theory. Use when the user asks for mechanical engineering calculations, sizing of components, or structural verification.
---
# Mechanical Calculations
## Quick start
[Step-by-step instructions for Claude to follow...]
```
### Frontmatter fields
| Field | Required | Description |
|-------|----------|-------------|
| `name` | No* | Slash command name. Lowercase letters, numbers, hyphens only. Max 64 chars. If omitted, uses directory name. |
| `description` | **Recommended** | What the Skill does and when to use it. Max 1024 chars. Critical for automatic discovery. |
| `argument-hint` | No | Hint shown during autocomplete. Example: `[component] [load]` |
| `disable-model-invocation` | No | `true` = only the user can invoke manually. Default: `false` |
| `user-invocable` | No | `false` = hidden from the `/` menu (Claude-only). Default: `true` |
> **Note:** Fields `context`, `agent`, `hooks`, `effort`, `allowed-tools`, and string substitutions like `$ARGUMENTS` are **Claude Code features only** and have no effect on claude.ai.
### Validation rules
**`name`:**
- Maximum 64 characters
- Lowercase letters, numbers, and hyphens only
- No XML tags
- Cannot contain the reserved words `anthropic` or `claude`
**`description`:**
- Must be non-empty
- Maximum 1024 characters
- No XML tags
- Always write in **third person** (it is injected into the system prompt)
### Invocation control
| Frontmatter | User can invoke (`/name`) | Claude auto-invokes | Description in context |
|-------------|--------------------------|---------------------|------------------------|
| (default) | Yes | Yes | Always present |
| `disable-model-invocation: true` | Yes | No | Not pre-loaded |
| `user-invocable: false` | No | Yes | Always present |
### Writing effective descriptions
The description is the **only** signal Claude uses to decide whether to trigger a Skill. Make it specific.
**Good:**
```yaml
description: Performs stress analysis, fatigue calculations, and beam theory for mechanical components. Use when the user mentions stress, load, fatigue, section modulus, or asks to verify a mechanical design.
```
**Bad:**
```yaml
description: Helps with mechanical engineering
```
Rules:
- Write in **third person** ("Performs…", not "I can…" or "You can…")
- Include **what** the Skill does
- Include **when** to use it (list key trigger words)
- Be specific — Claude may have 100+ Skills loaded
---
## 5. How to upload a Skill to claude.ai
### Step 1 — Build the Skill directory
```text
my-skill/
├── SKILL.md
├── reference/
│ └── guide.md
└── scripts/
└── helper.py
```
### Step 2 — Create the .zip
```bash
zip -r my-skill.zip my-skill/ -x "*.DS_Store" -x "*__pycache__*"
```
Or use the `compress-skills.sh` script in this repository:
```bash
./compress-skills.sh
# Output: dist/my-skill.zip
```
### Step 3 — Upload to claude.ai
1. Go to [claude.ai](https://claude.ai) → **Settings**
2. Navigate to **Features** → **Skills**
3. Click **Upload skill** and select the `.zip` file
4. Repeat for each Skill
### Step 4 — Use the Skill
In any conversation, invoke with a slash command:
```
/my-skill [optional description of the problem]
```
Or simply describe your problem — Claude will trigger the Skill automatically if it matches the description.
### Requirements
- Plan: **Pro, Max, Team, or Enterprise** with code execution enabled
- Max upload size: **8 MB** per `.zip`
- The `.zip` must contain `SKILL.md` at the top level of the skill folder
---
## 6. Runtime environment on claude.ai
On claude.ai, Skills run in a **code execution container** (virtual machine) with:
| Capability | Status on claude.ai |
|-----------|---------------------|
| Network access | Varies — depends on user/admin settings (may be full, partial, or none) |
| Package installation | Allowed: npm (Node.js), PyPI (Python), GitHub repositories |
| Filesystem access | Yes — Claude can read/write files within the container |
| Bash execution | Yes — scripts are executed via bash |
**Important:** Scripts can install packages at runtime (unlike the Claude API, which has no network access). Declare all dependencies explicitly in your `SKILL.md` so Claude installs them before use.
```markdown
## Dependencies
Install before use:
```bash
pip install pdfplumber pandas
```
```
---
## 7. Authoring best practices
### Be concise — context is shared
Only add context Claude doesn't already have. Challenge every line: "Does Claude really need this?"
**Good (~50 tokens):**
```markdown
## Extract PDF text
Use pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
```
**Bad (~150 tokens):**
```markdown
## Extract PDF text
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing...
```
### Set appropriate degrees of freedom
| Constraint level | When to use | How |
|-----------------|-------------|-----|
| **High freedom** | Multiple valid approaches, context-dependent | Text instructions with guidelines |
| **Medium freedom** | Preferred pattern exists, some variation OK | Pseudocode or templates |
| **Low freedom** | Fragile operations, consistency critical | Exact scripts with no parameters |
### Naming conventions
Prefer gerund form (verb + -ing) or noun phrases:
- `processing-pdfs`, `analyzing-data`, `calculating-stress`
- `pdf-processing`, `stress-analysis`, `material-selection`
- **Avoid:** `helper`, `utils`, `tools`, anything containing `anthropic` or `claude`
### Progressive disclosure
- Keep `SKILL.md` body **under 500 lines**
- Move detailed content to supporting files, referenced from `SKILL.md`
- Keep references **one level deep** — avoid chains (SKILL.md → a.md → b.md)
- Add a **table of contents** to reference files longer than 100 lines
```markdown
## Additional resources
- Complete formula reference → [reference/formulas.md](reference/formulas.md)
- Material properties database → [reference/materials.md](reference/materials.md)
- Worked examples → [examples.md](examples.md)
```
### Use consistent terminology
Choose one term and use it throughout:
- Always "stress" (not stress/tension/load interchangeably)
- Always "section modulus" (not section modulus/Z/W)
- Always "yield strength" (not yield strength/Rp0.2/Sy)
### Avoid time-sensitive information
**Bad:**
```markdown
If you're using Python before 3.10, use the old syntax.
```
**Good:**
```markdown
## Current method
[current approach]
## Legacy patterns
<details>
<summary>Python < 3.10 (deprecated)</summary>
[old approach]
</details>
```
---
## 8. Common patterns
### Pattern 1 — High-level guide with references
```yaml
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDFs, forms, or document extraction.
---
# PDF Processing
## Quick start
[...basic extraction code here...]
## Advanced features
- Form filling → [FORMS.md](FORMS.md)
- API reference → [REFERENCE.md](REFERENCE.md)
- Examples → [EXAMPLES.md](EXAMPLES.md)
```
### Pattern 2 — Domain-specific routing
```yaml
---
name: engineering-data
description: Provides material properties, standards, and formulas for mechanical engineering. Use when the user asks for material data, ISO/ASME standards, or engineering constants.
---
# Engineering Reference Data
## Available datasets
- **Materials** → [reference/materials.md](reference/materials.md)
- **Standards (ISO/ASME/DIN)** → [reference/standards.md](reference/standards.md)
- **Formulas** → [reference/formulas.md](reference/formulas.md)
```
### Pattern 3 — Conditional routing
```markdown
## Workflow
**New document?** → Follow "Creation workflow" below
**Editing existing?** → Follow "Editing workflow" below
```
### Template pattern
```markdown
## Report structure
Use this template:
```markdown
# [Analysis Title]
## Executive summary
[One-paragraph overview]
## Key findings
- Finding 1
- Finding 2
## Recommendations
1. Action item
```
```
### Examples pattern (input/output pairs)
```markdown
## Output format
**Example 1:**
Input: Calculate stress in M10 bolt with 5 kN axial load
Output:
```
Bolt M10 — Axial stress analysis
Tensile stress area: As = 58.0 mm²
Applied force: F = 5000 N
Nominal stress: σ = F/As = 86.2 MPa
Yield strength (8.8): Rp0.2 = 640 MPa
Safety factor: SF = 640/86.2 = 7.4 ✓
```
```
---
## 9. Workflows and feedback loops
### Workflow checklist pattern
Provide a checklist Claude copies into its response and checks off:
```markdown
## Verification workflow
Copy and track:
```
Progress:
- [ ] Step 1: Identify loads and boundary conditions
- [ ] Step 2: Select calculation method
- [ ] Step 3: Perform calculations
- [ ] Step 4: Check against allowable limits
- [ ] Step 5: State safety factor and conclusion
```
```
### Feedback loop pattern
```markdown
## Calculation review process
1. Perform calculations
2. **Check immediately**: verify units are consistent throughout
3. If inconsistency found:
- Identify the conversion error
- Correct and recalculate
4. **Only present results when all checks pass**
5. State assumptions and references used
```
### Plan-validate-execute pattern
For complex tasks with many steps:
1. Create an intermediate plan/mapping file
2. Validate the plan with a script or manual check
3. Execute only after validation passes
4. Verify the output
---
## 10. Security considerations
- **Only use Skills from trusted sources** — yourself or Anthropic
- **Audit all bundled files** before use: `SKILL.md`, all scripts, all reference files
- **Skills that fetch external URLs are high risk** — fetched content may contain malicious instructions
- **Treat like installing software** — malicious Skills can misuse file operations, bash, code execution, or exfiltrate data
> If you must use a Skill from an unknown source, thoroughly audit it before uploading. Malicious Skills could lead to data exfiltration or unauthorized operations.
---
## 11. Limitations on claude.ai
| Constraint | Detail |
|-----------|--------|
| Availability | Pro, Max, Team, Enterprise plans with code execution enabled |
| Sharing scope | **Per-user only** — each user must upload their own copy; no org-wide distribution |
| Cross-surface sync | Skills uploaded to claude.ai are **not** available via the API, and vice versa |
| Max zip size | 8 MB |
| Network access | Varies by user/admin settings |
| Advanced frontmatter | Fields `context`, `agent`, `hooks`, `effort`, string substitutions (`$ARGUMENTS`, `${CLAUDE_SKILL_DIR}`) are **Claude Code only** — ignored on claude.ai |
---
## 12. Pre-built Agent Skills
Available on claude.ai for all users with code execution — no setup required:
| Skill | Capability |
|-------|-----------|
| **PowerPoint** | Create presentations, edit slides, analyze content |
| **Excel** | Create spreadsheets, analyze data, generate charts |
| **Word** | Create and edit documents, format text |
| **PDF** | Generate formatted PDF documents and reports |
These Skills activate automatically when you ask Claude to create or edit the corresponding file type.
---
## 13. Troubleshooting
| Problem | Solution |
|---------|----------|
| Skill not triggering automatically | Check description includes natural-language keywords; try `/skill-name` directly |
| Skill triggers too often | Make description more specific; add `disable-model-invocation: true` |
| Upload fails | Verify `SKILL.md` is at the top level of the folder inside the zip; check zip is < 8 MB |
| Script error: package not found | Declare all dependencies in `SKILL.md`; claude.ai can install from PyPI/npm at runtime |
| Many Skills loaded but some ignored | Descriptions are capped at ~2% of context window; shorten existing descriptions |
README.md
+69
View File
@@ -0,0 +1,69 @@
# Claude Skills — Mechanical Design Engineer
A collection of **custom skills for Claude.ai** that transform the assistant into an expert mechanical design engineer with 20+ years of experience.
## Repository structure
```
skills-claude/
├── README.md
├── compress-skills.sh # Script to generate .zip packages
└── <skill-name>/
├── SKILL.md # Main instructions (YAML frontmatter + markdown)
├── reference/ # Technical reference documentation
│ └── *.md
└── scripts/ # Executable helper scripts
└── *.py / *.sh
```
## How to install skills on Claude.ai
### 1. Generate .zip files
```bash
chmod +x compress-skills.sh
./compress-skills.sh
```
The `.zip` files are created in the `dist/` folder.
### 2. Upload to Claude.ai
1. Go to [claude.ai](https://claude.ai) → **Settings**
2. Section **Features** → **Skills**
3. Click **Upload skill** and upload each `.zip` file from `dist/`
4. Repeat for every skill
### 3. Use the skills
Invoke skills with a slash command in chat:
```
/<skill-name> [problem description]
```
## Skill format (Anthropic spec)
The `SKILL.md` file contains:
- **YAML frontmatter** with `name`, `description`, `user-invocable`
- **Markdown instructions** that define Claude's behaviour
```yaml
---
name: skill-name
description: What this skill does and when to invoke it
user-invocable: true
argument-hint: [optional argument]
---
# Skill Title
[Detailed instructions in markdown]
```
## References
- [ANTHROPIC-SKILLS-DOCS.md](ANTHROPIC-SKILLS-DOCS.md) — full reference extracted from official docs (structure, frontmatter, best practices, API)
- [Anthropic Skills Documentation](https://code.claude.com/docs/en/skills)
- [Agent Skills API](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Skill Authoring Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
compress-skills.sh
Executable
+37
View File
@@ -0,0 +1,37 @@
#!/bin/bash
# compress-skills.sh
# Compresses each skill folder into a separate .zip file inside dist/
set -e
DIST_DIR="dist"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
echo "==> Creating $DIST_DIR directory..."
mkdir -p "$SCRIPT_DIR/$DIST_DIR"
# Iterate over all folders (excluding system and dist folders)
for skill_dir in "$SCRIPT_DIR"/*/; do
folder_name="$(basename "$skill_dir")"
# Skip excluded folders
if [[ "$folder_name" == "$DIST_DIR" || "$folder_name" == ".git" || "$folder_name" == ".claude" ]]; then
continue
fi
# Check that SKILL.md exists (valid skill folder)
if [[ ! -f "$skill_dir/SKILL.md" ]]; then
echo " [SKIP] $folder_name — no SKILL.md found"
continue
fi
zip_file="$SCRIPT_DIR/$DIST_DIR/${folder_name}.zip"
echo " [ZIP] $folder_name → $DIST_DIR/${folder_name}.zip"
# Create zip from repo root to preserve correct path structure
(cd "$SCRIPT_DIR" && zip -r "$zip_file" "$folder_name" -x "*.DS_Store" -x "*__pycache__*" -x "*.pyc")
done
echo ""
echo "==> Done. Files generated in $DIST_DIR/:"
ls -lh "$SCRIPT_DIR/$DIST_DIR/"