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

Each skill contains at least

SKILL.md

, with optional

scripts/

references/

assets/

directories. For the full format specification, see references/specification.md (source: agentskills.io/specification).

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

The directory name must match the

name

field in frontmatter (lowercase, hyphenated, 1–64 characters).

Naming conventions for rule design (applicable when creating/modifying skills): All file and directory names use lowercase unless necessary.

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.

Enhancements (no change to the main process)：

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

Two required fields:

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

Enhancements (no change to the main process)：

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

The Markdown body follows the YAML section. Choose the corresponding body organization method according to the skill type (see references/skill-type-taxonomy.md for details):

Procedural skill — follow the official recommendation:

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

Declarative skill — do not force the step format, use declarative organization instead:

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)

Enhancements (no change to the main process)：

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)

When the action type is

migrate

merge

, the lossless migration rules must be implemented:

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
```

Enhancements (no change to the main process)：

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

agent-skill-rules

NPX Install

Tags

SKILL.md Content (Chinese)

Agent Skill Rules

Instructions (Step-by-Step Explanation)

Step 1: Confirm directory structure

Step 2: Write frontmatter

Step 3: Write main content

Step 3.5: Lossless migration (mandatory for migrate scenarios)

Step 4: Self-check and verification

Sources and evolution path

Sources

Adoption strategy

Positioning and boundaries

Anti-patterns (must be avoided)

References