Skip to content

AGENTS.md

Latest commit

 

History

History
111 lines (76 loc) · 5.49 KB

AGENTS.md

File metadata and controls

111 lines (76 loc) · 5.49 KB
Raw

AGENTS.md — Host Instructions for AI Coding Agents

Goal

Use this pack to help an AI coding agent work with heilcheng/awesome-agent-skills safely and verifiably — without assuming the upstream tool is installed, verified, or officially endorsed.

When To Load This Pack

Load this pack when the user asks for any of the following:

User says... Why this pack applies
"which skills should I load from awesome-agent-skills?" The repo has 100+ skills with unresolved risk discussions; this pack provides a selection workflow with risk filters.
"can you install or use npx skills?" The install name does not match the repo name; this pack requires verification before claiming the tool works.
"help me add a skill to my AI agent (Claude/Cursor/Codex/Gemini)" The project can modify host AI config; this pack requires a rollback path before any install.
"is it safe to load [skill name] from awesome-agent-skills?" At least two skills have open security/risk discussions; this pack routes to the pitfall log before approval.
"run the awesome-agent-skills quick start" The quick start assumes the tool works; this pack requires smoke check evidence before claiming success.
"evaluate the quality of skills in this repo" Assumptions about documentation currency are explicit pitfalls in this pack; verification steps are required.

Do NOT load this pack for general conversation, non-agent-tooling tasks, or when the user is just browsing the upstream README without intent to install.

How To Use This Pack (Step by Step)

Step 1 — Restate the task

Before doing anything, restate what the user is asking for. Confirm the target host (Claude Code, Cursor, Codex, etc.), the specific goal, and any safety boundaries the user has stated.

Step 2 — Map the task to a known pitfall or risk

Consult 03_PITFALL_LOG.md before running any install, eval, or tool call. The top 3 pitfalls are at the top of the file and are immediately actionable. Each entry tells you:

  • What the symptom looks like
  • Which recovery step to follow
  • When to stop entirely

Step 3 — Identify required tool calls

Before calling any external tool (npm, npx, git, browser, network, filesystem, or credentials), state explicitly:

  • Which tool you need
  • Why it is needed
  • What boundary from 04_BOUNDARY_RISK_CARD.md applies
  • Wait for explicit user approval

Step 4 — Run the smoke check eval first

Run 06_EVALS/smoke_check.md before claiming any skill or capability works. The eval confirms the agent:

  • Restates the task correctly
  • Names the relevant boundaries
  • Proposes a verification step
  • Does not claim success without evidence

Step 5 — On failure, use the recovery table

If an eval fails, stop and consult the recovery table below.

Failure Recovery Table

Eval that failed What to do
smoke_check.md fails — agent claims tool is installed without evidence Stop. Open 03_PITFALL_LOG.md → Pitfall 1 (identity坑 · repo/install name mismatch). Verify with npx skills --version or npx skills --help before continuing.
smoke_check.md fails — agent skips risk checks Stop. Load 04_BOUNDARY_RISK_CARD.md explicitly. Do not proceed until the agent names at least one boundary.
boundary_check.md fails — agent calls external tool without asking Stop. The host has not granted tool permissions. Report which tool was called without approval and which boundary it violated.
boundary_check.md fails — agent asks for secrets unnecessarily Stop. Do not provide secrets. Report which pitfall applies (likely Pitfall 5 or 6 from 03_PITFALL_LOG.md).
failure_check.md fails — agent invents facts or ignores pitfall log Stop. Open 03_PITFALL_LOG.md directly and read the top 3 pitfalls aloud. Do not proceed until the agent correctly identifies the likely failure mode.

Inputs Expected From User

Before taking action, confirm:

  • Target host (Claude Code, Cursor, Codex, Gemini, etc.)
  • Task goal (e.g., "find a safe skill for X", "install Y skill", "evaluate Z")
  • Safety boundary (what tools, network, filesystem, or credentials are approved)
  • Whether the user has run npx skills successfully before (to establish a baseline)

Allowed Actions

  • Read files in this pack.
  • Ask clarifying questions before acting.
  • Produce a plan and wait for confirmation.
  • Run only user-approved verification commands.
  • Record failures in 03_PITFALL_LOG.md format when a new pitfall is discovered.

Disallowed Actions

  • Do not claim official endorsement by heilcheng/awesome-agent-skills.
  • Do not access secrets, API keys, or credentials without explicit user approval.
  • Do not send messages, publish, purchase, delete, or modify external systems without explicit user approval.
  • Do not claim the upstream tool works until an acceptance check passes.
  • Do not skip the smoke check before claiming any capability is verified.

Verification Checklist

Before claiming any skill or capability from awesome-agent-skills works, confirm all of:

  • AGENTS.md or CLAUDE.md is loaded
  • Task has been restated and boundaries confirmed
  • 03_PITFALL_LOG.md checked for relevant pitfalls
  • 04_BOUNDARY_RISK_CARD.md reviewed for hard stops
  • Smoke check eval (06_EVALS/smoke_check.md) has been mentally run or explicitly executed
  • User has approved any required tool calls

Source / Risk Reminder

This is an independent Doramagic pack. See SOURCE_MAP.md for evidence and upstream source links.