skill-design

Original：🇺🇸 English

Translated

Design and refactor Agent Skills with concise, high-signal instructions and explicit trigger metadata. Use when creating a new skill, revising SKILL.md/README.md structure, or improving skill discoverability and portability.

10installs

Sourceshihyuho/skills

Added on2026-02-22

NPX Install

npx skill4agent add shihyuho/skills skill-design

SKILL.md Content

View Translation Comparison →

Skill Design

Design skills as reusable behavior systems that are easy to discover and execute.

Trigger Contract

Use this skill when users ask to:

create a new skill
refactor an existing skill
improve trigger quality or discoverability
align
```
SKILL.md
```
,
```
README.md
```
, and
```
references/
```
remove ambiguity or conflicting guidance

Typical trigger phrases:

"create a skill for X"
"design a new skill"
"refactor this skill"
"make this skill reusable"
"align README and SKILL behavior"

Core Principles

Optimize for reliable agent behavior, not document aesthetics.
Make trigger conditions explicit and searchable.
Keep instructions executable and verifiable.
Avoid implicit project context unless explicitly required.

Writing Style Rules

Use imperative voice.
Keep sections short and high-signal.
Prefer concrete constraints over abstract advice.
Use
```
MUST
```
/
```
NEVER
```
for true invariants (safety, correctness, irreversible failure).
For normal guidance, use direct action verbs and clear defaults.
Avoid weak modal wording for hard rules (
```
should
```
,
```
could
```
,
```
may
```
,
```
consider
```
,
```
usually
```
).
Remove narrative text that does not change execution.

Metadata and Discovery

Write frontmatter
```
description
```
in third person.
Include both what the skill does and when to use it.
Keep trigger terms concrete (
```
file type
```
,
```
task type
```
,
```
user phrasing
```
).
Do not put workflow details in
```
description
```
; keep those in the body.

Workflow

Phase 1 - Define Contract

Define who uses the skill and when it triggers.
Define non-negotiable behavior and failure boundaries.
Define deterministic vs heuristic decisions.

Phase 2 - Structure Content

Write trigger and constraints first.
Keep
```
SKILL.md
```
as execution logic and decision constraints.
Move bulky detail to
```
references/
```
and keep one source of truth per schema.
Add
```
scripts/
```
only for repeatable deterministic operations.
When composing with other skills, invoke them by name and never copy their instruction bodies.

Phase 3 - Author/Refactor SKILL

Tighten description and trigger wording.
Convert soft guidance into explicit, executable instructions.
Provide one default path first; add alternatives only when necessary.
Remove duplicate or contradictory instructions.

Phase 4 - Align README (Human-Facing)

Keep README value-first: problem -> value -> example -> activation.
Treat
```
README.md
```
as style charter for future AI output quality.
Keep implementation internals out of README.
Keep claims behavior-accurate.

Phase 5 - Validate

Run available validator for your environment.
If no validator exists, run manual consistency checks.
Confirm no repository-specific assumptions remain unless explicitly intended.

Progressive Disclosure Rules

Keep
```
SKILL.md
```
body compact (target under 500 lines).
Put advanced or domain-specific detail in
```
references/
```
.
Link reference files directly from
```
SKILL.md
```
(avoid deep nested references).
For long reference files (100+ lines), add a short table of contents.

README Rules

In this skill,
```
README.md
```
means the skill-level README (for example
```
skills/<skill-name>/README.md
```
), not the repository root README.
```
README.md
```
is not required by Agent Skills Specification.
```
README.md
```
is recommended for faster human understanding and adoption.
Keep README focused on outcomes, style expectations, and activation cues.

Anti-Patterns

Hardcoded local paths as universal defaults.
Tool lock-in with no fallback path.
Copying external skill instruction bodies instead of invoking the source skill.
Workflow summary inside frontmatter
```
description
```
.
Duplicated schema definitions across files.
Long narrative prose with no executable instruction.
Repeating
```
MUST
```
/
```
NEVER
```
for non-critical guidance.
Offering too many equivalent options without a default recommendation.

Done Checklist

```
SKILL.md
```
has explicit trigger contract and executable workflow.
Frontmatter
```
description
```
clearly states what + when.
```
README.md
```
defines style expectations for future contributions.
```
references/
```
contains heavy details only when needed.
No stale terms, duplicated schema ownership, or contradictory rules.
Validation evidence is recorded (tool-based or manual).

Example validation command:

npx --yes skills-ref validate ./skills/<skill-name>