diff --git a/resources/example-skills/pptx/SKILL.md b/resources/example-skills/pptx/SKILL.md index df5000e17..14f12cfb0 100644 --- a/resources/example-skills/pptx/SKILL.md +++ b/resources/example-skills/pptx/SKILL.md @@ -162,36 +162,6 @@ If grep returns results, fix them before declaring success. ### Visual QA -**⚠️ USE SUBAGENTS** — even for 2-3 slides. You've been staring at the code and will see what you expect, not what's there. Subagents have fresh eyes. - -Convert slides to images (see [Converting to Images](#converting-to-images)), then use this prompt: - -``` -Visually inspect these slides. Assume there are issues — find them. - -Look for: -- Overlapping elements (text through shapes, lines through words, stacked elements) -- Text overflow or cut off at edges/box boundaries -- Decorative lines positioned for single-line text but title wrapped to two lines -- Source citations or footers colliding with content above -- Elements too close (< 0.3" gaps) or cards/sections nearly touching -- Uneven gaps (large empty area in one place, cramped in another) -- Insufficient margin from slide edges (< 0.5") -- Columns or similar elements not aligned consistently -- Low-contrast text (e.g., light gray text on cream-colored background) -- Low-contrast icons (e.g., dark icons on dark backgrounds without a contrasting circle) -- Text boxes too narrow causing excessive wrapping -- Leftover placeholder content - -For each slide, list issues or areas of concern, even if minor. - -Read and analyze these images: -1. /path/to/slide-01.jpg (Expected: [brief description]) -2. /path/to/slide-02.jpg (Expected: [brief description]) - -Report ALL issues found, including minor ones. -``` - ### Verification Loop 1. Generate slides → Convert to images → Inspect diff --git a/resources/example-skills/pptx/editing.md b/resources/example-skills/pptx/editing.md index f873e8a04..a058180c1 100644 --- a/resources/example-skills/pptx/editing.md +++ b/resources/example-skills/pptx/editing.md @@ -28,14 +28,14 @@ When using an existing presentation as a template: 3. **Unpack**: `python scripts/office/unpack.py template.pptx unpacked/` -4. **Build presentation** (do this yourself, not with subagents): +4. **Build presentation:** - Delete unwanted slides (remove from ``) - Duplicate slides you want to reuse (`add_slide.py`) - Reorder slides in `` - **Complete all structural changes before step 5** 5. **Edit content**: Update text in each `slide{N}.xml`. - **Use subagents here if available** — slides are separate XML files, so subagents can edit in parallel. + — slides are separate XML files. 6. **Clean**: `python scripts/clean.py unpacked/` @@ -112,16 +112,6 @@ Slide order is in `ppt/presentation.xml` → ``. ## Editing Content -**Subagents:** If available, use them here (after completing step 4). Each slide is a separate XML file, so subagents can edit in parallel. In your prompt to subagents, include: -- The slide file path(s) to edit -- **"Use the Edit tool for all changes"** -- The formatting rules and common pitfalls below - -For each slide: -1. Read the slide's XML -2. Identify ALL placeholder content—text, images, charts, icons, captions -3. Replace each placeholder with final content - **Use the Edit tool, not sed or Python scripts.** The Edit tool forces specificity about what to replace and where, yielding better reliability. ### Formatting Rules diff --git a/resources/example-skills/skill-creator/SKILL.md b/resources/example-skills/skill-creator/SKILL.md index 158979709..990a1de4a 100644 --- a/resources/example-skills/skill-creator/SKILL.md +++ b/resources/example-skills/skill-creator/SKILL.md @@ -1,7 +1,7 @@ --- name: skill-creator -description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations. -license: Complete terms in LICENSE.txt +description: Guide for creating effective skills. Use when creating a new skill or updating an existing skill that extends agent capabilities with specialized knowledge, workflows, or tool integrations. +license: Proprietary. LICENSE.txt has complete terms --- # Skill Creator @@ -10,9 +10,9 @@ This skill provides guidance for creating effective skills. ## About Skills -Skills are modular, self-contained packages that extend Claude's capabilities by providing +Skills are modular, self-contained packages that extend agent capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific -domains or tasks—they transform Claude from a general-purpose agent into a specialized agent +domains or tasks—they transform a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess. ### What Skills Provide @@ -26,9 +26,9 @@ equipped with procedural knowledge that no model can fully possess. ### Concise is Key -The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request. +The context window is a public good. Skills share the context window with everything else the agent needs: system prompt, conversation history, other Skills' metadata, and the actual user request. -**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?" +**Default assumption: The agent is already very capable.** Only add context the agent doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" and "Does this paragraph justify its token cost?" Prefer concise examples over verbose explanations. @@ -42,7 +42,7 @@ Match the level of specificity to the task's fragility and variability: **Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed. -Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom). +Think of the agent exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom). ### Anatomy of a Skill @@ -66,7 +66,7 @@ skill-name/ Every SKILL.md consists of: -- **Frontmatter** (YAML): Contains `name` and `description` fields (required), plus optional fields like `license`, `metadata`, and `compatibility`. Only `name` and `description` are read by Claude to determine when the skill triggers, so be clear and comprehensive about what the skill is and when it should be used. The `compatibility` field is for noting environment requirements (target product, system packages, etc.) but most skills don't need it. +- **Frontmatter** (YAML): Contains `name` and `description` fields (required), plus optional fields like `license`, `metadata`, and `compatibility`. Only `name` and `description` are read by the agent to determine when the skill triggers, so be clear and comprehensive about what the skill is and when it should be used. The `compatibility` field is for noting environment requirements (target product, system packages, etc.) but most skills don't need it. - **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all). #### Bundled Resources (optional) @@ -78,27 +78,27 @@ Executable code (Python/Bash/etc.) for tasks that require deterministic reliabil - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks - **Benefits**: Token efficient, deterministic, may be executed without loading into context -- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments +- **Note**: Scripts may still need to be read by the agent for patching or environment-specific adjustments ##### References (`references/`) -Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. +Documentation and reference material intended to be loaded as needed into context to inform the agent's process and thinking. -- **When to include**: For documentation that Claude should reference while working +- **When to include**: For documentation that the agent should reference while working - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides -- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed +- **Benefits**: Keeps SKILL.md lean, loaded only when the agent determines it's needed - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. ##### Assets (`assets/`) -Files not intended to be loaded into context, but rather used within the output Claude produces. +Files not intended to be loaded into context, but rather used within the output the agent produces. - **When to include**: When the skill needs files that will be used in the final output - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified -- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context +- **Benefits**: Separates output resources from documentation, enables the agent to use files without loading them into context #### What to Not Include in a Skill @@ -118,7 +118,7 @@ Skills use a three-level loading system to manage context efficiently: 1. **Metadata (name + description)** - Always in context (~100 words) 2. **SKILL.md body** - When skill triggers (<5k words) -3. **Bundled resources** - As needed by Claude (Unlimited because scripts can be executed without reading into context window) +3. **Bundled resources** - As needed by the agent (Unlimited because scripts can be executed without reading into context window) #### Progressive Disclosure Patterns @@ -143,7 +143,7 @@ Extract text with pdfplumber: - **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns ``` -Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed. +The agent loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed. **Pattern 2: Domain-specific organization** @@ -159,7 +159,7 @@ bigquery-skill/ └── marketing.md (campaigns, attribution) ``` -When a user asks about sales metrics, Claude only reads sales.md. +When a user asks about sales metrics, the agent only reads sales.md. Similarly, for skills supporting multiple frameworks or variants, organize by variant: @@ -172,7 +172,7 @@ cloud-deploy/ └── azure.md (Azure deployment patterns) ``` -When the user chooses AWS, Claude only reads aws.md. +When the user chooses AWS, the agent only reads aws.md. **Pattern 3: Conditional details** @@ -193,12 +193,12 @@ For simple edits, modify the XML directly. **For OOXML details**: See [OOXML.md](OOXML.md) ``` -Claude reads REDLINING.md or OOXML.md only when the user needs those features. +The agent reads REDLINING.md or OOXML.md only when the user needs those features. **Important guidelines:** - **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md. -- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing. +- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so the agent can see the full scope when previewing. ## Skill Creation Process @@ -262,12 +262,14 @@ Skip this step only if the skill being developed already exists, and iteration o When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. -Usage: +Usage (run from the skill-creator skill directory): ```bash -scripts/init_skill.py --path +python scripts/init_skill.py --path ``` +Note: The scripts are located in this skill's `scripts/` directory. Use the full path if running from a different directory. + The script: - Creates the skill directory at the specified path @@ -279,7 +281,7 @@ After initialization, customize or remove the generated SKILL.md and example fil ### Step 4: Edit the Skill -When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively. +When editing the (newly-generated or existing) skill, remember that the skill is being created for an agent to use. Include information that would be beneficial and non-obvious to the agent. Consider what procedural knowledge, domain-specific details, or reusable assets would help the agent execute these tasks more effectively. #### Learn Proven Design Patterns @@ -307,10 +309,10 @@ Any example files and directories not needed for the skill should be deleted. Th Write the YAML frontmatter with `name` and `description`: - `name`: The skill name -- `description`: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill. +- `description`: This is the primary triggering mechanism for your skill, and helps the agent understand when to use the skill. - Include both what the Skill does and specific triggers/contexts for when to use it. - - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude. - - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks" + - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to the agent. + - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when the agent needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks" Do not include any other fields in YAML frontmatter. @@ -320,22 +322,25 @@ Write instructions for using the skill and its bundled resources. ### Step 5: Packaging a Skill -Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements: +Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements. + +Usage (run from the skill-creator skill directory): ```bash -scripts/package_skill.py +python scripts/package_skill.py ``` Optional output directory specification: ```bash -scripts/package_skill.py ./dist +python scripts/package_skill.py ./dist ``` +Note: The scripts are located in this skill's `scripts/` directory. Use the full path if running from a different directory. + The packaging script will: 1. **Validate** the skill automatically, checking: - - YAML frontmatter format and required fields - Skill naming conventions and directory structure - Description completeness and quality diff --git a/resources/example-skills/skill-creator/references/output-patterns.md b/resources/example-skills/skill-creator/references/output-patterns.md index 073ddda5f..4b1fc6e31 100644 --- a/resources/example-skills/skill-creator/references/output-patterns.md +++ b/resources/example-skills/skill-creator/references/output-patterns.md @@ -79,4 +79,4 @@ Use UTC timestamps consistently across report generation Follow this style: type(scope): brief description, then detailed explanation. ``` -Examples help Claude understand the desired style and level of detail more clearly than descriptions alone. +Examples help the agent understand the desired style and level of detail more clearly than descriptions alone. diff --git a/resources/example-skills/skill-creator/references/workflows.md b/resources/example-skills/skill-creator/references/workflows.md index a350c3cc8..615bb5cbe 100644 --- a/resources/example-skills/skill-creator/references/workflows.md +++ b/resources/example-skills/skill-creator/references/workflows.md @@ -2,7 +2,7 @@ ## Sequential Workflows -For complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md: +For complex tasks, break operations into clear, sequential steps. It is often helpful to give the agent an overview of the process towards the beginning of SKILL.md: ```markdown Filling a PDF form involves these steps: @@ -16,7 +16,7 @@ Filling a PDF form involves these steps: ## Conditional Workflows -For tasks with branching logic, guide Claude through decision points: +For tasks with branching logic, guide the agent through decision points: ```markdown 1. Determine the modification type: diff --git a/resources/example-skills/skill-creator/scripts/init_skill.py b/resources/example-skills/skill-creator/scripts/init_skill.py index 2f666a12e..ee46c197a 100755 --- a/resources/example-skills/skill-creator/scripts/init_skill.py +++ b/resources/example-skills/skill-creator/scripts/init_skill.py @@ -89,20 +89,20 @@ Executable code (Python/Bash/etc.) that can be run directly to perform specific **Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations. -**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments. +**Note:** Scripts may be executed without loading into context, but can still be read by the agent for patching or environment adjustments. ### references/ -Documentation and reference material intended to be loaded into context to inform Claude's process and thinking. +Documentation and reference material intended to be loaded into context to inform the agent's process and thinking. **Examples from other skills:** - Product management: `communication.md`, `context_building.md` - detailed workflow guides - BigQuery: API reference documentation and query examples - Finance: Schema documentation, company policies -**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working. +**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that the agent should reference while working. ### assets/ -Files not intended to be loaded into context, but rather used within the output Claude produces. +Files not intended to be loaded into context, but rather used within the output the agent produces. **Examples from other skills:** - Brand styling: PowerPoint template files (.pptx), logo files @@ -179,7 +179,7 @@ This placeholder represents where asset files would be stored. Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed. Asset files are NOT intended to be loaded into context, but rather used within -the output Claude produces. +the output the agent produces. Example asset files from other skills: - Brand guidelines: logo.png, slides_template.pptx