Free to read · no account needed

10 min · skills

Pack references and optional scripts into a skill

Goal: Pack references and scripts with a short README, a version, and zero committed secrets.

Best for: people who wrote a first skill and now want it to use a style guide or a small script safely.

A skill is a reusable instruction pack (often a SKILL.md or similar). References are the extra files the skill may read (style guide, rubric, glossary). Optional scripts are tiny helpers the agent can run when the product allows—not a place to hide secrets.

Beginner rule: only pack files you would be fine pasting into a chat. Keep the pack small.

Why beginners skip this

Shipping only the skill body without references and scripts feels light—teammates cannot reproduce. Pack references + scripts together.

Step 1 — List what the skill must know

Separate always-on short rules from look-up reference files—do not stuff a whole handbook into always-on.

Skill purpose: [one line]
List:
A) Always-on rules (≤10 bullets)
B) Reference files to attach (name + why + max pages)
C) What must NOT be in the pack (secrets, whole databases)
Beginner-friendly.
Example

Filled prompt

I have a skill that links three reference PDFs and one script stub.
Write a beginner pack README: what each file is for, how to update versions, and a never-commit secrets line.

What good output looks like

  • Always-on is short
  • References might be voice-guide.md + example-email.md
  • Secrets/client private data excluded

Step 2 — Write a tiny reference index

At the top of the skill, say when to open which reference—like a menu.

Draft a Reference index section for SKILL.md:
For each file: when to open · what to extract · what to ignore.
Example

Filled prompt

Job: Open skill card for “attach the docs and helpers a skill”. Add Done + golden example if missing. Run fail case once.
Boundaries: draft only; Unknowns [?]; no silent send; no invented metrics.
Return: checkable artifact + one-minute pass/fail for skills-pack-references-and-scripts.

What good output looks like

  • Matches named constraints for “Pack references and optional scripts”
  • Unknowns labeled; no invented owners/metrics
  • Stops before irreversible actions
  • Pass/fail markable in ≤60s

Step 3 — Scripts only with a sandbox story

Scripts do one thing and stay offline by default; if you cannot read it, do not pack it.

Decide: does this skill need a script? If yes, describe in plain words what it would do, inputs, outputs, and why a prompt alone is not enough. If no, say why.
Example

Filled prompt

Skill needs a glossary CSV + a format script note.
Pack layout: references/ allowed, no secrets, how to cite file in steps, test without prod data.
Return folder tree + never-do.

What good output looks like

  • Often concludes prompt is enough for small CSV
  • If script: no silent uploads
  • Inputs/outputs named clearly
  • If you insist on a script: offline by default; pack only what you can read

Keep it real

Run this guide’s Practice now on work you will actually ship this week—not a fictional scenario. Dated notes beat perfect theory.

Do not bookmark-only

Finish Practice now, then tick this guide on your path. Titles unread are not skills.

Close the loop

Write one line: next time I ship body-only with no refs/scripts, I refuse “shareable.”

One more pass

Re-read your Save-this-card line. If it is vague, rewrite it until a stranger could apply it.

Red flag

Shipping unread scripts; README missing; secrets in the pack—block share.

Save this card

Card: README · version · no secrets · only scripts you can read. Block share if any box is empty.

Before you start

Open the skill card (or blank one-pager). Purpose must be one job for “attach the docs and helpers a skill.” Golden example slot cannot stay empty. Guide: skills-pack-references-and-scripts. Keep the real job visible the whole time; a blank box means stop and fetch the artifact first.

How to use this week

This week pack a real skill: body + reference links + runnable script; no “shareable” until all three land.

Close the week by quoting aloud the refuse line you actually used once. If you cannot, rerun Practice now and date the pass/fail (Asia/Shanghai).

Pitfalls

PitfallFix
Attaching entire company wikisSlim references
Scripts that call the internet by defaultOff unless required
Secrets inside SKILL.mdNever
Example

Filled prompt

Temptation: skip the habit for skills-pack-references-and-scripts to save five minutes.
Job still: attach the docs and helpers a skill
Smallest correct pass: Done visible · checkable artifact · Unknowns [?].
Boundaries: draft only; no silent send; no invented metrics.
Return: artifact + refuse-line said aloud.

What good output looks like

  • Names the shortcut refused (specific to skills-pack-references-and-scripts)
  • Still delivers checkable output for “attach the docs and helpers a skill”
  • Unknowns labeled; draft-only
  • Pass/fail: refuse-line dated (skills-pack-references-and-scripts #4)

Practice now

Broken-link hunt: open every ref link once (Asia/Shanghai).

Hash pin: note script hash/version on the skill card (Asia/Shanghai).

Missing-ref fail: delete a ref temporarily; skill should fail loud (Asia/Shanghai).

Script dry-run: run the script once with dry-run/no-op if available (Asia/Shanghai).

Ref-path drill: open the reference file once tonight to prove the path (Asia/Shanghai).

Pack-refs drill: one reference file path + one script path listed on the skill card (Asia/Shanghai).

Thin-spot drill: rewrite the Save card with real nouns from your work (repo, doc, inbox). Generic placeholders fail the drill.

Tonight open a real skill and cut references/scripts to a minimum-deps table; delete unused ones.

Today card (copy) — skills-pack-references-and-scripts: 1. Artifact I will produce: ___ 2. Pass/fail check: ___ 3. Refuse-line if tempted to skip verify/send: ___ (date: Asia/Shanghai) 4. One never-do from this guide: ___

Extra pass: do the card on a real file today—reading alone does not count.

One sentence takeaway

Body + reference links + runnable script; no “shareable” until all three.

Next

Test a skill before trust · Port across products

← Back to home · Learn · Tools · Compare · Start