From 1fd77b645737a478e4acc59567dc3ccda630228b Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Mon, 23 Mar 2026 09:50:41 +0100 Subject: [PATCH] initial commit --- .gitignore | 25 ++ ANTHROPIC-SKILLS-DOCS.md | 524 +++++++++++++++++++++++++++++++++++++++ README.md | 69 ++++++ compress-skills.sh | 37 +++ 4 files changed, 655 insertions(+) create mode 100644 .gitignore create mode 100644 ANTHROPIC-SKILLS-DOCS.md create mode 100644 README.md create mode 100755 compress-skills.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..68f05d3 --- /dev/null +++ b/.gitignore @@ -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 diff --git a/ANTHROPIC-SKILLS-DOCS.md b/ANTHROPIC-SKILLS-DOCS.md new file mode 100644 index 0000000..90f8cca --- /dev/null +++ b/ANTHROPIC-SKILLS-DOCS.md @@ -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 +
+Python < 3.10 (deprecated) +[old approach] +
+``` + +--- + +## 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 | diff --git a/README.md b/README.md new file mode 100644 index 0000000..9b589c0 --- /dev/null +++ b/README.md @@ -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.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: + +``` +/ [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) diff --git a/compress-skills.sh b/compress-skills.sh new file mode 100755 index 0000000..6aa40fd --- /dev/null +++ b/compress-skills.sh @@ -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/"