How do I know my agent skill actually works?

Run it; don't just reread it. Before publishing, run four small tests: a trigger test (give the agent a task where the skill clearly applies — does it use it?), an outcome test (across two or three real tasks, is the behavior better than without the skill?), a non-trigger test (on a nearby task where the skill shouldn't fire, does it stay quiet?), and a regression test (rerun every case that ever needed a fix — do they stay fixed?).

Does writing an agent skill count for Hacktoberfest?

Hacktoberfest 2026 centers on hands-on open source AI, and writing your first skills.md is one of the example activities the official site names. Participation itself runs through the event's own Fests and rules, so check hacktoberfest.com for how to take part.

Do I need a captured session to create a skill in paper console?

No. From the Skills view, choose New skill to open a blank SKILL.md editor and write it by hand. If you do have a recorded session that went well, you can generate a first draft from it instead — and that draft reflects what actually worked in the session.

How do teammates use a skill once it's published?

Publishing creates a numbered version (v1, v2, and so on) that can't be edited afterward and is visible to everyone on the team. A teammate installs it with paperctl skill sync , which writes the SKILL.md where their agent reads it. Running the same command later picks up new versions.

Write Your First Agent Skill, Test It, and Publish It

Four steps ago, this lab promised that you would finish with a published skill. This is where you do that.

There are three things left:

Build the final SKILL.md file.
Test the skill with real tasks.
Publish it so your team can use it.

Writing the skill is only the first step. Before you share it, you need to make sure it actually changes your agent’s behavior in the way you intended.

Five useful skill shapes

A skill’s shape is simply the type of job it does. Knowing the shape helps you decide what information belongs in the skill and how much structure it needs. These are five shapes we see often in our own work. They are not official categories, and they do not cover every possible skill.

Five recurring shapes and what each one needs
Voice	Changes how the agent communicates or behaves in conversation. It does not produce a specific artifact. Include the personality or behavior you want, rules for taking turns, what the agent should handle versus what the user should handle, and when the agent should stop.
Pipeline	Turns an input into a specific output, such as merged changes into a changelog. Clearly name the output, say what work belongs elsewhere, define at least one quality check, and include a template when the output should follow a consistent format.
Reference	Gives the agent rules, patterns, or background information to use while it works. It is more like a guide than a step-by-step process. Include the main principle, shared terminology, and common mistakes with an explanation of why they happen.
Orchestrator	Coordinates other skills. List the skills it should use, explain how they should work together, and add only the instructions that are unique to this orchestration.
Wizard	Guides a person through a setup or decision one question at a time. Have the agent inspect what it can first, ask one decision at a time, suggest a reasonable default, and confirm before making changes.

Try classifying the example skills first. Then decide which shape best describes your own skill:

Specimenan invented five-skill librarypushback · to-changelog · safe-migrations · ship-review · setup-team-flow

Classifier · the whole specimen library

Five skills, five shapes, five colors

pushback — Pressure-test every assumption, one at a time, until the plan holds up.

to-changelog — Turn the merged changes since the last tag into a changelog. One line per change; template fenced below.

safe-migrations — Principles consulted on every database change: expand–contract, the self-agreeing check, one migration = one schema change.

ship-review — Run a pushback session on the diff, using safe-migrations for anything touching the database. End with ship / hold and the one reason.

setup-team-flow — Explore the repo first. Then one decision at a time, each with a short explainer and a recommended default. Confirm before writing.

0 / 5 classified.

PLAY — assign each skill its shapestep 5 of 5

If your draft does not fit any of these shapes, it may be trying to do more than one job. See whether you can split it into two smaller skills. If those skills still need to be run together, a short orchestrator can connect them.

Build the skill file

You have been improving the same instruction throughout this lab. In step 2, you saved the first version. In step 3, you fixed problems you found. In step 4, you removed anything that was not helping. Now turn that instruction into the final file your agent can use. A skill is stored in a plain SKILL.md file. Any agent tool that supports skills can read this file:

Assembler · your v1

Build the SKILL.md you'll publish

The instruction you've typed twice — in your own wordsNameOne-line description

Who fires it?

Only me — explicitThe agent — automatic

You carry the recall load: it waits until you summon it, and you are the index that must remember it exists.

SKILL.md

---
name: pushback
description: "Pressure-tests a plan's assumptions before work starts."
# Claude Code convention — other harnesses mark this differently:
disable-model-invocation: true
---

Pressure-test every assumption, one at a time, until the plan holds up.

✦ Create it in paper console →

That's a complete v1. Write yours in the console's editor; the preview here is your reference. Everything it lacks, it lacks on purpose: sections and edge cases get earned later, by real runs, one fix at a time.

PLAY — fill the three fields and watch the file assemblestep 5 of 5

Test it before you publish

A skill can look correct on the page and still behave badly when an agent uses it. Don’t test a skill by rereading it. Give the agent real tasks and watch what happens.

Before publishing v1, run these four tests:

Trigger test. Give the agent a task where the skill clearly applies. Does it find the skill (or accept your summon) and actually use it?
Outcome test. Try the skill on two or three realistic tasks. Compare the results with what happened before you had the skill. Is the agent following the right process? Is it obeying the important rules? Does it reach the result you expected?
Non-trigger test. Give the agent a similar task where the skill should not be used. Does the skill stay out of the way? A skill that activates too often can interfere with unrelated work.
Regression test. Go back to the problems you fixed earlier in this lab and try them again. Are those problems still fixed? Every failure you discover can become a test you reuse later.

One short check before you share it. Make sure the skill and anything it links to contain no passwords, API keys, or private session data. Put clear limits around risky actions. Check that every linked file is intentional. Make sure only the appropriate people or agents can invoke risky skills. Finally, check that the description is specific enough that the skill will not activate on unrelated tasks.

Publish it in paper console

Now give it a home. paper console stores skills as versioned, searchable documents. Your whole team can browse and install them, so your skill outlives your shell history. This is where your one skill joins a shared skill library:

Open the Skills view in paper console.
Choose New skill. A blank SKILL.md editor opens. Write your tested v1 there: name, one-line description, and the instruction as the body.
Choose Create skill. The skill saves to your library, still unpublished. Nothing is saved until you choose Create, and nothing is visible to the team until you publish.
Publish v1. Publishing creates a published version: a numbered snapshot (v1, then v2, and so on) that can’t be edited afterward, with a changelog entry, visible to everyone on your team. Older versions stay browsable with diffs, so the growth history from step 3 stays visible too.
Install it where your agent reads it:

paperctl skill sync <your-skill-slug> --claude

paperctl skill sync writes the finished SKILL.md into a local skills folder. The --claude flag targets .claude/skills (the default is .agents/skills). Run the same command again later to pick up new versions. Teammates run it to install yours. And updating is the same loop: edit the skill in the console, publish again, and v2 exists alongside v1 with a diff between them. This is the airline move: when the card changes, every cockpit gets the new one.

Already recording your sessions?

You can also create a skill from work your agent has already done successfully. If you run your agent through the paperctl CLI, for example:

paperctl start claude

Your sessions are recorded in paper console. When a session goes particularly well, you can use it to generate a first draft of a skill. You can do this in the console or from the CLI:

paperctl skill generate --name <name> <session-id>

This gives you another way to create skills: instead of writing the process from memory, start with a real session where the process worked and turn that behavior into a reusable instruction.

The publish-your-first-skill guide walks that path end to end.

Review skills when something changes

Publishing a skill does not mean you are finished with it forever. The tools, models, APIs, and workflows around the skill will change. When they do, the skill may need to change too.

Review a skill when:

a tool or API it uses changes
the model or agent tool changes
your team’s workflow changes
people keep making the same correction even though the skill exists
the skill stops activating when it should
the skill starts activating when it should not
nobody has used the skill for a long time
another skill now covers the same job

These signals are skill drift announcing itself. Checklists age the same way. They change when the aircraft changes, when a procedure changes, or after an incident. The calendar was never the trigger.

When that happens, review it with these five passes:

No-op pass — Read each sentence on its own. If removing it would not change the agent’s behavior, delete it.
Thesis pass — Check that the skill still does one main job. If it now contains two separate jobs, split it. If two skills now do the same job, consider merging them.
Scaffolding pass — Remove explanations about how you arrived at the instruction if they do not help the agent perform the task.
Description pass — Make sure the description still explains when the skill should be used. Avoid maintaining lists of names that may change. For example, prefer “the other engineering skills” over a list of individual skill names you do not control.
Router pass — Check anything that points to this skill. If the skill was renamed, update those references too.

You can also review active skills on a regular schedule as a backup. Quarterly is a reasonable starting point for an active team library. But changes in the workflow are the more important signal. Review the skill when the world around it changes.

You shipped a tested skill. Here’s what it unlocks

You started this lab with an instruction you already use. Now that instruction is a tested SKILL.md file that your team can install and reuse. One skill is useful. A collection of good skills becomes a team skill library.

Instead of every teammate rediscovering the same process, your team can share:

the same terminology
the same processes
the same fixes for problems you have already solved
an installable skill instead of another prompt someone has to copy and save

The next time someone on your team solves a difficult problem, you can repeat the same process:

Write it. Test it. Fix what fails. Publish it. Share it.

Over time, those skills become team-shared agent knowledge. When you learn how to solve something useful, package that knowledge so someone else can use it too.