tentacle-skills-washing

name

tentacle-skills-washing

description

Adapt, repair, and environment-proof Agent Skills so they run correctly in this vault. Use this skill when: (1) A downloaded or third-party skill needs to be installed/adapted to this vault's runtime (uv/bun), folder conventions, and path rules. (2) An existing skill fails or errors at runtime due to environment issues—wrong Python/TS runner, broken paths, missing inline dependencies, incorrect execution commands, or artefacts written to the wrong location. (3) A skill's shipped docs (AGENTS.md / SKILL.md) conflict with this vault's standards and need to be reconciled. Triggers: "wash this skill", "fix this skill", "this skill is broken", "adapt skill from", "install skill", "skill throws an error", "skill can't find", "update skill to work here".

Skill: tentacle-skills-washing

Purpose

Adapt a downloaded third-party Agent Skill so it runs correctly in this vault's runtime environment and respects its folder conventions.

When to Invoke

User says something like:

• "wash this skill"
• "install/adapt this skill from [source/path]"
• "I downloaded a skill, make it work here"

---

Required Reading Before Acting

Always read these files first — do not proceed without them:

1. AGENTS.md (vault root) — folder rules, naming, artefact boundaries
2. .agents/skills/AGENTS.md — Python/TS runtime standards, execution commands

---

Inputs

Input	Description
skill_path	Path to the downloaded skill directory, relative to vault root (e.g. .agents/skills/my-downloaded-skill/)

---

Washing Protocol

Work through each step in order. Check off items as you verify or fix them.

Step 1 — Inventory

• List all files in the skill directory
• Identify primary entry point (main.py, main.ts, or equivalent)
• Note language(s) used (Python / TypeScript / shell)

Step 2 — Python scripts

• Remove requirements.txt, setup.py, .venv/ if present
• Add PEP 723 inline metadata to every standalone .py file (see .agents/skills/AGENTS.md)
• Replace any python main.py / pip install execution instructions with uv run .agents/skills/<skill-name>/main.py [args]

Step 3 — TypeScript scripts

• Ensure package.json exists inside the skill directory
• Verify dependencies are installed locally (bun add inside the skill dir)
• Replace execution instructions with bun .agents/skills/<skill-name>/main.ts [args]

Step 4 — Path references

• Replace all absolute paths or author-machine-specific paths with vault-root-relative paths
• Any file I/O that reads vault notes must target the correct folders per root AGENTS.md
• Any file I/O that writes logs/temp files must stay inside .agents/skills/<skill-name>/

Step 5 — Shipped docs (AGENTS.md / README / SKILL.md)

• If the skill ships its own AGENTS.md: review for conflicts with our standards; remove duplicates; keep only skill-specific overrides
• If the skill ships a SKILL.md: update execution commands and paths to match local standards; preserve the original's purpose description and parameter contracts
• If the skill ships neither: create a minimal SKILL.md describing what it does and how to invoke it

Step 6 — Obsidian data integrity

• If the skill reads .md files: confirm it preserves YAML frontmatter
• If the skill writes .md files: confirm it uses wikilink syntax [[Page Name]] for cross-references
• Confirm it does NOT write .log, .tmp artefacts outside its own directory

Step 7 — Smoke test

Instruct the user to run the adapted skill with a minimal input and verify it executes without errors.

---

Output Contract

A skill directory at .agents/skills/<skill-name>/ that:

• Runs via uv run or bun without any extra setup
• Contains a SKILL.md summarising purpose, inputs, and invocation command
• Leaves no artefacts outside its own directory
• Does not conflict with vault-wide rules in root AGENTS.md

---

Reference Artefacts in This Directory

File	Purpose
AGENTS-template.md	Template for generating vault-level AGENTS.md when bootstrapping a new vault