
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-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add oaustegard/claude-skills.
Contents
Discovered from sourceSkills 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
- references/creating-skills.md - For building full Skills
- references/project-instructions.md - Detailed guidance for Project instructions
- references/standalone-prompts.md - Effective prompt patterns
- references/skill-vs-project.md - Detailed comparison and decision guidance
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
| Situation | Use |
|---|---|
| Whether the instruction should be a skill, project instructions or a prompt | crafting-instructions |
| Sentence-level quality of instruction prose | writing-instructions |
| Revising an existing skill that has evidence of underperforming | optimizing-skills |
| Project-specific context, one-off tasks | project instructions or a prompt |
Procedure
-
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". -
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>200MBare 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.
-
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. -
Check confusability from
oaustegard/claude-workspace:python3 scripts/skill_confusability.py --skills <skills-root> --queries q.jsonq.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. -
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 | actiontable. 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.
-
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. -
Write the CHANGELOG entry: what changed, provenance, measurements, and the dated story of any diagnosed failure the body now encodes as a row.
-
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. -
Test on three real scenarios — simple, complex, edge — and fix what actually happened.
-
Package for claude.ai upload when needed:
zip -r <name>.zip <name>/ && unzip -l <name>.zipREADME.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
| Signal | Action |
|---|---|
| Skill does not load; no error | an unquoted : or an angle bracket in the description; run quick_validate.py |
| Skill loses its own queries | description too long or reusing a sibling's phrases; cut to ~250 characters with three phrasings |
| Skill wins queries it should ignore | a disclaimer in the description; delete it and move routing into the body |
| Body explains, tells history or sells | move 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 change | the release bot used a shared commit subject; edit it and bump separately next time |
| Agent applies the skill where it does not fit | the 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.pypasses; 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 | actionrows - 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 casesreferences/bundled-resources.md— scripts, references and assets patternsreferences/advanced-patterns.md— validation workflows, multi-stage skillsreferences/optimization-techniques.md— token budgetreferences/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
search "<what you want to do>"— get 3–10 ranked candidatesshow <top-pick>— read its SKILL.md- 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 linesearch: tab-separated<name>\t<description (truncated to 200 chars)>, one per lineshow: 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
| Function | Purpose |
|---|---|
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
| Function | Purpose |
|---|---|
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
| Function | Purpose |
|---|---|
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:
tree-sittingfor navigation and code reviewinspecting-skillsfor 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 listingraw.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
- 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.
- Hold two versions.
best= what you currently ship (never let it silently degrade).candidate=best+ your proposed edits. - 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. - Accept only if
candidatestrictly beatsbeston the triggering-failure criterion, with no regression guard worse. Ties → reject, keepbest. 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:
- Systematic impact — fixes a recurring failure across many cases, not one.
- Complementarity — fills a real gap rather than restating existing content.
- Generality — phrased as a durable principle, not tied to one task/entity.
- 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 checkbefore 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 theworkflowkeyword, 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 httpxif not) - No Anthropic SDK required
- API key: reads
ANTHROPIC_API_KEYenv 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:
| Skill | Purpose |
|---|---|
analytical_comparison | Compare items along dimensions with trade-offs |
fact_extraction | Extract facts with source attribution |
structured_synthesis | Combine multiple sources into narrative |
causal_reasoning | Identify cause-effect chains |
critique | Evaluate arguments for soundness |
classification | Categorize items with rationale |
summarization | Produce concise summaries |
gap_analysis | Identify missing information |
remember | Persist 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 processtask(str): What to accomplishmodel(str): Claude model, defaultclaude-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 ignoredmax_tokens(int): Per-subagent token limit, default 2048synthesis_max_tokens(int): Synthesis token limit, default 4096max_workers(int): Parallel subagent limit, default 5skills(dict): Custom skill library (merged with built-in)persist(bool): Auto-append aremembersubtask to store findings, default Falseverbose(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
rememberingskill must be installed (/mnt/skills/user/rememberingor/home/user/claude-skills/remembering)- Turso credentials must be available (auto-detected by the remembering skill)
- If unavailable, persistence is skipped silently and
memory_idsreturns[]
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:
- Run init_skill.sh
- Immediately:
git init && git add . && git commit -m "Initial structure" - Edit SKILL.md
- Commit:
git add . && git commit -m "Add: core documentation" - Continue editing → commit after each major change
During skill editing:
- Make change with str_replace or bash
- Test if needed
- Commit:
git add <file> && git commit -m "Fix: corrected example" - Repeat
Before delivery:
- Review history:
git log --oneline - Verify clean:
git status - 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
- references/project-instructions.md — Writing project instructions: role definition, quality standards, decision frameworks, domain tool patterns
- references/standalone-prompts.md — Crafting effective prompts: specificity, context, examples, complexity scaling
- references/choosing-formats.md — When to use skills vs projects vs prompts, combined approaches, migration patterns
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- social-and-lifestylev1.0.0
- web-and-retrievalv1.0.4
- ai-and-reasoningv2.9.1
- code-intelligencev2.6.0
- data-and-visualizationv1.0.0
- deciding-with-confidencev0.4.0
- declaudingv0.14.0
- delegating-with-contextv0.3.0
- development-toolsv1.2.1
- environment-and-configv2.0.0
- github-and-gitv2.0.1
- knowledge-and-memoryv1.3.0
- media-processingv2.3.0