SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsskill-writer

skill-writer

Writing & research

View repository

Updated 10-16 06:52

About this skill

Skill Writer

Applicable scenarios

  • Creating a project-level or personal-level skill
  • Compressing an overly long SKILL.md
  • Splitting an encyclopedic document into SKILL.md + reference/
  • Rewriting descriptionto improve skill routing hit rate
  • Unifying the structure, naming, and style of a batch of skills

Inapplicable scenarios

  • Only adding one or two lines of ordinary explanation, without involving skill structure adjustments
  • Only adding business knowledge, but no reusable skill needs to be formed
  • What the user wants to modify is a rule, hook, or ordinary document, not a skill

Quick guidance

  1. First determine the single responsibility of the skill. A skill solves only one type of problem; do not mix overview, tutorial, encyclopedia, and script descriptions together.
  2. Treat description as a routing trigger, not a feature introduction. Prioritize writing "in what scenarios the user will need it".
  3. The main SKILL.md should retain only high-signal content:
    • Applicable scenarios
    • Inapplicable scenarios
    • Quick guidance
    • High-signal rules
    • Key pitfalls
    • Further reading entry points
  4. By default, assume the model already knows general common sense. Retain only project-specific conventions, error-prone boundaries, historical pitfalls, and explicit preferences.
  5. The main SKILL.md goal is not "as short as possible", but "short enough to leave only routing and action guidance". In the current repository, the main file should usually be tightened to about 40-80 lines.
  6. Put heavy content in reference/：
    • Large blocks of background knowledge
    • Long tables
    • Code directories
    • Complete cases
    • FAQ
    • Payload examples
    • Status enums
    • Confirmation templates
  7. Only when the process is highly deterministic, stable, and error-prone should logic be offloaded to scripts/ or template files.
  8. Keep all links to one level of depth as much as possible, avoiding the main skill having to jump through many more directory levels.
  9. Within the same skill, prefer relative paths; across skills, prefer writing the skill name rather than hardcoding repository directory paths.
  10. When adding or refactoring, prioritize cleaning up legacy frontmatter fields, such as token_estimate、core_files、related_skills, unless there is still a clear consumer dependency.

Recommended skeleton

# Skill 名称

## 适用场景

## 不适用场景

## 快速指导

## 高信号规则

## 关键陷阱

## 延伸阅读

High-signal rules

  • Routing takes precedence over encyclopedia; trigger conditions take precedence over background introduction
  • The main file should prioritize telling the model "when to use it, how to proceed, and what pitfalls to avoid", rather than "the complete knowledge overview"
  • Operational skills should be even more restrained; the main file should not carry specific payloads, status tables, or long steps
  • Boundaries between similar skills must be hard to avoid routing overlap
  • For recurring AI misuse cases, prioritize depositing them into ai/evals/, and adjust the skill only after confirming stability

Acceptance checklist

  • name is consistent with the directory name, and uses only lowercase letters, numbers, and hyphens
  • description is short, third-person, and routable
  • The main SKILL.md is usually controlled to about 40-80 OK, special navigation-type skills may be slightly broader, but should not revert to manual-style body text
  • Keep only high-signal guidance in the main document; do not pile up encyclopedic content
  • The main document includes by default 适用场景 / 不适用场景 / 快速指导 / 高信号规则 / 关键陷阱 / 延伸阅读
  • Detailed materials have been split out to reference/ or other auxiliary files
  • Example payloads, confirmation templates, status enums, and long tables have been moved down out of the main document
  • For cross-skill references, prefer using the skill name; for internal references, prefer using relative paths
  • Legacy frontmatter fields have been cleaned up or explicitly retained with justification
  • Boundaries between similar skills are clear, and they will not be frequently mistriggered

Further Reading

  • If you need to build BK-CI module navigation, look first at 00-bkci-global-architecture
  • If you need to compress existing skills, first inventory duplicate concepts, then decide which is the authoritative source
  • If you need to determine the boundaries among rules, skills, references, and editor adaptation directories, refer to ../../HARNESS.md