AI & agents · Writing
skill-authoring
/skill-authoring
Use when writing, moving or checking a skill in this corpus. Layout, digest, gate.
For whom
- Author
- MergedBeastAgito ↗
- 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
- The contract
- The five principles
- Frontmatter
- References
- The format gate
- Pitfalls
- 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
| Repository | Score | Licence |
|---|---|---|
| This page · MergedBeastAgito/Agito | 95 | CC0-1.0 |
| TMCP-HUB/project-resolver | 100 | Apache-2.0 |
| contentful/skills | 100 | MIT |
| Esposter/Esposter | 100 | Apache-2.0 |
| komluk/scaffolding | 100 | MIT |
| nyldn/claude-octopus | 100 | MIT |
| redhat-developer/rhdh-skills | 100 | Apache-2.0 |
| tencentcloudbase/cloudbase-ai-toolkit | 100 | MIT |
| ovargas/virtual-team | 100 | MIT |
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.