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.
In this repository146 other files it gives its agents.
- agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- hooks/AGENTS.mdAGENTS.md
- agents-hooksSkill
- agents-mcpSkill
- agents-memorySkill
- agents-skills-feedback-loopSkill
- agents-subagentsSkill
- agents-swarm-orchestrationSkill
- ai-agentsSkill
- ai-architecture-advisorSkill
- ai-bot-builderSkill
- ai-coding-agents-observability-evalsSkill
- ai-coding-agents-pluginsSkill
- ai-coding-agents-provider-runtimeSkill
- ai-coding-agents-runtime-coreSkill
- ai-coding-agents-safety-envelopeSkill
- ai-coding-agents-settings-policySkill
- ai-coding-agentsSkill
- ai-coding-agents-stateSkill
- ai-coding-agents-surfacesSkill
- ai-context-layerSkill
- ai-data-curation-pretrainingSkill
- ai-deep-researchSkill
- ai-distributed-trainingSkill
- ai-evalsSkill
- ai-llm-inferenceSkill
- ai-llmSkill
- ai-local-model-opsSkill
- ai-ml-data-scienceSkill
- ai-mlopsSkill
- ai-ml-timeseriesSkill
- ai-post-trainingSkill
- ai-pretrainingSkill
- ai-product-operating-modelSkill
- ai-prompt-engineeringSkill
- ai-ragSkill
- ai-scaling-lawsSkill
- ai-vector-brainSkill
- ai-voice-botsSkill
- data-analytics-engineeringSkill
- data-lake-platformSkill
- data-metabaseSkill
- data-sql-optimizationSkill
- data-streamingSkill
- dev-ai-coding-metricsSkill
- dev-api-designSkill
- dev-context-code-graphSkill
- dev-context-engineeringSkill
- dev-context-multi-repoSkill
- dev-contribution-quality-analysisSkill
- dev-dependency-managementSkill
- dev-git-commit-messageSkill
- dev-git-workflowSkill
- dev-workflow-planningSkill
- docs-ai-prdSkill
- docs-codebaseSkill
- docs-notes-retrievalSkill
- document-docxSkill
- document-pdfSkill
- The first 60 shown.
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
- Distinctive: line 10
Create or modernize skill bundles while keeping the portable core separate from runtime extensions.
- Very specific: line 40
Treat license, compatibility, and metadata as portable optional fields.
- Very specific: line 41
Keep the main body focused on selection, workflow, completion criteria, and navigation.
- Distinctive: line 42
Keep the bundle usable when copied by itself.
- Distinctive: line 46
Verify runtime-specific fields and substitutions in current official documentation before copying them.
- Distinctive: line 48
Keep Anthropic-only mechanics in frontmatter-reference.md and anthropic-skills-guide.md, not in the portable example.
- Very specific: line 49
Treat agents/openai.yaml as Codex-facing adjunct metadata (UI, invocation policy, dependencies).
- Distinctive: line 54
Search the graph and existing bundles before creating anything.
- Distinctive: line 58
Run the static checks that match the edit, then trigger, non-trigger, navigation, and runtime-specific evals.
- Distinctive: line 59
If the body or routing changed, regenerate and validate the repository graph and eval manifest.
- Distinctive: line 68
Default shared skills to a matter-of-fact, outcome-oriented reference style.
- Distinctive: line 71
Never let enrichment silently drop candidates or evidence.
- Distinctive: line 74
Do not shrink useful full-body instructions merely to fit a discovery listing.
- Distinctive: line 75
Do not publish model-quality or token-saving numbers unless the exact claim has a reproducible control, dated evidence, and disclosed …
- Very specific: line 78
Do not add a generic ## Fact-Checking section to satisfy this.
- Very specific: line 118
When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present.
≈ “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.
Files
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
| Task | Load or run |
| Scaffold a skill | Standard skill-creator, then frontmatter-reference.md |
| Fix truncated or omitted skill listings | skill-context-budgets.md |
| Audit a skill | python3 scripts/validate_skill.py <skill-dir> and maintenance-workflows.md |
| Choose support-file boundaries | skill-patterns.md |
| Write a skill that wraps an MCP server or CLI tool | skill-patterns.md |
| Add runtime-specific metadata | frontmatter-reference.md |
| Test trigger and navigation behavior | skill-validation.md |
| Maintain Claude-specific behavior | anthropic-skills-guide.md |
| Ship across runtimes | dual-distribution.md |
| Choose skill, agent, or both | skill-vs-agent-decision.md |
| Run the runtime's skill eval or diagnostics | Look up the command in the runtime docs; see skill-validation.md |
| Review a third-party skill before installing | Check 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.mdwith explicitnameand trigger-richdescription. - Treat
license,compatibility, andmetadataas portable optional fields.allowed-toolsbelongs 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 inscripts/, and templates inassets/. - 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
compatibilitywhen 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.yamlas Codex-facing adjunct metadata (UI, invocation policy, dependencies).SKILL.mdremains canonical and independently valid; revalidate semantic alignment when intent changes.
Workflow
- 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.
- Search the graph and existing bundles before creating anything. Extend an existing owner when it already covers the capability.
- Scaffold the portable core: folder,
SKILL.md,name,description, minimal workflow, and completion criteria. - Choose the target runtimes, then add only verified runtime-scoped metadata.
- Split long detail and reusable artifacts into support files; link each file at the stage where it is needed.
- Run the static checks that match the edit, then trigger, non-trigger, navigation, and runtime-specific evals.
- If the body or routing changed, regenerate and validate the repository graph and eval manifest.
- 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.mdlinks each reference one hop away with a load condition. A reference may cross-link another reference only whenSKILL.mdlinks that one too, so no file sits two hops deep. Router graphs are checked withfoundations-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-Checkingsection to satisfy this; write the lookup step where the changeable fact is actually used.validate_skill.pyno longer treats## Fact-Checkingas 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 inSKILL.md, depth in linkedreferences/, 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 bundlescripts/validate_catalog.py— a catalog rootscripts/audit_skill_metadata.py— metadata, local inventory thresholds, and compact-index structurescripts/build_skill_graph.py— local skill graphscripts/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.
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
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.

