Building reusable prompts (skills)

WITHOUT skill                          WITH skill
──────────────────────────────────────────────────────────────────
Engineer types the 200-word prompt     Engineer types:
every time                              /payment-team-weekly

Inconsistent across team members        Same instructions run every time

Drift over time                         Edit the file → everyone benefits

Pasted into Slack ad-hoc                Versioned in git

Tribal knowledge ("ask jane,            Tooling
 she has the good prompt")              ("/payment-team-weekly")

LOCATION:
  ~/.claude/skills/<name>.md       (per-user, available everywhere)
  .claude/skills/<name>.md         (per-project, committed to repo)

STRUCTURE:
  ---
  description: One-line description for the menu
  args:                        (optional)
    team:
      description: Team name
      required: true
    days:
      description: Time window
      default: "7"
  ---

  # Instruction body (markdown)

  Step-by-step instructions for the agent.
  Can reference MCP tools by name.
  Can include examples.
  Can use {{var}} for parameters.

LOCATION:
  .cursor/commands/<name>.md  (per-project)

STRUCTURE: similar to Claude Code; refer to Cursor docs for exact spec.

---
description: Weekly cost summary for the payment team
---

Use the zopnight MCP server. Do the following:

1. Call get_costs filtered to last 7 days, team=payment-team
2. Call get_costs same filter, previous 7 days
3. Call get_recommendation_summary for payment-team
4. List open recommendations with savings > $100/mo

Output as a markdown table:
  | Metric | This Week | Last Week | Delta |

Followed by:
  ## Open items
  Top 3 recommendations by savings

  ## Suggested actions
  2-3 specific next steps for the team

---
description: Cost summary for any team (parameterized)
args:
  team:
    description: Team name (e.g., payment-team, ml-infra)
    required: true
  days:
    description: Time window in days
    default: "7"
---

Use zopnight MCP. Get costs for team={{team}} for last {{days}} days.
Compare to previous {{days}} days.

Output:
  | Metric | This Period | Previous Period | Delta % |

Top 3 resources by cost growth.
Top 3 open recommendations.

/cost-summary --team=payment-team --days=7
/cost-summary --team=ml-infra --days=14
/cost-summary --team=data-platform --days=30

1. REPORTS (regular structured outputs)
   /weekly-cost-summary
   /monthly-team-report
   /quarterly-savings-report
   /budget-status-snapshot

   Characteristic: predictable shape, run on cadence, consumed
   by team or leadership.

2. CHECKS (audit / verification)
   /tag-coverage-check
   /pat-rotation-check
   /idle-resource-check
   /multi-az-compliance-check

   Characteristic: pass/fail criteria, list of exceptions,
   driven by policy.

3. DRAFTS (writing output)
   /draft-incident-comms
   /draft-postmortem-skeleton
   /draft-budget-justification
   /draft-chargeback-explanation

   Characteristic: produces text the engineer edits and ships;
   structures recurring writing.

4. EXPLORATIONS (research / investigation)
   /investigate-cost-spike
   /research-savings-opportunities
   /compare-teams
   /find-similar-resources

   Characteristic: open-ended; agent does the legwork; engineer
   reads and decides.

AD-HOC PROMPT (typed fresh each time):
  "List all RDS not in Multi-AZ across all accounts"

↓ ADD team context, parameters, output format ↓

SKILL (team-specific):
  /rds-multi-az-check
    Filter: team={{team}}
    Account scope: {{accounts}}
    Output: table with resource_id, region, account, owner
    Highlight: prod resources (require Multi-AZ by policy)

USAGE:
  $ claude
  > /rds-multi-az-check --team=payment-team
  → returns formatted table; engineer copies into JIRA

RE-USABLE skills tend to be:
  ✓ Specific in scope (one team, one workflow)
  ✓ Parametrized for variation
  ✓ Output-format prescriptive (markdown table, JSON, etc.)
  ✓ Idempotent (same input → same output)
  ✓ Self-documenting (description field is clear)
  ✓ Quick (one or two MCP calls, not ten)

NOT re-usable:
  ✗ "Investigate this problem" (too vague)
  ✗ "What do you think about cost?" (no specific output)
  ✗ One-off questions
  ✗ 30-step workflows (LLM loses focus; split it)
  ✗ Requires constant editing each run (parametrize instead)

MODE 1: Per-user (~/.claude/skills/)
  Each engineer copies the file to their machine
  Simple to start; drifts over time
  Best for: personal preferences not relevant to team

MODE 2: Project-scoped (.claude/skills/)
  Committed to repo; auto-loaded for anyone with the repo
  Same skills for everyone touching the repo
  Best for: team-specific or repo-specific workflows

MODE 3: Centralized (team wiki + sync script)
  Master copy in wiki / shared folder
  Engineers run sync script to pull latest
  Versioned via wiki history; signed off by maintainer
  Best for: cross-team standards (org-wide skill library)

GOOD names (specific, scannable):
  /payment-cost-weekly
  /ml-infra-monthly-report
  /platform-budget-status
  /rds-multi-az-check

BAD names (vague, collision-prone):
  /cost
  /report
  /check
  /weekly

PATTERN: <team-or-domain>-<workflow>-<cadence>
  /finops-savings-report-quarterly
  /sre-incident-cost-comms-draft

SKILL changes over time. Track:
  - What changed
  - Why (which questions evolved? new data sources?)
  - Who maintains (single owner is best)
  - Last reviewed date
  - Breaking changes vs additive changes

Use git for version history.

Add a header comment in the skill file:
  ---
  description: Payment team weekly cost summary
  maintainer: jane@platform
  last_reviewed: 2026-05-21
  ---

M6.4.L4 covers versioning + maintenance in depth.

PITFALL                                  FIX
──────────────────────────────────────────────────────────────────
Skill returns generic output             Add specific output format
                                          ("Return as table with cols X, Y")

Works for one engineer, not another      PAT scope or permissions differ
                                          Add "requires PAT scopes: ..."
                                          in skill header

Skill becomes outdated as MCP evolves    Quarterly review
                                          (M6.4.L4)

Skill too long; LLM loses focus          Split into smaller skills
                                          Chain them via instructions

Hard to maintain because no docs         Use the description field well
                                          Add inline comments

"It worked last week, broke today"       Pin assumptions in the prompt
                                          (specific tool names, filter
                                          syntax) so changes are visible

SKILL CALLS COMBINATION:
  1. MCP tools (data from ZopNight)
  2. Bash commands (read local files, generate plots)
  3. File reads (load context from team wiki)
  4. Write to file (save output to a path)

EXAMPLE: weekly report skill:
  1. Pull data from ZopNight MCP
  2. Format as table
  3. Append last week's report from disk
  4. Write to docs/weekly-cost/2026-W21.md
  5. Open in editor for review

SKILL EXECUTION cost:
  ZopNight MCP calls: free
  LLM inference: paid by the engineer's AI tool subscription

TYPICAL skill costs:
  Short report skill (3 MCP calls + 500-word output):
    ~$0.01-0.05 per invocation (Claude/GPT-4 pricing)

  Complex investigation (10+ MCP calls + analysis):
    ~$0.50-2.00 per invocation

  Vs. engineer's time:
    Even at $0.50/skill-run, beats 10 minutes of manual analysis
    at $100/hr ($16.66/run).

WEEK 1 (creation):
  PAYMENT-TEAM lead writes the first skill.

  EDIT .claude/skills/payment-cost-weekly.md:

  ---
  description: Payment team weekly cost summary
  maintainer: jane@platform
  ---

  Use zopnight MCP. Generate this week's payment-team cost summary:

  1. get_costs (team=payment-team, last 7 days)
  2. get_costs (team=payment-team, previous 7 days)
  3. list_resources (team=payment-team, sorted by 7-day cost growth)
  4. get_recommendation_summary (team=payment-team)

  Output:
    ## Payment-Team Weekly Cost
    | Metric | This Week | Last Week | Delta |

    Top growers (top 3 by % change)

    Open recommendations (top 3 by savings)

    Action items for the team

  COMMIT to repo. Push to team's main branch.

WEEK 2 (adoption):
  Jane's teammates pull the repo.
  /payment-cost-weekly now appears in their slash menu.
  Friday: all 4 engineers run it before standup.
  Same format, same numbers, no negotiation.

WEEK 3 (refinement):
  Engineer asks: "can we add cost-by-account breakdown?"
  Jane edits the skill, adds:
    5. get_cost_by_provider (team=payment-team) → break out by account
    Updated output to include account-level table
  Commits. Push. Everyone gets the update automatically.

ELAPSED: 30-second invocation, weekly, by 4 engineers = 30 minutes
saved per week. 26 hours per year. The skill paid for itself in week 1.

□ STEP 1: Identify a recurring question (from M6.4.L1 hands-on)
  Question: __________

□ STEP 2: Choose category
  □ Report   □ Check   □ Draft   □ Exploration

□ STEP 3: Draft the skill
  Path:        ~/.claude/skills/__________.md
  Description: __________
  Body:        Step-by-step instructions
  Parameters:  {{team}} / {{days}} / __________

□ STEP 4: Test invocation
  $ claude
  > /__________
  Does it produce the expected output?

□ STEP 5: Refine output format
  Add explicit "Output as: ..." instructions
  Re-run until consistent

□ STEP 6: Commit to repo
  .claude/skills/__________.md
  Mention in #team-channel: "new skill: /__________"

□ STEP 7: Get teammate feedback
  Have 1-2 teammates run it; collect feedback
  Iterate until 3 engineers can run it independently