Agent Skill Rules

The main process follows the official Step 1–4 of Agent Skills, with platform-independent governance enhancements embedded in each step.

Instructions (Step-by-Step Explanation)

Step 1: Confirm directory structure

SKILL.md

scripts/

references/

assets/

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

name

• Default: All newly created or renamed files and directories use lowercase.
• "Necessary" case: Do not convert to lowercase only when the specification/framework explicitly requires a certain name (e.g.

  SKILL.md

  ,

  README.md

  ,

  Makefile

  ). Mandatory specifications take precedence over this convention.
• When in doubt: Check the specification document first; use lowercase if not specified.

• Identify the action type before building the structure:

  create / update / refactor / migrate / audit / deprecate

  .
• Decide whether to use the minimal structure or full structure according to the action (avoid creating excessive directories at one time).
• Avoid deep reference chains: Subsequent documents are designed to use single-layer references by default.

Step 2: Write frontmatter

• name: Consistent with the directory name, only

  a-z

  ,

  0-9

  ,

  -

  are allowed, cannot start or end with

  -

  , no

  --

• description: What it does + when to use it, contains keywords, 1–1024 characters, third person

• In addition to "what it does + when to use it", add trigger keywords to

  description

  to improve matching stability.
• Maintain triggerable semantics for maintenance actions (update/refactor/migrate/audit/deprecate).
• Explicitly platform-independent: Do not write platform-private fields or platform-bound terms in frontmatter.
• Identify skill type (see references/skill-type-taxonomy.md for details): Determine whether the current skill is procedural or declarative, and adjust the writing of

  description

  accordingly:
  • Procedural: "What it does + when to trigger"
  • Declarative: "What it constrains + applicable scope"
• Optional: Mark the type through

  metadata.type

  (

  procedural

  /

  declarative

  ) for classified management.

Step 3: Write main content

• Instructions (step-by-step description)
• Examples (input/output examples, if applicable)
• Edge cases (common boundary cases, if applicable)

• Core principles (bottom-line rules that must be followed)
• Behavior requirements (behavior specifications in specific scenarios, comparison tables are recommended)
• Judgment criteria (how to judge whether the principle is violated)
• Anti-patterns (behaviors that must be avoided, including specific examples)

• The body is organized as "core rules first, details sink to references" (progressive disclosure).
• The same rule is maintained in only one place, avoid duplication between

  SKILL.md

  and

  references/

  .
• Choose the degree of freedom according to task vulnerability: high freedom (principle), medium freedom (pattern), low freedom (hard constraint).
• It is recommended to add a minimum action table (create/modify/refactor/migrate/audit/deprecate) for maintenance tasks to improve execution consistency.
• Hybrid skill: Identify the dominant type, organize the body according to the dominant type, and take the content of the secondary type as supplementary paragraphs.

Step 3.5: Lossless migration (mandatory for migrate scenarios)

migrate

merge

• Migration is mainly based on "move/copy + reference reorganization", do not replace the original text with abstract rewriting.
• The original rule text (especially

  SKILL.md

  and

  references/*

  ) must be completely retained.
• If an aggregation entry is required, the aggregation layer only does routing and navigation, and does not cover the original rule details.
• It must be traceable after migration: The original text path can be located from the aggregation entry.

Step 4: Self-check and verification

• Directory name =

  name

• description

  contains "what it does", "when to use it" and keywords
• Reference files are only one level deep, use relative paths
• If the environment supports:

  skills-ref validate ./skill-name

• No platform-bound terms pollute core rules (Cloud/IDE/product private mechanisms)
• Maintenance actions are traceable (change summary, impact scope, migration path)
• No redundant document stacking (README, changelog, etc. unrelated to execution)
• migrate/merge scenarios meet "lossless migration": The original text is not deleted or modified by abstraction, and the aggregation layer only does navigation
• Type consistency: The body organization method matches the skill type (procedural uses Instructions, declarative uses core principles/behavior requirements/judgment criteria/anti-patterns)
• Declarative skills do not force the step format, procedural skills do not lack execution processes

Sources and evolution path

Sources

• First layer source: Official Agent Skills documentation (structure, frontmatter, progressive disclosure, verification constraints).
• Second layer source: General methods in community skill-creator documentation (content organization, iteration ideas, anti-pattern identification).

Adoption strategy

• The official Step 1–4 is used as the main process framework.
• New content is only incorporated into each Step as "enhancements", and does not replace the main process.
• Explicitly remove Cloud/IDE/product private binding content, retain platform-independent rules.

Positioning and boundaries

• This skill is responsible for rule standards and governance processes, and is not bound to a specific platform.
• Static rules and document verification are used by default, no fixed script chain is required.
• Focus on the design quality of migratable, maintainable and auditable skills.

Anti-patterns (must be avoided)

• Bind rules to specific Cloud/IDE/product private capabilities.
• Write platform installation, packaging, release statistics into the rule body.
• Pile up auxiliary documents unrelated to execution in the skill (such as general README, changelog).
• Maintain the same description repeatedly in

  SKILL.md

  and

  references/

  .
• Replace the original rule body with a concise abstract, resulting in migration distortion and detail loss.
• Force declarative skills into the Instructions/Step 1-2-3 format, resulting in far-fetched content or loss of "always effective" semantics.
• Write procedural skills as purely declarative, resulting in lack of executable step flow.

References

• references/specification.md

  - Agent Skills basic specifications and field constraints

• references/anthropic-enhancements.md

  - Platform-independent enhancement extraction based on Anthropic skill-creator (including source and removal strategies)

• references/skill-type-taxonomy.md

  - Skill type taxonomy: Guidance on organization methods for procedural vs declarative skills