agentleFS
vasilyu1983vasilyu1983/AI-Agents-public/skills/universal/agents-skills/SKILL.md

agents-skills

Skill94 starsChanged 35 days agoMITView on GitHub

Creates and audits agent skills: SKILL.md, references, scripts, runtime metadata. Use when writing, validating, or security-reviewing a skill, or fixing truncated skill listings.

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 11 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create or modernize skill bundles while keeping the portable core separate from runtime extensions.

    line 10
  2. Very specific:

    Treat license, compatibility, and metadata as portable optional fields.

    line 40
  3. Very specific:

    Keep the main body focused on selection, workflow, completion criteria, and navigation.

    line 41
  4. Distinctive:

    Keep the bundle usable when copied by itself.

    line 42
  5. Distinctive:

    Verify runtime-specific fields and substitutions in current official documentation before copying them.

    line 46
  6. Distinctive:

    Keep Anthropic-only mechanics in frontmatter-reference.md and anthropic-skills-guide.md, not in the portable example.

    line 48
  7. Very specific:

    Treat agents/openai.yaml as Codex-facing adjunct metadata (UI, invocation policy, dependencies).

    line 49
  8. Distinctive:

    Search the graph and existing bundles before creating anything.

    line 54
  9. Distinctive:

    Run the static checks that match the edit, then trigger, non-trigger, navigation, and runtime-specific evals.

    line 58
  10. Distinctive:

    If the body or routing changed, regenerate and validate the repository graph and eval manifest.

    line 59
  11. Distinctive:

    Default shared skills to a matter-of-fact, outcome-oriented reference style.

    line 68
  12. Distinctive:

    Never let enrichment silently drop candidates or evidence.

    line 71
  13. Distinctive:

    Do not shrink useful full-body instructions merely to fit a discovery listing.

    line 74
  14. Distinctive:

    Do not publish model-quality or token-saving numbers unless the exact claim has a reproducible control, dated evidence, and disclosed …

    line 75
  15. Very specific:

    Do not add a generic ## Fact-Checking section to satisfy this.

    line 78
  16. Very specific:

    When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present.

    line 118

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

Agent Skills

Create or modernize skill bundles while keeping the portable core separate from runtime extensions. This skill supplies this repository's dual-runtime, catalog, graph, and composition rules. Use the Agent Skills open spec and the standard skill-creator for generic scaffolding and eval mechanics.

Quick Reference

TaskLoad or run
Scaffold a skillStandard skill-creator, then frontmatter-reference.md
Fix truncated or omitted skill listingsskill-context-budgets.md
Audit a skillpython3 scripts/validate_skill.py <skill-dir> and maintenance-workflows.md
Choose support-file boundariesskill-patterns.md
Write a skill that wraps an MCP server or CLI toolskill-patterns.md
Add runtime-specific metadatafrontmatter-reference.md
Test trigger and navigation behaviorskill-validation.md
Maintain Claude-specific behavioranthropic-skills-guide.md
Ship across runtimesdual-distribution.md
Choose skill, agent, or bothskill-vs-agent-decision.md
Run the runtime's skill eval or diagnosticsLook up the command in the runtime docs; see skill-validation.md
Review a third-party skill before installingCheck allowed-tools, ! shell-injection lines, frontmatter hooks, bundled scripts, and source pinning (frontmatter-reference.md)

When Not to Use

  • Wiring per-skill learnings, consolidation, or drift audits of learnings.md: hand off to agents-skills-feedback-loop. This skill only tells you to consult the loop.
  • Designing task-quality evals, graders, or regression gates for an AI system rather than a skill's trigger and navigation behavior: hand off to ai-evals.
  • Deciding whether the work belongs in a subagent, hook, or MCP server instead of a skill: read skill-vs-agent-decision.md, then hand off to the owning agents-* skill listed under Navigation.

Core Contract

Portable baseline:

  • Require skill-name/SKILL.md with explicit name and trigger-rich description.
  • Treat license, compatibility, and metadata as portable optional fields. allowed-tools belongs to the open spec, but runtime support may vary.
  • Keep the main body focused on selection, workflow, completion criteria, and navigation. Put reference detail in references/, deterministic helpers in scripts/, and templates in assets/.
  • Keep the bundle usable when copied by itself. Every support file must be linked from the workflow or Navigation.

Runtime extensions:

  • Verify runtime-specific fields and substitutions in current official documentation before copying them.
  • Name the target runtime in compatibility when a skill depends on runtime-specific headers or invocation behavior; remove unqualified portability claims.
  • Keep Anthropic-only mechanics in frontmatter-reference.md and anthropic-skills-guide.md, not in the portable example.
  • Treat agents/openai.yaml as Codex-facing adjunct metadata (UI, invocation policy, dependencies). SKILL.md remains canonical and independently valid; revalidate semantic alignment when intent changes.

Workflow

  1. Before scaffolding, answer three questions: who or what invokes the skill (the user by slash command, or the model automatically), what a good output looks like, and which mistakes happen today without it. Then write two or three concrete user tasks, including a nearby case that should not trigger the skill.
  2. Search the graph and existing bundles before creating anything. Extend an existing owner when it already covers the capability.
  3. Scaffold the portable core: folder, SKILL.md, name, description, minimal workflow, and completion criteria.
  4. Choose the target runtimes, then add only verified runtime-scoped metadata.
  5. Split long detail and reusable artifacts into support files; link each file at the stage where it is needed.
  6. Run the static checks that match the edit, then trigger, non-trigger, navigation, and runtime-specific evals.
  7. If the body or routing changed, regenerate and validate the repository graph and eval manifest.
  8. Inspect the diff and fix failures caused by the change before handoff. Record observed routing behavior in the repository routing log.

For each completion claim, name its evidence level: static bundle validation, live runtime loading, observed routing, or task-quality evaluation. Passing validate_skill.py proves structure and local links; it does not prove that a runtime loaded the skill, selected it for a prompt, or produced a better answer.

For the exact create, audit, runtime, router, state, and graph recipes, load maintenance-workflows.md. For eval design and negative controls, load skill-validation.md.

Design Rules

  • Default shared skills to a matter-of-fact, outcome-oriented reference style. Put coaching voice or richer behavioral framing in a runtime-specific layer when needed.
  • Keep descriptions specific enough to select the skill from real user language. This library's convention (not a runtime limit) is a roughly 120–180 character, 25-word description; the enforced ceiling is the constant in scripts/audit_skill_metadata.py. Runtimes impose their own caps; check the runtime docs when they are tighter.
  • Model routers and composed workflows as explicit stages: candidate sources, enrichment, eligibility filters with reasons, independent scoring, selection, post-selection validation, then side effects.
  • Never let enrichment silently drop candidates or evidence. Preserve the input or report a named filter reason.
  • Evaluate adjacent candidates independently before selecting among them.
  • Lay out in-skill navigation as a hub and leaves: the root SKILL.md links each reference one hop away with a load condition. A reference may cross-link another reference only when SKILL.md links that one too, so no file sits two hops deep. Router graphs are checked with foundations-graph-theory (reachability, cycles, fan-out, single-path gates).
  • Do not shrink useful full-body instructions merely to fit a discovery listing. Use host-specific catalog controls and progressive disclosure; the generated compact map does not filter native startup discovery.
  • Do not publish model-quality or token-saving numbers unless the exact claim has a reproducible control, dated evidence, and disclosed limits.
  • Name the platform for runtime-specific guidance, and write a value that may drift as a lookup step (what to check, in which primary source, for which decision) rather than a dated value.
  • Do not add a generic ## Fact-Checking section to satisfy this; write the lookup step where the changeable fact is actually used. validate_skill.py no longer treats ## Fact-Checking as a required core section.
  • If the host repository has a skill edit contract (this library keeps one at rules/repo/skill-edit-contract.md), follow it. Without one, the essential steps are: search the catalog before creating; read only the files you will change; give every fact one home (judgment in SKILL.md, depth in linked references/, volatile values as lookup steps); keep the minimal diff; cite only what you read; and report the evidence level of each completion claim.

Completion Contract

A skill change is complete when:

  • portable frontmatter, local links, support-file navigation, and source metadata pass applicable static checks;
  • runtime-specific fields are scoped and verified rather than presented as portable;
  • trigger and non-trigger behavior is covered when selection semantics changed;
  • graph, catalog, and long-skill manifest artifacts are synchronized when affected;
  • known bugs, current runtime behavior, and version-specific workarounds used in the answer were checked against current primary sources;
  • any remaining failure is identified as pre-existing or outside scope with evidence.

Navigation

Load only the resource needed for the current decision:

  • skill-context-budgets.md — Codex catalog overflow, host-specific controls, and verification
  • maintenance-workflows.md — repository recipes, validation commands, completion criteria, and recurring traps
  • frontmatter-reference.md — portable and runtime-specific header contracts
  • skill-patterns.md — progressive-disclosure, script-backed, stateful, and composable patterns
  • skill-validation.md — static, trigger, non-trigger, navigation, and effectiveness-claim evals
  • anthropic-skills-guide.md — Anthropic-only behavior
  • dual-distribution.md — canonical source and wrapper drift controls
  • skill-vs-agent-decision.md — placement and execution-boundary decisions
  • data/sources.json — dated sources used by this skill

Scripts:

  • scripts/validate_skill.py — one bundle
  • scripts/validate_catalog.py — a catalog root
  • scripts/audit_skill_metadata.py — metadata, local inventory thresholds, and compact-index structure
  • scripts/build_skill_graph.py — local skill graph
  • scripts/test_validate_skill.py — validator regressions

Related skills: agents-subagents, agents-hooks, and agents-mcp.

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both. Add a durable new observation with agents-skills-feedback-loop/scripts/append_learning.py; do not use the main skill body as a task log.

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.