AGENTS.md

Guidance for AI agents (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, etc.) visiting this repository.

What this repo is

A catalog of methodology skills for software engineering — each skill is a reusable discipline for how to think about a class of problems (bug handling, tech selection, code review, etc.), not a utility that performs an action.

The repo is consumed, not built. There is no compilation step, no test suite, no runtime. Users install individual skills via:

npx skills add Donemeb/Donemeb-Skills --skill <name> --agent <agent-id> -g

What this repo is NOT

• Not a software project — do not run npm install, pip install, cargo build, make, or any build/test command. There is nothing to build.
• Not a place for spurious refactors — preserve the existing SKILL.md structure unless explicitly asked to change it. The tables, the numbered steps, the cross-references are all intentional.
• Not a place for prose polishing — these skills are distilled from real engineering experience. Casual rewording removes signal. If you must edit, preserve the voice and the structure.
• Not a place to introduce project specifics — skills must remain stack-agnostic. Do not add docs/X.md paths, framework names, or project-specific examples into skill bodies.

DO

• Read README.md first to understand the catalog and the 5 category directories.
• Treat each skills/<category>/<name>/SKILL.md as authoritative for its methodology.
• Follow the agentskills.io spec for any structural change.
• Cross-reference other skills by their bare name (e.g., error-handling, not software-engineering/error-handling) — npx skills add flattens install paths.

DON'T

• Don't reformat tables, change bullet styles, swap - for *, or "tidy" markdown — the structure is intentional.
• Don't rename skills or directories without an explicit user request — install paths depend on names, renaming breaks installed users.
• Don't edit the frontmatter name field — it must match the parent directory name (spec rule).
• Don't add README.md / CHANGELOG.md / INSTALLATION_GUIDE.md inside individual skill folders — anti-pattern per mgechev/skills-best-practices.
• Don't introduce ALL-CAPS ALWAYS / NEVER — explained reasoning is preferred (anthropic guideline).
• Don't add scripts/, references/, assets/ subdirectories without first considering whether the main SKILL.md can be trimmed under 500 lines instead.

Adding a new skill

1. Pick a category: methodology/ / software-decision/ / software-engineering/ / software-documentation/ / software-debugging/.
2. Create skills/<category>/<name>/SKILL.md (kebab-case name).
3. Frontmatter minimum:

   ---
   name: <name>                    # MUST match directory name
   description: "<What>. Use when <When>. Don't use for <Neg>."  # ≤ 1024 chars, target 200-400
   license: MIT
   metadata:
     author: Donemeb
     version: "1.0"
   ---

4. Body: under 500 lines. Imperative form, numbered steps, output templates, examples. Use ## When to use and ## When NOT to use headers near the top.
5. Register in two more places:
   • Add the skill name to the appropriate group in skills.sh.json.
   • Add the skill to the catalog table in both README.md and README.zh.md.

Modifying an existing skill

• Bump metadata.version — patch for typo fixes, minor for additive changes, major for breaking methodology changes.
• Keep cross-references in sync. The current graph:
  • workspace-consistency → legacy-code-disposition + repo-hygiene
  • tech-selection-convergence → deep-comparison-analysis + industry-practice-survey
  • error-handling ↔ comm-link-debugging
  • code-review ↔ change-recap (review produces items; recap sedimentates them)
  • phase-tracking ↔ readme-sync (both via change-recap and workspace-consistency)
• If you rename or remove a skill, grep for `<old-name>` across all SKILL.md and update every reference.

Skill description quality bar

Each description should answer three questions in ≤ 400 characters:

1. What does the skill do? (verb + object)
2. When should it trigger? (3-5 user-paraphrase trigger phrases)
3. Don't use for what adjacent cases? (negative triggers — points to companion skills)

Reference: Claude Platform skill-authoring best practices and anthropics/skill-creator.

License

MIT — see LICENSE. All skills in this repo inherit the repo-level MIT license.