oaustegard avatar

skill-development

Tools for creating, versioning, installing, inspecting, and orchestrating Claude skills.

version
2.6.0
GitHub stars
404

Install

/plugin install skill-development@oaustegard-claude-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add oaustegard/claude-skills.

Contents

Discovered from source

Skills 9

Crafting Instructions for Claude

Choose the format for instructions on Claude.ai — Project instructions, Skills, or standalone prompts — and structure them for the format chosen.

Overlap notice. The Core Optimization Principles below also appear in writing-instructions, which carries them in more depth. This skill owns the format decision; writing-instructions owns how to write well inside a format. The two descriptions are close enough that a request can land on either — route by which of those two questions is being asked.

Decision Framework: Which Format to Use?

Ask these questions to determine the right format:

Use PROJECT INSTRUCTIONS when:

  • Context needs to persist for ALL conversations in a workspace
  • Multiple team members collaborate with shared knowledge
  • Background knowledge required for specific initiative
  • Custom behavior scoped to one project only

Signals: "for this project", "all conversations about X", "team workspace", "project-specific"

Use SKILL when:

  • Capability needed across MULTIPLE contexts/projects
  • Procedural knowledge that applies broadly
  • Instructions should activate automatically when relevant
  • Want portable expertise that loads on-demand

Signals: "every time I", "whenever", "reusable", "across projects", "teach Claude how to"

Use STANDALONE PROMPT when:

  • One-off request with immediate context
  • Ad-hoc instructions for single use
  • Conversational refinement
  • No need for persistence

Signals: "for this task", "right now", "just this once", "can you"

Combined Approaches:

Project + Skill:

  • Project: Persistent context (market data, product specs)
  • Skill: Reusable methods (analysis framework, report templates)
  • Use when: Need both workspace context AND portable capabilities

Skill + Prompt:

  • Skill: General expertise (code review standards)
  • Prompt: Specific context ("review this PR for security")
  • Use when: Foundational capability + immediate direction

Core Optimization Principles

These apply to ALL instruction formats:

1. Imperative Construction

Frame as direct action commands, not suggestions:

  • ❌ "Consider creating X" → ✅ "Create X when conditions Y"
  • ❌ "You might want to" → ✅ "Execute" / "Generate"
  • ❌ "Try to optimize" → ✅ "Optimize by"

2. Positive Directive Framing

State WHAT to do, not what NOT to do:

  • ❌ "Don't use bullet points" → ✅ "Write in flowing paragraph form"
  • ❌ "Avoid technical jargon" → ✅ "Use accessible language for beginners"
  • ❌ "Never output lists" → ✅ "Present information in natural prose"

WHY: Negative instructions force inference. Positive instructions state desired behavior directly.

3. Context and Motivation

Explain WHY requirements exist:

  • ❌ "Use paragraph form"
  • ✅ "Use paragraph form because flowing prose is more conversational for casual learning"

WHY: Context helps Claude make better autonomous decisions in edge cases.

4. Strategic Over Procedural

Provide goals and decision frameworks, not step-by-step procedures:

  • Specify: Success criteria, boundaries, decision frameworks
  • Minimize: Sequential steps, detailed execution, obvious operations
  • Rule: If Claude can infer procedure from goal, specify only the goal

Current models plan from a stated goal. Write out a sequence only where one sequence is the safe one — destructive commands, auth flows, compliance steps.

5. Trust Base Behavior

Claude's system prompt already covers:

  • Citation protocols, copyright guidelines, safety
  • General tool usage, artifact creation basics
  • Conversational tone defaults, refusal handling
  • Base accuracy and helpfulness standards

ONLY specify project/domain-specific deviations.

Format-Specific Guidance

For Project Instructions

See: references/project-instructions.md

Key points:

  • Additive to system prompt (no duplication)
  • Focus on workspace-specific behavior
  • Name the domains that warrant deeper deliberation
  • Simple structure (headings/paragraphs) unless complexity demands more

For Skills

See: references/creating-skills.md

Key points:

  • Progressive disclosure (metadata → full instructions → bundled resources)
  • Frontmatter: name + description with trigger patterns
  • Keep SKILL.md under 500 lines
  • Use references/ for detailed domain content

For Standalone Prompts

See: references/standalone-prompts.md

Key points:

  • Clear and explicit about desired output
  • Provide context and examples when helpful
  • Scale complexity to task needs
  • Give permission to express uncertainty

When to Suggest What

"Use a Skill" when user says:

  • "I keep having to explain this every time"
  • "Can you remember how to do X?"
  • "I need this across multiple projects"
  • Repeating same instructions across conversations

"Use Project instructions" when user says:

  • "For this project, always..."
  • "My team needs to work with..."
  • "All conversations about this initiative should..."
  • Building workspace with persistent context

"Use a better prompt" when user says:

  • Results are inconsistent
  • Claude misunderstands intent
  • Output format isn't right
  • Need more comprehensive response

Skills vs Projects: Key Differences

Read: references/skill-vs-project.md for detailed comparison

Quick reference:

Project = "Here's what you need to know"

  • Static reference material always loaded
  • Background knowledge for initiative
  • Team workspace context

Skill = "Here's how to do things"

  • Dynamic expertise loading on-demand
  • Procedural knowledge and methods
  • Portable across any conversation

Example:

  • Project: "Q4 Product Launch" with market research, competitor docs
  • Skill: competitive-analysis framework for analyzing any competitor

Use both together for powerful combinations.

Example Quality Awareness

Examples teach every pattern they contain, including the ones you did not intend.

When including examples:

  • Audit EVERY detail (format, verbosity, structure, tone)
  • Ensure ALL aspects demonstrate desired behavior
  • Better to omit examples than include mixed signals
  • If example uses bullets but you want prose, Claude will default to bullets

Structural Simplicity

Default to clear organization:

  • Headings and whitespace (primary approach)
  • Explicit language stating relationships
  • Natural paragraph flow

Use structured markup (XML/JSON) only when:

  • Separating distinct content types in complex scenarios
  • Absolute certainty about content boundaries required
  • API-driven workflows needing structured parsing

Thinking Depth

No prompt phrase turns thinking on. Current Claude models think adaptively by default, and depth is set by configuration — the effort setting on the API, the UI control on Claude.ai. "Think step by step" and hand-written trigger phrases buy nothing.

What instructions can usefully carry is which parts of the domain deserve more deliberation, so the reader knows where to raise effort:

[Specific complexity] in this domain is worth extra deliberation because [why].

Complexity Scaling

Match instruction complexity to task needs:

Simple task → Simple prompt or brief instructions Medium task → Structured guidance with decision frameworks Complex task → Comprehensive instructions; raise effort

Before adding complexity: Could simpler formulation work equally well?

Instruction Density

Scale density to how far the task sits from what the model does unprompted. State the goal, the constraints, and how success is checked; add procedure only where order is fragile. When the choice is between another rule and more context about why, write the context — that is what the model cannot get elsewhere, and it is what it uses on the cases you did not enumerate.

State explicitly that judgment applies to cases the instructions do not cover.

Quality Checklist

Before delivering instructions:

Strategic:

  • Clear goals stated without micromanagement
  • Context explains WHY requirements exist
  • Decision frameworks for ambiguous cases
  • Constraints use positive framing when possible

Technical:

  • Imperative language throughout
  • Positive directives over negative restrictions
  • Appropriate structure (simple by default)
  • No system prompt duplication
  • Examples (if any) perfectly aligned

Execution:

  • Immediately actionable
  • Success criteria clear
  • Format matches complexity needs

Common Mistakes to Avoid

❌ System prompt duplication - "Use web_search for current info, cite sources" ✅ Omit unless project has SPECIFIC deviations

❌ Negative framing - "Don't use lists, never be verbose" ✅ "Present in natural prose paragraphs"

❌ Fake thinking triggers - "Use 'think carefully' for deep thinking" ✅ "Name where deliberation pays in this domain; set effort there"

❌ Procedural micromanagement - "Step 1: X, Step 2: Y..." ✅ "Goal: X. Quality standard: Y. Approach: Z."

❌ Contextless requirements - "Always use formal tone" ✅ "Use formal tone for professional docs because recipients expect authoritative voice"

❌ Imperfect examples - Example uses bullets when you want prose ✅ Either create perfect examples or omit entirely

Additional Resources

Creating skills

A skill is instructions to the agent: a procedure with commands, checks and failure signals. Facts alone belong in a document labelled as a reference. The measurements behind every rule here are in references/skill-utility-evidence.md; read it when a rule seems arbitrary.

Not for

SituationUse
Whether the instruction should be a skill, project instructions or a promptcrafting-instructions
Sentence-level quality of instruction prosewriting-instructions
Revising an existing skill that has evidence of underperformingoptimizing-skills
Project-specific context, one-off tasksproject instructions or a prompt

Procedure

  1. Create the directory. mkdir -p <name>/{scripts,references,assets}; delete unused ones before shipping. Name: gerund first word (processing-pdfs), lowercase and hyphens, at most 64 characters, no "anthropic" or "claude".

  2. Write the description (about 250 characters; 1024 is the hard limit):

    • one sentence on what it does, then two or three phrasings a user would type;
    • lead with the unit of the question (symbols, not ASTs);
    • third person; no angle brackets anywhere (-> and >200MB are rejected too);
    • separate from neighbours by omission — a disclaimer ("does not X") pulls toward X; routing goes in the body;
    • never reuse a sibling's trigger phrases.
  3. Validate the frontmatter:

    python3 /mnt/skills/examples/skill-creator/scripts/quick_validate.py <skill-dir>
    

    Allowed keys: name, description, license, allowed-tools, metadata, compatibility. One SKILL.md per directory.

  4. Check confusability from oaustegard/claude-workspace:

    python3 scripts/skill_confusability.py --skills <skills-root> --queries q.json
    

    q.json: five task-shaped queries under the skill's name, negatives under __none__. Require top-1 on 5/5, no steals of sibling queries, no near-miss above the hit floor. A neighbour above ~0.65 cosine needs a routing row in both bodies.

  5. Write the body in this order:

    • Not for — routing table naming real sibling skills; plus when to abandon the procedure mid-run.
    • Setup — install commands and each tool's silent-failure signal.
    • Procedure — numbered steps with the actual commands, flags and order; the intermediate checks and what a wrong result looks like. Leave to judgment whether the skill applies, which approach fits, and when to abandon.
    • Rules with exceptions — a table for any rule that is sometimes wrong.
    • Failure modes — a signal | action table. The signal is what the reader sees.
    • Verification — the commands that confirm success, and what a bad success looks like (passes inspection, lost content).

    Write imperatives. Give a reason only where it changes what the reader does, in one clause ("— it catches fixes the regression accepts"). Leave out motivation, provenance, results, dated incidents and paragraphs repeating the description; they go in the CHANGELOG. Phrase instructions positively, but keep negative scope (the Not-for table) as content.

  6. Add resources only when they earn it. Code Claude would rewrite each time → scripts/, with explicit errors and non-zero exits. Detail that would push SKILL.md past ~500 lines → references/, one level deep. Output templates → assets/. A script that fails quietly is worse than none.

  7. Write the CHANGELOG entry: what changed, provenance, measurements, and the dated story of any diagnosed failure the body now encodes as a row.

  8. Bump metadata.version (releases trigger on the change). Commit each skill's bump separately: the release bot writes the commit subject into every bumped skill's CHANGELOG.

  9. Test on three real scenarios — simple, complex, edge — and fix what actually happened.

  10. Package for claude.ai upload when needed:

    zip -r <name>.zip <name>/ && unzip -l <name>.zip
    

    README.md, CHANGELOG.md and tests/ are stripped from release zips; put anything that must ship (credits, licenses) in SKILL.md or a shipped file.

Failure modes

SignalAction
Skill does not load; no erroran unquoted : or an angle bracket in the description; run quick_validate.py
Skill loses its own queriesdescription too long or reusing a sibling's phrases; cut to ~250 characters with three phrasings
Skill wins queries it should ignorea disclaimer in the description; delete it and move routing into the body
Body explains, tells history or sellsmove it to the CHANGELOG; keep steps, commands, signals
Steps read as goals ("scan the repo and check")replace with the command and the output that means failure
CHANGELOG entry describes another skill's changethe release bot used a shared commit subject; edit it and bump separately next time
Agent applies the skill where it does not fitthe Not-for table is missing or names categories, not skills

Verification

python3 /mnt/skills/examples/skill-creator/scripts/quick_validate.py <skill-dir>
python3 scripts/skill_confusability.py --skills <skills-root> --queries q.json   # top-1 5/5
wc -l <skill-dir>/SKILL.md                                                       # under 500
grep -n "Diagnosed\|20[0-9][0-9]-[0-9][0-9]-" <skill-dir>/SKILL.md                # dated stories left in the body

Bad success: a skill that validates and wins its queries while its body is a goal statement or a history — read the procedure as someone who must execute it with no other context.

Checklist

  • Name and description follow step 1–2; quick_validate.py passes; confusability 5/5
  • Not-for table names real skills; abandonment condition stated
  • Setup with silent-failure signals, if it wraps a tool
  • Every step has a command or a concrete check
  • Failure modes are signal | action rows
  • Verification commands and the bad-success case
  • No motivation, provenance, results or dated stories in the body or references
  • Reasons only where they change behaviour, one clause each
  • SKILL.md under 500 lines; references one level deep; unused directories deleted
  • CHANGELOG entry; version bumped in its own commit
  • Tested on three real scenarios

References

  • references/skill-utility-evidence.md — measurements behind each rule, and the dated catalogue cases
  • references/bundled-resources.md — scripts, references and assets patterns
  • references/advanced-patterns.md — validation workflows, multi-stage skills
  • references/optimization-techniques.md — token budget
  • references/environment-reference.md — Claude.ai vs Claude Code paths

Finding Skills

Skills on disk at /mnt/skills/user/ are a catalog — too expensive to preload as descriptions in every session's context. This skill is the on-demand accessor, analogous to Anthropic's ToolSearch for MCP tools.

Usage

PY=/home/user/.spokes/claude-skills/finding-skills/scripts/skills.py

# List every skill by name (cheap, ~1.4KB)
python3 "$PY" list

# Search by keyword — ranks name matches above description matches
python3 "$PY" search "adversarial review"

# Load the full SKILL.md of a specific skill
python3 "$PY" show challenging

In a live CCotw session the script lives at /mnt/skills/user/finding-skills/scripts/skills.py.

When to reach for this

  • You have a task where a skill might help but no obvious name comes to mind → search <keywords>
  • The boot emitted names-only and you want the description of a candidate → show <name>
  • You want catalog breadth before picking an approach → list

Pattern

  1. search "<what you want to do>" — get 3–10 ranked candidates
  2. show <top-pick> — read its SKILL.md
  3. Follow the SKILL.md's instructions (which may point at scripts/, references/, etc.)

Stop at step 1 if none of the candidates fit — don't shoehorn an unrelated skill onto the task.

Ranking

  • Exact match on skill name: 100
  • Substring match on skill name: 10
  • Substring match in description: 1 per match (multiple hits compound)

Case-insensitive throughout. Results sorted high-to-low, ties broken by name.

Output format

  • list: one skill name per line
  • search: tab-separated <name>\t<description (truncated to 200 chars)>, one per line
  • show: raw SKILL.md contents to stdout; exit 1 with a stderr message if not found

All three are line-oriented so they compose with grep, head, etc.

Inspecting Skills

Discover Python code across skills and enable universal imports. Solves the dash-underscore naming mismatch between skill directories (e.g., browsing-bluesky) and Python imports (e.g., browsing_bluesky).

Installation

import sys
sys.path.insert(0, '/home/user/claude-skills')
from inspecting_skills import setup_skill_path, skill_import

Quick Start

Import a Skill

from inspecting_skills import skill_import

# Import by skill name (dash or underscore form)
bsky = skill_import("browsing-bluesky")
posts = bsky.search_posts("python")

# Import specific functions
search, profile = skill_import("browsing-bluesky", ["search_posts", "get_profile"])

Enable Transparent Imports

from inspecting_skills import setup_skill_path

# Configure once at session start
setup_skill_path("/home/user/claude-skills")

# Now import skills directly (underscore form)
from browsing_bluesky import search_posts, get_profile
from remembering import remember, recall

Discover Available Skills

from inspecting_skills import list_importable_skills

skills = list_importable_skills()
for s in skills:
    print(f"{s['name']} -> import {s['module_name']}")

Core Functions

Discovery

FunctionPurpose
discover_skill(path)Analyze a single skill directory
discover_all_skills(root)Find all skills with Python code
find_skill_by_name(name, root)Find skill by name (either form)
skill_name_to_module(name)Convert "browsing-bluesky" to "browsing_bluesky"

Indexing

FunctionPurpose
index_skill(layout)Extract symbols from a discovered skill
index_all_skills(root)Index all skills in repository
generate_registry(root, output)Create registry.json manifest

Importing

FunctionPurpose
setup_skill_path(root)Enable transparent skill imports
skill_import(name, symbols)Import skill or specific symbols
register_skill(name, path)Register skill at custom path
list_importable_skills()List all importable skills

Skill Layouts

Skills organize Python code in three patterns:

1. Scripts Directory

browsing-bluesky/
  SKILL.md
  __init__.py          # Re-exports from scripts/
  scripts/
    __init__.py
    bsky.py            # Main implementation

2. Root-Level Modules

remembering/
  SKILL.md
  __init__.py          # Re-exports functions
  memory.py            # Core functionality
  boot.py
  config.py

3. Simple Package

simple-skill/
  SKILL.md
  __init__.py          # Contains all code

Generating a Registry

Create a registry.json for offline symbol lookup:

from inspecting_skills import generate_registry
from pathlib import Path

registry = generate_registry(
    Path("/home/user/claude-skills"),
    output_path=Path("registry.json")
)

# Registry structure:
# {
#   "version": "1.0.0",
#   "skills": {
#     "browsing-bluesky": {
#       "module_name": "browsing_bluesky",
#       "exports": ["search_posts", "get_profile", ...],
#       "modules": [...]
#     }
#   }
# }

Indexing a Single Skill

from inspecting_skills import discover_skill, index_skill
from pathlib import Path

# Discover the skill layout
layout = discover_skill(Path("/home/user/claude-skills/remembering"))
print(f"Layout: {layout.layout_type}")
print(f"Has __init__.py: {layout.has_init}")
print(f"Python files: {[f.name for f in layout.python_files]}")

# Index symbols
index = index_skill(layout)
for module in index.modules:
    print(f"\n{module.file_path}:")
    for sym in module.symbols:
        print(f"  {sym.kind} {sym.name}{sym.signature or ''}")

Integration with tree-sitting

This skill complements tree-sitting, which extracts code structure at runtime:

  • tree-sitting: AST-derived structure via tree-sitter, multi-language
  • inspecting-skills: Runtime import support, Python-focused, dynamic discovery

Use both together:

  1. tree-sitting for navigation and code review
  2. inspecting-skills for actual code imports and execution

Troubleshooting

Import Errors

# If skill_import fails, check:

# 1. Skill exists and has __init__.py
from inspecting_skills import discover_skill
layout = discover_skill(Path("/path/to/skill"))
print(layout.has_init)  # Must be True for importing

# 2. Skills root is configured
from inspecting_skills import get_skills_root
print(get_skills_root())

# 3. Symbol is exported in __all__
import ast
init_code = open("/path/to/skill/__init__.py").read()
# Check for __all__ definition

Path Not Found

# Manually set skills root
from inspecting_skills import set_skills_root
set_skills_root("/home/user/claude-skills")

API Reference

SkillLayout

@dataclass
class SkillLayout:
    name: str              # "browsing-bluesky"
    path: Path             # Full path to skill directory
    layout_type: str       # "scripts" | "root" | "package" | "none"
    python_files: list[Path]
    has_init: bool         # Can be imported as package
    entry_module: str      # "browsing_bluesky"

SkillIndex

@dataclass
class SkillIndex:
    name: str              # "browsing-bluesky"
    module_name: str       # "browsing_bluesky"
    layout_type: str
    modules: list[ModuleIndex]
    exports: list[str]     # From __all__

Symbol

@dataclass
class Symbol:
    name: str              # Function/class name
    kind: str              # "function" | "class" | "method"
    signature: str | None  # "(self, x: int)"
    line: int | None       # 1-indexed
    docstring: str | None  # First line
    children: list[Symbol] # Methods for classes

Installing Skills

Install skills from github.com/oaustegard/claude-skills to /mnt/skills/user, making them available in the current and future conversations.

Execution

Run the installation script:

bash /mnt/skills/user/installing-skills/scripts/install.sh

The script:

  • Fetches repository contents via GitHub API
  • Downloads SKILL.md for each skill directory
  • Reports installed/updated/skipped counts
  • Excludes: templates, .github, .claude, .uploads directories

Network Requirements

Requires access to:

  • api.github.com - Repository structure listing
  • raw.githubusercontent.com - File downloads

If blocked, report the specific endpoint and suggest checking network settings.

Triggers

Execute installation automatically when:

  • User explicitly requests skill installation/update
  • User references a skill not present in /mnt/skills/user
  • User mentions missing capabilities that match known skill patterns

Verification

Installed skills appear in system's <available_skills> automatically. Manual verification:

ls /mnt/skills/user

Manual Installation

For single skills or testing:

mkdir -p /mnt/skills/user/{skill-name}
curl -s "https://raw.githubusercontent.com/oaustegard/claude-skills/main/{skill-name}/SKILL.md" \
  -o "/mnt/skills/user/{skill-name}/SKILL.md"

Optimizing Skills

Treat the skill document as the parameter under optimization: change it only when the change demonstrably beats the version you already ship. This is the discipline distilled from SkillOpt (microsoft/SkillOpt, arXiv:2605.23904) — its training apparatus dropped, its reproducibility discipline kept. The point is to stop editing skills on intuition and start editing them on evidence.

Core principle

A skill edit is only worth shipping if it strictly improves measured behavior on a held-out check. Most edits that feel like improvements don't move the needle, and some quietly regress. The gate below is what separates a real improvement from a confident guess.

The gate — run it every revision

  1. Assemble a held-out check set. 3–8 representative tasks/prompts the skill should handle well, and it must include the failure(s) that prompted this revision. Keep the set fixed across the revision so before/after scores are comparable.
  2. Hold two versions. best = what you currently ship (never let it silently degrade). candidate = best + your proposed edits.
  3. Score both on the check set. "Run" here = dispatch each check task to the Agent tool (subagent_type=general-purpose) with the skill version in context, or evaluate by hand for small sets. Give the scoring agent the skill version and the task, and nothing else. Never hand it the ledger, your revision notes, or the diagnosis that motivated the edit: it will solve the task from those instead of from the skill, and the score stops measuring the skill. WikiSkill (arXiv:2608.27454) ablated exactly this and lost 2.8 points of final quality, 7.8 on their hardest split, by letting the worker read the improver's knowledge store. Score per criterion, not one collapsed pass/fail. When a task carries several criteria, the criterion that decides accept/reject is the failure that prompted this revision; the others are regression guards that must not get worse. Collapsing criteria masks the win: in the down-skilling-v1.2.0 retro, the edit drove architectural hallucination 60%→0% while an unrelated length criterion stayed 0/5 in both arms — a single combined pass/fail scored that as a 0–0 tie and would have rejected a large, real improvement.
  4. Accept only if candidate strictly beats best on the triggering-failure criterion, with no regression guard worse. Ties → reject, keep best. An edit that doesn't move the needle does not ship.

When the skill's own output is compiled by an Agent (down-skilling and creating-skill produce a prompt an author writes from the SKILL), score ≥2 author samples per version, or fix one author across both arms. A single author sample per arm lets author capability dominate the edit effect: the same down-skilling edit measured 95%→0% with one author pair and 60%→0% with another — real either way, but n=1 cannot tell a real edit from a lucky author.

This two-tier best/candidate split is the heart of it: a working revision can explore, but the shipped skill only ever ratchets upward.

Bounded edits (the "textual learning rate")

Cap edits per revision — default ~4 distinct add/replace/delete operations, fewer as the skill matures. Large speculative rewrites drift and destroy your ability to attribute a regression to a cause. If a revision wants more edits than the budget, rank and keep the top ones (below) and let the rest wait.

Reflect: failures first, then successes

Separate the evidence before proposing edits:

  • Failure reflection. Across the failing cases, find the common, systematic pattern — not a one-off edge case. Propose edits that fix the pattern. Failures take priority in any merge.
  • Success reflection. Across cases that already work, find generalizable patterns worth encoding so they survive future edits. Reinforce; don't duplicate.

For both: edits must generalize (never hardcode task-specific values), and must not duplicate content already in the skill — patch genuine gaps only.

Rank when over budget

When candidate edits exceed the budget, keep them in this priority order:

  1. Systematic impact — fixes a recurring failure across many cases, not one.
  2. Complementarity — fills a real gap rather than restating existing content.
  3. Generality — phrased as a durable principle, not tied to one task/entity.
  4. Actionability — concrete, followable guidance over vague advice.

Drop the rest. They can return next revision if still warranted.

Protect the hard-won core

If a skill has a battle-tested core that routine edits keep eroding, fence it off and treat it as off-limits to fast edits. Revisit it only on a deliberate longitudinal review: compare the same check tasks across several versions to catch slow drift and regressions that single-edit review misses. (SkillOpt fences this region with HTML-comment markers and only rewrites it at epoch boundaries — the same idea, manual cadence.)

Recording rejected proposals

FIRST action of any revision, before you score anything:

python3 scripts/skill_ledger.py check --skill <name> --before best.md --after candidate.md

Exit 1 means this exact edit was proposed before and failed the gate. Read the recorded criterion and score, then propose something else. Do not re-score it.

After the gate decides, record the outcome — accepted or rejected:

python3 scripts/skill_ledger.py record --skill <name> \
    --before best.md --after candidate.md --outcome rejected \
    --criterion "<the triggering failure>" --score-before 0.6 --score-after 0.6

The ledger computes the diff itself and appends it. A rejected candidate is the artifact worth keeping. The edit reverts and the record stays. The next session cannot see this one, which is why the record has to live outside your context rather than in it.

This is WikiSkill's skill-impact.md (arXiv:2608.27454), whose outer loop keeps a never-rolled-back record of every proposal and its fate while the skill itself rolls back. Their proposer is told in prose not to repeat rejected approaches. check makes that mechanical instead, so it no longer depends on anyone having read the ledger. The script lives in claude-workspace at scripts/skill_ledger.py.

Carry memory across revisions

The ledger above holds the artifacts: which diffs were tried and how they scored. remember() holds the judgment the diffs cannot carry. After a revision, record what you learned about editing this skill — which kinds of edits helped, which were brittle, redundant, or harmful — via remember() tagged with the skill name. Before the next revision, recall() it. This is the compounding part: each revision starts smarter than the last, the way SkillOpt's optimizer-side meta-skill conditions its future edits.

Edit mechanics

Edits are literal string operations (the Edit tool): the target text must match exactly or the edit is a silent no-op. Keep targets unique and verbatim. Prefer append / insert-after-heading / replace-exact / delete-exact, and verify each edit landed before scoring.

When NOT to use this

  • Authoring a brand-new skill from scratch → creating-skill.
  • Tracking/rolling back versions during development → versioning-skills.
  • One-off prose with no reuse → just write it.

Checklist

  • Held-out check set assembled (includes the triggering failure), fixed for the revision
  • Edits bounded (~4 max), each generalizable and non-duplicative
  • Failure patterns addressed before success reinforcement
  • Candidate scored per-criterion against best; accept decided by the triggering-failure criterion, others as regression guards; shipped only if strictly better
  • For Agent-compiled artifacts (down-skilling, creating-skill): ≥2 author samples per version, or a fixed author across arms
  • Hard-won core left untouched unless doing a deliberate longitudinal review
  • Candidate run through skill_ledger.py check before scoring; a repeat was dropped, not re-scored
  • Scoring agent given the skill version and the task only, never the ledger or the diagnosis
  • Gate outcome recorded via skill_ledger.py record, rejections included
  • Lesson about editing this skill recorded via remember()

For the deeper "dispatch reflection/scoring to the Agent tool" recipe and the adapted reflection/ranking prompt templates, see references/skillopt-provenance.md.

SURFACE ROUTING — read first

This skill hand-rolls subagent orchestration via raw Anthropic API calls. A managed runtime now does the same job. Which one to use depends on your surface:

  • In Claude Code (incl. CCotw): use the native runtime, NOT this skill. If you can invoke /deep-research, trigger a run with the workflow keyword, set /effort ultracode, or spawn Task subagents — do that instead. The runtime gives 16-concurrent / 1000-agent ceilings, an approval gate, adversarial cross-review, and in-session resume that this skill would otherwise reimplement badly. Dynamic workflows shipped in research preview (Claude Code v2.1.154+, 2026).
  • In claude.ai chat or the bare API (no workflow runtime): use this skill. Parallel API instances over httpx is the only fan-out path here. Proceed below.

Discriminator: do you have a native subagent/Task tool or a workflow command? Yes → native. No → this skill. Never reimplement the runtime where it already exists.

Skill-Aware Orchestration

Orchestrate complex multi-step tasks through a four-phase pipeline that eliminates redundant context processing and reflexive subagent spawning.

When to Use

  • Task requires multiple analytical perspectives (e.g., compare + critique + synthesize)
  • Context is large and subtasks only need portions of it
  • Simple lookups should be self-answered without spawning subagents

When NOT to Use

  • Single-skill tasks (just use the skill directly)
  • Tasks requiring tool use or code execution (this is text-analysis orchestration)
  • Real-time streaming requirements (this is batch-oriented)

Quick Start

import sys
sys.path.insert(0, "/mnt/skills/user/orchestrating-skills/scripts")
from orchestrate import orchestrate

result = orchestrate(
    context=open("report.md").read(),
    task="Compare the two proposed architectures, extract cost figures, and recommend one",
    verbose=True,
)
print(result["result"])

Dependencies

  • httpx (usually pre-installed; pip install httpx if not)
  • No Anthropic SDK required
  • API key: reads ANTHROPIC_API_KEY env var or /mnt/project/claude.env

Four-Phase Pipeline

Phase 1: Planning (LLM)

The orchestrator reads the full context once and produces a JSON plan:

{
  "subtasks": [
    {
      "task": "Compare architecture A vs B on scalability, cost, and complexity",
      "skill": "analytical_comparison",
      "context_pointers": {"sections": ["Architecture A", "Architecture B"]}
    },
    {
      "task": "What is the project budget?",
      "skill": "self",
      "answer": "$2.4M"
    }
  ]
}

Key behaviors:

  • Assigns one skill per subtask from the built-in library
  • Uses "self" for direct lookups (numbers, names, dates) — no subagent spawned
  • Self-answering is an LLM judgment call, not a sentence-count heuristic
  • Context pointers use section headers (structural, edit-resilient)

Phase 2: Assembly (Deterministic Code)

No LLM calls. Extracts context subsets using section headers or line ranges, pairs each with the assigned skill's system prompt, builds prompt dicts.

Phase 3: Execution (Parallel LLM)

Delegated subtasks run in parallel via concurrent.futures.ThreadPoolExecutor. Each subagent receives only its context slice and skill-specific instructions.

Phase 4: Synthesis (LLM)

Collects all results (self-answered + subagent), synthesizes into a coherent response that reads as if a single expert wrote it.

Built-in Skill Library

Eight analytical skills plus one pipeline skill:

SkillPurpose
analytical_comparisonCompare items along dimensions with trade-offs
fact_extractionExtract facts with source attribution
structured_synthesisCombine multiple sources into narrative
causal_reasoningIdentify cause-effect chains
critiqueEvaluate arguments for soundness
classificationCategorize items with rationale
summarizationProduce concise summaries
gap_analysisIdentify missing information
rememberPersist key findings to long-term memory via remembering skill (pipeline-only, runs post-synthesis)

API Reference

orchestrate(context, task, **kwargs) -> dict

Returns:

{
    "result": "Final synthesized response",
    "plan": {...},
    "subtask_count": 4,
    "self_answered": 1,
    "delegated": 3,
    "memory_ids": ["abc123"],  # populated when remember subtasks ran
}

Parameters:

  • context (str): Full context to process
  • task (str): What to accomplish
  • model (str): Claude model, default claude-sonnet-5-5 ($2/$10 per MTok). Sampling parameters (temperature) are only sent to legacy 4.x/3.x ids; Sonnet 5.5, Haiku 5.5 and Opus 5.5 reject them, so on those models the internal temperatures (0.2-0.3) are ignored
  • max_tokens (int): Per-subagent token limit, default 2048
  • synthesis_max_tokens (int): Synthesis token limit, default 4096
  • max_workers (int): Parallel subagent limit, default 5
  • skills (dict): Custom skill library (merged with built-in)
  • persist (bool): Auto-append a remember subtask to store findings, default False
  • verbose (bool): Print progress to stderr

CLI

python orchestrate.py \
    --context-file report.md \
    --task "Analyze this report" \
    --verbose --json

Extending the Skill Library

from skill_library import SKILLS

custom_skills = {
    **SKILLS,
    "code_review": {
        "description": "Review code for bugs, style, and security",
        "system_prompt": "You are a code review specialist...",
        "output_hint": "issues_list with severity and fix suggestions",
    }
}

result = orchestrate(context=code, task="Review this PR", skills=custom_skills)

Persisting Findings with remember

remember is a pipeline skill — it executes in Phase 4 after synthesis, not as a parallel subagent. It uses LLM distillation to extract the key insight from the synthesized result, then writes it to long-term memory via the remembering skill.

Two ways to activate persistence

1. persist=True (automatic)

result = orchestrate(
    context=open("report.md").read(),
    task="Compare approaches A and B",
    persist=True,  # auto-injects a remember subtask
    verbose=True,
)
print(result["memory_ids"])  # ['abc123']

2. Planner-emitted (explicit)

The orchestrator planner can emit remember as a subtask when the task description implies storage:

{
  "task": "Store the key findings from this analysis",
  "skill": "remember",
  "context_pointers": {}
}

Requirements

  • remembering skill must be installed (/mnt/skills/user/remembering or /home/user/claude-skills/remembering)
  • Turso credentials must be available (auto-detected by the remembering skill)
  • If unavailable, persistence is skipped silently and memory_ids returns []

Architecture Details

See references/architecture.md for design decisions, token efficiency analysis, and comparison with SkillOrchestra (arXiv 2602.19672).

Versioning Skills

Use git to track changes during skill development. Initialize repos after creating skills, commit after each logical change, and use git commands to compare versions or revert mistakes.

When Creating a New Skill

After running init_skill.sh, immediately initialize git:

cd /home/claude/skill-name
git init
git add .
git commit -m "Initial commit: skill structure"

When Editing Skills

After each logical change (adding a section, fixing an example, refactoring), commit:

cd /home/claude/skill-name
git add .
git commit -m "Add: validation workflow pattern"

Commit message patterns:

  • "Add [feature]: description" - New functionality
  • "Fix [issue]: description" - Bug fixes
  • "Update [section]: description" - Content changes
  • "Refactor [component]: description" - Structural changes
  • "Remove [feature]: description" - Deletions

When User Asks "What Changed?"

Never display diffs inline — redirect to files and provide links (see below). Only create a diff or changelog when the user explicitly asks ("what changed?", "show differences").

Don't preemptively create:

  • CHANGELOG.md files
  • Change documentation
  • "Here's what I modified" summaries

Why: The updated code/docs ARE the documentation. Creating separate changelogs wastes tokens and duplicates information.

When user asks, show commit history:

cd /home/claude/skill-name
git log --oneline

Save diff to file (prevents token waste):

cd /home/claude/skill-name
git diff <commit-hash-1> <commit-hash-2> > /mnt/user-data/outputs/changes.diff

Then provide: [View changes](computer:///mnt/user-data/outputs/changes.diff)

For multiple diffs:

# Changed files list
git diff --name-only <commit-1> <commit-2> > /mnt/user-data/outputs/changed-files.txt

# Full diff
git diff <commit-1> <commit-2> > /mnt/user-data/outputs/full-diff.diff

# Summary stats
git diff --stat <commit-1> <commit-2> > /mnt/user-data/outputs/diff-stats.txt

Wrong: git diff <commit-1> <commit-2> (displays in stdout, wastes tokens) Right: git diff <commit-1> <commit-2> > /mnt/user-data/outputs/diff.txt (file + link)

Reverting Commits or Discarding Work

Undo last commit (keep uncommitted changes):

cd /home/claude/skill-name
git reset --soft HEAD~1

Undo last commit (discard all changes):

git reset --hard HEAD~1

Revert specific commit (creates new commit, preserves history):

git revert <commit-hash>

Discard uncommitted edits (restore to last commit):

git restore .

Prefer git revert over git reset --hard to preserve history.

When Testing Experimental Changes

Create a branch before risky modifications:

cd /home/claude/skill-name

# Create and switch to experiment branch
git checkout -b experiment-new-approach

# Make changes, test
# ... edit files ...
git add .
git commit -m "Experiment: alternative validation"

# If successful, merge back
git checkout main
git merge experiment-new-approach
git branch -d experiment-new-approach

# If failed, abandon and return to main
git checkout main
git branch -D experiment-new-approach

When Comparing Two Skill Versions

If user uploads or provides two versions:

cd /home/claude
mkdir -p compare

# Extract both versions
unzip /mnt/user-data/uploads/skill-v1.zip -d compare/v1
unzip /mnt/user-data/uploads/skill-v2.zip -d compare/v2

# Initialize git in each
cd compare/v1 && git init && git add . && git commit -m "Version 1"
cd ../v2 && git init && git add . && git commit -m "Version 2"

# Compare
cd ../v1
git diff --no-index . ../v2

Or use diff directly without git:

diff -ur compare/v1 compare/v2

When Packaging Skills

Before zipping, verify clean state:

cd /home/claude/skill-name
git status  # Should show no uncommitted changes
git log --oneline  # Review history

# Package (excludes .git automatically with -x)
cd /home/claude
zip -r /mnt/user-data/outputs/skill-name.zip skill-name/ -x "*.git*"

Workflow Integration

During skill creation:

  1. Run init_skill.sh
  2. Immediately: git init && git add . && git commit -m "Initial structure"
  3. Edit SKILL.md
  4. Commit: git add . && git commit -m "Add: core documentation"
  5. Continue editing → commit after each major change

During skill editing:

  1. Make change with str_replace or bash
  2. Test if needed
  3. Commit: git add <file> && git commit -m "Fix: corrected example"
  4. Repeat

Before delivery:

  1. Review history: git log --oneline
  2. Verify clean: git status
  3. Package with -x to exclude .git

Configuration

Set git identity once per session to avoid prompts:

git config --global user.name "Claude"
git config --global user.email "skill-dev@claude.ai"

Common Issues

"not a git repository" → Run git init first

"nothing to commit"
→ No changes made, or forgot git add

Commit message editor opens → Always use -m "message" with commit

Best Practices

Commit after each logical change, not every keystroke. Use descriptive commit messages in present tense. Create branches for experimental changes. Use git log --oneline frequently to track progress.

Limitations

Git repos in /home/claude reset between sessions. Version control only persists within a single development session. Network restrictions prevent push/pull to remote repos.

Writing Instructions for Claude

Principles and patterns for writing instructions that Claude follows reliably — whether as project instructions, standalone prompts, or skill content.

Overlap notice. crafting-instructions carries the same five core principles and a fuller format-decision framework. The two were written independently and never reconciled; a 2026-08-24 retrieval measurement put their descriptions at 0.843 cosine, the most confusable pair in the 92-skill catalogue. Until they are merged, this skill owns writing quality and crafting-instructions owns the format decision.

Choosing the Right Format

Determine format before writing. The wrong container undermines good instructions.

Project instructions — persistent context for a workspace. Use when all conversations in a project need shared knowledge, team collaboration context, or initiative-specific behavior. Signals: "for this project," "all conversations about X," "team workspace." Read references/project-instructions.md for detailed guidance.

Standalone prompts — ephemeral, conversational, immediate. Use for one-off requests, ad-hoc direction, or conversational refinement. Signals: "for this task," "right now," "just this once." Read references/standalone-prompts.md for techniques.

Skill content — portable expertise that loads on-demand across contexts. Use when capability is needed across multiple projects, procedural knowledge applies broadly, and instructions should activate automatically on relevant triggers. Signals: "every time I," "whenever," "reusable," "teach Claude how to." For building full skills (structure, testing, iteration, packaging), use the skill-creator skill.

Combined approaches work well: project instructions provide "what you need to know" (reference material, context) while skills provide "how to do things" (methods, procedures). Read references/choosing-formats.md for detailed comparison and migration patterns.

Core Writing Principles

These apply to ALL instruction formats. They are ordered by impact.

1. Imperative Construction

Frame as direct commands. Imperative language reduces ambiguity and signals that the instruction is not optional.

  • ❌ "Consider creating X" → ✅ "Create X when conditions Y"
  • ❌ "You might want to search" → ✅ "Search for"
  • ❌ "Try to optimize" → ✅ "Optimize by"

2. Context and Motivation

Explain WHY requirements exist. Claude uses reasoning about purpose to make better decisions in unstated edge cases, and WHY context is particularly valuable for Opus's autonomous judgment.

  • ❌ "Use formal tone"
  • ✅ "Use formal tone because documentation targets enterprise clients expecting authoritative voice"

A requirement without context is a rule Claude follows mechanically. A requirement with context is a principle Claude can extend intelligently.

3. Positive Directive Framing

State WHAT to do, not what NOT to do. Negative instructions force Claude to infer the desired alternative — positive instructions state it directly.

  • ❌ "Don't use bullet points" → ✅ "Write in flowing paragraph form"
  • ❌ "Avoid technical jargon" → ✅ "Use accessible language for beginners"
  • ❌ "Never output raw data" → ✅ "Present data with interpretation and context"

When a negative constraint is truly necessary, pair it with the positive alternative: "Present in prose paragraphs, not bullet lists, because flowing text is more conversational for learning contexts."

4. Strategic Over Procedural

Provide goals and decision frameworks rather than step-by-step procedures. If Claude can infer the procedure from the goal, specify only the goal.

  • Specify: success criteria, boundaries, decision frameworks, quality standards
  • Minimize: sequential steps, detailed execution, operations Claude can determine from goals

This principle scales with model capability — Opus needs less procedural detail than Haiku (see Model-Aware Calibration below).

5. Trust Base Behavior

Claude's system prompt already handles citation protocols, copyright, safety, general tool usage, artifact creation, conversational tone, and accuracy standards. Only specify project- or domain-specific deviations from these defaults.

Duplicating system prompt behavior wastes tokens and can create conflicting signals. Test whether Claude already does what you want before adding instructions for it.

Model-Aware Calibration

Instructions may execute across Haiku, Sonnet, and Opus. The tiers still differ in how much procedural detail they need — treat that as a direction to lean, not a ratio to compute; current models across all three tiers follow instructions more literally than the generation this calibration was first written against, so over-specifying for any of them now costs more than it buys.

Haiku: Lead with explicit imperative commands and concrete decision trees. Provide exact conditions, specific fallbacks, and examples for the scenarios that matter. Structure as: "When X, do Y. When Z, do W."

Sonnet: Provide decision frameworks with explicit conditions alongside a couple of concrete examples demonstrating desired patterns. Balance procedural clarity with strategic context.

Opus: Emphasize strategic goals, reasoning context, and principles over procedures. Opus uses rich WHY context for autonomous judgment in edge cases; one clear example often suffices, and overly procedural instructions constrain it unnecessarily. Frame as: "Goal is X because Y. Apply judgment for unstated cases."

Practical layering pattern: Structure instructions so imperative commands come first, followed by decision frameworks and examples, with strategic reasoning and WHY context woven throughout. A single instruction set serves all three models when layered well.

When uncertain about target model: Optimize for Sonnet — it degrades gracefully on both neighbors.

Example Quality Awareness

Examples are the most powerful and most dangerous instruction tool. Current Claude models learn ALL patterns from examples — format, verbosity, structure, tone, terminology — including patterns you didn't intend to teach.

Rules for examples:

  • Audit every detail: if the example uses bullets but you want prose, Claude defaults to bullets
  • Ensure ALL aspects of every example demonstrate desired behavior
  • Better to omit examples entirely than include ones with mixed signals
  • One well-crafted example outperforms three sloppy ones

Model-specific impact:

  • Sonnet: Examples are highly influential — include 2–3 that perfectly demonstrate desired patterns
  • Opus: Examples help but Opus weights explicit principles more heavily — one clear example suffices, omit entirely if examples can't perfectly align with all requirements
  • Haiku: Examples are critical — provide complete input/output pairs covering each expected scenario

Structural Simplicity

Default to clear organization using headings, whitespace, and natural paragraph flow. Explicit language stating relationships is usually sufficient.

Use structured markup (XML tags, JSON schemas) only when separating distinct content types in complex scenarios, when absolute certainty about content boundaries is required, or for API-driven workflows needing structured parsing.

Decision rule: Can this be organized with headings? → Do that first. Only reach for XML/JSON when headings genuinely fail to create clarity.

Extended Thinking Guidance

Extended thinking is a UI toggle, not controllable via prompt phrasing. In instructions:

  • Make the assistant aware it exists as a feature
  • Provide domain-specific indicators for when to suggest it
  • ❌ Do NOT include "trigger phrases" like "think carefully" — they don't activate extended thinking

Pattern: "For tasks involving [specific complexity], suggest enabling Extended thinking, briefly explaining why it would help for THIS task."

Complexity Scaling

Match instruction complexity to task needs. Before adding complexity, ask: could a simpler formulation work equally well?

Simple task → Clear, concise prompt with explicit output expectations Medium task → Structured guidance with decision frameworks and 1–2 examples Complex task → Comprehensive instructions with model-aware layering + suggest extended thinking

The best instructions use the minimum complexity that produces reliable results.

Common Mistakes

System prompt duplication — "Use web_search for current info, cite sources." This wastes tokens and adds no value. Omit unless the project has specific deviations from default behavior.

Negative framing without alternatives — "Don't use lists, never be verbose." State the positive: "Present in natural prose paragraphs."

Fake thinking triggers — "Use 'think carefully' for deep thinking." Phrases don't control extended thinking. Suggest the UI toggle for specific complexity types.

Procedural micromanagement — "Step 1: Analyze. Step 2: Search. Step 3: Synthesize." Instead: "Research goal: X. Quality standard: Y. Present findings as Z."

Contextless requirements — "Always use formal tone." Add WHY: "Use formal tone for audit reports because regulators expect authoritative voice."

Imperfect examples — Example uses bullets when you want prose. Either create perfect examples or omit them entirely.

Quality Checklist

Before delivering any instruction set:

Does it say what to do? Imperative commands, positive framing, clear success criteria.

Does it say why? Context and motivation for non-obvious requirements, enabling intelligent edge-case handling.

Is it calibrated? Appropriate detail density for the target model, with layered structure if model is unknown.

Is it minimal? No system prompt duplication, no unnecessary complexity, no procedural steps Claude can infer from goals.

Are examples safe? Every aspect of every example demonstrates desired behavior, or examples are omitted.

Format-Specific References

Sponsors

Details

Marketplace
oaustegard/claude-skills
Source
plugins/skill-development
Category
Skill Development
License
MIT
Keywords
crafting-instructions, creating-skill, finding-skills, inspecting-skills, installing-skills, optimizing-skills, orchestrating-skills, versioning-skills, writing-instructions

More from oaustegard/claude-skills

All 14