Claude Code Skills: Getting Differentiated Output

Claude’s default output is optimized for the average request. Ask for a landing page and you get a landing page that looks like every other AI-generated landing page – blue gradient, three feature cards, a CTA button. Ask for a customer email and you get corporate-polished prose that sounds like nobody in particular wrote it.

Skills fix this. A skill is a prompt file that pushes Claude into a specific, lower-probability region of its output space – one that encodes your taste, your domain knowledge, your brand, and your hard-won failure modes. The output stops looking like everyone else’s.

---

The Default Output Problem

Without a skill, Claude answers from the center of the distribution. That center is heavily weighted toward patterns that appeared frequently in training: generic SaaS copy, tutorial-style code, formal prose. High probability, low differentiation.

A skill doesn’t add constraints for their own sake. It narrows the search space to a region that reflects something specific – your company’s voice, your engineering conventions, your knowledge of what goes wrong in your domain.

Bad skill:

# Landing Page Skill
Create a high-converting landing page with a hero section,
features, social proof, and a call to action.

This just restates what Claude would do anyway. It freezes generic behavior into a reusable file and calls it a skill.

Good skill:

# Landing Page Skill
Our landing pages follow the "problem before solution" structure.
Open with a single sentence naming the pain, not the product.
We never use the word "streamline". We never use stock photo metaphors
(puzzle pieces, lightbulbs, handshakes). Our CTA copy comes from
customer interviews -- look at /ref/customer-quotes.md first.
Hero headlines are under 8 words. No exclamation marks.

The second skill encodes taste and real constraints. Every output is now shaped by something Claude can’t infer from the request alone.

---

What Goes in a Good Skill

1. Domain Knowledge Claude Doesn’t Have

Claude’s training has a cutoff and no access to your internals. A skill is how you close that gap.

# Competitor Analysis Skill
Our main competitor changed pricing in Q4 2025. They now charge
per-seat above 10 users. This is a weakness -- reference it when
comparing. See /ref/competitor-notes.md for current positioning.

We have won deals by emphasizing our single-instance deployment
model. Enterprises with data residency requirements respond well
to this. Multi-tenant SaaS is a blocker for them, not a feature.

2. Failure Modes – The Gotchas Section

This is the most valuable part of any skill. Every time Claude makes a mistake, you add a gotcha. Over time the skill becomes a dense knowledge base of what not to do.

## Gotchas

- Never promise specific delivery timelines to customers. We got
  burned on this. Say "typically" or "depends on your setup".
- Don't recommend the REST API for real-time use cases. It's
  polling-based. Push them toward the WebSocket endpoint.
- When a customer says "integration", ask which system first.
  They almost always mean Salesforce but sometimes mean SAP,
  and the answer is completely different.
- Never say "easy" or "simple" -- it sounds dismissive when
  something actually is hard for them.

You build this list iteratively. Claude gives a wrong answer, you add the rule, the next run is better. It works exactly like onboarding a new employee.

3. Reference Files for Deep Context

Keep the main skill.md focused on goals and rules. Move large reference material into separate files and tell the skill when to load them.

/skills/customer-success/
  SKILL.md          ← goals, gotchas, workflow
  ref/
    pricing.md      ← current pricing tiers
    competitor.md   ← competitive positioning
    objections.md   ← common objections and responses
    personas.md     ← buyer personas and what they care about

In SKILL.md:

Before drafting a response about pricing, read ref/pricing.md.
For competitive questions, read ref/competitor.md first.
Do not load all reference files by default -- only load what
the current question requires.

This is progressive disclosure. Claude only loads what’s relevant, keeping context high-signal instead of diluted.

---

Avoiding Railroading

A rigid skill that specifies every step produces brittle output. It works for one situation and breaks for anything adjacent.

Railroaded (bad):

Interview process:
1. Ask about their last role
2. Ask about a technical challenge
3. Ask about team conflict
4. Ask about their 5-year plan
5. Score each answer 1-5

Claude will follow this script for a junior engineer and a VP of Engineering alike, even though those interviews have completely different goals.

Goal-oriented (good):

Interview process:
Goal: assess whether this person can do the specific job, not
whether they interview well.

For senior roles: focus on judgment and system design decisions
they've actually made. Ask for specifics -- names, dates,
outcomes. Generic answers about "best practices" are a yellow flag.

For junior roles: focus on learning speed and intellectual
curiosity. They don't have experience to draw from; probe for
how they approach unfamiliar problems.

Gotchas:
- Don't ask "where do you see yourself in 5 years" -- it
  produces rehearsed answers and tells you nothing useful.
- If they haven't asked any questions by the halfway point,
  ask them directly what they want to know about the role.

The second version gives Claude the context to adapt. The questions change based on the candidate; the goal stays constant.

---

Scripts: Stop Re-Reading Docs

For skills that pull external data, have Claude write a reusable script on the first run. From then on, Claude calls the script instead of re-reading API docs and reinventing requests.

Example: Stripe revenue script

On first use, Claude generates scripts/stripe_revenue.py:

#!/usr/bin/env python3
"""Fetch MRR and recent charges from Stripe."""
import stripe, os, sys
from datetime import datetime, timedelta

stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

def get_mrr():
    subs = stripe.Subscription.list(status="active", limit=100)
    mrr = sum(
        s.items.data[0].price.unit_amount * s.items.data[0].quantity / 100
        for s in subs.auto_paging_iter()
        if s.items.data[0].price.recurring.interval == "month"
    )
    return mrr

def recent_charges(days=7):
    since = int((datetime.now() - timedelta(days=days)).timestamp())
    charges = stripe.Charge.list(created={"gte": since}, limit=100)
    return [{"amount": c.amount/100, "desc": c.description, "date": c.created}
            for c in charges.auto_paging_iter() if c.paid]

if __name__ == "__main__":
    print(f"MRR: ${get_mrr():,.0f}")
    print(f"Recent charges (7d): {recent_charges()}")

Now the skill just says:

For revenue questions, run scripts/stripe_revenue.py.
Do not re-fetch Stripe data by writing inline API calls.

Common scripts worth generating:

Script	What it does
stripe_revenue.py	MRR, churn, recent charges
analytics_summary.py	Page views, top pages, traffic sources
youtube_stats.py	Video views, subscriber delta, top performing content
github_activity.py	PRs merged, issues closed, contributor activity
db_snapshot.py	Row counts, recent records from key tables
uptime_check.py	Service health, recent errors from logs

Each script is written once, tested, and then called by reference. Claude composes them rather than re-reading documentation every run.

---

Hooks: Restricting What a Skill Can Do

Hooks let you define exactly what a skill is allowed to execute. This is a security boundary, not just a convenience.

A skill that reads analytics data should not be able to make write calls or read environment variables beyond what it needs. Hooks enforce this:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qv 'scripts/'; then echo 'Only scripts/ directory allowed'; exit 1; fi"
        }]
      }
    ]
  }
}

This prevents prompt injection attacks – a malicious value in external data telling Claude to run an unrelated command – by limiting Bash execution to the scripts directory.

---

Skills as Operational Packages

Each skill is a self-contained package for one task:

/skills/weekly-report/
  SKILL.md
  scripts/
    stripe_revenue.py
    analytics_summary.py
    github_activity.py
  ref/
    report-format.md
    previous-report.md     ← updated each run
  logs/
    2026-03-12-report.md   ← output from last week

The logs directory is particularly valuable. Claude reads the previous output to spot trends, compare week-over-week, and notice anomalies without you having to say “compare to last week” every time.

Skills can call other skills. A weekly-report skill might call an analytics skill to pull traffic data and a revenue skill to pull MRR. Keep them narrow – one skill, one domain – and compose at the top level.

---

Sharing Skills

A skill built for your setup can be shared if it includes a setup wizard and a config file.

# Setup (first run only)
If /config.json does not exist, run the setup wizard:
1. Ask for the Stripe account ID
2. Ask for the Google Analytics property ID
3. Ask for the Slack channel name for report delivery
4. Write these to /config.json

{
  "stripe_account": "acct_...",
  "ga_property": "UA-...",
  "slack_channel": "#weekly-metrics"
}

Anyone who clones the skill runs it once, answers four questions, and has a personalized version. The skill itself doesn’t change.

---

Building Skills Iteratively

A skill is never finished. The workflow:

1. Write a minimal skill – goal, context, one or two gotchas
2. Run it – observe where Claude goes wrong
3. Add the gotcha – one line describing the failure and the rule
4. Repeat

After ten runs, the skill knows your domain. After thirty, it’s better than a new hire on day one.

The best skills in production don’t look polished – they look like a document written by someone who has been burned before and is making sure it doesn’t happen again. That roughness is the signal. It means the skill encodes real experience.