skill best practices

Documentation Community

Skill notes

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 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]"

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.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/.

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. 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.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
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.

01
Step 1: Initialize and Validate Metadata

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]"`

02
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.

03
Step 3: Draft Core Logic (SKILL.md)

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/`.

04
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. 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.

05
Step 5: Final Logic Validation

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.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.