skill best practices
- Repo stars 374
- Author repo skills
- Domain
- Documentation
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @pedronauck · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Define a unique `name`: 1-64 characters, lowercase, numbers, and single hyphens only. Draft a `description`: Max 1,024 characters, written in the third person, including negative triggers. Execute Validation Script (read-only helper): Run the validation script to ensure compliance before proceeding: `python3 <skill-best-practices-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"`
Create the root directory using the validated `name`. 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.
Use the template in `assets/SKILL.template.md` as the starting point. Write all instructions in the third-person imperative (e.g., "Extract the text," "Run the build"). 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/`.
Identify "fragile" tasks (regex, complex parsing, or repetitive boilerplate). Outline a single-purpose script for the `scripts/` directory. Ensure the script uses standard output (stdout/stderr) to communicate success or failure to the agent. In `SKILL.md`, reference bundled helpers by a path that is unambiguous from the agent's working directory (the same path the agent will type to invoke them), rather than bare `scripts/helper.py` snippets that silently depend on CWD.
Review the `SKILL.md` for "hallucination gaps" (points where the agent is forced to guess). Verify all file paths are relative and use forward slashes (`/`). Verify every referenced helper path is unambiguous from the agent's working directory and that the helper's role (`read-only`, `bootstrap`, or `mutating`) is stated. Read `references/checklist.md` and cross-reference every checklist item against the final output.
# Skill Authoring Procedure
Follow these steps to generate a skill that adheres to the agentskills.io specification and progressive disclosure principles.
## Bundled Path Rule
Resolve bundled paths relative to the directory that contains this `SKILL.md`. When invoking a helper from another working directory, expand `<skill-best-practices-dir>` to that directory first so the command is unambiguous.
## 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 (read-only helper):** Run the validation script to ensure compliance before proceeding:
`python3 <skill-best-practices-dir>/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.
4. In `SKILL.md`, reference bundled helpers by a path that is unambiguous from the agent's working directory (the same path the agent will type to invoke them), rather than bare `scripts/helper.py` snippets that silently depend on CWD.
5. Label each helper as **read-only**, **bootstrap**, or **mutating** so downstream agents know whether the helper only inspects state or changes it.
## 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. Verify every referenced helper path is unambiguous from the agent's working directory and that the helper's role (`read-only`, `bootstrap`, or `mutating`) is stated.
4. Read `references/checklist.md` and cross-reference every checklist item against the final output.
## 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/`.
Listed in source order.
sections -> Bundled Path Rule → Step 1: Initialize and Validate Metadata → Step 2: Structure the Directory → Step 3: Draft Core Logic (SKILL.md) → Step 4: Identify and Bundle Scripts → Step 5: Final Logic Validation
terms -> Execute Validation Script (read-only helper) · third-person imperative · Enforce Progressive Disclosure · read-only · bootstrap · mutating · relative · Metadata Failure
files/cmd -> <skill-best-practices-dir> · name · description · stderr · scripts/ · references/ · assets/ · assets/SKILL.template.md
body sha256 -> b8cb20c9deba
Bundled Path Rule
Resolve bundled paths relative to the directory that contains this
SKILL.md. When invoking a helper from another working directory, expand<skill-best-practices-dir>to that directory first so the command is unambiguous.Step 1: Initialize and Validate Metadata
Define a unique
name: 1-64 characters, lowercase, numbers, and single hyphens only. Draft adescription: Max 1,024 characters, written in the third person, including negative triggers. Execute Validation Script (read-only helper): Run the validation script to ensure compliance before proceeding:python3 <skill-best-practices-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"Step 2: Structure the Directory
Create the root directory using the validated
name. 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.Step 3: Draft Core Logic (SKILL.md)
Use the template in
assets/SKILL.template.mdas the starting point. Write all instructions in the third-person imperative (e.g., "Extract the text," "Run the build"). Enforce Progressive Disclosure: Keep the main logic under 500 lines. If a procedure requires a large schema or complex rule set, move it toreferences/.Step 4: Identify and Bundle Scripts
Identify "fragile" tasks (regex, complex parsing, or repetitive boilerplate). Outline a single-purpose script for the
scripts/directory. Ensure the script uses standard output (stdout/stderr) to communicate success or failure to the agent. InSKILL.md, reference bundled helpers by a path that is unambiguous from the agent's working directory (the same path the agent will type to invoke them), rather than barescripts/helper.pysnippets that silently depend on CWD.