awesome-skills/first-principles-skill installation guide

Install First Principles Thinking Skill on macOS Tahoe (Apple silicon)

What this repository is

`awesome-skills/first-principles-skill` is a small Claude Code skill that adds a structured first-principles thinking method. It is designed to help Claude identify the essence of a problem, challenge assumptions, establish ground truths, reason upward from those truths, and validate the resulting recommendation.

**Classification:** Claude Code **context-injection skill** (a Claude extension). Its `SKILL.md` supplies instructions and an output format that Claude Code can load when relevant. The supplied files do not show an MCP server, lifecycle hook, standalone application, executable helper, or external service. Installation consists of placing the skill folder in the documented Claude Code skills location.

The skill is version `0.2.0` in `SKILL.md`, and the repository metadata identifies an MIT license.

Important source discrepancy

There is a mismatch in the supplied first-party evidence:

• GitHub metadata identifies the repository as `awesome-skills/first-principles-skill`.
• The README’s installation commands clone `https://github.com/tt-a1i/first-principles-skill.git`.

This guide does not silently rewrite that documented command. The command blocks below reproduce only installation commands explicitly provided by the README. Before continuing, understand that they retrieve the `tt-a1i` repository named in the README rather than the `awesome-skills` repository named in the metadata. If you want to avoid that mismatch, use the GitHub web page for the metadata repository to download and inspect its files manually; no separate first-party command for cloning that owner was supplied.

Before you begin

You need Claude Code because this repository is only a skill for Claude Code, not a complete application. You also need a Terminal environment capable of running the README’s `git`, `cp`, and `ln` commands.

On macOS Tahoe, open **Terminal** from Applications → Utilities. Apple silicon does not require a special build here: the supplied repository consists of Markdown and reference material, and no architecture-specific binary or package installation is documented.

The documented destination is:

`~/.claude/plugins/superclaude/skills/first-principles`

Here, `~` means your macOS home folder. The supplied files do not document how to install Claude Code, SuperClaude, Git, or any missing parent directories. They also do not provide commands for creating the destination’s parent folders. If the destination hierarchy does not already exist, stop rather than improvising an undocumented setup command.

Choose one installation method

Use **either** the copy method or the symbolic-link method—not both. The copy method creates a separate installed copy. The symbolic-link method points the Claude skills location at a clone stored under `~/skills`.

Option 1: Clone and copy

This is the README’s first installation method. Paste the following commands into Terminal:

# Clone the repo
git clone https://github.com/tt-a1i/first-principles-skill.git

# Copy to Claude Code skills directory
cp -r first-principles-skill ~/.claude/plugins/superclaude/skills/first-principles

The first command downloads the repository into a folder named `first-principles-skill` under Terminal’s current working directory. The second command recursively copies that folder to the documented Claude Code skills location and names the installed folder `first-principles`.

This method is straightforward, but the installed copy is independent of the original clone. The supplied documentation does not provide an update command, so this guide does not recommend one.

Option 2: Clone and create a symbolic link

Instead of copying, the README offers this method:

git clone https://github.com/tt-a1i/first-principles-skill.git ~/skills/first-principles-skill
ln -s ~/skills/first-principles-skill ~/.claude/plugins/superclaude/skills/first-principles

The first command clones the repository into `~/skills/first-principles-skill`. The second creates a symbolic link at the documented Claude skills path. Claude Code therefore sees the files through the link while the actual repository remains in `~/skills`.

This method assumes that both relevant parent directories already exist and that the destination link does not already exist. The README supplies no commands for resolving either condition, so do not add flags or corrective commands that are not documented.

What should be installed

The README describes this repository structure:

• `SKILL.md` — the main skill definition
• `README.md` — project documentation
• `LICENSE` — MIT license text
• `references/software-examples.md` — software-engineering case studies
• `references/elon-musk-examples.md` — SpaceX and Tesla examples
• `examples/architecture-review.md` — a complete microservices analysis example

Install the complete directory rather than copying only `SKILL.md`. The main skill explicitly refers to files in `references` and `examples`, so retaining the directory structure preserves the supporting material described by the repository.

Using the skill

No separate launch command is documented. The README says the skill triggers automatically when your request uses relevant language. After installation, open or return to Claude Code and ask for a first-principles analysis in ordinary language.

Documented English trigger phrases include:

• “analyze from first principles”
• “think from scratch”
• “question this design”
• “is this the right approach”
• “challenge assumptions”

Documented Chinese triggers include:

• “第一性原理”
• “从根本分析”
• “从零开始思考”
• “这个设计合理吗”
• “为什么要这样做”
• “有没有更好的方案”

For a simple test, ask Claude Code to analyze an architectural or design decision from first principles. The expected response structure is described as:

1. Problem Essence
2. Assumptions Challenged
3. Ground Truths
4. Reasoning Chain
5. Conclusion

A successful response should state the core problem and success criteria, question assumptions in a table, identify irreducible facts, connect those facts to a proposed solution, and acknowledge trade-offs.

What the skill does and does not do

The skill is intended for architecture reviews, foundational design choices, legacy assumptions, questionable “best practices,” and situations where conventional solutions may not fit. It can complement trade-off analysis, 5-Whys, pre-mortems, and hypothesis testing.

Its own boundaries say that it will challenge assumptions, identify ground truths, and build traceable reasoning chains. It will not automatically reject existing solutions, ignore practical constraints, spend unlimited time on every decision, or guarantee a perfect answer. Treat its output as structured reasoning that still needs human judgment and factual verification.

Troubleshooting within the supplied evidence

If cloning fails, the supplied files provide no troubleshooting or alternative Git command. Check the repository URL discrepancy noted above and avoid substituting undocumented commands.

If copying or linking reports that a path does not exist, the likely issue is that a required parent directory is absent. The README does not document creating it, nor does it explain how the `superclaude` hierarchy is provisioned. Confirm your Claude Code or SuperClaude setup through its own first-party documentation before proceeding.

If the skill does not activate, use one of the exact trigger phrases above and make the request explicitly about evaluating a design, architecture, assumption, or problem-solving approach. No diagnostic, reload, restart, listing, or verification command is supplied by this repository, so none is recommended here.

Security and maintenance notes

The inspected files contain methodology and examples rather than executable scripts. Even so, review `SKILL.md` and its supporting Markdown before relying on it, because a skill changes the instructions available to Claude Code.

No update, uninstall, rollback, compatibility-check, or minimum Claude Code version command is documented. The evidence also does not establish specific macOS Tahoe testing. Apple silicon should not create an architecture issue for Markdown files, but host compatibility ultimately depends on the Claude Code/SuperClaude skill system represented by the documented destination path.