agentleFS
wardawgmalviciouswardawgmalvicious/agent-config/.claude/skills/author-skill/SKILL.md

author-skill

Skill1 starsChanged 34 days agoMITView on GitHub

Author a new skill for this repo end to end — take a topic, check for existing coverage, drill the official docs behind it, write a filled handoff brief to docs/handoffs/, then draft the SKILL.md and run the post-draft checks. Use when asked to write, author, create, or scaffold a new skill, or when a drift-audit new-skill candidate has been accepted. Encodes this repo's own conventions rather than generic skill advice — verb naming for behavioral skills and namespace prefixes for platform ones, the description as the entire trigger mechanism, long detail split into references/, lint-frontmatter.py, and which tree a new skill belongs in and its deploy step. Drills before it writes and never encodes an unverified claim. Ends at a linted draft plus a fresh-session test plan; writes no test fixtures and does not commit — fixtures and validation are test-skill's, which reads the brief back off disk. To fold a session learning into guidance that already exists, use learn instead.

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 9 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the user wants a *subagent* rather than a skill, this is the wrong skill: the artifact lives in claude/agents/ and uses …

    line 76
  2. Distinctive:

    Before naming anything, find out whether the topic is already covered.

    line 82
  3. Very specific:

    Check that file explicitly.

    line 89
  4. Distinctive:

    Put the proposal to the user before drilling.

    line 140
  5. Distinctive:

    Do not write from training data.

    line 211
  6. Distinctive:

    Prefer them when present; fall back without ceremony when not.

    line 224
  7. Distinctive:

    Stop drilling when new pages stop changing the outline, not when the source list is exhausted.

    line 254
  8. Distinctive:

    If something is there, read it in full and treat it as source rather than as an obstacle.

    line 274
  9. Very specific:

    If an existing brief in docs/handoffs/examples/ matches the new skill's shape, lift it as design source and record that lineage in Changes …

    line 301
  10. Very specific:

    Write the SKILL.md from the brief, at the path the tree decision in step 3 picked — skills/<group>/<name>/SKILL.md for payload, …

    line 310
  11. Distinctive:

    Write it to fire on the queries the skill should answer — the user's vocabulary, error strings, tool and command names — not to summarize …

    line 315
  12. Distinctive:

    Run all five. Each catches something the others do not.

    line 355
  13. Very specific:

    Add the entry to skills/README.md for a payload skill, in the section its group implies, or to .claude/skills/README.md for a project-scope …

    line 403
  14. Distinctive:

    No unverified claims: If step 4 did not establish it, it does not go in the skill.

    line 476
  15. Very specific:

    Do not edit other skills: Only the new skill's own directory, the new brief, and its single catalogue entry -- skills/README.md for a …

    line 490

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Author a skill

Take a topic and end at a linted SKILL.md draft plus a runnable fresh-session test plan. The input is a subject, not a specification — deciding the name, the boundaries, and what the skill deliberately will not cover is the work, not a precondition for it.

This skill is house-style. It encodes how this repo builds skills; the generic mechanics of the Agent Skills format are somebody else's job (see step 1).

Paths below are relative to the repo root. This skill is project scope and fires only in sessions here, but a skill it authors in skills/ deploys through ~/.claude/skills — a real directory holding one junction per skill in that tree.

An edit is immediate; a new skill needs the linker once. The asymmetry follows from those per-skill junctions. Editing an already-junctioned skill is live the moment it hits disk, for every session on this machine, committed or not. But a directory that did not exist at the last scripts/link-claude.ps1 run has no junction, so a newly authored skill is invisible everywhere — absent from the listing, and /<name> answers Unknown command. Measured 2026-09-02: land was missing from a listing of 8 junctions immediately after its SKILL.md was written, and appeared only once the linker ran. On this machine the form is ./scripts/link-claude.ps1 -SkillGroups workflow,social,meta, never bare — see root CLAUDE.md.

A platform skill is the exception that proves the rule: its group is pruned from user scope here on purpose, so a new one enters no session's payload until a -ClaudeDir run links it into one repo's .claude/.

A project-scope skill needs the linker not at all, which is the third case and the easiest to get wrong in the other direction. Nothing junctions .claude/skills/ — Claude Code reads it in place — so a new skill there is live on save for sessions in this repo, with no deploy step to forget. Do not run the linker "to pick it up"; it selects out of skills/ and will not see it. The trade is that it is live only here, which is the whole reason it is there.

Once linked, a half-drafted skill is a live half-drafted skill; finish the frontmatter before walking away.

1. Check this is the right skill

Two routes out, both cheap to check first.

Guidance that already exists → /learn. The dividing line is whether the destination exists. /learn folds a session learning into a skill, rule, or CLAUDE.md that should already have covered it. This skill creates guidance that has no home yet. A learning that arrives as "the fabric-deploy skill was wrong about X" is /learn work even if the fix is large.

Generic skill-authoring help → skill-creator or plugin-dev:skill-development. Both are loaded and both are good. They are not wrong, only generic: they know the Agent Skills format, progressive disclosure, and description tuning in the abstract. They do not know this repo's naming rules, its lint command, its references/ split, its junction deployment, or the discipline of writing a handoff brief first. That gap is the entire reason this skill exists alongside them. Say so plainly when the overlap comes up, so the duplication reads as deliberate rather than as something nobody noticed.

If the user wants a subagent rather than a skill, this is the wrong skill: the artifact lives in claude/agents/ and uses docs/handoffs/templates/subagent-handoff.md. Stop and say so.

2. Check for existing coverage

Before naming anything, find out whether the topic is already covered.

grep -li "<topic term>" skills/*/*/SKILL.md .claude/skills/*/SKILL.md
grep -n -i "<topic term>" skills/fabric-core/fabric-rest-api/references/gotchas.md

Check that file explicitly. /learn treats it as the default home for cross-product troubleshooting content, so a topic can be half-covered there without any dedicated skill existing.

An incidental grep hit is not coverage. The worked failure is a Mirroring search matching "Spark History Server mirror" in fabric-spark — same substring, unrelated subject. Read the surrounding heading before counting a hit. Conversely, a topic can be genuinely covered under vocabulary you did not grep for; skim the skills/README.md section list for the relevant domain as a second pass.

A grep finds a word; the script finds a competitor. The second outcome below — two descriptions that both half-match one request — is invisible to a grep, because neither description need contain the other's vocabulary. Run it against the nearest existing skill the topic would sit beside:

uv run --with pyyaml scripts/skill-overlap.py overlap --skill <nearest-skill>

It ranks that skill's pairs by shared distinctive tokens, so what already clusters around your topic shows up before you have written a line. A description that does not exist yet cannot be scored, so this runs against the neighbour here and against the candidate at step 7. Read its output into the three outcomes; it changes what you find, not what you do about it.

Before authoring a platform skill, check upstream first. Microsoft ships a catalog at microsoft/skills-for-fabric, and vendoring one of its skills is sometimes the better answer than authoring a parallel one. drift-audit's skills-for-fabric registry entry carries the counterpart table as a starting map. Decide vendor-versus-author deliberately; the failure this prevents is a local skill and an upstream one competing for the same request, with no record of why both exist.

Three outcomes:

  • Covered correctly — stop. Say where, and that nothing is needed.
  • Covered partially, in a skill that owns the domain — stop and propose extending that skill instead. A second skill splitting one domain makes both harder to trigger, because the model is choosing between two descriptions that both half-match.
  • Not covered — continue.

The stop cases are real stops. Do not proceed to drilling because the topic is interesting.

3. Decide the name and namespace

Put the proposal to the user before drilling. Naming is cheap to change now and expensive later — the name is in the directory, the slash command, and every cross-reference.

  • Behavioral, cross-domain skills take the verb you invoke — commit, learn, code-review, drift-audit. Read the name as the user typing it.
  • Platform skills take their group's namespace prefix — fabric-, pbir-/pbid-/pbip-, or msix- (the lint's PLATFORM_PREFIXES).
  • powerbi-* is reserved. Those are vendored from microsoft/skills-for-fabric and keep upstream naming so re-sync diffs stay clean. Never take that prefix for a local skill.
  • Pick the TREE before the group, and pick it by asking what the skill acts on — not from the namespace, which cannot answer this. Does it act on this repo, or on the user's own work?

    • Acts on agent-config itself — its groups, its linter, its handoff queue, its audit ledger: .claude/skills/<name>/SKILL.md, project scope. No group directory. It deploys nowhere and no script reaches it, which is the point: outside this working tree it has nothing to act on, so shipping it to user scope would put it in the startup listing of every client-repo session for no possible benefit.
    • Acts on the user's work — code, Fabric items, reports, any repo: skills/<group>/<name>/SKILL.md, deployable payload.

    Getting this wrong is silent and costs listing budget everywhere. The 2026-09-09 split took this repo's own maintenance skills out of user scope for exactly this reason; ls -d .claude/skills/*/ lists what sits at project scope now.

  • Within skills/, the job picks the group directory; the group directory is load-bearing: skills/fabric-*/ by a fabric-* skill's job, skills/power-bi/ for pbir-/pbid-/pbip- and a semantic-model fabric-*, skills/windows/ for msix-*, skills/workflow/ for the repo-general behavioral verbs (ls skills/workflow), skills/meta/ for upkeep of the agent configuration that must also run in client repos, kept from Copilot by its .no-copilot marker (ls skills/meta), and skills/social/ for personal-profile writing (linkedin-highlights), split out so a workplace Copilot deployment of workflow never carries it. A new group goes in PLATFORM_GROUPS or BEHAVIOURAL_GROUPS in scripts/lint-skill-overrides.py; a platform one stays out of the -SkillGroups default, linked per repo by -ClaudeDir (windows, 2026-10-01), and a user-scope one joins that default everywhere it is written, or the next linker run prunes it.
  • Depth is pinned per tree and a misplacement fails twice silently. The pre-commit hook matches ^(skills/[^/]+|\.claude/skills)/[^/]+/SKILL\.md$ — two directories under skills/, one under .claude/skills/. A skill placed flat at skills/<name>/SKILL.md, or nested a level deeper in either tree, is invisible to the linter and to Claude Code, which discovers skills exactly one level under a skills root.
  • Name the job, not the target, where they differ. drift-audit is named that way because it audits rules, CLAUDE.md, and the MCP templates too — skill-audit would have named a quarter of its scope and collided with a plausible future skill.
  • The linter enforces the mechanics: lowercase letters, digits and hyphens only, ≤ 64 chars, and no anthropic or claude anywhere in the name.

Check the name against the loaded plugin skills, not just this repo. A local skill competing with skill-creator or a plugin-dev:* skill for the same trigger surface is a real collision even though the directories never touch.

Also settle the scope question at this point: is this one skill or two? Reference and workflow halves of one topic are two skills only if each is asked for on its own; else the reference goes in the workflow's references/, as pbir-cli did into pbir-report-workflow on 2026-10-12, report work having run through the workflow. Decide with the user now; discovering it during drafting means rewriting the brief.

4. Drill the sources

Do not write from training data. The point of this step is that every claim in the finished skill traces to something read during this run.

  • Microsoft Learn — microsoft_docs_search to find the pages, then microsoft_docs_fetch for the ones that matter. Search returns 500-token excerpts, which are enough to locate a page and never enough to encode a constraint from.
  • Exact repo bytes, changelogs, release notes — github-mcp.
  • Anything else — WebFetch.

MCP tools are not in this skill's allowed-tools, which only pre-approves and never restricts (Claude Code skills docs, verified 2026-09-11), so leaving them out costs at most a permission prompt. Prefer them when present; fall back without ceremony when not.

Record what was drilled and what was not. The undrilled set is what bounds the draft, and it is the part that gets lost if it is not written down at the time. A brief that says "the REST surface was not drilled; nothing in this skill describes it" is what stops the next reader assuming the omission was an oversight. The template's Sources drilled section is where both halves go — not Notes, and not a sentence buried in Scope.

Evidence from a client's estate is cited by kind, never by name. Observed platform behaviour often comes from client work, and the behaviour is generic where the names are not. Write "a client sandbox workspace" and "a directory of upload files", not the workspace, item, table, column or repo names you saw — and never write a list of names "to genericize at draft time", which is the leak itself. This repo is public, a pushed name cannot be fixed forward, and the identity guard matches only names already on the denylist. On 2026-09-10 a brief reached public main carrying a client's workspace and table names in exactly such a list.

Delegating the drill is fine; delegating the verification is not. A large surface splits cleanly across subagents by source family, and each one must return a verbatim quote per claim rather than a summary. Then re-read the quotes behind anything load-bearing — a permission, a limit, a path, a gate — yourself, before it reaches the draft. Observed 2026-09-11: a subagent marked a claim CONFIRMED against a quote that did not support it, and the firsthand re-reads also caught a wrong endpoint path that two shipped skills had been carrying.

Stop drilling when new pages stop changing the outline, not when the source list is exhausted.

5. Write the handoff brief

The target is docs/handoffs/execute/<name>.md, built from docs/handoffs/templates/skill-handoff.md.

A queue brief under another stem is replaced, not kept beside it. Queue names often end -skill (ls docs/handoffs/execute/*skill*), and /test-skill step 1 reads <name>.md: carry the queue brief's content as below, git rm it, and drop its name wherever a blocked-by or a link holds it (2026-10-01).

Check whether that path is already occupied before writing a byte. A /drift-update escalation leaves its scoping input at exactly this name, so the file that authorizes the work and the file this step produces collide by default. Such a file is normally untracked, which makes an overwrite unrecoverable — git has nothing to restore.

If something is there, read it in full and treat it as source rather than as an obstacle. Carry across everything that outlives it — the authorization, the audit evidence, the undrilled set, and anything citing a gitignored path that will not survive on its own — then confirm with the user that the file may be replaced. Never overwrite a brief path unread.

Every heading in the template survives into the filled brief. Sections that do not apply get N/A — <brief reason> under the heading, never deletion.

Strip the per-section > Guidance: notes. They are instructions for filling the template, not content, and a brief that keeps them reads as half-finished. Exactly two blocks are reproduced verbatim: the guidance note directly under the title, and Claude Code's post-draft checklist. docs/handoffs/examples/author-skill.example.md is the reference — two guidance blocks in the finished brief, not one per heading.

Fill Last verified with today's date.

The brief is not ceremony and not a handoff to another surface. It is the record of what was decided and what was deliberately left out, and the excluded set is the half that cannot be reconstructed from the finished skill. Write it before drafting even though the same session does both — the ordering is what makes the scope decisions explicit instead of emergent.

If an existing brief in docs/handoffs/examples/ matches the new skill's shape, lift it as design source and record that lineage in Changes from source proposal using the wording that examples/README.md specifies, rather than re-narrating the design.

Show the brief to the user before drafting from it.

6. Draft the SKILL.md

Write the SKILL.md from the brief, at the path the tree decision in step 3 picked — skills/<group>/<name>/SKILL.md for payload, .claude/skills/<name>/SKILL.md for a skill that maintains this repo.

The description is the entire model-invoked trigger mechanism. Write it to fire on the queries the skill should answer — the user's vocabulary, error strings, tool and command names — not to summarize the body. A description that reads as an accurate abstract and never triggers has failed at its only job. Where the skill neighbours another, spend a clause on the disambiguation.

A disambiguation pointer must be reachable from where it is read. A paths:-scoped skill is in the listing only once one of its own globs has matched, so "use <other-skill>" is dead whenever the two share no trigger file. The failure is worse than a no-op: the model calls the Skill tool, gets Unknown skill, and reports that skill as not installed — a false diagnosis layered on a dead pointer, in a session where it was deployed and merely not activated. So point at a co-active neighbour by name, and point off the shared surface by file — opening the file is what activates the skill there, which makes the file the only pointer that works cold. Measured 2026-09-04: pbir-filters said "for filter-pane styling use pbir-themes", and their globs are disjoint.

Long detail goes to the skill's own references/, not the body. Root CLAUDE.md is explicit about this. Command flag tables, per-item-type matrices, and long worked examples belong in a reference file the body points at. The linter caps the body at 500 lines, but that is a backstop, not a target.

If you are relocating content out of an existing body, verify nothing was lost before committing, with the check in references/relocating-content.md.

Match the house voice: numbered steps, bold lead-ins for the rule being stated, an explicit constraints section at the end, and reasons attached to rules that would otherwise look arbitrary.

Nothing goes in that drilling did not establish. A plausible claim with no source behind it is the failure mode this whole procedure exists to prevent. If something is believed but unverified, mark it as such inline with the date and version, the way /learn does, so a later /drift-audit can confirm or remove it.

7. Post-draft checks

Run all five. Each catches something the others do not.

uv run --with pyyaml scripts/lint-frontmatter.py <the SKILL.md you wrote>

Re-count the description. The linter gates description at 1,024 and when_to_use at 512 — the two halves of the 1,536 listing truncation point — but it reports overflow only after the fact and never warns on a near miss:

uv run --with pyyaml python -c "import sys,yaml; print(len(yaml.safe_load(open(sys.argv[1],encoding='utf-8').read().split('---')[1])['description']))" <the SKILL.md you wrote>

1,024 is the Agent Skills spec cap, and description is one of the six fields the claude.ai upload path accepts — so that is the field that has to stay portable. Re-count after any wording change, not once at the end. If the skill sets when_to_use, count it too against its own 512: it is a Claude Code extension the spec does not carry, so spending the remainder there costs no portability the skill still had.

cat the whole file after any edit. YAML frontmatter is a single malformed line away from the skill silently not loading, and the Edit tool on Windows is where that line comes from.

pre-commit run --files <the SKILL.md you wrote> <its references/*.md> <the brief>

Not --all-files, which is the index (git ls-files): an untracked draft is invisible to it, so lint-skills passes without reading the draft; --files takes any path on disk (pre-commit 4.6.2, 2026-10-01).

Score the draft against its neighbours, which step 2 could not:

uv run --with pyyaml scripts/skill-overlap.py overlap --skill <name>

A borrowed clause scores as competition: recreate-repo's when_to_use reused a sentence of land's, and the pair scored 43.7, then 35.6 reworded (2026-10-01). Report the score, the shared tokens and the pair's place in the bare overlap listing, since --skill ranks only <name>'s own pairs; it is a question for the user, not a gate.

8. Register it in its catalogue

Add the entry to skills/README.md for a payload skill, in the section its group implies, or to .claude/skills/README.md for a project-scope one. Update the count in the section heading where one is present.

Match the house style there: what the skill covers, and — where the name is not self-evident — why it is named that. The drift-audit and drift-handoff entries in .claude/skills/README.md are the model for the second half. An entry that only restates the description earns nothing the description does not already do.

This is the one place this skill edits a file it did not create. Keep the diff to the single added entry and the count.

9. Report, sweep, hand off

Report:

  1. What was drilled and what was not. The undrilled set, verbatim from the brief.
  2. The scope decisions — what the skill deliberately does not cover, and why.
  3. Check results — lint, description count, pre-commit, overlap.
  4. That the skill is not behaviourally tested. Say it plainly — but for the right reason. It is not that the file cannot reload: skills hot-reload in-session, fixed upstream in 2.1.216 and verified here 2026-08-31 and again 2026-09-02 on an in-place description edit. It is that the session which wrote the skill is the worst place to test it — accumulated context can mask a co-load failure, and you already know the answers you are checking for. A cold run against a --safe-mode baseline is the test. Name the specific queries it should fire on, so the fresh-session test is runnable rather than aspirational — those queries are what /test-skill reads back out of the brief, so a vague one here becomes a vague test there.

Then sweep docs/handoffs/execute/ for briefs whose work has landed. A queued brief is deleted once its change lands, or promoted into examples/ in the one case where something cites it. That convention has already failed once unattended, which is why the sweep is a step here instead of a habit.

  • The brief written at step 5 stays queued. Nothing is validated until the fresh-session test has run.
  • A skill brief beside a skill that now exists stays queued too: docs/handoffs/CLAUDE.md says why; /test-skill step 10 deletes it.
  • For any other brief whose subagent or other work now exists, propose deletion or promotion and name which. Propose rather than act: you can see that an artifact exists, but not whether the user considers the work landed. Deletion itself is safe — briefs are committed when written, so the deleting commit and its content stay recoverable.

Hand off to /commit, then /test-skill, and do neither here. For a skill in a deployed group, workflow, social or meta, /test-skill step 7 cannot run in a worktree — the group's junction serves the main checkout's copy, and link-claude.ps1 refuses a worktree — so land it as docs/handoffs/CLAUDE.md says, deploy, then test on main. A platform or project-scope skill can be tested in its worktree, its stamp still waiting for main (/test-skill step 10). The test reads the brief from disk, so it need not follow at once, and a cold run is the better one (2026-10-01).

In a brief's worktree, the hand-off opens with this session leaving it, by ExitWorktree with keep when the user asks: the landing runs from the main checkout, and a session entering .claude/worktrees/<brief> to test a project-scope skill is refused while this one is inside, belongs to another running Claude Code session (locked: <reason>) (2.1.283, 2026-09-30). If step 5 renamed the brief, name the worktree's move to the new stem for whoever lands it, or the queue view pairs it with nothing (docs/handoffs/execute/README.md § "Every brief takes a worktree", 2026-10-01).

10. Constraints

  • No unverified claims. If step 4 did not establish it, it does not go in the skill. Marked-unverified is the only exception, and it carries a date.
  • The stop cases in steps 1 and 2 are stops. Route to /learn, propose an extension, or hand off to a generic authoring skill — do not author anyway.
  • Name before drilling. Naming and the one-skill-or-two call go to the user first; both are cheap now and expensive after a draft exists.
  • Brief before draft, even in one session.
  • No test fixtures. tests/ is a separate, deliberate exercise — and it is /test-skill's, which writes the fixtures, updates expected_activations.md and runs both the static and the real-path activation test.
  • No commit, no push.
  • Do not edit other skills. Only the new skill's own directory, the new brief, and its single catalogue entry -- skills/README.md for a payload skill, .claude/skills/README.md for a project-scope one. Edit is available for those two existing files and nothing else — adjacent cleanups are /learn and /simplify territory, and an unbriefed edit made here has no evidence behind it. The one removal is step 5's, of a queue brief the new one replaces.
  • Deletion is the user's call. Step 9 proposes; it does not sweep files away.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.