feat: skill-discovery-layer — workflow guides, agent configs, AGENT.md convention, credential store by whoabuddy · Pull Request #4 · aibtcdev/skills

whoabuddy · 2026-02-20T05:31:13Z

Summary

Added what-to-do/ workflow discovery layer with 9 workflow guides
Added aibtc-agents/ community agent configuration directory with template and arc0btc reference
Added AGENT.md subagent definitions to all 18 skill directories
Added credentials/ skill with AES-256-GCM encrypted credential storage
Updated README.md with documentation for all new directories

Closes #1, closes #2, closes #3

Test plan

Verify all what-to-do/ workflow files render correctly on GitHub
Verify aibtc-agents/ template is usable for new agent configs
Verify credentials/ TypeScript compiles: npx tsc --noEmit credentials/*.ts
Spot-check AGENT.md files match their SKILL.md subcommands

Creates the what-to-do/ discovery layer with a workflow index and eight numbered workflow guides covering the core agent tasks on the AIBTC platform: registration, check-ins, inbox messaging, ERC-8004 identity, BTC payments, balance checking, token swaps, contract deployment, and message signing. Each workflow file follows the Phase 1 format spec with frontmatter, prerequisites, numbered steps with CLI commands, expected output descriptions, verification checklists, and related skills tables. All bun run commands use accurate subcommand names verified against SKILL.md frontmatter. Co-Authored-By: Claude <noreply@anthropic.com>

Creates the aibtc-agents/ directory as a community registry for agent configurations. README explains what configs contain, how to contribute, and PR guidelines (accurate skills, valid addresses, no secrets). template/setup.md is a blank slate with all sections and placeholder values that any agent can copy and fill in. Co-Authored-By: Claude <noreply@anthropic.com>

Arc (arc0btc) is a fully configured reference agent that uses all 18 skills and participates in all 8 what-to-do/ workflows. The config documents wallet setup, environment variables, per-workflow cadence, and operational preferences — serving as a realistic working example for community contributors adding their own agent configs. Co-Authored-By: Claude <noreply@anthropic.com>

Add subagent definition files for the four foundational infrastructure skills: wallet (lifecycle + security gatekeeper), settings (API key and Stacks node URL configuration), query (read-only Stacks blockchain queries), and signing (four standards: SIP-018, Stacks SIWS, BTC BIP-137, and Schnorr BIP-340 for Taproot multisig). Co-Authored-By: Claude <noreply@anthropic.com>

Add subagent definition files for the seven asset-layer skills: btc (L1 balance, UTXOs, cardinal/ordinal classification, transfers), stx (L2 STX balance, transfers, contract calls and deployment), sbtc (wrapped BTC on Stacks, deposits and transfers), tokens (SIP-010 fungible tokens), nft (SIP-009 NFTs), ordinals (Bitcoin inscriptions via two-step commit/reveal), and bns (.btc domain name registration and lookup). Co-Authored-By: Claude <noreply@anthropic.com>

Add subagent definition files for the seven protocol-layer skills: identity (ERC-8004 on-chain registry and reputation), bitflow (Bitflow DEX swaps, mainnet-only), defi (ALEX DEX + Zest Protocol lending, mainnet-only), stacking (PoX STX locking for BTC rewards), pillar (smart wallet in browser-handoff and direct agent-signed modes), x402 (paid API endpoints and inbox messaging), and yield-hunter (autonomous sBTC yield daemon with delegation-with-care warning). Co-Authored-By: Claude <noreply@anthropic.com>

…ntation Introduces the core credential store with: - types.ts: EncryptedCredential, CredentialStore, CredentialMeta, DecryptedCredential interfaces - store.ts: full CRUD using AES-256-GCM + PBKDF2-SHA256 (100k iterations, per-credential salt) - Atomic file writes (temp + rename), 0o600 permissions on credentials.json - No external dependencies — Node.js crypto module only Co-Authored-By: Claude <noreply@anthropic.com>

…ate-password Wires the credential store operations to a Commander CLI following the same pattern as wallet.ts — JSON output, handleError with exit 1, --confirm DELETE guard on destructive operations, --password flag on all write commands (no session persistence by design). Co-Authored-By: Claude <noreply@anthropic.com>

…ntial-store SKILL.md follows the established pattern — frontmatter with name/description/ user-invocable/arguments, one subcommand section per command with options and JSON output examples, and a Security Notes section. AGENT.md defines the credentials-agent subagent with delegation triggers and constraints for the orchestration layer. Workflow 9 guides agents through seeding the credential store before running API-dependent skills, with verification checkboxes and a See Also cross-reference. Co-Authored-By: Claude <noreply@anthropic.com>

Added four new sections to README.md covering all work from Phases 2-5: - Workflow Discovery section with table of all 9 what-to-do/ workflows - Community Agents section introducing aibtc-agents/ with template and arc0btc reference - AGENT.md Convention section explaining subagent behavior definitions - credentials/ added to the Skills table with description - Directory Structure diagram updated to include credentials/, what-to-do/, aibtc-agents/, and AGENT.md files Co-Authored-By: Claude <noreply@anthropic.com>

Adds VERSION file at repo root for easy agent access to current version. Release Please bumps package.json, VERSION, and generates CHANGELOG.md on merge to main. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds a “skill discovery layer” on top of the existing skill CLIs by introducing workflow guides (what-to-do/), a community agent-config registry (aibtc-agents/), a new encrypted credential-store skill (credentials/), and Release Please automation for versioning.

Changes:

Added what-to-do/ workflow guides + index for task-oriented navigation across skills.
Added AGENT.md files to define subagent behavior/guardrails per skill, plus community agent config templates/examples under aibtc-agents/.
Introduced credentials/ AES-256-GCM + PBKDF2 encrypted credential store (CLI + docs) and added Release Please config/workflow + VERSION tracking.

Reviewed changes

Copilot reviewed 41 out of 41 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
yield-hunter/AGENT.md	Defines subagent guardrails + example invocations for yield-hunter.
x402/AGENT.md	Defines subagent behavior for x402 endpoints and inbox messaging.
what-to-do/INDEX.md	Workflow index (routing layer into the workflow guides).
what-to-do/1-register-and-check-in.md	Workflow guide for platform registration + heartbeat check-ins.
what-to-do/2-inbox-and-replies.md	Workflow guide for inbox messaging + BIP-137 reply/read flows.
what-to-do/3-register-erc8004-identity.md	Workflow guide for on-chain ERC-8004 identity registration.
what-to-do/4-send-btc-payment.md	Workflow guide for BTC L1 payments with UTXO safety.
what-to-do/5-check-balances-and-status.md	Workflow guide for comprehensive balances + network readiness checks.
what-to-do/6-swap-tokens.md	Workflow guide for Bitflow token swaps with quote/impact checks.
what-to-do/7-deploy-contract.md	Workflow guide for deploying Clarity contracts and verifying deployment.
what-to-do/8-sign-and-verify.md	Workflow guide for signing/verification across supported standards.
what-to-do/9-setup-credential-store.md	Workflow guide for seeding the encrypted credential store.
wallet/AGENT.md	Defines wallet subagent decision rules and safety constraints.
tokens/AGENT.md	Defines tokens subagent behavior and examples.
stx/AGENT.md	Defines STX subagent behavior and examples.
stacking/AGENT.md	Defines stacking subagent behavior and examples.
signing/AGENT.md	Defines signing subagent behavior and examples.
settings/AGENT.md	Defines settings subagent behavior and examples.
sbtc/AGENT.md	Defines sBTC subagent behavior and examples.
query/AGENT.md	Defines query subagent behavior and examples.
pillar/AGENT.md	Defines pillar subagent behavior and operational constraints.
ordinals/AGENT.md	Defines ordinals subagent behavior and safety constraints.
nft/AGENT.md	Defines NFT subagent behavior and examples.
identity/AGENT.md	Defines identity subagent behavior and examples.
defi/AGENT.md	Defines DeFi subagent behavior and constraints.
btc/AGENT.md	Defines BTC subagent behavior and examples.
bns/AGENT.md	Defines BNS subagent behavior and examples.
bitflow/AGENT.md	Defines bitflow subagent behavior and examples.
credentials/types.ts	Credential-store types (encrypted/decrypted shapes + metadata).
credentials/store.ts	Credential-store crypto + atomic persistence + CRUD + password rotation.
credentials/cli.ts	Commander CLI for credentials CRUD + rotation operations.
credentials/SKILL.md	Skill contract documenting CLI usage/output and security properties.
credentials/AGENT.md	Subagent guardrails for managing encrypted secrets.
aibtc-agents/README.md	Contribution guide + structure for community agent configs.
aibtc-agents/template/setup.md	Template agent configuration for new contributors.
aibtc-agents/arc0btc/README.md	Reference “arc0btc” agent configuration example.
README.md	Documents new directories (what-to-do/, aibtc-agents/) + AGENT.md convention + credentials skill.
release-please-config.json	Release Please configuration (changelog + VERSION file).
.release-please-manifest.json	Release Please manifest with current version.
.github/workflows/release-please.yml	GitHub Action workflow to run Release Please on main.
VERSION	Repo version tracked for releases.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-20T05:58:26Z

+bun run btc/btc.ts get-cardinal-utxos --address bc1q...
+
+# Transfer BTC with a specific fee rate
+bun run btc/btc.ts transfer --to bc1q... --amount 0.001 --fee-rate 5


The BTC transfer example uses --to and --amount 0.001, but btc.ts transfer expects --recipient and --amount in satoshis (integer). Update the example invocation to use the correct flag name and units so it is copy/paste-able.

Suggested change

bun run btc/btc.ts transfer --to bc1q... --amount 0.001 --fee-rate 5

bun run btc/btc.ts transfer --recipient bc1q... --amount 100000 --fee-rate 5

Copilot · 2026-02-20T05:58:26Z

+bun run query/query.ts get-account-transactions --address SP2...
+
+# Call a read-only contract function
+bun run query/query.ts call-read-only --contract-address SP2... --contract-name my-contract --function-name get-value --args '[]'


query.ts call-read-only expects a single --contract-id address.contract-name option, not --contract-address + --contract-name. Update this example to use --contract-id so it matches the actual CLI.

Suggested change

bun run query/query.ts call-read-only --contract-address SP2... --contract-name my-contract --function-name get-value --args '[]'

bun run query/query.ts call-read-only --contract-id SP2...my-contract --function-name get-value --args '[]'

Copilot · 2026-02-20T05:58:26Z

+### 2. Add the Hiro API Key
+
+Store the Hiro API key for use by the `query`, `stx`, and other network skills.
+


This workflow claims the stored Hiro API key will be used by the query/stx skills, but those skills actually read the Hiro API key from settings (config) or the HIRO_API_KEY env var (see src/lib/services/hiro-api.ts). Either update this workflow to use settings/settings.ts set-hiro-api-key (or HIRO_API_KEY), or add integration so query/stx can read from the credentials store.

Copilot · 2026-02-20T05:58:27Z

+```bash
+bun run credentials/cli.ts add \
+  --id hiro-api-key \
+  --value "your_hiro_api_key_here" \
+  --password $CRED_PASS \
+  --label "Hiro API Key" \
+  --category api-key


The command examples pass the master password as --password $CRED_PASS unquoted. If the password contains shell-special characters or spaces, this can break. Quote the variable expansion (e.g., --password "$CRED_PASS") in the examples to make them robust.

Copilot · 2026-02-20T05:58:27Z

+
+The AIBTC inbox system enables direct messaging between agents. Sending a new message to another agent's inbox costs 100 satoshis paid via x402 sBTC. Reading your own inbox, replying to messages, and marking messages as read are all free operations authenticated with BIP-137 signatures.
+
+Payments route directly to the recipient's Stacks address — no platform intermediary. If an x402 payment times out but the on-chain transfer succeeded, resubmit with the `paymentTxid` field (each txid usable only once).


This workflow states inbox messaging costs 100 satoshis, but the x402 skill documentation and implementation indicate the payment amount is 1000 sats sBTC (read from the 402 challenge). Update the stated cost here to match the actual send-inbox-message behavior (or describe it as “~1000 sats” / “amount returned by the 402 challenge”).

Copilot · 2026-02-20T05:58:27Z

+bun run bitflow/bitflow.ts get-quote --from STX --to sBTC --amount 100
+
+# Execute a swap with slippage tolerance
+bun run bitflow/bitflow.ts swap --from STX --to sBTC --amount 100 --slippage 0.5


The Bitflow CLI examples here use --from/--to/--amount/--slippage, but bitflow.ts uses --token-x, --token-y, --amount-in, and --slippage-tolerance (plus --confirm-high-impact). Please update the example commands to match the actual CLI flags.

Suggested change

bun run bitflow/bitflow.ts get-quote --from STX --to sBTC --amount 100

# Execute a swap with slippage tolerance

bun run bitflow/bitflow.ts swap --from STX --to sBTC --amount 100 --slippage 0.5

bun run bitflow/bitflow.ts get-quote --token-x STX --token-y sBTC --amount-in 100

# Execute a swap with slippage tolerance

bun run bitflow/bitflow.ts swap --token-x STX --token-y sBTC --amount-in 100 --slippage-tolerance 0.5

# For high price-impact swaps, add: --confirm-high-impact

Copilot · 2026-02-20T05:58:27Z

+bun run signing/signing.ts sip018-sign --message '{"amount":{"type":"uint","value":100}}' --domain-name "My App" --domain-version "1.0.0"
+
+# Verify a BIP-137 Bitcoin signature
+bun run signing/signing.ts btc-verify --message "hello" --signature <sig> --address bc1q...


btc-verify does not accept an --address option; the CLI uses --expected-signer for optional address checking. Update this example so it matches signing.ts btc-verify options.

Suggested change

bun run signing/signing.ts btc-verify --message "hello" --signature <sig> --address bc1q...

bun run signing/signing.ts btc-verify --message "hello" --signature <sig> --expected-signer bc1q...

Copilot · 2026-02-20T05:58:28Z

+The credential store lets agents keep secrets — API keys, tokens, and passwords — encrypted at rest using AES-256-GCM. Each value is encrypted with a unique salt and IV derived from a master password; the master password itself is never written to disk. Run this workflow once to seed the credentials needed by other skills before running API-dependent workflows.
+
+This workflow does not require a wallet — the credential store is independent of the wallet system.


The intro states the salt and IV are “derived from a master password”, but the implementation generates random salt+IV and derives the encryption key from the password via PBKDF2. Consider rephrasing to avoid implying salt/IV are password-derived.

Copilot · 2026-02-20T05:58:28Z

+| [5. Check Balances and Status](./5-check-balances-and-status.md) | Check all asset balances: BTC, STX, sBTC, tokens, NFTs, and wallet status |
+| [6. Swap Tokens](./6-swap-tokens.md) | Swap tokens on Bitflow DEX with quote preview and slippage protection |
+| [7. Deploy Contract](./7-deploy-contract.md) | Deploy a Clarity smart contract to Stacks and verify its on-chain state |
+| [8. Sign and Verify](./8-sign-and-verify.md) | Sign messages or structured data using BTC, Stacks, or SIP-018 standards |


The workflow index omits the new credential-store workflow file (9-setup-credential-store.md). This makes the index incomplete and inconsistent with README.md which lists 9 workflows. Add a row linking to ./9-setup-credential-store.md with a short description.

Copilot · 2026-02-20T05:58:28Z

+- Execute a paid x402 endpoint (payment handled automatically via sBTC)
+- Probe an x402 endpoint to check payment requirements without executing
+- Send an inbox message to another AIBTC agent (costs 100 satoshis via x402 sBTC payment)
+- Scaffold a new x402 Cloudflare Worker API project
+- Scaffold an x402 AI endpoint backed by OpenRouter
+- Get the OpenRouter integration guide for building AI-powered x402 endpoints
+- List available OpenRouter models and their pricing
+
+## When to Delegate Here
+
+Delegate to this agent when the workflow needs to:
+- Send a message to another agent's AIBTC inbox (required for inter-agent communication)
+- Call a paid API endpoint that requires x402 sBTC micropayment
+- Discover what x402 endpoints are available before deciding which to call
+- Create a new x402-enabled API service or AI endpoint
+- Find the right OpenRouter model for an AI feature
+
+## Key Constraints
+
+- Inbox messaging costs 100 satoshis per new message — requires sBTC balance and unlocked wallet
+- Payment goes directly to the recipient's STX address, not via platform intermediary
+- Sponsored transactions may be available via `sponsorApiKey` from AIBTC registration


This agent doc says inbox messaging costs 100 satoshis, but the x402 skill output and server challenge amount are 1000 sats sBTC. Please update the stated cost here to match the actual send-inbox-message behavior (or describe it as “amount returned by the 402 challenge”).

whoabuddy and others added 11 commits February 19, 2026 22:11

ci: add release-please for automated releases

eafd7d0

Adds VERSION file at repo root for easy agent access to current version. Release Please bumps package.json, VERSION, and generates CHANGELOG.md on merge to main. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings February 20, 2026 05:51

Copilot started reviewing on behalf of whoabuddy February 20, 2026 05:51 View session

whoabuddy merged commit 7f62fe5 into main Feb 20, 2026
2 checks passed

github-actions Bot mentioned this pull request Feb 20, 2026

chore(main): release skills 0.2.0 #5

Merged

Copilot AI reviewed Feb 20, 2026

View reviewed changes

whoabuddy deleted the feat/skill-discovery-layer branch February 20, 2026 05:58

arc0btc mentioned this pull request Mar 18, 2026

Add aibtc.news role skill files #181

Merged

4 tasks

sonic-mast mentioned this pull request Mar 25, 2026

feat(hodlmm-risk): add HODLMM volatility risk monitoring skill #235

Closed

TheBigMacBTC mentioned this pull request Apr 7, 2026

feat(payout-reconciler): reconcile earnings API against on-chain sBTC #304

Closed

5 tasks

secret-mars mentioned this pull request May 19, 2026

fix(bitflow-funding-coordinator): add subprocess timeout guards; fix SKILL.md authorship #388

Open

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: skill-discovery-layer — workflow guides, agent configs, AGENT.md convention, credential store#4

feat: skill-discovery-layer — workflow guides, agent configs, AGENT.md convention, credential store#4
whoabuddy merged 11 commits into
mainfrom
feat/skill-discovery-layer

whoabuddy commented Feb 20, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	bun run btc/btc.ts transfer --to bc1q... --amount 0.001 --fee-rate 5
	bun run btc/btc.ts transfer --recipient bc1q... --amount 100000 --fee-rate 5

	bun run query/query.ts call-read-only --contract-address SP2... --contract-name my-contract --function-name get-value --args '[]'
	bun run query/query.ts call-read-only --contract-id SP2...my-contract --function-name get-value --args '[]'

		### 2. Add the Hiro API Key

		Store the Hiro API key for use by the `query`, `stx`, and other network skills.


		The AIBTC inbox system enables direct messaging between agents. Sending a new message to another agent's inbox costs 100 satoshis paid via x402 sBTC. Reading your own inbox, replying to messages, and marking messages as read are all free operations authenticated with BIP-137 signatures.

		Payments route directly to the recipient's Stacks address — no platform intermediary. If an x402 payment times out but the on-chain transfer succeeded, resubmit with the `paymentTxid` field (each txid usable only once).

	bun run signing/signing.ts btc-verify --message "hello" --signature <sig> --address bc1q...
	bun run signing/signing.ts btc-verify --message "hello" --signature <sig> --expected-signer bc1q...

		The credential store lets agents keep secrets — API keys, tokens, and passwords — encrypted at rest using AES-256-GCM. Each value is encrypted with a unique salt and IV derived from a master password; the master password itself is never written to disk. Run this workflow once to seed the credentials needed by other skills before running API-dependent workflows.

		This workflow does not require a wallet — the credential store is independent of the wallet system.

Conversation

whoabuddy commented Feb 20, 2026

Summary

Test plan

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants