agentleFS
Sign inStart free
BlockKnown publisherblock/berd/distro/skills/skill-builder/SKILL.md

skill-builder

Skill1k starsChanged 3 months agoApache-2.0View on GitHub

Create, edit, or inspect Berd skills stored as skill folders with SKILL.md files. Use when the user wants to build a new skill, update an existing skill, convert a workflow into a reusable skill, or decide whether instructions, scripts, references, or assets belong in a skill.

We split this skill into the rules it gives an agent

17 rules. 0 are common, 13 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 60 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

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

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

    Use this skill when creating, editing, or inspecting Berd skills.

    line 14
  2. Very specific:

    Do not create README.md, CHANGELOG.md, or extra documentation files inside a skill folder.

    line 29
  3. Distinctive:

    Default to global unless the user is clearly working in a project directory.

    line 39
  4. Distinctive:

    If a project directory is active and the user has not specified scope, ask whether the skill should be saved for this project only or …

    line 41
  5. Distinctive:

    Do not ask when intent is clear:

    line 45
  6. Distinctive:

    When editing an existing skill, keep it in its current location unless the user explicitly asks to move it.

    line 50
  7. Very specific:

    Do not start or end with -

    line 84
  8. Distinctive:

    Do not use spaces, underscores, slashes, or capitals

    line 85
  9. Distinctive:

    Ask for 2-3 example requests or workflows if the goal is vague.

    line 96
  10. Very specific:

    Keep simple procedural guidance in SKILL.md.

    line 99
  11. Distinctive:

    Create or edit the skill folder.

    line 104
  12. Distinctive:

    Prefer direct file edits over helper scripts unless the repo already has a relevant script.

    line 105
  13. Distinctive:

    Read the existing skill before editing.

    line 115
  14. Distinctive:

    When useful, suggest a tiny test set:

    line 135
  15. Distinctive:

    Should trigger: obvious requests and paraphrases for the workflow.

    line 137
  16. Distinctive:

    Should not trigger: unrelated tasks and adjacent workflows outside scope.

    line 138
  17. Distinctive:

    If a skill under-triggers, make the description more concrete.

    line 140

“Common” is measured: kept by at least 6 in 10 of the 60 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

Skill Builder

Use this skill when creating, editing, or inspecting Berd skills.

What a Skill Is

A skill is a folder with a required SKILL.md file and optional supporting resources:

skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Do not create README.md, CHANGELOG.md, or extra documentation files inside a skill folder. Skill documentation belongs in SKILL.md or references/.

Storage Decision

Skills can be global or project-local:

  • Global: ~/.agents/skills/<skill-name>/SKILL.md
  • Project-local: <project>/.agents/skills/<skill-name>/SKILL.md

Default to global unless the user is clearly working in a project directory.

If a project directory is active and the user has not specified scope, ask whether the skill should be saved for this project only or globally for all projects.

Do not ask when intent is clear:

  • Project-local: "this repo", "this project", "only here", "project skill"
  • Global: "all projects", "global", "personal skill", "always available"

When editing an existing skill, keep it in its current location unless the user explicitly asks to move it.

Format

SKILL.md is UTF-8 Markdown with YAML frontmatter:

---
name: skill-name
description: What the skill does. Use when the user asks to...
---

# Skill Title

Instructions the agent follows.

Required frontmatter keys are name and description. Preserve unknown frontmatter keys when editing existing skills unless the user explicitly asks to change them.

The description is the trigger surface. It must explain both what the skill does and when to use it. Include concrete user phrases or task types. Keep it specific enough to avoid triggering for unrelated work.

Names

Skill names and folder names must match.

Use lowercase kebab-case:

  • Allowed: a-z, 0-9, and -
  • Maximum: 64 characters
  • Do not start or end with -
  • Do not use spaces, underscores, slashes, or capitals

Normalize user-provided titles by lowercasing, replacing invalid character runs with -, collapsing repeated separators when practical, trimming leading and trailing -, and truncating to 64 characters. Fall back to skill if needed.

On create collisions, use <skill-name>-2, <skill-name>-3, etc.

Authoring Workflow

  1. Understand the skill with concrete examples. Ask for 2-3 example requests or workflows if the goal is vague. Do not ask when the user has already provided enough detail.
  2. Decide the skill shape. Keep simple procedural guidance in SKILL.md. Add optional folders only when they earn their keep:
    • scripts/ for deterministic or repeatedly rewritten code
    • references/ for detailed docs loaded only when needed
    • assets/ for templates, fonts, icons, or files used in outputs
  3. Create or edit the skill folder. Prefer direct file edits over helper scripts unless the repo already has a relevant script.
  4. Validate the result. Confirm the folder exists, SKILL.md exists with exact casing, frontmatter is valid YAML, required keys are present, the name matches the folder, and existing metadata was preserved.
  5. Report the final path and a short summary of what the skill now does.

Editing Existing Skills

Read the existing skill before editing. Resolve targets by exact path, then frontmatter name, then folder name. Ask only if multiple matches remain.

Preserve supporting folders and unknown files unless the user explicitly asks to remove them.

Quality Checklist

Before finishing, check:

  • The skill has a clear, narrow purpose.
  • The description has likely trigger phrases and avoids vague claims.
  • Critical instructions are near the top of the body.
  • The body is concise; detailed material moves to references/.
  • Any fragile or repetitive operation uses a script where practical.
  • The skill can work alongside other skills without assuming it is the only active skill.

Trigger Testing

When useful, suggest a tiny test set:

  • Should trigger: obvious requests and paraphrases for the workflow.
  • Should not trigger: unrelated tasks and adjacent workflows outside scope.

If a skill under-triggers, make the description more concrete. If it over-triggers, narrow the description and add negative scope guidance.

Download now (ZIP)

  • Other versions69 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 69

    1. yusufkaraaslan/Skill_Seekers★ 15ksame name
    2. boshu2/agentops★ 452same name
    3. metaskills/skill-builder★ 112same name
    4. AsiaOstrich/universal-dev-standards★ 82same name
    5. Amazon-Quick/Amazon-Quick-official-catalog★ 50same name
    6. nateherkai/a-bunch-of-skills★ 41same name
    7. clasen/Skills★ 40same name
    8. sanqi-cd/Sanqi-Skills★ 28same name
    9. arctan303/creator.skill★ 19same name
    10. aiagentwithdhruv/skills★ 16same name

    59 more not listed

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Used alongsideProjects with it also use literature-research, commit-and-push and 10 more.

    Other files people use alongside this one.

    Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
    • nickjwellsSkill

      literature-research

      Search academic literature and perform deep research reviews. Use when user asks to search PubMed, find academic papers, or do literature reviews.

      Also in 3 projects that use this

    • nopandererSkill

      commit-and-push

      Automatically analyze git changes, generate Conventional Commits compliant commit messages, commit changes, and push to remote in a single automated workflow. Use when the user invokes /commit-and-push or explicitly requests to automatically commit and push changes following Conventional Commits format (feat:, fix:, docs:, etc.). This skill provides a fully automated git workflow without manual intervention.

      Also in 3 projects that use this

    • MicrosoftSkill

      excalidraw-diagram

      Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts.

      Also in 4 projects that use this

    • SkillPilotCHSkill

      level-up

      Eine Automatisierung pro Woche finden, scopen, shippen. Output landet als proposed-Eintrag in cadence.md mit konkreten Implementations-Schritten.

      Also in 3 projects that use this

    • SentrySkill

      onboard

      Onboard a service to sentry-options. Use when integrating a new service, creating schemas, or setting up the multi-repo sentry-options workflow.

      Also in 5 projects that use this

    • wpankSkill

      session-handoff

      WHAT: Create comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves long-running agent context exhaustion problem.

      Also in 5 projects that use this

  • In this repository18 other files it gives its agents.

Does it work?

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

Reviews can't be read right now.

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.

Check your setup, free