Write a Notion Agent Skill

Create a Notion-hosted skill and prove it changes your coding agent's output.

Introduction

30 Second Summary

A tiny wording fix should take seconds. Too often, the person who spots it has to wait for someone else to make the change.

In this project, you will write an agent skill on a Notion page for installation into your coding agent with the skills CLI. Three runs of the same request will reveal the original behavior, the installed rules, then the effect of an updated rule.

What You'll Build

The same request produces visibly different answers once your coding agent starts following a Notion page that you can edit in seconds.

By the end of this project, you'll have:

A saved before case that shows exactly how your agent handles one narrow request with no skill installed.
A team-editable Notion skill page that installs into your coding agent. Your own skill appears in the CLI's installed list.
A three-run comparison that proves the first installation changed the agent's behavior. The final run proves the reinstalled page edit took effect.
Secret Mission: An optional challenge to push your skills further.

Are there any prerequisites?

Node lets npx run the skills CLI. The remaining setup needs a free Notion workspace plus a coding agent supported by the skills CLI.

Before We Start

Every later comparison depends on a clean baseline. If the tool or request changes between runs, the result cannot show what the skill changed.

You will prepare a Notion workspace plus a supported coding agent. You will also lock one test request before checking skills CLI version 1.7.0.

In this step, get ready to:

Prepare a Notion workspace for the skill page.
Prepare a supported coding agent with the skills CLI.
Lock the fixed test request for every comparison.

Set up Notion and your coding agent

Notion gives your skill one editable home. Your coding agent provides the behaviour that you will compare across each test.

Your Notion path depends on whether you already have an account.

✔️ I already use Notion

Go to notion.so in your browser.
Sign in to your Notion account.
Select a workspace from the workspace switcher in the top left corner.

Your Notion account is ready. The selected workspace is the home for your skill page.

ⓧ I need a Notion account

Go to the official Notion signup page in your browser.
Create an account with your preferred sign-in method.
Choose the Free Plan if a plan screen appears.
Complete the onboarding flow to create your workspace.

Your new workspace is ready to hold the skill page in the next step.

The skills CLI supports many coding agents. Your test needs one supported agent running in a disposable workspace.

✔️ I already use a supported agent

Confirm your agent appears in the official supported agents list.
Launch the agent with its usual start method.
Select a disposable test workspace in the agent.
Confirm the agent shows an input where you can submit a request.

ⓧ I need a supported agent

Review the official supported agents list.
Select one coding agent from the list.
Follow the installation guide on that agent's official product page.
Launch the agent with its documented start method.
Create a disposable test workspace in the agent.
Confirm the agent shows an input where you can submit a request.

Agent not opening?

Return to your chosen agent's installation guide. Check any operating system requirements listed there.

Use this if the setup still fails: Help me troubleshoot my coding agent installation.

Good, your two work surfaces are ready. Notion holds the instructions while the agent provides the output.

Choose one fixed test request

A useful before-and-after test focuses on one narrow task that your agent currently handles poorly. The request stays identical so any visible difference can be traced to the skill.

What makes a fair test?

A fair test asks for one observable output. It gives you a specific result to place beside the later responses.

The request must remain unchanged before installation, after initial installation, and after updating the agent skill.

Choose a repeated agent task whose current output misses one clear expectation.
Reduce the task to one output that you can compare.
Write the request with wording that you can reuse unchanged.
Record the exact request here: your fixed test request.

Check npx and the skills CLI

The skills CLI runs through npx. A working Node.js installation gives your terminal access to that command.

What is the skills CLI?

The skills CLI installs reusable skill folders into supported coding agents. Version 1.7.0 adds Notion pages as an installation source.

Check whether npx is available by running this command:

npx -v

What does this command check?

This command asks npx to print its installed version. A version number confirms that your terminal can run packages through npx.

✔️ I see a version number

Your Node.js toolchain is ready to run the skills CLI.

ⓧ Command not found

Your terminal needs Node.js before it can use the skills CLI.

Go to the official Node.js download page.
Download the long-term support release for your operating system.
Run the downloaded installer with its default options.
Close your terminal after the installation finishes.
Start a new terminal session.
Run the version check above again.

Still missing npx?

A terminal that stayed open during installation may still use the old system path. Restart the terminal before testing again.

Use this if the command is still unavailable: Help me make npx available in my terminal.

The first skills check can pause while npx fetches the package. A short wait here is normal.

Check the available skills CLI version by running this command:

npx skills --version

What does this command check?

This command runs the skills package through npx. The version output shows whether the CLI includes Notion support.

✔️ I see version 1.7.0 or higher

Your available skills CLI meets the minimum version for this project.

ⓧ I see an older version

Run the project release directly with this pinned command:

npx skills@1.7.0 --version

Why pin the version?

The package suffix tells npx to use the project release. This avoids an older cached package.

You should see version 1.7.0 in the terminal.

ⓧ The command does not run

Close the current terminal session.
Start a new terminal session.
Run the pinned version check:

npx skills@1.7.0 --version

What does the pinned check do?

This command requests skills CLI version 1.7.0 directly. It removes uncertainty about which release npx selects.

Pinned command still failing?

Check that your terminal has internet access. A restricted network can stop npx from fetching the package.

Use this to inspect the failure: Help me run the pinned skills CLI version.

Before you run the final check, which version do you expect the pinned command to print?

Confirm the exact project release by running this command:

npx skills@1.7.0 --version

What does the final check prove?

The pinned command confirms that your terminal can fetch the release used in this project. It also proves that the Notion-capable CLI is accessible.

You should see 1.7.0 in the terminal. That's your toolchain ready for the Notion installation flow.

Version not appearing?

Make sure the command includes the package version after the at sign. Check that the version flag uses two hyphens.

Use this if your output still differs: Help me verify skills CLI version 1.7.0.

✔️ My setup is ready

Great. Your Notion workspace, coding agent, fixed request, and pinned CLI are ready.

ⓧ I'd like to double check the setup

Confirm your Notion account opens the workspace you selected.
Confirm your supported coding agent opens the disposable test workspace.
Confirm the terminal prints skills CLI version 1.7.0.
Confirm your Test Request: A fixed, narrow prompt selected to run unchanged before installation, after initial installation, and after updating the skill.

Your test conditions are fixed. Next up, you will run the request before any skill is installed to capture the baseline.

Capture Your Baseline Output

Your skill needs a fair before case so you can prove that its rules change the result. The current response captures how your coding agent handles the task on its own.

In this step, you will run the selected test request before installing the custom skill. You will save the complete response without editing it.

In this step, get ready to:

Keep the selected test request unchanged.
Run the request with no custom skill installed.
Save the agent's unedited response as your before case.

Protect the comparison

A reliable baseline keeps the test request fixed. The custom skill becomes the only new variable in later runs.

Switch back to the test workspace from earlier.
Leave the custom skill uninstalled for this run.
Use the selected test request exactly as saved earlier.

Why keep the request unchanged?

The baseline is your control result. It records the agent's default behaviour under the same conditions you will use later.

Changing the request would add another variable to the comparison. A fixed request makes any later difference easier to connect to the skill.

Run the unchanged request

This first run exposes how the agent currently handles your narrow task. Its strengths and gaps give the skill a concrete result to improve.

Before you submit the request, predict whether the agent will follow the rule you plan to add later.

Paste the selected test request into the coding agent's input.
Submit the request with no extra context.
Wait for the response to finish.

You'll see the agent's default response to the selected task. That's your control result captured under the original conditions.

Response stopped early?

Submit the identical test request again.
Use only the first complete response as the before case.
Help me preserve a fair baseline comparison.

Save the unedited before case

The response must stay untouched because later comparisons depend on its exact wording. Small edits would blur the effect of the skill.

Copy the complete response from its first line through its last line.
Save the copied response in the test workspace under the label Before Case Output.

You'll now see a saved before case containing the agent's original response.

Before you compare the copies, predict whether any wording changed while you saved the response.

Compare the saved before case with the original response line by line.

Every line should match the original response. Your baseline is now ready for a fair before-and-after comparison.

Your baseline is locked in. Next up, you'll turn your expectations into a skill page in Notion.

Write and Publish Your Skill

Your saved before case shows how your coding agent handles the task with no custom guidance. The next version needs precise instructions that address a visible weakness in that response.

In this step, you will turn that evidence into an agent skill on a Notion page. The page becomes the source your team can edit before you install it in the next step.

In this step, get ready to:

Create a Notion page for the selected narrow task.
Turn the weakness in your before case into clear rules.
Publish the page at a shareable URL.

Create the skill page

A narrow scope gives the agent a clear moment to apply the skill. Your unchanged test request sets that boundary.

Hover over the teamspace that should own the skill in the left sidebar of your Notion workspace from earlier.
Click the + that appears beside the teamspace name.

You'll see a blank page nested under the selected teamspace.

Enter a title for your narrow skill in the page title area.
Write one sentence below the title that names the exact request this skill handles.

You should now see a named skill page with a one-sentence scope beneath its title.

What Makes a Skill Narrow?

A narrow skill handles one repeatable request. Its scope should match the unchanged test request you saved.

Clear boundaries make the later comparison easy to judge. You will be able to trace each changed behaviour back to a rule.

Turn the before case into clear rules

The before case gives you evidence instead of guesses. Each rule should correct something visible in that response.

Return to the saved before case from the previous step.
Identify one response trait that made the result weak for your selected task.
Switch back to a title for your narrow skill in Notion.
Add a heading named Rules below your scope sentence.
Write the first rule so it targets the trait you identified.

Your first rule should describe a change you can spot when you compare the next response with the before case.

Add a short bulleted list of any remaining rules beneath the first rule.
Remove any rule that extends beyond the fixed test request.

Your rules should now describe one task with observable requirements. The page should stay focused enough for a single before-and-after comparison.

Add a heading named When to use this skill below the rules.
Describe the exact kind of request that should trigger the skill.

The page now defines the task boundary plus the behaviour expected from your coding agent.

Publish the skill page

The next step needs a public page URL. Publishing gives the skill a shareable address while your team keeps editing its source in Notion.

Keep the Page Safe

Publishing makes the skill readable on the public web. A page that contains only the skill instructions is ready to share.

Click Share at the top of the skill page.
Open the Publish tab.
Select Publish.

You have crossed the key threshold. Your skill now has a public home that stays tied to the editable Notion page.

Use the copy control beside the live site URL.
Record the copied address here: your published Notion skill URL.

Before you test the link, do you expect someone outside your workspace to see the complete skill page?

Load your published Notion skill URL in a private browsing window where you are signed out of Notion.

You'll see a title for your narrow skill load without a workspace sign-in. The public page should show the scope sentence plus every rule.

Does the Page Ask for Access?

A workspace link may still require access. Copy the live site URL from the Publish tab instead.
A private page has no live site URL. Select Publish before copying the address.
Ask for help if the public page still does not load: Help me troubleshoot access to my published Notion skill page.

✔️ My skill page is public

Great. Your published Notion page is now the team-editable source of truth for this skill.

ⓧ I'd like to double check my page

Use this checklist against the page you just published:

Confirm a title for your narrow skill names one narrow task.
Confirm the scope sentence matches the unchanged test request.
Confirm the Rules section contains clear requirements tied to the before case.
Confirm the When to use this skill section defines the exact trigger.
Confirm your published Notion skill URL opens without a Notion sign-in.

Your skill now lives in Notion at a working public URL. Next up, you'll install that page into your coding agent.

Install the Notion Skill

Your published Notion page now holds the rules for your selected task. The before case captures how your coding agent behaves without those rules.

Installation turns that page into an Agent Skill your coding agent can load. The Notion CLI gives the skills CLI authorized access to the page.

You will authenticate first. You will finish by confirming that the custom skill appears in the installed-skills list.

In this step, get ready to:

Authenticate the Notion CLI for the workspace that owns the skill page.
Install the custom skill from its shareable Notion page URL.
Confirm the installed-skills list includes your custom skill.

Authenticate with Notion

The skills CLI relies on ntn to request access to your Notion workspace. That access follows the permissions of your Notion account.

Set up the Notion CLI in the terminal from earlier by running this command:

curl -fsSL https://ntn.dev | bash

What does this command do?

The curl command retrieves the official setup script.
The bash command runs the script.
The setup makes ntn available in your terminal.

Notion CLI unavailable?

Use a terminal shell that supports bash if your current shell cannot run the setup script.
Start a fresh terminal session if your shell cannot find ntn after installation.
Ask your workspace owner for help if your Notion membership does not allow CLI access.
Help me troubleshoot my Notion CLI setup.

Authentication can feel sensitive. Notion opens a browser page so you can verify the login request before granting workspace access.

Start the Notion login flow by running this command:

ntn login

How does the login work?

The ntn login command opens a Notion authorization page in your browser.
A matching code links the browser approval to the request in your terminal.
Notion stores the approved credentials in your operating system's credential store.

Compare the code in your browser with the code shown in your terminal.
Approve the workspace access request in your browser.
Return to the terminal from earlier to confirm the login completed.

You should see confirmation that the Notion CLI is authenticated with your workspace.

Login not completing?

Confirm that the browser code matches the terminal code before approving the request.
Confirm that you are a full member of the workspace containing the published skill page.
Ask a workspace owner to check whether the workspace allows personal access tokens.
Help me complete my Notion CLI login.

Install the skill from its Notion page

The published page remains the source of truth for the skill. The skills CLI reads that page through your authenticated Notion access.

Page permissions control whether the CLI can reach the skill. Your authenticated account must have access to the published page.

Use the shareable Notion page URL from earlier as your shareable Notion page URL in the command below.
Select the coding agent from your test workspace if the installer displays detected agents.
Install the custom skill by running this command:

npx skills add [[NOTION_PAGE_URL="your shareable Notion page URL"]]

What happens during installation?

The npx skills add command passes your Notion page URL to the skills CLI.
Your authenticated Notion access allows the CLI to read the published skill page.
The skills CLI installs the page as a standard skill for your selected coding agent.

Wait for the installation process to finish.

You should see confirmation that the custom skill was installed for your selected coding agent.

Skill not installing?

Confirm that the command uses the shareable URL for the published skill page.
Confirm that the authenticated Notion account can view the skill page.
Repeat the Notion login if the installer reports an authentication problem.
Help me install my skill from its Notion page.

Confirm the skill is installed

The installed-skills list is your independent check that the skills CLI registered the custom skill. This gives you evidence beyond the install message.

Before you run this check, which custom skill name do you expect to appear?

List the installed skills by running this command:

npx skills list

What does this check prove?

The npx skills list command reads the skills currently installed for your coding agent.
Your custom skill's presence confirms that the published Notion page was installed successfully.

You should see your custom skill in the installed-skills list. That is the proof you need: your coding agent can now access the rules from your Notion page.

Custom skill missing from the list?

Confirm that you selected the same coding agent when installing the skill.
Repeat the installation command with the published page's shareable URL.
Run the installed-skills check again after the installation completes.
Help me find my missing installed skill.

Your custom skill is installed from the team-editable Notion page. Next up, you will repeat the original test request to see which rules the coding agent follows.

Compare the Skill's Results

Your custom Notion skill is installed. The installed-skills list proves your coding agent can find it.

The real test is whether the skill changes the agent's behaviour. You will rerun the unchanged Test Request to create a fair comparison.

You will save the new response beside the Before Case Output. Then you will identify every initial rule the agent followed or ignored.

In this step, get ready to:

Run the unchanged Test Request after the initial skill installation.
Save the new response beside the Before Case Output.
Classify each initial Notion Skill Page rule as followed or ignored.

Run the unchanged request

A controlled comparison uses the same input on both runs. This gives you a consistent basis for checking the installed skill's visible influence.

Return to the coding agent session in your test workspace.
Copy the saved Test Request without changing any wording.
Paste the copied Test Request into the agent's prompt field.

Before you submit it, which rule do you expect to shape the response most clearly? Keep that prediction in mind.

Submit the request.

You'll see a fresh response to the same request. Keep the response unedited so it reflects the agent's actual behaviour.

Save the unedited response as your After Installation Output beside the Before Case Output.

You now have two unedited outputs from one fixed request. This gives you a clean basis for evaluating the skill.

Compare both outputs rule by rule

Agent responses can vary between runs. Your comparison focuses on the behaviours explicitly requested by each rule.

How do the labels work?

A followed rule has a visible match in the After Installation Output.
An ignored rule has no visible match or conflicts with the After Installation Output.
The rule itself remains your comparison standard when the overall quality varies.

Arrange the Before Case Output and After Installation Output side by side in the test workspace.
Switch back to the published Notion Skill Page from earlier.
Read the first initial rule.
Find observable evidence for that rule in the After Installation Output.
Label the rule followed when the output demonstrates the required behaviour.
Label the rule ignored when the required behaviour is absent or conflicting.
Repeat the review for every initial rule.
Save the completed labels as Rule Comparison Notes beside both outputs.

Your notes now connect each initial rule to visible evidence from the new response. Any ignored rule gives you a precise target for the next test.

Verify the comparison

A reliable comparison keeps the request fixed. It also preserves both responses exactly as the agent produced them.

Before your final check, do you expect every initial rule to have a clear label? Test that prediction now.

Compare the request used for the After Installation Output with the saved Test Request.
Confirm the wording matches exactly.
Confirm the Before Case Output remains unedited.
Confirm the After Installation Output is saved beside it.
Confirm the Rule Comparison Notes cover every initial Notion Skill Page rule.

You should be able to match the request for both runs word for word. You should also see both unedited outputs side by side.

Your Rule Comparison Notes should give every initial rule a followed or ignored label.

Well done. You now have a before-and-after record that shows how the initial skill performed.

Next, you'll change one Notion rule. A third run with the reinstalled skill will reveal whether the edit took effect.

Update and Reinstall the Skill

Your first comparison revealed how the coding agent interpreted your initial Agent Skill.

The installed copy only changes when you reinstall it from the published Notion page. This step tests that update loop with one revised rule.

In this step, get ready to:

Revise one rule on the published Notion page.
Reinstall the skill from the same page URL.
Prove the revision with a third run of the unchanged Test Request.

Revise one rule in Notion

A controlled test changes one variable at a time. Every other rule stays fixed so the revised rule is the only planned difference.

Return to the published Notion Skill Page from earlier.
Review the Rule Comparison Notes from your initial test.
Choose one rule that the coding agent ignored or followed inconsistently.
Rewrite the selected rule as a requirement you can see in the agent's response.
Load the shareable page URL in a separate browser tab to confirm the revised rule is visible.

Make the Rule Observable

A testable rule names a visible result in the agent's response. Your third output can then show clear evidence that the behavior changed.

Good. The published page now contains one deliberate change while every other test condition stays fixed.

Reinstall the updated skill

The coding agent still has the original installed copy. The skills CLI must read the published page again before the agent can use the revised rule.

Return to the terminal panel from the initial installation.
Replace <NOTION_PAGE_URL> in the command below with the same shareable Notion page URL.
Use the same coding agent as the installation target if the CLI asks you to choose one.
Reinstall the current page by running the completed command:

npx skills add <NOTION_PAGE_URL>

What Does Reinstalling Do?

The skills CLI reads the current content at the same Notion page URL. It refreshes the installed Agent Skill for your selected coding agent.

This keeps the published Notion page as the single source of truth.

The CLI should finish the installation flow for the same custom skill.

Before you check, predict whether the custom skill keeps the same name after its contents change.

List the installed skills by running:

npx skills list

What Does This Check Prove?

The list confirms that the custom skill still exists after reinstallation. Its installed instructions now come from the revised Notion page.

You should see your custom skill in the installed-skills list.

Skill Missing From the List?

Return to the same test workspace from the initial installation before listing the skills again.
Reuse the same shareable page URL from the published Notion page when reinstalling.
Complete the Notion authentication flow again if the CLI requests access.
Help me diagnose why my reinstalled Notion skill is missing from the installed-skills list.

Run the unchanged request again

The Test Request is your control. Changing its wording would introduce a second variable.

Switch back to the coding agent from earlier.
Start a fresh conversation for the third test.

You should see an empty conversation with none of the earlier responses in its context.

Copy the unchanged Test Request from your saved workspace.
Paste the request into the fresh conversation.

Before you submit it, predict whether the revised behavior appears more clearly this time.

Submit the Test Request to the coding agent.

You will receive a third response to the same request. Its content shows whether the revised rule is active.

Save the response as your After Update Output beside the earlier outputs.
Arrange the Before Case Output, After Installation Output, and After Update Output side by side.

You now have three saved responses from the same request at three points in the skill's lifecycle.

Compare the After Update Output with the Before Case Output.
Compare the After Update Output with the After Installation Output.
Record whether the revised rule took effect in the Rule Comparison Notes.
Record which rules the coding agent followed across all three outputs.
Record which rules the coding agent ignored across all three outputs.

Your Rule Comparison Notes should name the revised rule's result. They should also identify the rules followed or ignored across all three outputs.

✔️ My evidence is complete

Great. Your updated skill test now has a documented third result.

ⓧ I'd like to double check my evidence

Use this checklist to confirm every final artifact is ready.

Confirm the published Notion Skill Page shows one revised rule at the same shareable URL.
Confirm the installed-skills list shows your custom skill after reinstallation.
Confirm the Before Case Output remains unedited.
Confirm the After Installation Output remains beside the Before Case Output.
Confirm the After Update Output contains the third response to the unchanged Test Request.
Confirm the Test Request is identical across all three runs.
Confirm the Rule Comparison Notes state whether the revised rule took effect.
Confirm the notes identify which rules the coding agent followed or ignored.

That closes the update loop. You changed the source page, refreshed the installed skill, and captured evidence of the result.

Secret mission

Build a Rule Compliance Scorecard

Turn your three saved agent outputs into a rule-by-rule compliance scorecard. Use evidence quotes to show which Notion instructions changed the coding agent's behaviour.

Clean Up Your Resources

Your published Notion page adds no new project cost. Choose whether to keep the project materials, pause testing, or remove them.

Resources you used:

Published Notion Skill Page containing the revised rule.
Test Request with the Before Case Output, After Installation Output, and After Update Output.
Rule Comparison Notes covering which instructions the coding agent followed or ignored.

Keep everything running

No action is needed. Choose this option if you want to refine the skill or share it with your team.

Keep the published Notion Skill Page as the single copy of the skill.
Keep the installed custom skill available in your coding agent.
Keep the Test Request with all three outputs in the test workspace.
Keep the Rule Comparison Notes as evidence of how each rule affected the agent.

Pause - I'll come back to this later

Pause further testing while preserving the page and comparison evidence. There is no project process to stop.

Keep the Notion Skill Page published as the single source of truth.
Keep the Test Request with all three outputs in the test workspace.
Keep the Rule Comparison Notes for your next revision.
Return to the same Notion Skill Page when you are ready to revise another rule.
Reinstall the skill after your next rule change.

Delete - I don't want to use this again

Remove the published skill page and its saved comparison evidence. This clears the teardownable project materials from Notion and the test workspace.

Return to the published Notion Skill Page.
Open the three-dot page menu in the top-right corner.
Choose the option that moves the Notion Skill Page to the workspace trash.
Open the shareable URL to confirm that the published skill page is unavailable.
Return to the test workspace.
Select the Test Request, Before Case Output, After Installation Output, After Update Output, and Rule Comparison Notes.
Use the test workspace's delete control to remove the selected artifacts.
Refresh the test workspace to confirm that the five artifacts are gone.

Installed Skill Cleanup

This project does not establish a verified removal path for the installed custom skill. The skill stays available in your coding agent because no uninstall command is included.

Nice Work!

You did it! Your Notion skill now guides your coding agent from one shared source.

You've learned how to:

Create a repeatable behaviour test with one unchanged request plus saved outputs from before installation and after installation.
Publish a Notion skill page as the single source of truth for your custom rules. You installed that skill into your coding agent and confirmed it appeared in the installed-skills list.
Prove a rule update took effect by reinstalling the skill and running the same request again. Your comparison notes reveal which instructions the agent followed or ignored.
Take on an optional Secret Mission to push your skills further.

Ready to quiz yourself?