agent-install-guide

📁 shihyuho/skills 📅 5 days ago

总安装量

周安装量

#16745

全站排名

安装命令

npx skills add https://github.com/shihyuho/skills --skill agent-install-guide

Agent 安装分布

amp 6

opencode 6

kimi-cli 6

codex 6

antigravity 6

Skill 文档

Agent Install Guide

Overview

AI agents need deterministic, verifiable instructions. Unlike humans who can infer “download to a safe place”, AI agents need exact paths and explicit success criteria.

This skill provides principles for writing “Agent-Ready” installation guides.

When to Use

Creating installation or setup documentation
Writing guides that AI agents will execute
Documenting installation for automation

Workflow

Ask for filename: User may have a preferred location (e.g., docs/setup.md, INSTALL.md). If no preference, suggest INSTALL.md.
Apply principles: Follow the core principles below when writing.
Offer README integration: After creating the guide, ask if user wants to add a reference to their project README.

Core Principles

These are the concepts to internalize, not rules to follow blindly:

1. Determinism

Every instruction should have exactly one interpretation.

â Ambiguous	â Deterministic
“Download to a safe location”	“Download to `~/.local/share/toolname`“
“Add to your PATH”	`echo 'export PATH=...' >> ~/.zshrc`
“Edit the config file”	Provide full content via heredoc

2. Idempotency

Commands should be safe to run multiple times.

â Fragile	â Idempotent
`mkdir config`	`mkdir -p ~/.config/app`
`ln -s src dest`	`ln -sf src dest`
`rm file`	`rm -f file`

3. Verifiability

Every significant step should have a way to confirm success.

Examples of verification:

which toolname – binary is in PATH
toolname --version – correct version installed
ls -l ~/.config/app/ – config file exists
curl localhost:8080/health – service is running

4. Interactivity

When choices exist, ask the user rather than assuming.

Trigger situations:

Multiple installation options (plugins, themes)
Platform-specific paths
Optional features
Subscription tiers

Patterns & Techniques

Use these when applicable to your specific installation:

Meta-Instructions Block

A block at the top telling executing agents what to do. Adapt to your needs:

> **ð¤ AI AGENTS:** [What to do before/during installation]
> - [Action 1]
> - [Action 2]
> - [Verification instruction]

Heredoc for Config Files

Instead of “edit the file”, provide complete content:

cat <<EOF > ~/.config/myapp/config.json
{
  "key": "value"
}
EOF

Decision Trees

When installation branches based on user choice:

**If user has Pro subscription:**
`npm install myapp-pro`

**If user has Free tier:**
`npm install myapp-free`

Shell Detection (when needed)

Only when modifying shell config. Not every installation needs this.

# Detect shell config file
case "$SHELL" in
  */zsh)  SHELL_RC="${ZDOTDIR:-$HOME}/.zshrc" ;;
  */bash) SHELL_RC="$HOME/.bashrc" ;;
  */fish) SHELL_RC="$HOME/.config/fish/config.fish" ;;
  *)      SHELL_RC="$HOME/.profile" ;;
esac

Common Pitfalls

Pitfall	Problem	Solution
Relative paths	`ln -s ./file` breaks in wrong directory	Use `$(pwd)/file` or absolute paths
Vague “add to PATH”	Agent doesn’t know which shell	Provide exact command or detect shell
Missing `sudo` warning	Agent fails on permission denied	Warn upfront or use user-space dirs
Interactive prompts	`apt install` hangs waiting for input	Use `-y` flag or equivalent

Limitations

Unix-focused: macOS/Linux assumed. Windows needs different handling.
User-space preferred: Avoid system directories when possible.

Reference

See references/INSTALL_TEMPLATE.md for structural concepts. See references/README_INTEGRATION_TEMPLATE.md for adding install links to README.

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台