Skip to content
Skills Library
AI & agents · Writing

skill-authoring

/skill-authoring

Use when writing, moving or checking a skill in this corpus. Layout, digest, gate.

Repository
Agito ↗
Licence
CC0-1.0
Last repository change
13.11.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

CC0-1.0, otwarta.

What it does and when to use it

Use when writing, moving or checking a skill in this corpus. Layout, digest, gate.

Original author description

Use when writing, moving or checking a skill in this corpus. Layout, digest, gate.

How it works

  1. The contract
  2. The five principles
  3. Frontmatter
  4. References
  5. The format gate
  6. Pitfalls
  7. Claims and how to test them
Original SKILL.md headings · 134 lines, 1,157 words
SKILL.md preview
---
name: skill-authoring
description: Use when writing, moving or checking a skill in this corpus. Layout, digest, gate.
version: 1.0.0
license: MIT
platforms: [macos, linux]
metadata:
    hermes:
        tags: [skills, authoring, validation, corpus, methodology]
        related_skills: [workspace, diagrams]
---

# Skill Authoring

A skill that is fluent, unverifiable and in the wrong tree costs twice: the reader follows a command
someone paraphrased, and the next session never sees the file at all. This corpus has one layout and
one validator, and both are cheap to satisfy once they are known.

## The contract

`agito skills Documentation/Skill` reports rather than returning early, and it checks three rules:

- **parsable** - `SKILL.md` exists, its frontmatter block is closed, it is a mapping, it carries a
  non-empty `description`, and its `name` equals the directory lowercased (`Diagrams/` is
  `name: diagrams`);
- **cited** - every file under `Reference/` is named in `Reference/Index.md`;
- **listed** - the corpus root's index names the skill: `Documentation/Skill/Index.md`, or
  `AGENTS.md`.

A finding is a rule, a skill and a sentence, and an empty finding list is a valid corpus.

```sh
agito skills Documentation/Skill
agito skills Documentation/Skill --json
```

The command also prints a digest. It is `sha256:` over the canonical JSON
`[[name, description, references], …]` - no body text, no path, no modification time - so two
checkouts of the same corpus agree on it, and it moves when a skill is added, renamed, re-described
or gains a reference file. It does not move when only the prose changes, which is why a stale
description survives a green check.

`Documentation/Skill/Index.md` belongs to whoever owns the corpus. Adding a skill is a directory
plus `SKILL.md`; the index row is a separate edit, and the `listed` rule reports the skill until it
lands.

## The five principles

**1. Commands are variables, never prose.** Copy every command, flag, path and identifier
byte-stable. Do not paraphrase, clarify or modernize one. If the source has no command where one is
needed, write UNKNOWN rather than inventing one, and a sentence that asserts live system state
carries its probe in the same paragraph or is marked CLAIM.

**2. Relations over fluency.** English hides relations behind verbs. Every "not" in the source
becomes two sentences: what it is, and what it is not. Every prohibition keeps its reason in the
next sentence, because a rule without a reason is the first one dropped. Never write "verified",
"works" or "exists" unless the same paragraph holds the command that would prove it.

**3. Size is grammar.** A bullet stays in `SKILL.md` when violating it causes a wrong write, a lost
commit or a false success. A bullet moves to `Reference/` when it is a worked instance of a rule
already stated - the one-line rule and a pointer stay in the body. A body of about 200 lines is the
shape here; a page of narrative is a page the reader skims, and the claim-to-test table is what they
were looking for.

**4. Lessons, not logs.** No dates, no incident narration, no "we once saw". A scar is allowed as a
test case, never as a story. Every success claim pairs with the probe that would falsify it.
Forbidden endings: "in short", "be careful", "make sure", and a summary paragraph that restates the
body.

**5. Placement discipline.** A skill that describes this repository lives in
`Documentation/Skill/<Name>/`, beside the code it describes, and travels with it. A method that
holds in any repository can live in a profile tree instead, and there it may name the machine it
runs on, because it never leaves that machine. The test is one question: does this file travel with
the repository? Yes means the repo tree, anonymised; no means the profile. A file written to the
wrong tree is invisible rather than merely untidy - not in the corpus, not in the index, not in the
next clone.

## Frontmatter

```yaml
---
name: skill-authoring
description: Use when writing, moving or checking a skill in this corpus. Layout, digest, gate.
version: 1.0.0
license: MIT
platforms: [macos, linux]
metadata:
    hermes:
        tags: [skills, authoring, validation, corpus]
        related_skills: [workspace, diagrams]
---
```

`name` is the directory lowercased, so a directory rename is a frontmatter edit. `description` is
one line stating the trigger before the content, because a reader chooses a skill by that line
alone. `related_skills` names skills that exist in this corpus, by their lowercased name.

## References

`Reference/Index.md` lists every file in the directory, one line each, saying what it carries. A
file present but unlisted is an `unlisted-reference` finding; a file listed but absent is a dead end
the reader finds before the validator does. Add a reference when a worked instance outgrows a rule,
not before.

## The format gate

```sh
node node_modules/prettier/bin/prettier.cjs --check Documentation/Skill/<Name>
```

`prettier.config.mjs` sets `printWidth: 100`, `useTabs: true` and `proseWrap: "always"`, so write
the body wrapped at 100 columns and align the tables by hand. A failure is a real defect. A pass is
not evidence of style: the check answers whether the formatter is content with the file, and it
cannot tell a well-shaped skill from a ragged one. Read the body once against the five principles
before believing the exit code.

## Pitfalls

- **An unquoted colon in a value kills the block.**
  `description: Drive the pipeline: scrape, build.` is invalid YAML, and a line grep for `^name:`
  still passes while the loader reads nothing. Quote any value containing `: `, and validate with a
  parser rather than with grep.
- **A description past the print width is a formatting casualty.** A formatter that reflows
  frontmatter wraps the value onto a continuation line, and a line-based reader then sees an empty
  description while the file looks correct in the editor. Keep every value on one line under 100
  columns.
- **The validator does not read the body.** A skill with no claim-to-test table, no reason beside a
  prohibition and a dated story in the middle passes all three rules, because the corpus contract
  checks structure and the house style does not. The gate is a floor.
- **A body edit does not move the digest.** Editing prose changes nothing the digest covers, so a
  description that no longer matches the body stays green; re-read the description whenever the
  body's scope changes.

## Claims and how to test them

| Claim                             | Test                                                                                          |
| --------------------------------- | --------------------------------------------------------------------------------------------- |
| The corpus passes its own gate    | `agito skills Documentation/Skill` prints no findings                                         |
| The gate reports, not stops       | a skill with an unclosed frontmatter block still yields findings for the others               |
| `name` must match the directory   | rename a copy of a directory without editing `name` and the gate reports that skill           |
| An unlisted reference is caught   | add `Reference/Probe.md` and leave it out of the index; the gate reports `unlisted-reference` |
| The digest covers metadata only   | run `--json`, edit one body sentence, run it again; the digest is unchanged                   |
| The digest covers the description | run `--json`, change one `description` value, run it again; the digest changes                |
| The formatter accepts the tree    | `node node_modules/prettier/bin/prettier.cjs --check Documentation/Skill` exits `0`           |
Files in this package (4)
  • SKILL.md 8 KB
  • Reference/Before-After.md 3 KB
  • Reference/Frontmatter.md 3 KB
  • Reference/Index.md 1 KB

Versions

RepositoryScoreLicence
This page · MergedBeastAgito/Agito95CC0-1.0
TMCP-HUB/project-resolver100Apache-2.0
contentful/skills100MIT
Esposter/Esposter100Apache-2.0
komluk/scaffolding100MIT
nyldn/claude-octopus100MIT
redhat-developer/rhdh-skills100Apache-2.0
tencentcloudbase/cloudbase-ai-toolkit100MIT
ovargas/virtual-team100MIT

Database snapshot: 13.11.2026 · package version 25820a28dca4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100skill-authoring-lifecycle
    Scaffold and formally review a new Agent Skill in this marketplace repo. Covers valid SKILL.md generation, directory layout, registry entries, and spec auditing. Use when adding a skill, validating frontmatter, or checking marketplace readiness before a PR.
  • 100skill-authoring-lifecycle
    Scaffold and formally review a new Agent Skill in this marketplace repo. Covers valid SKILL.md generation, directory layout, registry entries, and spec auditing. Use when adding a skill, validating frontmatter, or checking marketplace readiness before a PR.
  • 95claude-skill-authoring
    Use when authoring or editing a skill in this estate — file layout, description length limits, and the self-contained-execution rule. General skill-authoring guidance is covered by Anthropic's own Agent Skills docs.
  • 100claude-skill-authoring
    Use when authoring or editing a skill in this estate — file layout, description length limits, and the self-contained-execution rule. General skill-authoring guidance is covered by Anthropic's own Agent Skills docs.
  • 96toskill
    Create a repository digest and review a SKILL.md. Use when the user asks to add agent instructions to a tool, lint skill frontmatter, or prepare an upstream contribution.
  • 85claude-md-authoring
    Best practices for writing effective CLAUDE.md files. Use when creating, updating, or auditing CLAUDE.md files for projects or directories.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.