Skill Authoring Guide (hx-make-skill)

Relevant source files

The following files were used as context for generating this wiki page:

• ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md
• ai-docs/003-AI/006-多智能体/002-Multica智能体模板与小队编排skills调研/index.md
• blog/2026/10/07/01-AI代码质量.md
• ai-docs/003-AI/004-记忆/003-obsidian-second-brain/index.md
• ai-docs/003-AI/004-记忆/003-obsidian-second-brain/obsidian-second-brain-deck.tsx

The hx-make-skill methodology provides a standardized framework for creating, organizing, and validating Agent Skills. It ensures that skills are effectively triggered by models while maintaining optimal context window efficiency through progressive disclosure and strict structural constraints.

This guide defines the architecture of a skill, the engineering of trigger descriptions, and the validation processes required to prevent "silent failures" where skills exist but are never utilized by the AI Agent.

0x01 Skill Architecture and Context Budget

Skills follow a three-tier loading architecture designed to manage the context window budget. Each level has specific constraints on when it enters the model's context.

Level	Content	Loading Trigger	Budget
Level 1	name + description	Preloaded for all installed skills at startup	~100 words
Level 2	SKILL.md body	Loaded entirely upon skill trigger	< 5,000 tokens / 500 lines
Level 3	references/, scripts/, assets/	Loaded on-demand by the Agent	Virtually unlimited

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:80-92, ai-docs/003-AI/004-记忆/003-obsidian-second-brain/obsidian-second-brain-deck.tsx:100-110

Content Layering Logic

Effective skill authoring requires separating content based on frequency of use. If content is needed for every trigger, place it in the Level 2 SKILL.md. If it is specific to certain scenarios (e.g., API schemas, long examples), move it to Level 3 references/.

0x02 Trigger Engineering

A common failure in skill authoring is the "Silent Failure," where a skill is never triggered because the model cannot see the trigger conditions. The model only reads Level 1 metadata (name and description) to decide whether to load the full SKILL.md.

The Description Formula

The description must contain both "What the skill does" and "When to use it." Information regarding "When to use" placed inside the SKILL.md body is invisible until after the skill has already been triggered.

• Bad Pattern: Putting trigger conditions in the Markdown body.
• Good Pattern: [Capability List] + [Trigger Scenarios + User Keywords]

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:120-150

0x03 Directory Structure and File Roles

Skills are organized into specific directories to ensure the Agent can correctly locate resources.

Directory	Purpose	Context Loading
scripts/	Executable code for deterministic steps	No (executed via tool)
references/	Docs, schemas, and specifications	Yes (on-demand)
assets/	Templates, icons, and boilerplate	No (used as output)

Prohibited Files: Skill directories must not contain README.md, CHANGELOG.md, or other human-centric documentation, as these distract the Agent and waste context.

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:195-215, ai-docs/003-AI/004-记忆/003-obsidian-second-brain/index.md:160-175

0x04 Authoring Best Practices

Instruction Style

Use imperative sentences to give direct commands. Avoid indirect language like "the agent should consider."

• Correct: "When the user asks for X, always do Y first."
• Incorrect: "The agent might want to do Y."

Reference Management

• Single Source of Truth: Do not repeat information between SKILL.md and references/.
• Depth Limit: Keep file references one level deep. All reference files should be linked directly from SKILL.md.
• Indexing: Large reference files (over 100 lines) require a table of contents or search patterns (e.g., grep keywords) provided in the core instructions.

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:220-245

0x05 Skill Naming and Metadata

Skills must adhere to strict naming conventions to avoid registration failures in host environments:

• Max 64 characters.
• Lowercase letters, numbers, and hyphens only.
• The name field in frontmatter must match the parent directory name exactly.

Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:255-265

0x06 Validation and Verifiable Testing

Because skill failures are often silent (no error messages), authoring must include a verification phase.

Verifiable Testing Workflow

Testing must be performed by an Agent that does not know it is being tested to prevent "meta-cognitive" bias where the Agent fixes skill errors using its own internal knowledge.

1. Fresh Session: Use a clean session to avoid context leakage.
2. Raw Input: Provide raw task inputs and logs rather than summaries.
3. No Expected Answers: Do not provide the intended solution to the testing Agent.

0x07 Automated Quality Gates (Meta-Gates)

Skills should be subject to automated checks before deployment. The primary validation criteria include:

• Context Limit: Sum of AGENTS.md and injected skill context must be $\le 64$ KB.
• Self-Containment: Notes and skills must be readable independently without relying on external back-links.
• No Emoji/CJK Punctuation: Use ASCII punctuation for consistency in model parsing.

Sources: blog/2026/10/07/01-AI代码质量.md:145-160, ai-docs/003-AI/004-记忆/003-obsidian-second-brain/index.md:70-85

Summary

The hx-make-skill guide prioritizes engineering over aesthetics. By strictly managing the context budget across three layers, ensuring triggers are correctly defined in metadata, and enforcing automated validation, developers can create reliable skills that models load accurately and execute with high precision. Success is defined by a skill's ability to guide an Agent to a correct result using only the provided instructions and resources.