Skip to content

SUBSTANCE.md

Latest commit

 

History

History
170 lines (117 loc) · 7.14 KB

SUBSTANCE.md

File metadata and controls

170 lines (117 loc) · 7.14 KB
Raw

Substance vs. Growth: Transparency Note

This repository prioritizes skill frameworks and agent workflows but also includes growth and discovery tools. This document clarifies what's core to the project and what's optional growth infrastructure.

What's Core (The Skills & Framework)

These are the actual tools you'd install and use:

  • 18 agent skills in skills/ directory
  • Workflow examples in examples/
  • Installation scripts and adapters for Claude Code, Cursor, Windsurf, Codex, Gemini
  • Guides (GUIDE.md, CLAUDE.md, GEMINI.md)

These are genuine agent capabilities designed to solve real problems:

  • verify-before-claim prevents hallucinated completion claims
  • wiki-ingest structures knowledge instead of scattering it
  • daily-okr closes the knowledge-to-action loop
  • agentic-engineering designs agent workflows with verification gates

How to Evaluate the Substance

  1. Read one skill spec — try skills/verify-before-claim/SKILL.md
  2. Run one example — follow examples/3-minute-quickstart.md
  3. Test on real work — ingest one article, run one daily OKR, verify one coding session claim

The framework either works for your workflow or it doesn't. No marketing changes that.

What's Growth Infrastructure (Optional)

These tools are NOT required to use the skills:

tools/
├── find-awesome-pr-targets.py    ← Finds Awesome list repos (>500 stars)
├── submit-awesome-prs.py         ← Generates PR templates for Awesome lists
├── configure-github-repo.py      ← Optimizes repo topics for search discoverability
└── growth-loop.py                ← Daily repo health + launch readiness validation

outreach/
├── awesome-lists/                ← Awesome list submission templates + targets
├── launch/                        ← HackerNews, ProductHunt, Dev.to templates
└── growth-reports/               ← Daily growth metrics and analysis

Why these exist:

  • The author wanted the framework to be discoverable by the right users
  • Awesome lists, HackerNews, ProductHunt are legitimate discovery channels
  • The tools are honest: dry-run-by-default, require a GitHub token (safe), generate templates not auto-submit spam

Why we're being transparent:

  • A project optimized for growth can accidentally optimize for stars over substance
  • Combined with outreach/ folder + daily "growth reports," the priority order can look inverted
  • You deserve to know which parts are core vs. growth machinery

Red Flags We've Fixed

1. Title Had a Typo

Before: "claude sikkls" (garbled)
After: "Agent Skills" (clear)

Why it mattered: A typo in the title suggests rushed launch under growth pressure, not careful preparation. This has been fixed.

2. Dead Links in README

Before: README pointed to docs/github-star-growth-sprint.md and other pages that don't exist or broke during navigation
After: All links verified; dead ones removed; README refactored to focus on substance

Why it mattered: If the initial quality gate was weak, what else wasn't verified?

3. Growth Tools Mentioned Heavily

Before: Growth sprint docs, Awesome-list guidance, and star-growth metrics featured prominently in main README
After: Moved to this transparency section; main README focuses on substance

Why it mattered: A user seeing "github-star-growth-sprint.md" prominently listed might wonder if that's the project's actual focus.

How to Use This Responsibly

✅ Safe to Extract & Adapt

  • Verify-before-claim concept — Apply this discipline to any agentic workflow
  • Wiki-ingest source-risk taxonomy — Use for your own knowledge system design
  • Daily-OKR 7-KR structure — Adapt for your closure loops (without the growth reporting)
  • Behavior experiment template — Valid for habit design systems
  • Multi-agent orchestration patterns — Genuine engineering frameworks

⚠️ Verify Before Adopting

  • Run a test: Ingest one article using the wiki-ingest skill, evaluate output quality
  • Check completeness: Not all 18 skills are equally polished; some are aspirational
  • Adapt paths: Change frontmatter, directories, and config to match your vault structure
  • Test with your agent: Skills work best with Claude; results with other agents may vary

❌ Ignore

  • Growth optimization as career guidance — Awesome-list automation is useful for discovery, not a life strategy
  • "18 skills" claim without verification — Review each skill you plan to use individually
  • Star count as quality signal — Useful repos and unuseful repos both get stars
  • "Production-ready" without testing — Verify skills work for your workflow, not on faith

What We're Not Hiding

The Growth Strategy Is Honest

# From find-awesome-pr-targets.py
def make_candidate(item, keyword, headers):
    # Finds repos matching keywords, generates PR templates
    # Does NOT: fork, commit, submit automatically
    # Does: write review-ready markdown for manual submission

The scripts are dry-run-by-default. They find targets and generate templates. You decide whether to submit.

The Tools Require a GitHub Token

If someone were building a spam bot, they'd hide the auth requirement or create a public endpoint. These tools require GITHUB_TOKEN in your environment — they're explicitly local-only.

The Philosophy Is Sound

The core beliefs are genuine:

  • Verification prevents hallucination
  • Knowledge should compound
  • Agents need closed loops
  • Context is expensive
  • Multi-agent teams need orchestration gates

These aren't growth hacks; they're engineering principles.

Credibility Assessment

Signal Assessment
Core frameworks ✅ Legitimate, useful, not cargo-cult
Skill specifications ⚠️ Well-written but variable depth (some aspirational)
Execution quality ✅ Fixed: typos corrected, dead links removed, README refactored
Growth infrastructure ⚠️ Honest but present; reveals growth optimization priorities
Transparency ✅ This document + refactored README exist because transparency matters

Final Word

This framework has real value. The verify-before-claim concept alone is worth adopting. The wiki-ingest pattern is a legitimate knowledge-management architecture.

The project launched with growth-first urgency, which affected initial polish. We've addressed this by:

  1. Fixing the title typo
  2. Removing dead links
  3. Refactoring README to focus on substance first
  4. Creating this transparency document

Use the skills; test them; adapt them. But don't adopt them uncritically just because the repo got stars or you read a glowing review.

Your job: Try one skill on a real problem. If it works, keep using it. If it doesn't, discard it. That's all the validation you need.

Questions?