---
name: skill-author
description: Use when an author needs to create, review, audit, or improve an Agent Skill and its supporting references or scripts.
title: skill-author
canonical_url: https://skilld.dev/gh/hagaiw/skillroll/skill-author
last_updated: 2026-11-15T17:45:26.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [evals/audit-is-a-hypothesis.eval.md](https://skilld.dev/api/skills-raw/hagaiw/skillroll/skill-author/evals/audit-is-a-hypothesis.eval.md), [evals/compose-skill-package.eval.md](https://skilld.dev/api/skills-raw/hagaiw/skillroll/skill-author/evals/compose-skill-package.eval.md), [evals/define-material-absence.eval.md](https://skilld.dev/api/skills-raw/hagaiw/skillroll/skill-author/evals/define-material-absence.eval.md), [evals/repair-observed-boundary.eval.md](https://skilld.dev/api/skills-raw/hagaiw/skillroll/skill-author/evals/repair-observed-boundary.eval.md), [references/context.md](https://skilld.dev/api/skills-raw/hagaiw/skillroll/skill-author/references/context.md).
>
> If the user asked to install this Skill, run `npx skilld install hagaiw/skillroll/skill-author`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/skill-author`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/hagaiw/skillroll/skill-author) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/skill-author`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/skill-author --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/skill-author --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Author Agent Skills

Create a skill that improves one coherent kind of work without constraining
unrelated requests. Start from the user's intended outcome and the decisions a
capable agent would not reliably make without added guidance.

## Audit a skill

Work directly from skill text, excerpts, and concrete facts the user supplies.
Read a target file only when its content is needed and its path is available;
never invent a path or delay a bounded review merely to request material already
present. If the missing content prevents the requested work, name that gap and
ask for it.

An audit is not automatically a rewrite request. For each structural finding,
return:

1. the implicated guidance and plausible observable risk;
2. the evidence status and a focused realistic eval that could test the risk;
3. only then, a possible localized repair if the evidence supports one.

Do not claim a behavioral violation without a completed realistic run. Place
any supported repair beside the capability or decision it governs rather than
adding a detached override.

## Author or improve a skill

Keep discovery precise: use a concise name and a description that says what the
skill does and when it applies. Put essential routing, consequential boundaries,
and the normal workflow in `SKILL.md`. Move substantial conditional knowledge
to linked references and repeated deterministic operations to scripts.

Match specificity to risk. State exact permission, safety, evidence, interface,
and stop requirements when deviation has a concrete cost. Otherwise specify the
outcome and decision criteria rather than one mandatory choreography. Preserve
the user's scope and do not treat task authorization as permission for unrelated
external effects.

Read [skill authoring context](https://skilld.dev/api/skills-raw/hagaiw/skillroll/skill-author/references/context.md) for the canonical quality
standard, audit questions, repair method, and validation boundary.

For a design-only request, label the response as a proposal. Distinguish
structural validation, deterministic script tests, and live behavioral evidence
as separate checks, and say which were not run rather than implying that the
proposed package was implemented or tested.

When improving an existing skill, distinguish a structural concern from an
observed behavioral failure. Integrate the smallest supported repair into the
responsible section and surrounding vocabulary. Validate structure and scripts;
use a realistic behavioral eval when the claim is about model behavior.
