new-scroll skill
✓ VerifiedAuthor and modify agent skills using a structured format with frontmatter, progressive disclosure, references, and scripts.
- GitHub stars
- 113
- Files
- 1
- Last commit
- Nov 1, 2026
- License
- MIT
- Allowed tools
- —
What does the new-scroll skill do?
new-scroll is an agent skill. Author and modify agent skills using a structured format with frontmatter, progressive disclosure, references, and scripts.
Summary generated from the skill's SKILL.md.
About the new-scroll skill
Authoring and modifying agent skills using a structured format is what new-scroll enables for developers building plugin libraries. This skill provides a systematic workflow for creating SKILL.md files that work across both Claude Code and Codex runtimes. It guides the user through defining frontmatter, setting up progressive disclosure via references and scripts, and ensuring compatibility between different agent environments.
When an agent loads this skill, it follows a specific lifecycle of checking existing libraries, collecting trigger phrases, and organizing content into folders like references, scripts, or assets. It produces a validated skill ready for deployment. The process relies on specific commands such as running the validator via node scripts/validate-team-avatar.mjs and using pai-sho for behavior testing of structural changes. It distinguishes itself by enforcing a tiered loading system where heavy documentation and code remain hidden until specifically requested by the agent.
What an agent can do with it
- 1Create a new skillA developer wants to build a brand new agent skill from scratch following the library standards.
- 2Improve existing skill descriptionsAn agent needs to refine the trigger phrases and documentation for a skill that already exists.
- 3Refactor a large skillA developer needs to take a single large skill and break it into smaller, manageable references.
- 4Automate repetitive workflowsA user wants to capture a recurring manual process into a formal agent skill.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the new-scroll skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the new-scroll skill in Plugin
/plugin marketplace add tmcfarlane/team-avatar /plugin install team-avatar@team-avatar
Install the new-scroll skill in Claude Code
~/.claude/skills/new-scroll/SKILL.md
$ npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/new-scroll ~/.claude/skills/new-scrollInstall the new-scroll skill in Claude Code (project)
.claude/skills/new-scroll/SKILL.md
$ npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/new-scroll .claude/skills/new-scrollInstall the new-scroll skill in Codex
~/.agents/skills/new-scroll/SKILL.md
$ npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/new-scroll ~/.agents/skills/new-scrollInstall the new-scroll skill in Gemini CLI
~/.gemini/skills/new-scroll/SKILL.md
$ npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/new-scroll ~/.gemini/skills/new-scrollInstall the new-scroll skill in Claude.ai
npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/new-scroll new-scroll && zip -r new-scroll.zip new-scroll # claude.ai → Customize → Skills → + → Create skill → Upload a skill → new-scroll.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachabletmcfarlane/team-avatar/plugins/team-avatar/skills/new-scroll is public and reachablegithub.com/tmcfarlane/team-avatar/tree/HEAD/plugins/team-ava ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-01github.com/tmcfarlane/team-avatar/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/tmcfarlane/team-avatar/blob/HEAD/plugins/team-ava ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/tmcfarlane/team-avatar/blob/HEAD/plugins/team-ava ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 105 linesgithub.com/tmcfarlane/team-avatar/blob/HEAD/plugins/team-ava ↗Pass
SKILL.md
View on GitHubA new scroll for the library
Iroh carried a library in his head and shared only what the moment called for. A good scroll is the same. It says exactly when to open it, gives the essential teaching on the first page, and keeps the long commentary in the back for the reader who needs it. You own the scroll's voice.
Steps
- Check the library first. Search the existing skills for one that already covers the workflow. Extend it instead of writing a near-duplicate. Write a new skill only for a workflow you keep hitting that no skill captures.
- Collect concrete triggers. Write down three to five real requests that should load the skill, in the words a user would type, including any old command names people already use. These become the description.
- Plan the contents. For each trigger, ask what an agent would otherwise rewrite or rediscover each time. Code it rewrites goes in
scripts/. Long reference material it rereads goes inreferences/. Files copied into the output go inassets/. Create only the folders you use. - Write the frontmatter. See Frontmatter.
- Write the body. See The body. Write it through
tea-time. - Validate. See Validate. In this plugin, that means registering the skill, regenerating the tables, and running the validator.
- Test it if it is structural. A skill that changes what an agent does (steps, routing, a checklist, a script) gets a behavior test. Run
pai-shoon it before you promote it. A purely stylistic skill skips this step. Recordskip: subjectivein the todolist. - Ship it. Hand to
yip-yip.
Frontmatter
Both Claude Code and Codex read a skill from skills/<name>/SKILL.md and decide whether to load it from two frontmatter fields. Use exactly these two so both runtimes read the file the same way.
---
name: new-scroll
description: Iroh writing a new scroll for the library. Use for authoring or modifying a skill, ...
---
nameequals the directory name. Lowercase words joined by hyphens.descriptionis one line, under 1024 characters. Both runtimes keep every skill's description in context all the time, so every word costs. Say what the skill does and when to use it, then list the trigger phrases from step 2 in quotes. Include the old command name when the skill replaces one ("Use for babysit, /babysit, get this green") so old habits still work.- In this plugin, the description opens with the character theme, then the plain trigger words.
- Do not wrap the description across lines or quote it with YAML block syntax. The validator reads one
key: valueline.
A weak description says "Helps with PRs." A strong one names the job and the exact phrases ("Use for opening a pull request, 'ship it', 'open a PR', 'write the PR description'").
The body
Progressive disclosure. A skill loads in three levels. The frontmatter is always in context. The SKILL.md body loads when the skill triggers. Files in references/ and scripts/ load only when the body sends the agent to them. Put each piece of information at the lowest level that still gets it read when it is needed.
- Keep SKILL.md the quick path. The steps, the rules, and the reply contract belong there. Aim for under about 2,000 words.
- Move long detail (full catalogs, rubrics, schemas, worked examples, edge cases) to
references/<topic>.md. Link it from SKILL.md with a relative Markdown link toreferences/<topic>.md, and say when to read it.tea-timeis a working example. - Keep references one level deep. A reference file does not send the reader to a third file for the core of its content.
- Put each fact in one place. Do not repeat a reference's content in SKILL.md.
- For a reference over about 10,000 words, give grep patterns in SKILL.md so the agent can find the part it needs.
Scripts. A script earns its place when the same code would be rewritten each time or when the result must be deterministic. Scripts run with plain node or sh, with no npm dependencies. Give the exact command to run, with the path relative to the skill, and say what its output means.
Writing.
- Open with a one-paragraph character framing, as the other skills here do. Everything after it is plain.
- Write imperative instructions to the agent that will run the skill. Tell it to do the thing and skip the reason. Explain only when the rule is confusing without one.
- When in doubt, delete. Keep only prose that changes a decision. Match the tone to the scope.
- Point at structural sources (types, READMEs, config, a validator) instead of restating them. When you write the same instruction a second time, encode it in a check instead (Encode Lessons in Structure, Fire in
four-elements). - Delegate to other skills by name. Do not restate them. Write a skill name in backticks after a routing word ("Run
seismic-sense", "Hand toyip-yip"). The validator checks that each one exists. - End with a Reply section that names what the final answer contains.
Two runtimes. Write in Claude Code tool names. A skill that dispatches subagents, asks fixed-choice questions, or uses task tools adds this line near the top, with the relative path fixed for the file's depth.
On Codex, read [avatar-mode/references/codex.md](../avatar-mode/references/codex.md) for tool equivalents.
- A skill loads as
team-avatar:<name>on Claude Code and as$<name>on Codex. - Dispatch a character with
subagent_type: "team-avatar:<character>". Codex has no agent types, so the codex reference says how to spawn the same character. - Name models through the avatar-setup sheet lines (for example "Iroh's model from the avatar-setup sheet", or the
panelline for a review panel). Do not hard-code a model, and do not invent a sheet line. - Never write a path outside the skill that only exists on one machine. Use paths relative to the skill file.
Validate
For any skill, check these before you ship.
- The frontmatter has
nameanddescription, andnamematches the directory. - Every file the skill links or names exists.
- Every cross-skill reference resolves to a real skill.
- Every script runs with the command the skill gives.
- The text has no long dash characters.
When the skill belongs to this plugin, also do these three things from the repository root.
-
Register the skill in
plugins/team-avatar/team.json. Add{ "name": "<name>", "owner": "<character>", "from": [] }toskills. The owner is the character whose discipline fits. -
Regenerate the roster tables and the agents' skill lines.
node scripts/generate-team-avatar.mjs -
Run the validator and fix every line it prints.
node scripts/validate-team-avatar.mjsIt prints
team-avatar OKwith the skill and agent counts when everything passes.
If the owner's agent file should load the skill by default, add a Load line to the hand-written part of agents/<character>.md. Never edit between the <!-- team:... --> markers. The generator owns those.
To try the skill in a live session, run claude --plugin-dir plugins/team-avatar from the repository root and type one of the trigger phrases. On Codex, add the local checkout as a plugin marketplace, as the plugin README describes, and invoke $<name>. Check that the skill loads from the phrase alone.
Reply
A summary of the skill, the key design decisions (what went in SKILL.md, what went in references, what you left out), and the validation output.
Files in this skill
1new-scroll skill questions
How do I install the new-scroll skill in Claude Code?
Run npx degit tmcfarlane/team-avatar/plugins/team-avatar/skills/new-scroll ~/.claude/skills/new-scroll. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the new-scroll skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How should I structure a skill for both Claude Code and Codex?
Use exactly two frontmatter fields, 'name' and 'description', and ensure the description is a single line without YAML block syntax. For tool equivalents on Codex, include a relative Markdown link to the appropriate reference file.
What is the best way to handle long reference material in a skill?
Move long details like catalogs, rubrics, or schemas to a file in the references/ directory and link to it from the main SKILL.md using a relative Markdown link.
When should I use a script instead of prose?
Use a script when the same code would need to be rewritten every time or when the output must be deterministic.