Accelint Skill Manager

Skill Name

Brief introduction to what this skill provides (1-2 sentences maximum).

NEVER Do [Domain-Specific Anti-Patterns]

<!-- CRITICAL: This section is half of expert knowledge. Good anti-patterns are SPECIFIC with WHY (non-obvious reasons). Bad anti-patterns are vague warnings like "be careful" or "avoid errors".

Ask yourself: "Would an expert say 'yes, I learned this the hard way'?"

Include 5-8 specific anti-patterns with concrete reasons. -->

• NEVER [specific anti-pattern 1] - [Why this fails / non-obvious consequence]. [Example if helpful].
• NEVER [specific anti-pattern 2] - [Concrete reason from experience].
• NEVER [specific anti-pattern 3] - [What happens when violated].
• NEVER [generic mistake in this domain] - [Why experts avoid this].
• NEVER [common beginner error] - [Non-obvious reason it's problematic].

<!-- Examples from real skills:

• NEVER write tutorials explaining basics - Claude knows standard concepts. Focus on expert-only knowledge.
• NEVER use Inter/Roboto fonts - Overused in AI-generated designs, lacks originality.
• NEVER edit OOXML directly without unpacking first - XML structure breaks, file corrupts.

-->

Before [Domain Action], Ask

<!-- CRITICAL: Teach THINKING PATTERNS, not just procedures. This transforms agents from "following steps" to "making expert decisions".

Format: "Before [action], ask yourself:" Include 3-5 key questions experts ask before acting. These should shape HOW agents think about the problem. -->

Apply these tests before [performing key domain action]:

[Expert Thinking Framework 1]

• [Key Question]? [Guidance on what to consider]. [Consequence if ignored].
• [Key Question]? [How experts think about this]. [Example if needed].

[Expert Thinking Framework 2]

• [Key Question]? [Critical consideration]. [Trade-off to understand].
• [Key Question]? [Decision criteria]. [What to optimize for].

[Expert Thinking Framework 3]

• [Key Question]? [Edge case consideration]. [When standard approach fails].

<!-- Examples from real skills: "Before Creating a Skill, Ask:"

• Does this capture what takes experts years to learn?
• Am I explaining TO Claude or arming Claude?

"Before Designing, Ask:"

• What makes this memorable vs generic?
• What extreme aesthetic direction fits the purpose?

-->

How to Use

<!-- Choose ONE structure based on skill complexity:

OPTION A - For SIMPLE skills (<100 lines, single workflow, no references): Delete this section and put direct instructions here. Example: "Run scripts/process.sh <input> to process files. See examples in assets/."

OPTION B - For COMPLEX skills (rules, references, multiple scenarios): Use progressive disclosure pattern below.

NEVER mix both - either direct instructions OR progressive disclosure. -->

This skill uses progressive disclosure to minimize context usage:

1. Start with the Workflow (SKILL.md)

Follow the [workflow/decision tree/process] below for [domain task].

2. Reference Implementation Details (AGENTS.md)

Load AGENTS.md for [specific type of guidance: file conventions / optimization rules / architectural patterns].

3. Load Specific Examples as Needed

When [specific scenario], load corresponding reference files for ❌/✅ examples:

• [Scenario 1] → Load reference-file-1.md
• [Scenario 2] → Load reference-file-2.md

[Main Workflow / Decision Tree / Process]

<!-- This is the CORE of your skill. Choose format based on task type:

For PHASED WORKFLOWS (Process pattern ~200 lines):

• Step-by-step numbered workflow
• Include checklist for tracking progress
• "Skip this step only when..." guidance

For DECISION TREES (Tool pattern ~300 lines):

• Table format: "Scenario | Approach | Fallback"
• If/then logic with clear branches
• Error handling and edge cases

For CREATIVE GUIDANCE (Mindset pattern ~50 lines):

• Principles over procedures
• High freedom with examples
• Focus on taste and judgment

Include DOMAIN-SPECIFIC procedures Claude wouldn't know. NEVER include generic procedures (open file, edit, save). -->

[Your workflow/decision tree/creative guidance here]

Freedom Calibration

<!-- ONLY include this section if your skill needs to teach agents how to calibrate freedom. Most skills don't need this - it's for meta-skills or skills that work across task types.

If your skill is ONLY creative → Don't include (just use high freedom throughout) If your skill is ONLY fragile ops → Don't include (just use low freedom throughout) If your skill spans multiple task types → Include this table -->

Calibrate guidance specificity to task fragility:

The test: "If the agent makes a mistake, what's the consequence?"

• High consequence (corruption, data loss) → Low freedom with precise scripts
• Medium consequence (suboptimal result, style issues) → Medium freedom with examples
• Low consequence (aesthetic choices, multiple valid approaches) → High freedom with principles

Important Notes

<!-- Only include NON-OBVIOUS critical considerations. NEVER include obvious reminders like "test your code" or "handle errors". Think: "What do experts know that isn't written elsewhere?" -->

• [Critical non-obvious consideration that affects success]
• [Edge case that's easy to miss]
• [Domain-specific constraint or requirement]

<!-- DELETE "Additional Resources" section - it's redundant with "How to Use" section. Progressive disclosure is already explained above. -->

Skill Manager

Note:

This document is mainly for agents and LLMs to follow when maintaining, generating, or refactoring agent skills. Humans may also find it useful, but guidance here is optimized for automation and consistency by AI-assisted workflows.

---

Abstract

Comprehensive guide for agent skills, designed for AI agents and LLMs. Each rule includes one-line summaries here, with links to detailed examples in the references/ folder. Load reference files only when you need detailed implementation guidance for a specific rule.

---

How to Use This Guide

1. Start here: Scan the rule summaries to identify relevant optimizations 2. Load references as needed: Click through to detailed examples only when implementing 3. Progressive loading: Each reference file is self-contained with ❌/✅ examples

This structure minimizes context usage while providing complete implementation guidance when needed.

---

Quick Reference

• 1.1 File System - Directory structure and naming conventions
• 1.2 SKILL.md - Description field and keyword usage
• 1.3 AGENTS.md - Token efficiency and compression
• 1.4 Progressive Disclosure - Context optimization
• 1.5 References - Example format and organization
• 1.6 Scripts - Bash conventions and error handling
• 1.7 Assets - Templates and static resources

---

1. General

1.1 File System

Use kebab-case for directories/scripts, UPPERCASE for main files, keep references one level deep. View detailed examples

1.2 SKILL.md

Write "Use when..." descriptions with triggering conditions only, never workflow summaries. View detailed examples

1.3 AGENTS.md

Provide rule summaries with reference links, compress examples, eliminate redundancy. View detailed examples

1.4 Progressive Disclosure

Keep SKILL.md <500 lines, metadata ~100 tokens, load resources on-demand. View detailed examples

1.5 References

Use ❌/✅ examples, self-contained files, avoid duplication with SKILL.md. View detailed examples

1.6 Scripts

Bash preferred, use set -e, stderr for messages, stdout for JSON output. View detailed examples

1.7 Assets

Static resources, templates, data files for complex/repetitive tasks. View detailed examples

Skill Name

Note:

This document is mainly for agents and LLMs to follow when [condition for skill usage]. Humans may also find it useful, but guidance here is optimized for automation and consistency by AI-assisted workflows.

---

Abstract

Brief summary of what this skill provides and how it's organized. Explain that each rule includes one-line summaries with links to detailed examples in the references/ folder.

Token efficiency principle: This guide maximizes knowledge delta by providing only expert-level insights Claude doesn't already know. All rules assume Claude understands standard concepts, libraries, and patterns. Focus is on non-obvious decisions, trade-offs, and edge cases.

---

How to Use This Guide

1. Start here: Scan the rule summaries to identify relevant guidance 2. Load references as needed: Click through to detailed examples only when implementing 3. Progressive loading: Each reference file is self-contained with ❌/✅ examples

This structure minimizes context usage while providing complete implementation guidance when needed.

---

Quick Reference

<!-- Add all rule sections here with brief summaries. This TOC is critical for agents to quickly find relevant rules without loading all references. Each entry should be 5-10 words max. -->

• 1.1 Rule Name - Brief description (5-10 words)
• 1.2 Rule Name - Brief description (5-10 words)
• 1.3 Rule Name - Brief description (5-10 words)

<!-- Add more rules as needed -->

---

1. General

<!-- For simple skills: 3-5 rules may be sufficient For complex skills: Consider grouping into multiple sections:

1. General

2. Specific Domain Area

3. Advanced Patterns

-->

1.1 Rule Name

One-line summary of this rule (what it optimizes or prevents). View detailed examples

1.2 Rule Name

One-line summary of this rule (what it optimizes or prevents). View detailed examples

1.3 Rule Name

One-line summary of this rule (what it optimizes or prevents). View detailed examples

<!-- ADVANCED PATTERNS (uncomment if needed):

1.4 Cross-Referencing Other Skills

When your skill depends on another skill, reference it explicitly: View detailed examples

Example inline guidance (for rules that don't need full reference file):

1.5 Short Rule Without Reference File

Brief rule that fits in 2-3 sentences. For rules that need ❌/✅ examples or detailed explanation, create a reference file instead. Only inline rules that are self-explanatory.

❌ Incorrect: [description of why]

Brief example of anti-pattern

✅ Correct: [description of why]

Brief example of correct pattern

TOKEN EFFICIENCY TIP:

• If a rule has 3+ examples, move to reference file
• If explanation is >5 lines, move to reference file
• Inline only simple, obvious rules

-->

Changelog

All notable changes to this skill will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.0.0] - YYYY-MM-DD

Added

• Initial skill release
• [List key capabilities and sections]
• [Reference any scripts, assets, or references included]

Rationale

• [Explain the motivation for creating this skill]
• [What expert knowledge does it externalize?]
• [What problems does it solve?]

---

How to Update This CHANGELOG

When updating this skill, add a new version section above this one:

## [X.Y.Z] - YYYY-MM-DD

### Added
- New features, sections, patterns, scripts with rationale

### Changed
- Modifications to existing content
- **Always include rationale** (why changes were made)
- Link to evaluation results if improvements stem from testing

### Fixed
- Bug fixes, corrections, broken links with explanation

### Version
- Explicit version bump note (e.g., "Bumped from 1.0 → 1.1")

Version Guidelines:

• Major (1.0 → 2.0): Substantial rewrites, breaking changes, complete restructuring
• Minor (1.0 → 1.1): New sections, significant additions, refinements
• Patch (1.0.0 → 1.0.1): Bug fixes, typo corrections, minor clarifications

Important: Ensure the version here matches metadata.version in SKILL.md frontmatter.

Skill Name

<!-- NOTE: README.md is for HUMANS and DISTRIBUTION ONLY.

Include README.md when:

• Publishing skill to npm/registry
• Sharing skill on GitHub
• Distributing to other users

EXCLUDE README.md for:

• Private/local skills
• Company-internal skills
• Skills that won't be distributed

Why: Skills aren't software projects. Agents don't read READMEs. README is purely for human discovery and installation. -->

Brief description of what this skill does and who it's for.

Installation

npm

npx skills add https://github.com/gohypergiant/agent-skills --skill skill-name

pnpm

pnpm dlx skills add https://github.com/gohypergiant/agent-skills --skill skill-name

Usage

Describe how users interact with this skill either via a prompt, command, or explicit skill invocation:

prompt

Persona:
Describe the intended persona.

Objective:
1. Goal 1
2. Goal 2
3. Goal 3

Output:
Explain what skills are used and why.

command

/command-name path/to/code

Persona:
Describe the intended persona.

Objective:
1. Use the skill-name skill
2. Goal 1
3. Goal 2
4. Goal 3

Output:
Explain why rules from the skill are applied.

What's Included

• SKILL.md - Main skill documentation with usage instructions
• AGENTS.md - Agent-optimized reference guide with implementation rules
• references/ - Detailed examples and best practices
• scripts/ - Automation scripts (if applicable)
• assets/ - Templates and static resources (if applicable)

Requirements

• List any prerequisites
• Required tools or dependencies
• Minimum versions if applicable

Examples

Example 1: [Use Case]

# Example command

Expected result: [description]

Example 2: [Use Case]

# Example command

Expected result: [description]

---

Contributing

Contributions are welcome! When contributing to this skill:

1. CRITICAL: Ensure description field in SKILL.md answers WHAT/WHEN/KEYWORDS - this determines if skill gets activated 2. Follow the skill structure guidelines in the accelint-skill-manager skill 3. Ensure all examples use ❌/✅ format for clarity 4. Keep SKILL.md under 500 lines (move details to references/) 5. Focus on expert-only knowledge - assume Claude knows basics 6. Test changes with actual use cases

Maintain CHANGELOG.md:

• Use "Keep a Changelog" format with semantic versioning
• Update after each skill iteration with Added/Changed/Fixed/Version sections
• Always include rationale (WHY changes were made)
• Link to evaluation results when changes stem from testing
• Ensure version matches metadata.version in SKILL.md frontmatter

NEVER create:

• CONTRIBUTING.md - Keep contribution guide in README only
• INSTALLATION.md - Keep installation in README only
• Other meta-documentation - Skills aren't software projects

---

Skill Architecture Philosophy

<!-- Optional: Remove this section if your skill doesn't need philosophical grounding. Keep it if your skill embodies specific principles worth explaining. -->

This skill follows these principles:

1. [Principle 1] - [Explanation] 2. [Principle 2] - [Explanation] 3. [Principle 3] - [Explanation]

---

Learn More

• Agent Skills Specification
• AGENTS.md - Detailed implementation rules
• references/ - Comprehensive examples and patterns

---

License

[Your license here]

1.1 Example Rule

Overview

<!-- State the problem this rule solves and why it matters for agents. Focus on: What goes wrong without this rule? What does this optimize? Keep to 2-3 sentences.

CRITICAL: Focus on EXPERT-ONLY knowledge Claude doesn't have. Ask: "Does Claude already know this?" If yes, delete it. NEVER explain basic concepts, standard library usage, or common patterns. Only include non-obvious trade-offs, edge cases, and expert decisions. -->

Brief explanation of what this rule covers and why it matters (expert knowledge only).

Key Principles

<!-- Optional section. Use when there are 3-5 fundamental concepts to understand. Skip this section if the Examples below are self-explanatory. Each principle should be one sentence. -->

1. Principle 1: Explanation 2. Principle 2: Explanation 3. Principle 3: Explanation

Examples

<!-- CRITICAL: Always use ❌/✅ paired examples. Never show only correct examples - agents learn best from contrasts. Keep examples realistic and specific (not "foo/bar" placeholders). Use actual code/commands from the domain. -->

Pattern 1: [Description]

❌ Incorrect: [description of why]

Example of what NOT to do

Why this is wrong: Explanation of the problem (focus on consequences: bugs, inefficiency, confusion)

✅ Correct: [description of why]

Example of the right approach

Why this is better: Explanation of the improvement (focus on benefits: clarity, performance, correctness)

Pattern 2: [Description]

❌ Incorrect: [description of why]

Another example of what NOT to do

Why this is wrong: Explanation of the problem

✅ Correct: [description of why]

Correct approach

Why this is better: Explanation of the improvement

Additional Guidelines

<!-- Optional section for supplementary rules that don't need full examples. Use bullet points for quick reference. Remove this section if everything is covered in Examples above. -->

• Guideline 1
• Guideline 2
• Guideline 3

Common Pitfalls

<!-- Highlight mistakes agents commonly make when applying this rule. Focus on subtle errors, not obvious ones covered in Examples. Each pitfall should include how to avoid it. -->

• Pitfall 1: Description and how to avoid it
• Pitfall 2: Description and how to avoid it
• Pitfall 3: Description and how to avoid it

---

Reference: [Link to external documentation if applicable]

Changelog

All notable changes to this skill will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[2.1.1] - 2026-03-18

Changed

• Removed duplicative Step 5
• Deleted Step 5 (Update Documentation) which repeated CHANGELOG guidance already in Step 4
• Updated workflow checklist from 5 steps to 4 steps
• Rationale: Eliminates ~25 lines of redundant content, improves token efficiency

• Added workflow routing decision tree
• New "Which Workflow Should You Follow?" section after "How to Use"
• Provides clear navigation: creating new skill, improving existing, auditing
• Rationale: Users landing on the skill didn't know which workflow to follow for their task

• Revised generic advice to be skill-specific
• Changed "Avoid overwhelming users" to concrete guidance: "Ask 2-3 concrete questions first"
• Rationale: Generic advice is redundant; specific guidance is actionable

• Removed packaging from scope
• Removed "package this as a skill" and "packaging" from description
• Rationale: Packaging is a single script call, not a workflow requiring skill guidance

• Standardized version format to full semver
• Changed frontmatter version from "2.1" to "2.1.1" (X.Y.Z format)
• Rationale: Consistency with CHANGELOG format, clearer patch/minor/major distinction

Fixed

• Version consistency between frontmatter and CHANGELOG

Version

• Bumped from 2.1.0 → 2.1.1

[2.1.0] - 2026-03-18

Added

• New Step 5: Update Documentation (CHANGELOG and Version)
• Added comprehensive CHANGELOG maintenance workflow to skill creation process
• Updated workflow checklist to include documentation step
• Rationale: Skills lacked version history and rationale for changes, making maintenance difficult

• New reference file: references/changelog.md
• Detailed guidance on CHANGELOG format, versioning, and best practices
• Examples of strong vs weak CHANGELOG entries
• Templates for creating new entries with proper rationale
• Rationale: Agents needed comprehensive examples to write meaningful CHANGELOGs

• CHANGELOG.md template in skill-template/
• Added template CHANGELOG.md with instructions and examples
• Rationale: New skills should start with proper version tracking from v1.0

Changed

• Enhanced references/skill.md with frontmatter metadata documentation
• Added comprehensive metadata.version field guidance
• Added metadata.author field conventions
• Added name field rules with examples
• Rationale: Version control documentation was incomplete

• Updated Skill Audit Workflow
• Added Step 3: CHANGELOG and Version Audit
• Enhanced Frontmatter Audit to check version consistency
• Renumbered subsequent steps (Knowledge Delta Test: 3→4, Produce Output: 4→5)
• Rationale: Audits should verify CHANGELOG presence and quality

• Updated assets/skill-template/README.md
• Changed from "NEVER create CHANGELOG.md" to proper CHANGELOG guidance
• Rationale: CHANGELOG provides curated history with rationale, complementing git history

Version

• Bumped from 2.0 → 2.1

[2.0.0] - Previous

Added

• Complete skill manager rewrite with progressive disclosure
• 4-step workflow: Understanding, Planning, Initializing, Editing
• Skill audit workflow with knowledge delta test
• Freedom calibration guidance for task-specific instruction style
• Comprehensive reference files for file-system, skill.md, agents.md patterns

Rationale

• Previous version lacked structured workflow for skill creation
• No guidance on when to use prescriptive vs principle-based approaches
• Missing audit capabilities for existing skills

Skill Manager

Comprehensive guide for creating effective agent skills that extend Claude's capabilities with specialized knowledge, workflows, and tool integrations.

Installation

npm

npx skills add https://github.com/gohypergiant/agent-skills --skill accelint-skill-manager

pnpm

pnpm dlx skills add https://github.com/gohypergiant/agent-skills --skill accelint-skill-manager

Overview

This skill provides structured guidance for skill creation and management, covering:

• 4-step skill creation workflow
• Skill architecture and file structure
• Progressive disclosure patterns
• Best practices for reusable resources
• Examples and templates

Think of this as a "meta-skill" - a skill for building skills. It provides the methodology, conventions, and structural guidelines needed to develop high-quality agent skills.

Note: This skill is optimized for AI agents creating other skills, but humans may find it useful for understanding skill architecture and contributing to skill development.

---

Requirements

• Claude Code CLI or compatible agent environment
• File system write permissions for skill creation
• Git repository (recommended for version tracking)
• Understanding of agent skill architecture

---

Quick Start

For Agents/LLMs

1. Read [SKILL.md](SKILL.md) - Understand the 4-step workflow for creating skills 2. Reference [AGENTS.md](AGENTS.md) - Browse detailed implementation rules and conventions 3. Load specific guidelines - Access detailed examples in references/ as needed 4. Follow the workflow - Apply the systematic approach to skill creation

For Humans

This skill is optimized for AI agents but humans may find it useful for:

• Understanding how agent skills are structured
• Learning best practices for skill architecture
• Contributing to existing skills
• Creating new skills for specialized domains
• Packaging domain expertise for AI agents

---

Skill Creation Workflow

Step 1: Understanding with Concrete Examples

Gather real examples of how the skill will be used. Ask questions to understand:

• What functionality should the skill support?
• Can you give examples of how this skill would be used?
• What would a user say that should trigger this skill?

This ensures the skill solves actual problems rather than hypothetical ones.

Step 2: Planning Reusable Contents

Analyze each example to identify reusable resources:

• Scripts: Executable helpers that eliminate repetitive coding
• References: Documentation of schemas, patterns, or domain knowledge
• Assets: Templates, boilerplate, or example files

Step 3: Initializing the Skill

Create the skill structure following established conventions:

• Check for existing relevant skills
• Follow naming conventions (kebab-case directories, uppercase SKILL.md)
• Set up proper directory structure

Step 4: Editing and Refining

Develop skill content with agent-focused information:

• Include procedural knowledge that isn't obvious
• Focus on non-obvious implementation details
• Structure content for progressive disclosure

---

Key Features

Progressive Disclosure

• Metadata (~100 tokens) loaded at startup
• Main SKILL.md (<5000 tokens) loaded when activated
• References loaded only when needed
• Minimizes context usage for LLMs

Concrete Examples

Every skill should be built around real usage patterns:

• Start with actual user requests
• Identify repetitive workflows
• Package reusable solutions

Structured Guidelines

All guidelines follow a consistent format:

• One-line summaries with links
• ❌/✅ examples in reference files
• Self-contained documentation

Reusable Resources

Package three types of resources:

• Scripts: Automate repetitive tasks
• References: Document schemas, patterns, APIs
• Assets: Provide templates and boilerplate

---

What Skills Provide

Skills are modular packages that extend Claude's capabilities by providing:

1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex tasks 5. Best practices - Documentation and examples for particular subjects

Skills act as "onboarding guides" that transform agents into specialized problem solvers equipped with procedural knowledge.

---

Example Skills

• pdf-editor: Scripts for rotating, merging, and manipulating PDFs
• frontend-app-builder: Boilerplate templates for React/Next.js apps
• big-query: Table schemas and relationships for database queries
• vitest: Best practices and patterns for testing with Vitest
• react-best-practices: Performance optimization patterns for React

---

Usage

This skill is designed to be used with environments such as Claude Code. It automatically activates when creating, refactoring, or auditing agent skills.

Auditing an Existing Skill

prompt

Persona:
You are an expert skill architect.

Objective:
1. Use the accelint-skill-manager skill to audit ./skills/example-skill
2. Identify any best practice optimizations that can be made
3. Optimize towards deterministic output and correctness when auditing
4. Explain your reasoning clearly with specific examples

Output:
A complete, production-ready skill following all best practices.

Creating a New Skill

prompt

Persona:
You are an expert skill architect.

Objective:
1. Use the accelint-skill-manager skill
2. Create a new skill for [domain/tool/workflow]
3. Follow the 4-step workflow
4. Ensure adherence to all conventions

Output:
A complete, production-ready skill following all best practices.

Manual Invocation

command

/accelint-skill-manager

See SKILL.md for complete activation criteria and detailed workflow.

---

Contributing

When creating or updating skills:

1. Follow the 4-step workflow - Don't skip steps 2. Start with concrete examples - Real usage patterns, not hypothetical scenarios 3. Structure for progressive disclosure - Keep SKILL.md under 500 lines, move details to references 4. Use consistent formatting - Follow naming conventions and directory structure 5. Include both ❌ and ✅ examples - Show anti-patterns and correct implementations 6. Document for agents - Focus on non-obvious procedural knowledge

See AGENTS.md for detailed implementation guidelines.

Learn More:

• Agent Skills Specification
• references/ - Detailed examples and best practices

---

Skill Architecture Philosophy

This skill follows these principles:

1. Progressive disclosure - Load information only when needed 2. Concrete over abstract - Build from real examples, not hypothetical use cases 3. Agent-focused content - Include procedural knowledge that helps agents execute effectively 4. Reusable resources - Package scripts, schemas, and templates to eliminate repetitive work 5. Consistent structure - Follow conventions for predictable, maintainable skills 6. Minimal nesting - Keep file references one level deep from SKILL.md

---

Learn More

• Agent Skill Best Practices
• What Are Agent Skills?
• Agent Skill Spec

---

License

Apache 2.0

1.3 AGENTS.md

Overview

General rule of thumb is to follow guidance from Agents.md. At minimum try and provide concise and descriptive examples of what incorrect and correct. Consolidate examples as reasonably as possible to reduce token usage. The persona and target audience for this document is an AI Agent or LLM.

Token Efficiency (Critical)

Use cross-references:

❌ Incorrect: repeated workflow details

When searching, dispatch subagent with template...
[20 lines of repeated instructions]

✅ Correct: reference other skill

Always use subagents. REQUIRED: Use [other-skill-name] for workflow.

Compress examples:

# ❌ BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

❌ Incorrect: verbose example (42 words)

your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

✅ Correct: minimal example (20 words)

Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

Eliminate redundancy

• Don't repeat what's in cross-referenced skills
• Don't explain what's obvious from skill
• Don't include multiple examples of same pattern

---

Reference: https://agents.md/#examples

1.7 Assets

Contains static resources that are not intended to be loaded into context, but rather used within the output an agent produces.

• Templates (document templates, configuration templates)
• Images (diagrams, examples)
• Data files (lookup tables, schemas)

When to include: When the skill needs files that will be used in the final output

Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified

Benefits: Separates output resources from documentation, enables an agent to use files without loading them into context

---

Reference: https://agentskills.io/specification#assets%2F

CHANGELOG.md Maintenance

Purpose

CHANGELOG.md tracks version history and the rationale behind skill changes. Unlike git history (which shows individual commits), a CHANGELOG provides a curated, human-readable summary of what changed and why — critical for future maintainers understanding design decisions.

When to Update

Update CHANGELOG.md after:

• Creating a new skill (v1.0 entry)
• Making iterative improvements based on evaluation results
• Fixing bugs or errors
• Adding new sections, patterns, or references
• Restructuring or refactoring
• Any change that bumps the version in frontmatter

Format

Use "Keep a Changelog" format with semantic versioning:

# Changelog

## [X.Y.Z] - YYYY-MM-DD

### Added
- New features, capabilities, sections, or patterns

### Changed
- Modifications to existing content
- **Rationale:** [WHY the change was made]

### Fixed
- Bug fixes, corrections, broken links

### Version
- Explicit version bump note

Versioning Guidelines

Major Version (1.0 → 2.0)

When: Substantial rewrites, breaking changes, complete restructuring

Example:

## [2.0.0] - 2026-03-18

### Changed
- **COMPLETE RESTRUCTURE:** Migrated from prescriptive workflow to principle-based guidance
  - Rationale: Testing showed agents performed better with decision frameworks than rigid steps
  - Evaluation results: Pass rate improved from 65% → 89% with freedom-calibrated approach
- Reorganized into progressive disclosure pattern (SKILL.md → references/)

### Version
- Bumped from 1.4 → 2.0

Minor Version (1.0 → 1.1)

When: New sections, significant additions, refinements

Example:

## [1.3.0] - 2026-03-18

### Added
- New "NEVER Do React" section with 8 critical anti-patterns
  - Rationale: Evaluation revealed common mistakes not covered by existing guidance
- Created comprehensive test suite (evals/evals.json) with 8 realistic prompts

### Changed
- Enhanced description to be more "pushy" about triggering
  - Increased from 344 chars to 640 chars for better keyword coverage
  - Added explicit triggers: useEffect, useState, useMemo, useCallback, memo, SSR

### Version
- Bumped from 1.2 → 1.3

Patch Version (1.0.0 → 1.0.1)

When: Bug fixes, typo corrections, minor clarifications

Example:

## [1.2.1] - 2026-03-18

### Fixed
- Corrected skill name reference in SKILL.md line 168
  - Was: /accelint-ts-best-practices
  - Now: /accelint-react-best-practices
- Fixed broken link to references/optimization.md

### Version
- Bumped from 1.2.0 → 1.2.1

What to Document

✅ Always Include

Rationale for changes:

### Changed
- Removed 80 lines of activation knowledge from SKILL.md body
  - **Rationale:** Activation knowledge belongs ONLY in frontmatter description per spec
  - **Impact:** Reduced token usage by 30%, improved activation accuracy

Links to evaluation results:

### Changed
- Simplified error handling workflow to 3 steps instead of 7
  - **Evaluation result:** Agents skipped complex workflows, achieving 40% pass rate
  - **After simplification:** Pass rate improved to 85%
  - **Rationale:** Agents need decision frameworks, not checklists

Trade-offs and alternatives considered:

### Changed
- Chose mounted flag pattern over synchronous script for SSR hydration
  - **Alternatives considered:** useEffect + setTimeout, React 18 useId
  - **Trade-off:** Slightly more code but works across React versions 16-19
  - **Rationale:** Evaluation showed mixed React versions in user projects

❌ Don't Include

Individual commit messages:

❌ ### Changed
- Updated line 45
- Fixed typo
- Renamed variable

Vague summaries without rationale:

❌ ### Changed
- Improved the workflow
- Made it better
- Enhanced performance

Future plans (use issues/roadmap instead):

❌ ### Planned
- Will add X feature next
- TODO: Improve Y section

Linking Evaluation Results

When changes stem from testing or user feedback, reference the source:

Format 1: Direct reference to eval iteration

### Changed
- Restructured workflow from 5 phases to 3 decision points
  - **Source:** iteration-3 eval results (see workspace/iteration-3/benchmark.md)
  - **Key finding:** Agents bypassed phase 2 & 4, completing only 1, 3, 5
  - **Rationale:** Consolidated essential decision points, removed redundant phases

Format 2: Reference user feedback

### Fixed
- Removed confusing "Freedom Calibration" section
  - **User feedback:** "Agent kept asking which mode to use mid-task"
  - **Root cause:** Section implied multiple modes exist when only one workflow applies
  - **Rationale:** Single-type skills don't need freedom calibration

Format 3: Reference external issues

### Added
- New anti-pattern: NEVER use nested promises without error boundaries
  - **Motivation:** Issue #47 - agents generated unhandled rejection patterns
  - **Expert knowledge:** Nested promises silently swallow errors in Node.js
  - **Reference:** Added references/error-handling.md with examples

Version Consistency

Critical: CHANGELOG version must match metadata.version in SKILL.md frontmatter.

Verification checklist:

• [ ] Latest CHANGELOG entry version matches frontmatter
• [ ] Date is in YYYY-MM-DD format
• [ ] At least one of Added/Changed/Fixed has content
• [ ] Rationale provided for all changes
• [ ] Version bump explicitly noted

Example frontmatter sync:

---
name: example-skill
metadata:
  version: "1.3.0"  # Must match CHANGELOG
---

## [1.3.0] - 2026-03-18  # Must match frontmatter

Anti-Patterns

❌ Weak Entry (No Rationale)

## [1.2.0] - 2026-03-18

### Changed
- Updated the workflow section
- Made improvements

### Version
- Bumped from 1.1 → 1.2

Why weak: No rationale, no specifics, future maintainer can't understand WHY changes happened.

✅ Strong Entry (Clear Rationale)

## [1.2.0] - 2026-03-18

### Changed
- Converted workflow from checklist to decision tree format
  - **Rationale:** Evaluation showed 60% of agents skipped checklist items
  - **Testing:** Decision tree format improved task completion from 60% → 92%
  - **Trade-off:** Slightly longer skill body but dramatically better outcomes

### Added
- New section "Before Starting, Ask" with 5 key questions
  - **Rationale:** Agents dove into implementation without understanding requirements
  - **User feedback:** "Agent built wrong thing because it didn't ask about existing code"

### Version
- Bumped from 1.1 → 1.2

Why strong: Clear rationale, links to testing/feedback, explains trade-offs, future maintainer understands context.

Template

Copy this template when creating a new CHANGELOG entry:

## [X.Y.Z] - YYYY-MM-DD

### Added
- [New feature/section/pattern]
  - **Rationale:** [Why was this needed?]
  - **Source:** [Evaluation/feedback/issue that motivated this]

### Changed
- [Modification to existing content]
  - **Rationale:** [Why make this change?]
  - **Trade-off:** [What was gained/lost?]
  - **Alternatives considered:** [What else was tried?]

### Fixed
- [Bug fix/correction]
  - **Root cause:** [Why did this error exist?]
  - **Impact:** [What broke before this fix?]

### Version
- Bumped from X.Y → X.Z

Example: Real CHANGELOG Entry

From skills/accelint-react-best-practices/CHANGELOG.md:

## [1.4.0] - 2026-03-18

### Added
- **New "Using Skill Patterns Appropriately" section** to improve flexibility
  - Encourages presenting reference patterns while mentioning alternative approaches
  - Guides agents to consider user's React version, project complexity, and team preferences
  - Suggests simpler solutions for basic cases even when not in reference files
  - Example: SSR hydration can use mounted flag pattern for simple cases vs synchronous script
  - **Rationale:** Evaluation showed skill could be overly prescriptive by only suggesting one solution from reference files

### Version
- Bumped from 1.3 → 1.4

What makes this strong:

• Specific: Lists exactly what was added
• Context: Provides concrete example (SSR hydration)
• Rationale: Explains WHY (evaluation revealed over-prescription)
• Actionable: Future maintainer knows to balance prescription vs flexibility

1.1 File System

Directory Structure

A skill is a directory containing at minimum a SKILL.md file. You can optionally include additional directories such as scripts/, references/, and assets/ to support your skill. A README.md file should be included with a general overview of the skill via content optimized for human consumption instead of agent consumption. Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.

Naming Conventions

• Skill directory: kebab-case (e.g., ts-best-practices)
• SKILL.md: Always uppercase, always this exact filename
• AGENTS.md: Always uppercase, always this exact filename
• README.md: Always uppercase, always this exact filename
• Scripts directory: scripts Always this exact folder name
• Scripts: kebab-case.sh (e.g., run.sh, fetch-logs.sh)
• References directory: references Always this exact folder name
• References: kebab-case.md (e.g., aaa-pattern.md, derive-state.md)

Local File References

When referencing other files in your skill, use relative paths from the skill root:

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.sh

---

Reference: https://agentskills.io/specification#directory-structure

1.4 Progressive Disclosure

Skills should be structured for efficient use of context:

• Metadata (~100 tokens): The name and description fields are loaded at startup for all skills
• Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated
• Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required
• Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files.
• Aim to break each rule into a dedicated references/* markdown file to optimize token usage

---

Reference: https://agentskills.io/specification#progressive-disclosure

1.5 References

Contains additional documentation with detailed technical references that agents can read when needed. Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context. References should incorrect and correct examples of a rule to help reinforce context. Show the "Incorrect" version before the "Correct" version for better pedagogical flow. The persona and target audience for this document is an AI Agent or LLM.

Follow the structure in the reference template as closely as possible. If a different structure exists already you must prioritize alignment and consistency. Ask the user if it is okay to aggressively refactor the format of the document.

When to include: For documentation that an agent should reference while working

Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides, best practices, code recipes

Avoid duplication: Information should live in either AGENTS.md, or references files, not both. Prefer references files for detailed information unless it's truly core to the skill. This keeps AGENTS.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.

---

Reference: https://agentskills.io/specification#references%2F

1.6 Scripts

Overview

Contains executable code that agents can run. Scripts should:

• Be self-contained or clearly document dependencies
• Include helpful error messages
• Handle edge cases gracefully

When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed

Benefits: Token efficient, deterministic, may be executed without loading into context

Recommendations

Bash scripts are preferred. When using bash scripts:

• Use #!/bin/bash shebang
• Use set -e for fail-fast behavior
• Write status messages to stderr: echo "Message" >&2
• Write machine-readable output (JSON) to stdout
• Include a cleanup trap for temp files
• Reference the script path as skills/{skill-name}/scripts/{script}.sh

After creating any script, audit it with the bash-defensive-patterns skill and apply any necessary changes.

---

Reference: https://agentskills.io/specification#scripts%2F