⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.7.2

advise-project-approach

aaravkashyap12@aaravkashyap12⭐ 329 stars· last commit 2mo ago· 0 open issues

Research and advise on the best way to approach a software project, including architecture, tech stack, implementation strategy, pricing/operating-cost tradeoffs, benchmark research, and comparisons with similar real-world projects. Use before building, mid-build, or after completion when the user asks for project strategy, optimal approach, research comparables, similar projects, stack selection, vendor/service choice, repo analysis, architecture critique, implementation feedback, or a prioritized improvement plan. Avoid for narrow single-bug debugging or isolated file edits unless the user asks for broader project direction.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 329 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

advise-project-approach is an agent skill for project planning, course correction, and review. Its portable SKILL.md can be loaded by Codex, Claude Code, pi, Hermes, and other Agent Skills-compatible harnesses.

Portability is a design contract, not proof of identical behavior in every host. See the host evidence matrix.

Before recommending a stack, architecture, vendor, refactor, or shipping plan, it checks:

  • your actual constraints
  • comparable real-world projects
  • tradeoffs and failure conditions
  • cost and lock-in realities
  • when the recommendation becomes wrong

Use It When

  • you have a rough project idea and need a build plan
  • your repo is getting messy and you need course correction
  • you are choosing between stacks or vendors
  • you want a review before shipping
  • you want the agent to explain what not to build yet

One-Line Install

npx skills@latest add AaravKashyap12/advise-project-approach --skill advise-project-approach

This uses the open skills installer to fetch the repo from GitHub and install only this skill. It requires Node.js/npm. Review installed skills before use; skills run with your agent's normal permissions.

Source of Truth

The runtime skill spec lives in skills/advise-project-approach/SKILL.md. That file is the source of truth for the workflow agents actually run.

Everything else in this repo exists to package, explain, test, or distribute that skill.

What's New in v0.7.2

v0.7.2 addresses concrete failures found by independent audits, adversarial package tests, and repeated model evaluations.

  • Adds no-clobber and recovery checks for advice that changes user data, plus stronger concurrency-test guidance.
  • Keeps private project details out of public research queries and stops research after an inconclusive follow-up.
  • Clarifies project-stage routing, accepted intake unknowns, safety prerequisites, and requested answer limits.
  • Hardens YAML/metadata, archive integrity, release consistency, and failed-build handling, with permanent regression tests.
  • Preserves failures, mixed baseline comparisons, and post-fix evidence in a dedicated audit report.

See the full changelog for earlier versions.

Where This Fits

Use recent-signal tools to discover what changed.

Use advise-project-approach to decide what to build, change, defer, or avoid.

The skill is not trying to be a general search engine. It is a project-judgment workflow for turning evidence into engineering decisions.

Try These Prompts

"What's the best way to build a self-hosted bookmark manager?"
"Research comparable projects before I start this."
"I'm halfway through building a Node/Express API. Is my approach right?"
"Review my finished project at github.com/owner/repo."
"Should I use Postgres or SQLite for this?"
"What stack should I use given I know Python and want to self-host?"
"Should I use Supabase/Firebase/Neon/Vercel, or will pricing hurt later?"

What It Does

Drop it into your agent and it will:

  • Pre-build: Research your stack, find comparable real projects, compare architecture options, and hand you a build plan before you commit to anything you will regret in month three.
  • Mid-build: Inspect your repo, identify what is actually wrong, not just what is fashionable to fix, and give you a prioritized list of changes ordered by impact.
  • Post-build: Review your finished project against mature comparables, call out the gaps, and tell you what to harden before you ship.

It does the research loop a good engineer would do manually: understand the goal, inspect the evidence, study credible comparables, evaluate the tradeoffs, and recommend the highest-leverage path.

No vibes. Evidence first.

Works Across Agent Harnesses

The workflow is self-contained in its runtime skill file:

skills/advise-project-approach/SKILL.md

From a local clone, install the same skill folder into the location your harness scans:

HarnessLocal skill location
pi~/.agents/skills/ or ~/.pi/agent/skills/
Claude Code~/.claude/skills/
Codex~/.codex/skills/
Other compatible agentsPoint the loader at the skill folder or SKILL.md
cp -r skills/advise-project-approach <your-agent-skill-directory>/

Pi documents recursive discovery of directories containing SKILL.md and permits freeform additional files. See pi's skill documentation.

The packaged .skill archive, .claude-plugin/plugin.json, and agents/openai.yaml are additive compatibility layers for installers and host UIs. They do not change the portable SKILL.md workflow, and harnesses that do not use them can ignore them.

Other Install Methods

To inspect the available skill before installing:

npx skills@latest add AaravKashyap12/advise-project-approach --list

Manual Download

Download the packaged skill:

dist/advise-project-approach.skill

Or install from the GitHub release:

Download the v0.7.2 release asset

Skill UI

  1. Download dist/advise-project-approach.skill.
  2. Open your agent's skill settings.
  3. Upload the .skill file.
  4. Start a new conversation.

Plugin Metadata

This repo also includes .claude-plugin/plugin.json for plugin-aware installers that can read skill collections from GitHub repositories.

Demo

You: I want to build a self-hosted bookmark manager. Solo dev, Python background, want tags and full-text search.

Agent, with skill: researches linkding, Linkwarden, LinkAce, official framework docs, and relevant search/storage options.

## Project Approach: Self-Hosted Bookmark Manager

### TL;DR
Go with Django + SQLite FTS5 or Postgres full-text search, depending on your hosting target and expected scale. Keep the main UI server-rendered with HTMX, Turbo, or light JavaScript unless the UI needs true SPA complexity. This matches your Python skills, keeps deployment simple, and is backed by nearby real projects like linkding.

### Comparable Projects
1. linkding - github.com/sissbruecker/linkding; Django, DRF, Huey, Turbo/Lit, Docker, optional Postgres; nearest domain match; limits: current details must be verified at review time.
2. Linkwarden - github.com/linkwarden/linkwarden; heavier collaborative bookmark manager; useful contrast for when archiving/collaboration matter more than simplicity.
3. LinkAce - linkace.org; mature self-hosted bookmark manager in a different stack; useful for feature comparison, less useful for implementation fit.

The demo avoids hard-coded star counts and "latest" dates because those decay. The skill requires the agent to verify those values at review time.

See more examples:

  • [Illustrative contrasts with generic advice, not measured A/B tests](./examples/ab-comparisons.md

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/advise-project-approach/SKILL.md7.8 KBupstream ↗
    ---
    name: advise-project-approach
    description: Research and advise on the best way to approach a software project, including architecture, tech stack, implementation strategy, pricing/operating-cost tradeoffs, benchmark research, and comparisons with similar real-world projects. Use before building, mid-build, or after completion when the user asks for project strategy, optimal approach, research comparables, similar projects, stack selection, vendor/service choice, repo analysis, architecture critique, implementation feedback, or a prioritized improvement plan. Avoid for narrow single-bug debugging or isolated file edits unless the user asks for broader project direction.
    ---
    
    # Advise Project Approach
    
    Help the user decide, validate, or improve how a project should be built. This skill automates the research loop a strong engineer would normally do manually: understand the project goal, inspect any existing work, study credible comparables, evaluate tech-stack and architecture choices, then recommend the highest-leverage path.
    
    ## Non-Negotiable Protocol
    
    Apply these gates before all other instructions:
    
    1. **Stop for vague intake.** For an initial broad pre-build request, if two or more facts material to the requested decision are unknown, ask the concise intake batch and end the response. Do not invent a product direction or constraints. Skip repetitive intake for bounded questions or an already answered interview; handle accepted unknowns as described in Project Intake. If the user asks to skip questions, proceed with visible assumptions.
    2. **Keep repository review read-only.** A request to inspect or review a repository does not authorize dependency installation or execution of its tests, builds, linters, audits, benchmarks, scripts, or application code. Ask before running them.
    3. **Do not outsource judgment to popularity.** Never select or copy a stack because a repository has the most stars or adoption. If the user requests that shortcut, explain why it is not a fit test and continue only with visible assumptions or known constraints.
    4. **Require receipts before recommendation.** For a substantive recommendation, inspect relevant local evidence and normally two comparables plus primary documentation or pricing sources when available. State what was inspected, what each source supports, its limits, and the observed date for time-sensitive claims.
    5. **Complete the decision.** A substantive choice needs constraint fit, a credible alternative, tradeoffs, reversal conditions, and next actions. Mark unavailable evidence explicitly. For narrow implementation guidance, do not reopen the user's settled choices just to fill these fields.
    6. **Stop when evidence is sufficient or exhausted.** Track whether each lookup adds new support. Stop after two consecutive lookups add no decision-relevant evidence, even if the question remains unresolved. Use the bounded research and repository-inspection rules below.
    7. **Make advice disprovable.** Pair the first action with observable acceptance and a check that actually exercises the failure mode. Proposed checks are neither passing results nor architecture diagnoses. A failing invariant triggers debugging of the write path, test, or requirement first, not an automatic new layer.
    8. **Honor the requested scope and format.** Respect explicit length, paragraph, and step limits in every mode; combine essential evidence and advice rather than filling template headings. When the direction is fixed and the question is bounded, use the narrow-advice route. Gather fresh evidence only if it could materially change the answer; that does not expand the requested output.
    9. **Sequence observable outcomes.** Prefer end-to-end capabilities over speculative abstractions. A required safety, recovery, or correctness check is a valid earlier step when the user or evidence makes it a prerequisite. Avoid layer extraction solely for anticipated reuse.
    
    ## Operating Modes
    
    First identify which mode applies:
    
    - **Pre-build strategy** - no repo exists yet, or the user is deciding how to build. Focus on requirements, constraints, comparable projects, stack choices, architecture options, risks, and a recommended implementation path.
    - **Mid-build course correction** - a repo or partial implementation exists. Inspect the code, compare it with the intended goal and external references, then recommend what to keep, change, or defer.
    - **Post-build review** - the project is mostly complete. Review architecture, quality, maintainability, deployment readiness, security posture, and gaps against similar mature projects.
    
    Mode selection rule:
    
    - Use the user's explicit stage for the subject project first. A comparable, dependency, or upstream-template URL is reference material, not evidence that the user's own project exists or is finished.
    - If the subject has no implementation yet, use **pre-build strategy**. If work is underway, use **mid-build course correction**. If the subject is finished, deployed, or being assessed for launch, use **post-build review**.
    - Use repository and language clues only when the subject's stage is unclear. Distinguish current state from an intended future launch or scale.
    
    If a mid-build or post-build request provides only a description and no repo/code, proceed as an **advisory review from description**. Say that file-level findings require a repo or code sample; do not pretend local evidence was inspected.
    
    ### Narrow-advice route
    
    Use this route when the user has fixed the main direction and asks a bounded question such as "give me the first three steps," "how should I validate this choice," or "compare these two options." It overrides the full workflow and output contracts for that response.
    
    - Preserve the requested count and format. For `N` steps, return exactly `N` primary steps.
    - Put the action, acceptance behavior, and focused check inside each step.
    - Keep checks concrete: for a race, name independently competing operations and how overlap is synchronized. Label unsynchronized parallel requests as a stress probe, not deterministic proof.
    - State assumptions or evidence limits in one compact sentence only when material.
    - End with at most one compact failure or escalation condition when it changes the advice.
    - Express that escalation as a testable threshold or event, such as the same invariant duplicated across two entry points, a focused check failing, or a measured performance/cost limit being crossed. Do not use "awkward," "complex," or "hard to maintain" without an observable proxy.
    - Do not browse, research comparables, restate the chosen stack, or emit full-report headings unless fresh evidence is necessary to answer the bounded question safely.
    - Prefer the framework's default organization. Do not introduce a service layer, repository pattern, queue, cache, microservice, or other architectural boundary without evidence that the current requirement needs it.
    - Give each numbered step an observable capability or risk-reducing result, including prerequisite safety checks when necessary. Keep early slices in the framework's ordinary structure; extract abstractions only for evidenced duplication or conflicting entry points, not merely because a test failed.
    
    ## Project Intake
    
    Use a lightweight intake interview before research when a pre-build request is vague enough that different answers would materially change the recommendation.
    
    Decision-critical facts include the primary user, core workflow, project stage, must-haves, builder/team capability, budget or deadline, deployment target, and dominant priority.
    
    Do not interrogate users who already supplied clear constraints. If the project, users, must-have workflow, stage, and major constraints are sufficiently specified, begin research immediately and ask only the missing decision-critical question.
    
    For a vague idea, ask these questions in one concise batch and accept "not sure" answers:
    
    1. What are you trying to build, and who is it for?
    2. 
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/aaravkashyap12-advise-project-approach-skills-advise-project-approach.md

// REPO STATS

329 stars
0 open issues
Last commit: 2mo ago