agentleFS
Sign inStart free
shalombshalomb/agent-skills/skills/software-design-principles/SKILL.md

software-design-principles

Skill3 starsChanged 3 months agoMITView on GitHub

Capture, catalogue, and retrieve software design principles discovered during coding sessions. Use this skill when the user asks to "capture a design principle", "remember this principle", "what principles do we have", or "apply our design principles".

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When the user asks to capture or remember a newly discovered design principle:

    line 14
  2. Very specific:

    Read the existing catalogue in references/index.md to ensure no duplicates.

    line 16
  3. Very specific:

    Create a new markdown file in references/principles/<kebab-case-name>.md with:

    line 22
  4. Distinctive:

    When you are about to make an architectural decision, or the user asks what principles we have:

    line 31
  5. Very specific:

    Read references/index.md to load the current registry into your context.

    line 32
  6. Very specific:

    If a principle seems relevant, read its specific references/principles/<name>.md file.

    line 33
  7. Distinctive:

    Follow Related Principles links — principles that cross-reference each other usually apply together.

    line 34

≈ “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

Software Design Principles

Overview

This skill allows you to capture and retrieve software design principles discovered during coding sessions. By cataloging these principles (like the DWIM - "Do What I Mean" pattern), you can build a repository of context-specific architectural and UX patterns that can be re-applied to future problems.

Workflows

1. Capturing a New Principle

When the user asks to capture or remember a newly discovered design principle:

  1. Identify the core concept, context, and the problem it solves.
  2. Read the existing catalogue in references/index.md to ensure no duplicates.
  3. State the problem and solution in domain-agnostic terms — no specific language, framework, or vendor. The concrete discovery context belongs in the Example, not in the statement of the principle.
  4. Identify Tags (e.g. UX, Architecture, Refactoring, Security) and any Related Principles already in the catalogue, for cross-referencing.
  5. Create a new markdown file in references/principles/<kebab-case-name>.md with:
    • Tags and Related Principles (immediately under the title)
    • Context/Problem
    • Solution/Pattern
    • Example (Use the exact coding context where it was discovered)
  6. Append a link and a one-sentence summary to references/index.md.
  7. Confirm with the user that the principle has been saved and summarize it briefly.

2. Retrieving and Applying Principles

When you are about to make an architectural decision, or the user asks what principles we have:

  1. Read references/index.md to load the current registry into your context.
  2. If a principle seems relevant, read its specific references/principles/<name>.md file.
  3. Follow Related Principles links — principles that cross-reference each other usually apply together.
  4. Suggest the relevant principle(s) based on the user's current task.
  5. Apply the principle directly to the code you are writing.

Reference Materials

  • index.md: The lightweight registry of all captured software design principles.
  • references/principles/: Directory containing detailed files for each principle.

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