Getting Started With Skills

Name: Getting Started With Skills
Author: obra

obra/clank

44 installs
41 repo stars
Updated October 9, 2025
obra/clank

Claude Code agent workflow helper from OBRA clank repository.

About

getting started with skills — Clank skill from OBRA repository—agent workflow reference for Claude Code power users in the Superpowers ecosystem.

OBRA clank agent workflow.
Install via skills.sh registry.
Pairs with Superpowers ecosystem.

Getting Started With Skills by the numbers

44 all-time installs (skills.sh)
+2 installs in the week ending Jul 26, 2026 (Skillselion tracking)
Ranked #7,773 of 16,659 AI & Agent Building skills by installs in the Skillselion catalog
Security screen: MEDIUM risk (skills.sh audit)
Data as of Jul 26, 2026 (Skillselion catalog sync)

npx skills add https://github.com/obra/clank --skill getting-started-with-skills

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/obra/clank/getting-started-with-skills.svg)](https://skillselion.com/skills/obra/clank/getting-started-with-skills)

Installs	44
repo stars	★ 41
Security audit	2 / 3 scanners passed
Last updated	October 9, 2025
Repository	obra/clank ↗

What it does

Claude Code agent workflow helper from OBRA clank repository.

Files

SKILL.mdMarkdownGitHub ↗

Getting Started with Skills

Your personal wiki of proven techniques, patterns, and tools at ~/.claude/skills/.

How to Reference Skills

DO NOT use @ links - they force-load entire files, burning 200k+ context instantly.

INSTEAD, use skill path references:

Format: skills/category/skill-name (no @ prefix, no /SKILL.md suffix)
Example: skills/collaboration/brainstorming or skills/testing/test-driven-development
Load with Read tool only when needed

When you see skill references in documentation:

skills/path/name → Use Read tool on ~/.claude/skills/path/name/SKILL.md
Load supporting files only when implementing

Mandatory Workflow 1: Before ANY Task

1. Search skills:

~/.claude/skills/getting-started/skills-search PATTERN

2. Search conversations: Dispatch subagent (see Workflow 2) to check for relevant past work.

If skills found: 1. READ the skill: ~/.claude/skills/path/skill-name/SKILL.md 2. ANNOUNCE usage: "I'm using the [Skill Name] skill" 3. FOLLOW the skill (many are rigid requirements)

"This doesn't count as a task" is rationalization. Skills/conversations exist and you didn't search for them or didn't use them = failed task.

Mandatory Workflow 2: Historical Context Search

When: Your human partner mentions past work, issue feels familiar, starting task in familiar domain, stuck/blocked, before reinventing

When NOT: Info in current convo, codebase state questions, first encounter, partner wants fresh thinking

How (use subagent for 50-100x context savings): 1. Dispatch subagent with template: ~/.claude/skills/collaboration/remembering-conversations/tool/prompts/search-agent.md 2. Receive synthesis (200-1000 words) + source pointers 3. Apply insights (never load raw .jsonl files)

Example:

Partner: "How did we handle auth errors in React Router?"
You: Searching past conversations...
[Dispatch subagent → 350-word synthesis]
[Apply without loading 50k tokens]

Red flags: Reading .jsonl files directly, pasting excerpts, asking "which conversation?", browsing archives

Pattern: Search → Subagent synthesizes → Apply. Fast, focused, context-efficient.

Announcing Skill Usage

Every time you start using a skill, announce it:

"I'm using the [Skill Name] skill to [what you're doing]."

Examples:

"I'm using the Brainstorming skill to refine your idea into a design."
"I'm using the Test-Driven Development skill to implement this feature."
"I'm using the Systematic Debugging skill to find the root cause."
"I'm using the Refactoring Safely skill to extract these methods."

Why: Transparency helps your human partner understand your process and catch errors early.

Skills with Checklists

If a skill contains a checklist, you MUST create TodoWrite todos for EACH checklist item.

Don't:

Work through checklist mentally
Skip creating todos "to save time"
Batch multiple items into one todo
Mark complete without doing them

Why: Checklists without TodoWrite tracking = steps get skipped. Every time.

Examples: TDD (write test, watch fail, implement, verify), Systematic Debugging (4 phases), Creating Skills (RED-GREEN-REFACTOR)

Navigation

Really, try skills-search first.

Categories: skills/INDEX.md → testing, debugging, coding, architecture, collaboration, meta Individual skill: Load from category INDEX

How to Read a Skill

1. Frontmatter - when_to_use match your situation? 2. Overview - Core principle relevant? 3. Quick Reference - Scan for your pattern 4. Implementation - Full details 5. Supporting files - Load only when implementing

Many skills contain rigid rules (TDD, debugging, verification). Follow them exactly. Don't adapt away the discipline.

Some skills are flexible patterns (architecture, naming). Adapt core principles to your context.

The skill itself tells you which type it is.

Referencing Skills in Documentation

When writing documentation that references other skills:

Use path format without @ prefix or /SKILL.md suffix:

✅ Good: skills/testing/test-driven-development
✅ Good: skills/debugging/systematic-debugging
❌ Bad: @skills/testing/test-driven-development/SKILL.md (force-loads, burns context)

Why no @ links: @ syntax force-loads files immediately, consuming 200k+ context before you need them.

To read a skill reference: Use Read tool on ~/.claude/skills/category/skill-name/SKILL.md

Creating Skills

Found something valuable? See skills/meta/creating-skills

Want a skill that doesn't exist? Edit skills/REQUESTS.md (at ~/.claude/skills/REQUESTS.md)

Summary

Starting conversation? You just read this. Good.

Starting any task? Run skills-search first, announce usage, follow what you find.

Skill has checklist? TodoWrite for every item.

Skills are mandatory when they exist, not optional.

Last thing

In the first response after reading this guide, you MUST announce to the user that you have read the getting started guide

#!/usr/bin/env bash
# skills-search - Find relevant skills using grep patterns
# Logs all searches for gap analysis (gardening skill processes the log)

set -euo pipefail

# Detect if running from repo or installed location
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
if [[ "$SCRIPT_DIR" == *"/.claude/skills/getting-started" ]]; then
    # Installed location
    SKILLS_DIR="${HOME}/.claude/skills"
else
    # Running from repo
    SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
fi

LOG_FILE="${SKILLS_DIR}/.search-log.jsonl"

# Show usage if no arguments
if [[ $# -eq 0 ]]; then
    cat <<'EOF'
Usage: skills-search PATTERN [PATTERN...]

Searches skills using grep patterns.

Examples:
  skills-search 'test.*driven|TDD'
  skills-search 'debug.*systematic|root.cause'
  skills-search 'refactor|extract'
  skills-search 'async.*test|flaky|timeout'
  skills-search 'validat.*input'

The search is logged. Failed searches help identify missing skills.
EOF
    exit 1
fi

# Log the search for gap analysis
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
query="$*"
echo "{\"timestamp\":\"$timestamp\",\"query\":\"$query\"}" >> "$LOG_FILE" 2>/dev/null || true

# Search all SKILL.md files - both content AND path names
# Content search: grep file contents
content_matches=$(grep -E -r "$@" "$SKILLS_DIR/" --include="SKILL.md" -l 2>/dev/null || true)

# Filename search: find all SKILL.md paths, then grep the paths themselves
all_skills=$(find "$SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null || true)
path_matches=$(echo "$all_skills" | grep -E "$@" 2>/dev/null || true)

# Combine and deduplicate
results=$(printf "%s\n%s" "$content_matches" "$path_matches" | sort -u | grep -v '^$' || true)

if [[ -z "$results" ]]; then
    echo "❌ No skills found matching: $*"
    echo ""
    echo "Search logged. If a skill should exist, it will be created."
    echo "Proceed carefully - document your approach."
    exit 0
fi

echo "✅ Found skills:"
echo ""

# Display results with metadata
echo "$results" | while read -r file; do
    # Extract description from frontmatter
    description=$(grep "^description:" "$file" 2>/dev/null | sed 's/description: *//' || echo "")

    # Get relative path without @ prefix or /SKILL.md suffix
    rel_path="${file#$SKILLS_DIR/}"
    rel_path="skills/${rel_path%/SKILL.md}"

    if [[ -n "$description" ]]; then
        echo "$rel_path - $description"
    else
        echo "$rel_path"
    fi
done

echo ""

exit 0