Repository Overview

AGENTS.md

This file provides guidance to LLM Agents when working with code in this repository.

Repository Overview

This is a collection of Claude Skills - custom extensions that enhance Claude's capabilities through structured prompt engineering. Each skill is packaged as a directory containing a SKILL.md file with frontmatter metadata and optional supporting resources (scripts, references, assets).

Important Context: This repository is deprecated and read-only. Skills shown here demonstrate patterns but may reference environments/features that differ from the current Claude Code CLI environment you're running in. When working on skills, verify current environment capabilities rather than assuming the patterns shown here still apply.

Skills Availability in This Repository

This repository has project skills available via .claude/skills/ symlinks. However:

Environment-Specific Skills: Many skills are designed for specific Claude environments and may not be appropriate for all contexts. For example:

• invoking-github: Designed for Claude.ai chat (iOS/Android/Web) where native git access isn't available. NOT needed in Claude Code which has native git proxy access.
• Skills targeting specific file formats, APIs, or workflows may only be relevant in certain contexts
• Some skills assume environments with features that may not be present in Claude Code

Before Invoking a Skill:

1. Check with the user first before invoking any skill in this repository
2. Verify the skill is appropriate for the current environment (Claude Code vs Claude.ai chat)
3. Confirm the user wants to use the skill rather than native capabilities
4. Example: "I see you want to commit to GitHub. Should I use the invoking-github skill, or would you prefer I use native git commands since we're in Claude Code?"

Why Check First:

• Avoid redundant operations (using a skill when native tools work better)
• Prevent environment mismatches (claude.ai-only skills in Claude Code)
• Give users choice of approach
• Skills are for development/testing, not automatic invocation

Available Project Skills: Check .claude/skills/ for currently available skills in this session.

Repository Structure

claude-skills/
├── skill-name/              # Each directory = one skill
│   ├── SKILL.md            # Required: frontmatter + instructions to Claude
│   ├── scripts/            # Optional: executable code for deterministic operations
│   ├── references/         # Optional: detailed docs loaded on demand
│   └── assets/             # Optional: templates, files used in output
├── .uploads/               # Drop zone for .zip files (triggers automation)
└── .github/workflows/      # Automation for skill uploads
    └── skill-upload.yml

Key Principles

1. SKILL.md as interface: Each skill's SKILL.md contains YAML frontmatter (name, description) followed by imperative instructions written TO Claude, not documentation ABOUT Claude
2. Progressive disclosure: Keep SKILL.md concise (~500 lines max), move detailed content to references/
3. Naming convention: Use gerund form (e.g., creating-mcp-servers, processing-pdfs)
4. Token efficiency: Every line should justify its context window cost

Working with Skills

Developing or Modifying Existing Skills

When working on skills in this repository (not just using them):

Pre-flight Checklist:

1. Check for CLAUDE.md - If the skill directory contains a CLAUDE.md file, READ IT FIRST before any code execution. This file contains Claude Code-specific context, development patterns, and critical guidance.
2. Explore structure - Use ls -la skill-name/ to understand what files exist before importing or executing
3. Follow skill's own practices - If CLAUDE.md says "use this skill to develop itself", do that
4. Verify imports - Check for init.py location and symlink structure before running code

Example workflow:

# 1. Explore first
ls -la remembering/

# 2. Check for development docs
test -f remembering/CLAUDE.md && cat remembering/CLAUDE.md

# 3. Follow guidance in CLAUDE.md before executing
# 4. Use proper import paths (check symlinks!)

Why this matters: Skills like remembering contain meta-instructions about their own development. Skipping CLAUDE.md means missing critical context that prevents errors.

Creating a New Skill

Note: Skill creation typically happens in a skill development environment (using paths like /home/claude/, /mnt/user-data/outputs/, etc.) which differs from this repository checkout.

The conceptual workflow when creating skills:

1. Create skill directory structure:

   mkdir -p skill-name/{scripts,references,assets}
   

2. Create SKILL.md with required frontmatter:

   ---
   name: skill-name
   description: What it does. Use when [trigger patterns].
   ---
   

3. Add supporting resources to scripts/, references/, or assets/ as needed

4. Delete unused directories

5. Package as ZIP:

   cd /home/claude
   zip -r skill-name.zip skill-name/ -x "*.git*"
   

Uploading Skills (Automated Workflow)

When a .zip file is pushed to .uploads/:

1. GitHub Actions workflow skill-upload.yml is triggered
2. Validates skill structure (must contain SKILL.md at root)
3. Runs security checks (path traversal, blocked file types, zip bomb)
4. Extracts to root directory as skill-name/
5. Creates PR with changes
6. Deletes original .zip from .uploads/

Security validations:

• Path traversal detection
• Blocks executables/binaries (.exe, .dll, .so, .jar, nested archives)
• Max 1000 files per skill
• Scripts (.sh, .py, .js) are allowed as reviewable text

Skill Frontmatter Requirements

name:

• Lowercase letters, numbers, hyphens only
• Max 64 characters
• No reserved words (anthropic, claude)

description:

• Max 1024 characters
• Third person voice ("Processes files" not "I process files")
• Include WHAT it does and WHEN to use it (trigger patterns)
• No XML tags

Key Skills in This Repository

Meta-Skills (Skills for Creating Skills)

• crafting-instructions: Comprehensive guide for creating all instruction types (Project instructions, Skills, Standalone prompts). Includes skill creation workflow, structure, and patterns.
• versioning-skills: Git-based workflow for tracking changes during skill development
• asking-questions: When and how to ask clarifying questions during implementation

Domain-Specific Skills

• creating-mcp-servers: Build production-ready MCP servers using FastMCP v2 with progressive disclosure patterns
• creating-bookmarklets: Create browser bookmarklets
• developing-preact: Preact development patterns and guidance
• updating-knowledge: Patterns for updating Claude's knowledge through context
• hello-demo: Simple skill demonstrating asset delivery pattern
• check-tools: Tool checking utilities
• convening-experts: Pattern for multi-expert collaboration

Important Implementation Patterns

1. Progressive Disclosure

For skills with extensive content:

• Keep core workflow in SKILL.md
• Move detailed docs to references/ (loaded on-demand)
• Store output assets in assets/ (not loaded into context)

2. Skill.md Structure

---
name: skill-name
description: Brief description. Use when [triggers].
---

# Skill Title

When users request [trigger]:
1. [Action]
2. [Action]

## Workflow A

For [condition]:
- [Instruction]

## Advanced Topics

See [references/details.md](references/details.md) for...

3. Scripts Pattern

Add scripts/ when Claude would repeatedly write similar code:

• Validation logic
• Format transformations
• Complex deterministic operations

Scripts should have explicit error handling and no "magic numbers".

4. Token Efficiency

Challenge each line:

• Does Claude really need this explanation?
• Can I assume Claude knows this?
• Does this justify its token cost?

Prefer code examples over verbose explanations.

Git Workflow

This repository follows standard git practices:

# Create feature branch
git checkout -b feature-name

# Make changes
git add .
git commit -m "feat: description"

# Push
git push -u origin feature-name

# Create PR via GitHub UI or gh CLI
gh pr create --title "..." --body "..."

Common Tasks

Viewing a Skill's Structure

ls -R skill-name/

Testing SKILL.md Frontmatter

head -20 skill-name/SKILL.md  # Check first 20 lines for frontmatter

Finding Skills by Pattern

grep -r "pattern-name" */SKILL.md

Packaging Multiple Skills

for dir in skill-*/; do
  skill=$(basename "$dir")
  zip -r "${skill}.zip" "$dir" -x "*.git*"
done

Architecture Notes

Skill Discovery and Activation

The frontmatter description field is critical - it contains trigger patterns that help Claude decide when to activate a skill. The description should be specific about:

• File types that trigger it (.pptx, .pdf, etc.)
• Keywords (MCP, bookmarklet, etc.)
• Task types (creating, analyzing, optimizing, etc.)

Context Window Management

Skills are loaded progressively:

1. Metadata (name + description): Always loaded
2. SKILL.md body: Loaded when skill triggers
3. Bundled resources: Loaded as needed by Claude

This three-tier loading enables context-efficient skill ecosystems.

Validation and Quality

Before uploading a skill:

• Frontmatter validates (name/description requirements)
• SKILL.md under 500 lines (move extras to references/)
• Written in imperative voice (instructions TO Claude)
• No over-explanations of basic concepts
• Scripts tested if present
• Unused directories deleted

Anti-Patterns to Avoid

• Writing documentation ABOUT Claude instead of instructions TO Claude
• First person in descriptions ("I can help..." → "Processes...")
• Over-explaining what Claude already knows
• Nesting references deeply (file1→file2→file3)
• Including executables or binaries in skills
• Creating CHANGELOG.md files (not needed for skills)
• Skills over 500 lines without splitting to references/

Note on README.md files: README.md files in this repository are auto-generated from SKILL.md frontmatter and are automatically removed during the release process. They do not appear in the final skill bundle distributed to users.

License

MIT License - See LICENSE file