initial commit

2026-03-23 09:50:41 +01:00
commit 1fd77b6457
4 changed files with 655 additions and 0 deletions
@@ -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
@@ -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 |
@@ -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)
@@ -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/"