Skip to content

Instantly share code, notes, and snippets.

@kim-em

kim-em/README.md

Created May 7, 2026 01:47
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save kim-em/ec2795b60963d51d9361c0001f01ba46 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save kim-em/ec2795b60963d51d9361c0001f01ba46 to your computer and use it in GitHub Desktop.
Download ZIP
Claude Code skill: acquiring-skills — meta-skill that teaches Claude how to write new skills
Raw
README.md

Claude Code skill: acquiring-skills

A meta-skill for Claude Code that documents how to write new skills. When invoked, it tells Claude how to structure a new SKILL.md, where to put it, what makes a good trigger description, when to add helper scripts, and how to iterate on skills as you use them.

Installation

Drop SKILL.md into ~/.claude/skills/acquiring-skills/:

mkdir -p ~/.claude/skills/acquiring-skills
# (download SKILL.md from this gist into that directory)

Claude Code auto-discovers skills under ~/.claude/skills/ on next launch. The skill activates when you ask Claude to write, create, or document a new skill (or mention SKILL.md / ~/.claude/skills/).

Why this is useful

Skills are how you teach Claude Code reusable workflows that persist across sessions. Without acquiring-skills, Claude has to figure out the skill format from scratch each time, often producing inconsistent results. With it, you can say "write a skill for X" and Claude follows a documented process: practice the workflow first, identify helpers worth extracting, write the manifest with proper trigger conditions, iterate based on use.

Files

This is a single-file skill — just SKILL.md.

Raw
SKILL.md
name acquiring-skills
description Create new Claude Code skills. Use when the user asks to write, create, or add a new skill, or asks to document a workflow as a skill. Also use when the user mentions SKILL.md or ~/.claude/skills/.
allowed-tools Read, Write, Edit, Bash, Glob

Creating Claude Code Skills

This skill covers how to create new skills for Claude Code.

Skill Locations

Skills can be stored at three levels:

Location Path Applies to
Personal ~/.claude/skills/<skill-name>/ You, across all projects
Project .claude/skills/<skill-name>/ Anyone working in this repository
Plugin Bundled with plugins Anyone with the plugin installed

Project skills are committed to version control - anyone who clones the repository gets them automatically.

Personal skills are for workflows you use across multiple projects.

Skill File Structure

Each skill directory contains a SKILL.md file with:

  1. YAML frontmatter (required)
  2. Markdown content describing the skill

YAML Frontmatter Format

---
name: skill-name
description: One-line description of when to use this skill. Use when the user asks X, wants Y, or needs Z.
allowed-tools: Read, Edit, Write, Bash, Glob, Grep
---

Frontmatter Fields

  • name: Short identifier for the skill (should match directory name)
  • description: Explains when Claude should activate this skill. Write it as trigger conditions:
    • "Use when the user asks to..."
    • "Use when the user wants to..."
    • "Use when working with X and Y happens..."
  • allowed-tools: Comma-separated list of tools the skill may use

Available Tools

Common tools to include in allowed-tools:

  • Read - Read files
  • Write - Create new files
  • Edit - Modify existing files
  • Bash - Run shell commands
  • Glob - Find files by pattern
  • Grep - Search file contents
  • WebFetch - Fetch web pages
  • WebSearch - Search the web

Markdown Content Guidelines

After the frontmatter, write clear documentation:

  1. Overview - What the skill does and when to use it
  2. Principles - Key rules or constraints to follow
  3. Workflow - Step-by-step process
  4. Commands/Examples - Specific commands or code snippets
  5. Common Patterns - Frequently used approaches
  6. Notes - User-specific context (locations, preferences, etc.)

Example Skill

---
name: example-skill
description: Handle X tasks. Use when the user asks about X, wants to do Y, or needs help with Z.
allowed-tools: Read, Edit, Bash
---

# Example Skill

This skill handles X.

## Overview

Brief description of what this skill does.

## Workflow

1. First step
2. Second step
3. Third step

## Commands

\`\`\`bash
example command
\`\`\`

## Notes

- User-specific detail 1
- User-specific detail 2

Creating a New Skill

Personal Skill (applies to all your projects)

  1. Create the directory:

    mkdir -p ~/.claude/skills/<skill-name>

  2. Create SKILL.md with frontmatter and content

  3. Commit to the .claude repo:

    cd ~/.claude
git add skills/<skill-name>
git commit -m "Add <skill-name> skill"
git push

Project Skill (shared with collaborators)

  1. Create the directory in the project:

    mkdir -p .claude/skills/<skill-name>

  2. Create SKILL.md with frontmatter and content

  3. Commit to the project repository so collaborators get the skill too

Writing Good Descriptions

The description field determines when Claude activates the skill. Write it to match user intent:

Good descriptions:

  • "Manage the user's TODO list. Use when the user asks about tasks, wants to add/update TODOs, or asks what needs to be done."
  • "Create minimal working examples from Lean errors. Use when the user asks to minimize an error or create an MWE."
  • "Synchronize the home git repo. Use when git pull fails or the user asks to sync their home directory."

Bad descriptions:

  • "A skill for TODOs" (too vague, no trigger conditions)
  • "This handles git stuff" (unclear when to activate)
  • "Use when the user asks X. Encodes that you must do Y and Z" (mixes the trigger with the skill body — the description field describes when to activate, never what the skill contains; activation logic should not depend on skill content)

Skill Development Process

Creating a good skill requires practice and iteration, not just documentation.

Personal vs. project skill? Before you start, decide where the skill belongs:

  • Project skill (.claude/skills/): Only useful for this specific codebase
  • Personal skill (~/.claude/skills/): Useful across multiple projects

Default to personal. If there's any doubt, put it in ~/.claude/skills/. You can always move it later, and personal skills are easier to maintain (one location, synced across machines).

1. Practice First

Before writing SKILL.md, perform the workflow manually in the current session. If you've already been doing the task, you have the context you need. If not, do it now.

Why this matters:

  • Instructions grounded in real experience are more accurate
  • You'll discover edge cases and gotchas
  • You'll know which steps are error-prone

Don't skip this. Theoretical documentation leads to skills that don't work in practice.

2. Identify Helper Scripts

During practice, note:

  • Commands you type repeatedly
  • Multi-step operations that could be a single script
  • Complex logic that's easy to get wrong

These are candidates for helper scripts that live alongside SKILL.md:

~/.claude/skills/my-skill/
├── SKILL.md
├── search.sh          # Helper script
├── process.py         # Another helper
└── templates/         # Supporting files

3. Helper Script Conventions

  • Location: Store in the skill directory
  • Permissions: Make executable (chmod +x)
  • Documentation: Include usage comments at the top
  • References: Call from SKILL.md with the full path (~/.claude/skills/my-skill/search.sh)

Example helper script header:

#!/bin/bash
# Usage: search.sh <query> [--after DATE] [--before DATE]
# Searches the corpus and formats results for the skill workflow

4. Practice With the Skill

After creating SKILL.md and any helper scripts:

  1. Invoke the skill on a real task (not a toy example)
  2. Note friction points:
    • Unclear instructions?
    • Missing steps?
    • Scripts that need different arguments?
  3. Update immediately based on what you learned

5. Iterate

Skills improve through use. Each time you invoke a skill and hit friction:

  1. Stop and fix the skill right now
  2. Don't just work around the problem
  3. Commit and push the improvement

A skill that gets used and updated is better than a "perfect" skill written once.

Updating Existing Skills

When modifying skills, always commit and push to keep machines in sync:

cd ~/.claude
git add -A
git commit -m "Update <skill-name> skill"
git push
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment