​

Skill metadata

​

Reference: full SKILL.md

​

Authoring Mibyan-Agent Skills (in-repo)

​

Overview

1. User-local: ~/.mibyan/skills/<maybe-category>/<name>/SKILL.md — personal, not shared. Created via skill_manage(action='create').
2. In-repo (this skill is about this case): skills/<category>/<name>/SKILL.md or optional-skills/<category>/<name>/SKILL.md inside the mibyan-agent repo — committed, shipped with the package. Use write_file + git add. skill_manage(action='create') does NOT target this tree.

​

When to Use

• User asks you to add a skill “in this branch / repo / commit”
• You’re committing a reusable workflow that should ship with mibyan-agent
• You’re editing an existing skill under skills/ or optional-skills/ (use patch for small edits, write_file for rewrites; skill_manage still works for patch on in-repo skills, but not for create)
• Don’t use for: personal skills in ~/.mibyan/skills/ (just use skill_manage)

​

Decide the Tier First: Bundled vs Optional

• Bundled (skills/<category>/) — daily-driver behavior, broadly useful across many user types, low footprint. Hard bar: you can say “a user will load this in 5+ sessions per month” with a straight face.
• Optional (optional-skills/<category>/) — niche, vertical-specific (blockchain, gaming, finance, one app), recurring-job/task skills, or anything heavy. Installed via mibyan skills install official/<category>/<skill>.

​

Required Frontmatter

• Starts with --- as the first bytes (no leading blank line).
• Closes with \n---\n before the body.
• Parses as a YAML mapping.
• name field present.
• description field present (validator ceiling 1024 chars — but see the repo hardline below, which is much stricter).
• Non-empty body after the closing ---.

---
name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
description: Concise capability statement, under sixty chars.
version: 0.1.0                    # semver; new skills start at 0.1.0
author: Real Name (github-handle), Mibyan
license: MIT
platforms: [linux, macos, windows]   # audit, don't guess — see Platform Gating
metadata:
  mibyan:
    tags: [Short, Descriptive, Tags]
    related_skills: [other-in-repo-skill]
---

​

description rules (HARDLINE — the validator’s 1024 is NOT the standard)

• ≤ 60 characters. One sentence. Ends with a period.
• State the capability, not the implementation, and don’t repeat the skill name.
• No marketing words (“powerful”, “comprehensive”, “seamless”, “advanced”).
• The system prompt skill index truncates at 57 chars + ”…” — the trigger/capability must be self-contained in that window.
• If the description contains a :, wrap it in double quotes or YAML parses it as a mapping and the docs generator crashes. Quotes don’t count toward the 60.

​

author rules

• Credit the human first, then “Mibyan” as secondary collaborator: Ben Barclay (benbarclay), Mibyan.
• Never author: Mibyan alone for contributed skills — credit the human, not the tool, even (especially) when an agent drafted the text.
• Maintainer-authored skills: Teknium (teknium1), Mibyan.

​

related_skills rules

• Every entry must resolve to an existing in-repo skill in the same tree state as your PR. Do not reference skills that were only planned, live in another PR, or exist only in ~/.mibyan/skills/.
• Verify each entry: search_files(pattern='<name>', target='files', path='skills') (and optional-skills/).

​

Platform Gating: audit, don’t trust

​

Size Limits

• Full SKILL.md: ≤ 100,000 chars enforced (MAX_SKILL_CONTENT_CHARS), but target ~100 lines for a simple skill, ~200 for a complex one. Peer skills sit at 8-14k chars.
• Bulky or branch-specific material goes in references/*.md, templates/, or scripts/ — pointed to from SKILL.md, not inlined.
• Don’t expect the model to inline-write parsers or non-trivial logic every call — ship a helper script in scripts/ and reference it by path.

​

Body Structure (modern section order)

# <Skill> Skill
2-3 sentence intro: what it does, what it doesn't do, dependency stance.

## When to Use          — bulleted triggers (+ "Don't use for:" counter-triggers)
## Prerequisites        — exact env vars, installs, API key sourcing
## How to Run           — canonical invocation through the `terminal` tool
## Quick Reference      — flat command list, no narration
## Procedure            — numbered steps, each with a checkable completion criterion
## Pitfalls             — known limits, things that look broken but aren't
## Verification         — how to prove the skill worked

​

Reference Mibyan tools, not raw shell

​

Never use machine-local paths

​

Writing Quality Principles

1. Optimize for process predictability. If a line does not change behavior, cut it.
2. Choose the right context load. The description is paid for every turn; details go in the body or linked references.
3. End steps with completion criteria. Checkable and, when it matters, exhaustive: “every modified file accounted for” beats “summarize changes.”
4. Co-locate rules with the concept they govern.
5. Use strong leading words (“tight loop,” “root cause,” “regression test”) over long repeated explanations.
6. Prune duplication and no-ops. “Be careful” and “use best practices” don’t change model behavior — replace with a checkable criterion or delete.

​

Tests and Docs (required for repo skills)

1. Tests live at tests/skills/test_<skill>_skill.py — stdlib + pytest + unittest.mock only, no live network. Run via scripts/run_tests.sh tests/skills/test_<skill>_skill.py -q. (The generic tests/tools/test_skill_manager_tool.py passing proves nothing about YOUR skill.)
2. Docs regen: run python website/scripts/generate-skill-docs.py, then apply scope discipline — the generator rewrites EVERY auto-gen page. git checkout -- everything that isn’t yours; the final diff must show only your SKILL.md, your one per-skill docs page, a one-line catalog row, and a one-line website/sidebars.ts insertion (verify with search_files(pattern='<your-slug>', path='website/sidebars.ts') — exactly one hit, or the page is an orphan).
3. .env.example (only if the skill needs new env vars): one clearly delimited commented block; touch nothing else in the file.

​

Workflow

1. Survey peers in the target category with search_files(target='files') and read 2-3 peer SKILL.md files to match tone and structure. Prefer extending an existing skill over creating a narrow sibling.
2. Decide tier and category (see above). When in doubt, optional — and ask before pushing rather than defaulting.
3. Draft with write_file to skills/<category>/<name>/SKILL.md (or optional-skills/...).
4. Validate locally:
   import re, pathlib
   from ruamel.yaml import YAML
   content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
   assert content.startswith("---")
   m = re.search(r'\n---\s*\n', content[3:])
   fm = YAML(typ="safe").load(content[3:m.start()+3])
   assert "name" in fm and "description" in fm
   assert len(fm["description"]) <= 60, f"description {len(fm['description'])} chars — hardline is 60"
   assert fm["description"].endswith(".")
   assert "platforms" in fm
   assert len(content) <= 100_000
   
   Also verify every related_skills entry exists in-repo.
5. Add tests + regen docs (previous section).
6. Git add + commit on the active branch; open a PR.
7. Note: the CURRENT session’s skill loader is cached — skill_view / skills_list will not see the new skill until a new session. This is expected, not a bug.

​

Editing Existing In-Repo Skills

• Small fix: skill_manage(action='patch', ...) works on in-repo skills, as does patch.
• Major rewrite: write_file the whole SKILL.md.
• Supporting files: write_file to references/, templates/, or scripts/ under the skill dir.
• Always commit — in-repo skills are source, not runtime state. Re-run the docs generator when frontmatter changed.

​

Common Pitfalls

1. Using skill_manage(action='create') for an in-repo skill. It writes to ~/.mibyan/skills/, not the repo tree. Use write_file.
2. Trusting the validator’s limits as the standard. The validator allows 1024-char descriptions; review rejects anything over 60. The validator doesn’t check platforms:, author format, tests, or docs — review does.
3. author: Mibyan on a contributed skill. Credit the human first.
4. Leading whitespace before ---. Validation fails on any leading blank line or BOM.
5. Description too generic or trigger buried past char 57.
6. related_skills pointing at skills that don’t exist in-repo (user-local, planned, or in a sibling PR).
7. Duplicating a peer. Survey the category first; extend rather than sibling.
8. Skipping the docs generator or pushing its unrelated drift. Both directions are wrong: no regen = orphan skill with no docs page; blind regen = a ballooned diff full of other skills’ drift.
9. Expecting the current session to see the new skill. The loader is initialized at session start.
10. Letting skills accumulate sediment. When adding a rule, remove the old wording it replaces.

​

Verification Checklist

• Tier decided deliberately (bundled bar: 5+ sessions/month; else optional-skills/)
• File at skills/<category>/<name>/SKILL.md or optional-skills/<category>/<name>/SKILL.md
• Frontmatter starts at byte 0 with ---, closes with \n---\n
• name, description, version, author, license, platforms, metadata.mibyan.{tags, related_skills} all present
• Description ≤ 60 chars, one sentence, ends with a period, no marketing words
• author credits the human contributor first
• platforms: audited against actual prose/scripts, not copied from a sibling
• Every related_skills entry resolves in-repo
• Body follows the modern section order; commands framed through Mibyan tools
• No machine-local paths anywhere in the file
• Each ordered step has a checkable completion criterion
• Tests at tests/skills/test_<skill>_skill.py pass under scripts/run_tests.sh
• Docs regenerated with scope discipline; sidebar has exactly one entry for the slug
• git add + commit on the intended branch; PR opened