Skills
skills/popodidi/harvis/skill-creator

skill-creator

SKILL.md

Skill Creator

This skill provides guidance for creating effective skills in this workspace.

Workspace Integration

This workspace has a two-tier skill structure:

Location Invocation Use Case
projects/self/skills/<name>/ /skill-name Global skills for the whole workspace
projects/<proj>/skills/<name>/ /proj-skill-name Project-specific skills

After creating a skill, run /sync-skills to copy it to .claude/skills/ for native integration.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. They transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.

What Skills Provide

  1. Specialized workflows - Multi-step procedures for specific domains
  2. Tool integrations - Instructions for working with specific file formats or APIs
  3. Domain expertise - Company-specific knowledge, schemas, business logic
  4. Bundled resources - Scripts, references, and assets for complex tasks

Core Principles

Concise is Key

The context window is a shared resource. Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this?" and "Does this justify its token cost?"

Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

Match specificity to the task's fragility:

  • High freedom (text instructions): Multiple approaches valid, context-dependent decisions
  • Medium freedom (pseudocode/parameterized scripts): Preferred pattern exists, some variation acceptable
  • Low freedom (specific scripts): Operations are fragile, consistency critical

Anatomy of a Skill

Every skill consists of a required SKILL.md and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description, allowed-tools)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable code (Python/Bash)
    ├── references/   - Documentation loaded into context as needed
    └── assets/       - Files used in output (templates, etc.)

SKILL.md (required)

  • Frontmatter (YAML): name, description, and optionally allowed-tools
  • Body (Markdown): Instructions loaded when skill triggers

Bundled Resources (optional)

scripts/ - Executable code for deterministic reliability

  • When to include: Same code rewritten repeatedly, deterministic reliability needed
  • Example: scripts/validate.py for data validation
  • Convention: Use uv inline dependencies (see below)

references/ - Documentation loaded into context as needed

  • When to include: Detailed info Claude should reference while working
  • Examples: API docs, schemas, detailed workflows
  • Best practice: If large (>10k words), include grep patterns in SKILL.md

assets/ - Files used in output, not loaded into context

  • When to include: Templates, images, boilerplate used in final output
  • Examples: .pptx templates, starter code directories

What NOT to Include

Do not create extraneous documentation:

  • README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, etc.

The skill should only contain information needed for Claude to do the job.

Python Scripts Convention

All Python scripts must use uv inline dependencies (PEP 723). This ensures scripts are self-contained and run without manual environment setup.

Template

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.11"
# dependencies = ["requests>=2.31.0", "pyyaml>=6.0"]
# ///
"""
Script description here.

Usage:
    ./script.py [args]
"""

import sys
# ... rest of script

Key Points

  1. Shebang: #!/usr/bin/env -S uv run - allows direct execution
  2. Inline metadata: PEP 723 format between # /// script markers
  3. Dependencies: List all required packages with version constraints
  4. Execution: Run directly with ./script.py (no python prefix needed)

Benefits

  • Zero setup: uv automatically creates ephemeral venv and installs deps
  • Self-documenting: Dependencies visible at top of file
  • Reproducible: Version constraints ensure consistent behavior
  • Portable: Works on any machine with uv installed

Self-Contained Skills Convention

Skills should be self-contained and portable. This means:

  1. Bundle all config files within the skill folder
  2. Use relative paths from the script location
  3. No external dependencies outside the skill folder (except system tools)

Directory Structure for Self-Contained Skills

skill-name/
├── SKILL.md              # Main documentation
├── config.yaml           # Configuration (bundled)
├── secrets.yaml          # Secrets (gitignored, bundled)
├── scripts/
│   └── auth.sh           # Scripts use relative paths
└── references/           # Optional documentation

Bash Scripts - Relative Path Pattern

#!/bin/bash
# Get skill directory using relative path from this script
# This makes the skill self-contained and portable

_get_skill_dir() {
    local script_path="${BASH_SOURCE[0]}"
    if [[ -z "$script_path" ]]; then
        script_path="$0"
    fi
    # Resolve to absolute path and get parent of scripts/
    local script_dir="$(cd "$(dirname "$script_path")" && pwd)"
    local skill_dir="$(dirname "$script_dir")"  # Go up from scripts/
    echo "$skill_dir"
}

SKILL_DIR="$(_get_skill_dir)"
CONFIG_FILE="$SKILL_DIR/config.yaml"

Benefits of Self-Contained Skills

  • Shareable: Can share skill folder without full repo access
  • Portable: Works in any location, not tied to repo structure
  • Testable: Can test skill in isolation
  • Clear dependencies: All files skill needs are visible in folder

Migration from Shared Files

If a skill currently uses files from shared/:

  1. Move files into the skill folder
  2. Update scripts to use relative paths
  3. Update SKILL.md documentation
  4. Update .gitignore if secrets files moved

allowed-tools Security

When specifying allowed-tools in frontmatter, follow these rules:

  • Never use unrestricted Bash — it bypasses ALL user confirmation prompts. This is the highest-risk permission a skill can have.
  • Scope Bash with glob patterns: Bash(pattern*) matches against the command string prefix. Example: Bash(source*meegle-auth.sh*) scopes to sourcing a specific auth script.
  • MCP wildcards (mcp__tn-lark__*) auto-approve both reads and writes — there's no built-in read/write separation. Mitigate with plan-before-write instructions in the skill body.
  • No allowed-tools = safe default — every tool call prompts the user. Only add allowed-tools when the prompt friction hurts the workflow.

See: contexts/archived/20260212-skill-security-audit/

Skill Creation Process

  1. Understand the skill with concrete examples
  2. Plan reusable contents (scripts, references, assets)
  3. Initialize the skill (run init_skill.py)
  4. Edit the skill (implement resources, write SKILL.md)
  5. Run /sync-skills to deploy
  6. Iterate based on real usage

Step 1: Understanding with Concrete Examples

Ask clarifying questions:

  • "What functionality should this skill support?"
  • "Can you give examples of how it would be used?"
  • "What would a user say that should trigger this skill?"

Conclude when there's a clear sense of functionality.

Step 2: Planning Reusable Contents

For each example, consider:

  1. How to execute from scratch
  2. What scripts/references/assets would help with repeated execution

Step 3: Initializing the Skill

Run the init script:

# For global skills (invoked as /skill-name)
./projects/self/skills/skill-creator/scripts/init_skill.py <skill-name>

# For project-specific skills (invoked as /proj-skill-name)
./projects/self/skills/skill-creator/scripts/init_skill.py <skill-name> --project <proj>

The script creates a template with proper structure and TODO placeholders.

Step 4: Editing the Skill

Frontmatter

---
name: skill-name
description: Complete explanation of what the skill does and WHEN to use it. Include specific triggers, scenarios, or tasks.
allowed-tools: Read, Write, Bash, Glob  # Optional: restrict available tools
---

The description is the primary triggering mechanism. Include all "when to use" information here since the body only loads after triggering.

Body

Write instructions for using the skill. Consult:

  • references/workflows.md for sequential/conditional workflows
  • references/output-patterns.md for template and example patterns

Step 5: Deploy with /sync-skills

After creating or modifying a skill:

/sync-skills

This copies skills from projects/*/skills/ to .claude/skills/ for native integration.

Step 6: Iterate

  1. Use the skill on real tasks
  2. Notice struggles or inefficiencies
  3. Update SKILL.md or bundled resources
  4. Run /sync-skills and test again

Context Budget

Context consumed by instructions directly impacts quality — "less context = fewer hallucinations." When creating or reviewing skills:

  • Split skills >300 lines into SKILL.md (core workflow) + references/ (detail, loaded on demand)
  • Consolidate permission rules (prefer wildcards over many specific entries)
  • Challenge every line: "Does Claude need this to do the job?"

See: projects/self/contexts/archived/20260223-systematic-optimization/

Progressive Disclosure

Keep SKILL.md under 500 lines. Split content when approaching this limit.

Pattern 1: High-level guide with references

## Quick start
[Essential workflow]

## Advanced features
- **Feature X**: See [FEATURE_X.md](references/feature_x.md)

Pattern 2: Domain-specific organization

skill/
├── SKILL.md (overview + navigation)
└── references/
    ├── domain_a.md
    ├── domain_b.md

Validation

Validate a skill before deploying:

./projects/self/skills/skill-creator/scripts/quick_validate.py projects/self/skills/<skill-name>

Checks:

  • SKILL.md exists with valid frontmatter
  • Required fields present (name, description)
  • Naming conventions (hyphen-case)
  • No angle brackets in description
Weekly Installs
1
Repository
popodidi/harvis
First Seen
5 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
mcpjam1
claude-code1
replit1
junie1
windsurf1
zencoder1