agentleFS
Sign inStart free
Siddharth00Siddharth00/agent-revamp-skills/skills/_template/SKILL.md

_template # RENAME THIS to match your skill's folder name when you copy this file

Skill1 starsChanged 7 months agoMITView on GitHub

<<One-sentence description of what this skill does and for whom.>>

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 11 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not delete any section heading or its comment block.

    line 47
  2. Distinctive:

    STOP CONDITION: If any Required input is absent at runtime, Claude must halt and ask: "I need <<input_name>> to proceed.

    line 138
  3. Distinctive:

    Do not infer or guess required inputs.

    line 140
  4. Distinctive:

    If this fails: <recovery action or escalation>

    line 158
  5. Distinctive:

    If this fails: <<Recovery action — retry, fallback, or escalate to user.>>

    line 176
  6. Distinctive:

    Test Name : Short identifier, kebab-case.

    line 248
  7. Distinctive:

    Add more rows as needed. Remove placeholder rows that don't apply.

    line 274
  8. Distinctive:

    Every test listed here must be referenced by name in Section 9 Done Criteria.

    line 275
  9. Distinctive:

    Always include the anti-patterns doc when the skill involves destructive operations.

    line 317
  10. Distinctive:

    Always include the strangler-fig doc when the skill touches traffic routing or dual-write.

    line 318
  11. Distinctive:

    Prefer internal paths over external URLs.

    line 319

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- ═══════════════════════════════════════════════════════════════════════════ SKILL TEMPLATE — agent-revamp-skills Copy this file into skills/<NN-phase>/<skill-id>/<skill-id>.md Replace every <<PLACEHOLDER>> with real content before marking status: stable. Do not delete any section heading or its comment block. ═══════════════════════════════════════════════════════════════════════════ -->

1. Purpose

<!-- WHAT TO WRITE One paragraph, 3–6 sentences, plain English. No bullet points. Answer three questions in order: (a) What problem does this skill solve? (b) Who runs it, and at what point in the migration? (c) What is the key constraint or risk it manages? COMMON MISTAKES - Describing HOW the skill works (belongs in Steps). - Listing what it needs (belongs in Inputs). - Writing "This skill migrates X" and nothing else — no context, no risk framing. EXAMPLE (one sentence each of a–c) "This skill extracts the authentication service from a Rails monolith into a standalone Rack app behind a shared JWT issuer. A backend engineer runs it once per authentication boundary, after the strangler-fig proxy is in place (Phase 3). The primary risk is session continuity: existing tokens must remain valid across both implementations during the dual-run window." -->

<<3–6 sentence description of purpose, who runs it, and the key risk it manages.>>

2. Trigger Conditions

<!-- WHAT TO WRITE Two explicit lists: "Use when" (positive triggers) and "Do NOT use when" (anti-triggers). Each item must be a concrete, observable signal — not a vague intention. COMMON MISTAKES - "Use when: you want to migrate something." — too vague; any skill matches this. - Omitting anti-triggers. Without them, skills get run at the wrong phase. - Listing the same condition in both lists. EXAMPLE trigger : "The Phase 3 strangler-fig proxy is deployed and health-checked." EXAMPLE anti-trigger: "The audit report (Phase 1) has not been completed for this unit." -->

Use when:

  • <<Observable signal that this skill is appropriate — be specific.>>
  • <<Observable signal 2.>>
  • <<Observable signal 3 (add or remove rows as needed).>>

Do NOT use when:

  • <<Condition that makes this skill wrong or dangerous to run.>>
  • <<Condition 2 — include at least one phase-order anti-trigger.>>
  • <<Condition 3 (add or remove rows as needed).>>

3. Inputs

<!-- WHAT TO WRITE Two tables: Required and Optional. For every input: the exact name used in Steps, its type, and a clear description. TYPES: file-path | string | boolean | enum(<values>) | json-file | integer COMMON MISTAKES - Listing an input as Optional when a missing value would break a Step. - Omitting the Default column for Optional inputs (every optional must have one). - Using vague names like "config" or "path" — be specific: "audit_report_path". EXAMPLE Required row : | `target_module` | string | The module name as it appears in the migration manifest. | EXAMPLE Optional row : | `--dry-run` | boolean | false | Preview changes without writing files. | -->

Required:

InputTypeDescription
<<input_name>><<type>><<What it is and where to get it.>>
<<input_name>><<type>><<What it is and where to get it.>>

Optional:

InputTypeDefaultDescription
<<input_name>><<type>><<default>><<What it controls and when to override the default.>>
<<input_name>><<type>><<default>><<What it controls and when to override the default.>>
<!-- STOP CONDITION: If any Required input is absent at runtime, Claude must halt and ask: "I need <<input_name>> to proceed. <<Where the user can find it>>." Do not infer or guess required inputs. -->

4. Steps

<!-- WHAT TO WRITE Numbered, ordered, imperative instructions. This is the executable core of the skill. Each step is a direct command to Claude — written as if Claude is the subject. VOICE RULES - Correct : "Read <<file>>. Extract all exported function names." - Incorrect : "<<file>> should be read" / "You may want to look at <<file>>." STEP ANATOMY <number>. <imperative action> - If this fails: <recovery action or escalation> - → Hand off to `<agent-name>` (see Section 5. Agent Handoffs) COMMON MISTAKES - Steps that reference context not defined in Inputs ("use the config from earlier"). - Steps without failure handling on destructive or network-dependent actions. - Steps so coarse they hide ambiguity ("migrate the service") — each step must be unambiguous to a cold Claude session with no prior context. EXAMPLE "1. Read `<<audit_report_path>>`. Extract the list of exported symbols for `<<target_module>>`." "2. Search for every import of those symbols across `<<repo_root>>`. Write matches to `output/<<skill-id>>-symbol-map-<<timestamp>>.json`." " - If this fails: check that `<<repo_root>>` is accessible and retry once." -->
  1. <<First step — read, load, or gather the inputs declared in Section 3.>>
  2. <<Second step — perform the primary analysis or transformation.>>
    • If this fails: <<Recovery action — retry, fallback, or escalate to user.>>
  3. <<Third step.>>
    • → Hand off to <<agent-name>> (see Section 5. Agent Handoffs) if <<condition>>.
  4. <<Write all outputs to the paths declared in Section 7.>>
  5. <<Run the Equivalence Tests defined in Section 6. Record results.>>
  6. <<Evaluate every item in Section 9 Done Criteria. Report pass/fail for each.>>

5. Agent Handoffs

<!-- WHAT TO WRITE One block per sub-agent this skill delegates to. If the skill is self-contained, write "None — this skill is self-contained." with a one-sentence reason. Each block must include: - Agent file path (in agents/) - The Step number that triggers the handoff - A complete, self-contained prompt template using <<PLACEHOLDER>> syntax for values that are resolved at runtime from Inputs or prior Steps. COMMON MISTAKES - Copying the agent's system prompt here — don't. Reference the file; only supply the task-specific prompt template. - Using vague placeholders like {{stuff}} — every placeholder must match an Input name or a named output from a prior Step. - Forgetting to specify OUTPUT_FILE — agents must always write to a file. EXAMPLE ## code-archaeologist - **File:** `agents/code-archaeologist.md` - **Triggered by:** Step 3 - **Prompt template:** ``` TASK: Inventory all usages of <<target_module>> in <<repo_root>>. SCOPE: <<repo_root>>/src OUTPUT_FILE: output/<<skill-id>>-inventory-<<timestamp>>.md FORMAT: markdown ``` -->

<<agent-name | None>>

<!-- Replace the heading with the agent name, or keep "None" and delete this block. -->
  • File: agents/<<agent-file>>.md
  • Triggered by: Step <<N>>
  • Prompt template:
    TASK:        <<Specific task for this invocation.>>
REPO_ROOT:   <<repo_root>>
SCOPE:       <<subdirectory or glob, or "all">>
OUTPUT_FILE: output/<<skill-id>>-<<agent-name>>-<<timestamp>>.<<ext>>
FORMAT:      <<markdown | json>>

6. Equivalence Tests

<!-- WHAT TO WRITE A table of behavioral tests that prove the migrated component is equivalent to the original. These tests are run in Step 5 and their results feed into Done Criteria. This section answers: "How do we know the new thing does what the old thing did?" It is NOT a test plan — it is a concrete, runnable specification. COLUMNS - Test Name : Short identifier, kebab-case. Used in Done Criteria to reference results. - Input : The exact stimulus — HTTP request, function call, CLI command, SQL query. - Expected Output: The exact response the migrated implementation must produce. - Tool : The Claude Code tool or external command used to run the test. Examples: Bash, WebFetch, Read, custom test runner command. COMMON MISTAKES - Vague Expected Outputs like "returns successfully" — specify status codes, shapes, values. - Omitting error-path tests — at least one row must test an invalid or edge-case input. - Using "manual" as the Tool with no description of what to do manually. - Having fewer than 3 rows (aim for coverage of: happy path, error path, edge case). EXAMPLE ROWS | auth-happy-path | POST /auth/login {user:"alice", pass:"correct"} | 200 {token: <jwt>} | Bash: curl -s ... | | auth-wrong-pass | POST /auth/login {user:"alice", pass:"wrong"} | 401 {error: "..."} | Bash: curl -s ... | | auth-missing-field | POST /auth/login {user:"alice"} | 400 {error: "..."} | Bash: curl -s ... | -->
Test NameInputExpected OutputTool
<<test-happy-path>><<Exact input — request, call, command, or query.>><<Exact expected response — status, shape, value.>><<Bash | Read | WebFetch | <<command>>>>
<<test-error-path>><<An invalid or missing input that should trigger an error.>><<Expected error response — code, message.>><<Tool>>
<<test-edge-case>><<A boundary input — empty, max-length, concurrent, etc.>><<Expected output for this edge.>><<Tool>>
<<test-name-4>><<Input>><<Expected Output>><<Tool>>
<!-- Add more rows as needed. Remove placeholder rows that don't apply. Every test listed here must be referenced by name in Section 9 Done Criteria. -->

7. Outputs

<!-- WHAT TO WRITE A table of every artifact this skill writes to disk. Nothing goes only to stdout. COLUMNS - Artifact : Human-readable name. - Path Pattern : Relative path from repo root. Use <<timestamp>> to avoid collisions. - Format : markdown | json | yaml | shell | csv | other - Description : What the file contains and who consumes it next. COMMON MISTAKES - Listing outputs without <<timestamp>> in the path — causes overwrites on reruns. - Forgetting to list the equivalence test results file. - Describing what the file IS rather than what it CONTAINS and who USES it. EXAMPLE ROW | Migration log | `output/<<skill-id>>-log-<<timestamp>>.md` | markdown | Step-by-step record of changes made; reviewed by engineer before cut-over. | -->
ArtifactPath PatternFormatDescription
<<Artifact name>>output/<<skill-id>>-<<artifact>>-<<timestamp>>.<<ext>><<format>><<What it contains and who/what uses it next.>>
<<Artifact name>>output/<<skill-id>>-<<artifact>>-<<timestamp>>.<<ext>><<format>><<What it contains and who/what uses it next.>>
Equivalence test resultsoutput/<<skill-id>>-equiv-<<timestamp>>.mdmarkdownPass/fail results for every row in Section 6; required input for Section 9 Done Criteria.

8. References

<!-- WHAT TO WRITE A pointer list — internal skill paths, reference docs, and (sparingly) external URLs. This is a navigation aid, not a literature review. Keep it short. RULES - Always include the anti-patterns doc when the skill involves destructive operations. - Always include the strangler-fig doc when the skill touches traffic routing or dual-write. - Prefer internal paths over external URLs. External URLs rot. - One line per reference: `path or URL` — one-sentence description of what it adds. COMMON MISTAKES - Listing a reference that has nothing to do with this specific skill. - External URLs without a description of why they're relevant. - Linking to the template itself in a real skill (fine here; remove in copies). EXAMPLE - `references/strangler-fig-pattern.md` — dual-write and traffic-shifting mechanics -->
  • skills/_template/SKILL.md — this template (remove this line in real skills)
  • references/strangler-fig-pattern.md — <<remove if not applicable>>
  • references/migration-anti-patterns.md — <<remove if not applicable>>
  • references/stack-compatibility-matrix.md — <<remove if not applicable>>
  • <<skills/<related-skill>/ — description of why it's related.>>
  • <<external URL — one sentence on what it adds that internal docs don't cover.>>

9. Done Criteria

<!-- WHAT TO WRITE A binary checklist. Every item must be objectively pass/fail — no judgment calls. Claude evaluates each item and reports its verdict before declaring the skill complete. Minimum 5 items. A skill with all items checked is DONE; any unchecked item means NOT DONE. ITEM ANATOMY - [ ] <Gate description> — <how Claude verifies it (file exists / grep / test result / etc.)> MANDATORY ITEMS (keep all of these; add skill-specific items above them) - [ ] All output files exist at their declared paths in Section 7. - [ ] Every equivalence test in Section 6 has a recorded result (pass or fail). - [ ] No equivalence test in Section 6 is recorded as fail. - [ ] The output report includes a confidence level (High / Medium / Low). - [ ] The output report includes a numbered assumptions list. COMMON MISTAKES - "Code quality looks good" — not binary; cannot be objectively checked. - Duplicating an item from Section 6 Equivalence Tests without connecting it to a test name. - Fewer than 5 items — the mandatory items alone give you 5; add skill-specific ones on top. - Items that can only be checked by a human with no description of what they check. EXAMPLE SKILL-SPECIFIC ITEMS - [ ] `pre-migrate.sh` exited 0 for `<<target_module>>` in `<<env>>` — check hook log. - [ ] No references to the old module path remain in `<<repo_root>>/src` — grep confirms. -->
  • <<Skill-specific gate 1>> — <<how Claude verifies this.>>
  • <<Skill-specific gate 2>> — <<how Claude verifies this.>>
  • <<Skill-specific gate 3 — e.g., pre-migrate hook exited 0.>> — check output/migration-run-log.jsonl.
  • All output files listed in Section 7 exist at their declared paths — verify with file read.
  • Every equivalence test in Section 6 has a recorded result in output/<<skill-id>>-equiv-<<timestamp>>.md.
  • No equivalence test in Section 6 is recorded as fail — review results file.
  • The output report includes a confidence level (High / Medium / Low) — grep for "Confidence:".
  • The output report includes a numbered assumptions list — grep for "Assumptions:".

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free