Skill Best Practices

Name: Skill Best Practices
Author: pedronauck

pedronauck/kodebase-go

1 installs
95 repo stars
Updated June 28, 2026
pedronauck/kodebase-go

Authors and structures agent skills following the agentskills.io spec, validating metadata and enforcing progressive disclosure.

About

Guides creation of a skill directory with validated name and description, correct subdirectories, and third-person imperative instructions under 500 lines. A developer uses it when writing or optimizing an agent skill.

Structures skills per the agentskills.io spec
Metadata validation script and progressive disclosure rules

Skill Best Practices by the numbers

1 all-time installs (skills.sh)
Ranked #642 of 782 Skill Development skills by installs in the Skillselion catalog
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/pedronauck/kodebase-go --skill skill-best-practices

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/pedronauck/kodebase-go/skill-best-practices.svg)](https://skillselion.com/skills/pedronauck/kodebase-go/skill-best-practices)

Installs	1
repo stars	★ 95
Last updated	June 28, 2026
Repository	pedronauck/kodebase-go ↗

What it does

Authors and structures agent skills following the agentskills.io spec, validating metadata and enforcing progressive disclosure.

Files

SKILL.mdMarkdownGitHub ↗

Skill Authoring Procedure

Follow these steps to generate a skill that adheres to the agentskills.io specification and progressive disclosure principles.

Step 1: Initialize and Validate Metadata

1. Define a unique name: 1-64 characters, lowercase, numbers, and single hyphens only. 2. Draft a description: Max 1,024 characters, written in the third person, including negative triggers. 3. Execute Validation Script: Run the validation script to ensure compliance before proceeding: python3 scripts/validate-metadata.py --name "[name]" --description "[description]" 4. If the script returns an error, self-correct the metadata based on the stderr output and re-run until successful.

Step 2: Structure the Directory

1. Create the root directory using the validated name. 2. Initialize the following subdirectories:

scripts/: For tiny CLI tools and deterministic logic.
references/: For flat (one-level deep) context like schemas or API docs.
assets/: For output templates, JSON schemas, or static files.

3. Ensure no human-centric files (README.md, INSTALLATION.md) are created.

Step 3: Draft Core Logic (SKILL.md)

1. Use the template in assets/skill-template.md as the starting point. 2. Write all instructions in the third-person imperative (e.g., "Extract the text," "Run the build"). 3. Enforce Progressive Disclosure:

Keep the main logic under 500 lines.
If a procedure requires a large schema or complex rule set, move it to references/.
Command the agent to read the specific file only when needed: "Read references/api-spec.md to identify the correct endpoint."

Step 4: Identify and Bundle Scripts

1. Identify "fragile" tasks (regex, complex parsing, or repetitive boilerplate). 2. Outline a single-purpose script for the scripts/ directory. 3. Ensure the script uses standard output (stdout/stderr) to communicate success or failure to the agent.

Step 5: Final Logic Validation

1. Review the SKILL.md for "hallucination gaps" (points where the agent is forced to guess). 2. Verify all file paths are relative and use forward slashes (/). 3. Cross-reference the final output against references/checklist.md.

Error Handling

Metadata Failure: If scripts/validate-metadata.py fails, identify the specific error (e.g., "STYLE ERROR") and rewrite the field to remove first/second person pronouns.
Context Bloat: If the draft exceeds 500 lines, extract the largest procedural block and move it to a file in references/.

Agent Skill Validation Checklist

Use this checklist to perform a final audit of the generated skill before deployment. Every item must be marked as "Pass" to ensure the skill is discoverable, lean, and deterministic.

1. Metadata & Discovery

[ ] Naming: The name field is 1-64 characters, lowercase, and contains only numbers or single hyphens.
[ ] Directory Match: The name field exactly matches the parent directory name.
[ ] Description Length: The description is under 1,024 characters.
[ ] Trigger Optimization: The description includes both use cases ("Use when...") and negative triggers ("Don't use for...").
[ ] Third-Person Tone: The description avoids "I", "me", "my", "you", or "your".

2. File Structure & Paths

[ ] Flat Hierarchy: All files in scripts/, references/, and assets/ are exactly one level deep (no nested subfolders).
[ ] Standard Folders: Only use scripts/, references/, and assets/.
[ ] No Human Docs: The directory contains NO README.md, CHANGELOG.md, or INSTALLATION_GUIDE.md.
[ ] Forward Slashes: All file paths in SKILL.md use forward slashes (/) regardless of the operating system.

3. Logic & Instructions (SKILL.md)

[ ] Lean Context: The SKILL.md file is under 500 lines.
[ ] Imperative Mood: Instructions use direct commands (e.g., "Extract," "Run," "Validate").
[ ] Deterministic Steps: The workflow is a numbered, chronological sequence with clear decision trees.
[ ] Progressive Disclosure: Large schemas, templates, or rule sets are stored in references/ or assets/ and read only when needed.
[ ] Specific Terminology: Uses domain-native terms consistently (e.g., "component" instead of "file").

4. Scripts & Determinism

[ ] CLI Design: Scripts in scripts/ are designed as tiny CLIs that take arguments.
[ ] Feedback Loop: Scripts provide descriptive stdout for success and stderr for failure to allow agent self-correction.
[ ] No Library Code: Scripts are single-purpose; complex logic is offloaded to the repository's standard CLI or external tools.

5. Error Handling

[ ] Edge Cases: The SKILL.md includes an "Error Handling" section addressing common failure states or missing configurations.
[ ] Validation: The SKILL.md includes a step to run validation scripts where applicable.

import re
import sys
import argparse

def validate_metadata(name, description):
    errors = []

    # 1. Validate Name Length
    if not (1 <= len(name) <= 64):
        errors.append(f"NAME ERROR: '{name}' is {len(name)} characters. Must be between 1-64.")

    # 2. Validate Name Characters (lowercase, numbers, single hyphens)
    # Regex: Starts/ends with alphanumeric, allows single hyphens in between
    if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", name):
        errors.append(
            f"NAME ERROR: '{name}' contains invalid characters. "
            "Use only lowercase letters, numbers, and single hyphens. "
            "No consecutive hyphens, and cannot start/end with a hyphen."
        )

    # 3. Validate Description Length
    if len(description) > 1024:
        errors.append(
            f"DESCRIPTION ERROR: Description is {len(description)} characters. "
            "Must be 1,024 characters or fewer."
        )

    # 4. Check for Third-Person Perspective (Basic Heuristic)
    first_person_words = {"i", "me", "my", "we", "our", "you", "your"}
    desc_words = set(re.findall(r'\b\w+\b', description.lower()))
    found_forbidden = first_person_words.intersection(desc_words)
    if found_forbidden:
        errors.append(
            f"STYLE WARNING: Description contains first/second person terms: {found_forbidden}. "
            "Use third-person imperative (e.g., 'Creates...', 'Updates...')."
        )

    if errors:
        print("\n".join(errors), file=sys.stderr)
        sys.exit(1)
    else:
        print("SUCCESS: Metadata is valid and optimized for discovery.")
        sys.exit(0)

if __name__ == "__main__":